{ "openapi": "3.1.0", "info": { "title": "Print STA API", "version": "v1", "summary": "Impressão remota via API e Agent Windows", "description": "Documentação pública autossuficiente 2.0.27. Contrato HTTP v1; runtime atual 2.0.32; schema 23. A versão do contrato é independente da versão do produto." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://bryzmdvfbowtljycefbs.supabase.co/functions/v1", "description": "Endpoint público ativo durante a transição para o domínio próprio" }, { "url": "https://api.print-sta.com.br/v1", "description": "Domínio canônico Print STA preparado; ativar como padrão após DNS + alias no Netlify" } ], "tags": [ { "name": "Conta", "description": "Identidade da conta e ambiente." }, { "name": "Computadores", "description": "Agents Windows registrados." }, { "name": "Impressoras", "description": "Inventário sincronizado pelo Agent." }, { "name": "Trabalhos", "description": "Criação, acompanhamento, cancelamento e retry." }, { "name": "Webhooks", "description": "Notificações assíncronas HMAC-SHA256." } ], "security": [ { "PrintStaApiKey": [] } ], "paths": { "/print-sta-api-account": { "get": { "tags": [ "Conta" ], "operationId": "getAccount", "summary": "Validar credencial e consultar a conta", "description": "Primeira chamada recomendada do quickstart. Confirma API Key, ambiente e conta ativa. Limite: 120 req/min por chave.", "x-print-sta-permissions": [ "account:read" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-computers": { "get": { "tags": [ "Computadores" ], "operationId": "listComputers", "summary": "Listar computadores", "description": "Lista somente computadores da conta e ambiente da API Key. Limite: 120 req/min.", "x-print-sta-permissions": [ "computers:read" ], "parameters": [ { "$ref": "#/components/parameters/ComputerStatus" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputersEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-printers": { "get": { "tags": [ "Impressoras" ], "operationId": "listPrinters", "summary": "Listar impressoras", "description": "Lista impressoras sincronizadas pelo Agent Windows. Use `computer_id` para restringir a um computador. Limite: 120 req/min.", "x-print-sta-permissions": [ "printers:read" ], "parameters": [ { "name": "computer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/PrinterStatus" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintersEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-printers/{printer_id}/test": { "post": { "tags": [ "Impressoras" ], "operationId": "testPrinter", "summary": "Solicitar impressão de teste", "description": "Requer simultaneamente `printers:read` e `jobs:create`. Limitado a 20 req/min. O teste respeita as restrições do ambiente/impressora.", "x-print-sta-permissions": [ "printers:read", "jobs:create" ], "parameters": [ { "$ref": "#/components/parameters/PrinterId" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "202": { "description": "Teste aceito", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrinterTestEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-print-jobs": { "get": { "tags": [ "Trabalhos" ], "operationId": "listPrintJobs", "summary": "Listar trabalhos", "description": "Filtra por estado, impressora e `external_id`. Limite: 120 req/min.", "x-print-sta-permissions": [ "jobs:read" ], "parameters": [ { "$ref": "#/components/parameters/JobStatus" }, { "name": "printer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "external_id", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Trabalhos" ], "operationId": "createPrintJob", "summary": "Criar trabalho de impressão", "description": "Cria um job idempotente. Limite: 60 req/min. Conteúdo público efetivo: até 10 MiB; o plano e a impressora podem impor limite menor. Texto usa UTF-8; PDF e RAW usam Base64.", "x-print-sta-permissions": [ "jobs:create" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrintJobRequest" }, "examples": { "text": { "summary": "Cupom em texto UTF-8", "value": { "printer_id": "11111111-2222-4333-8444-555555555555", "content": { "type": "text", "encoding": "utf8", "data": "PRINT STA\\nPedido #123\\nTotal: R$ 42,90\\n" }, "copies": 1, "external_id": "pedido-123", "title": "Cupom pedido 123" } }, "pdf": { "summary": "PDF em Base64", "value": { "printer_id": "11111111-2222-4333-8444-555555555555", "content": { "type": "pdf", "encoding": "base64", "data": "JVBERi0xLjQKLi4u" }, "copies": 1, "external_id": "nf-123", "title": "Nota fiscal 123" } }, "raw": { "summary": "RAW / ESC-POS em Base64", "value": { "printer_id": "11111111-2222-4333-8444-555555555555", "content": { "type": "raw", "encoding": "base64", "data": "G0BQUklOVCBTVEEKQ1VQT00gVEVTVEUKVE9UQUwgUiQgMTAsMDAKCh1WAA==" }, "copies": 1, "external_id": "cupom-raw-123", "title": "Cupom ESC-POS" } } } } } }, "responses": { "200": { "description": "Replay idempotente: o trabalho original é devolvido", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnvelope" } } } }, "201": { "description": "Trabalho criado", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-print-jobs/{job_id}": { "get": { "tags": [ "Trabalhos" ], "operationId": "getPrintJob", "summary": "Consultar trabalho e histórico", "description": "Retorna todos os campos públicos do job e a linha do tempo de eventos. Limite: 120 req/min.", "x-print-sta-permissions": [ "jobs:read" ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDetailEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-print-jobs/{job_id}/cancel": { "post": { "tags": [ "Trabalhos" ], "operationId": "cancelPrintJob", "summary": "Cancelar trabalho", "description": "Cancela quando o estado ainda permite. O backend aceita `created`, `queued` e, com invalidação da lease, `leased`; evite cancelar depois que o Agent já aceitou o trabalho. Limite: 60 req/min.", "x-print-sta-permissions": [ "jobs:cancel" ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobRequest" }, "example": { "reason": "Pedido cancelado pelo cliente." } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-api-print-jobs/{job_id}/retry": { "post": { "tags": [ "Trabalhos" ], "operationId": "retryPrintJob", "summary": "Reprocessar trabalho com proteção contra duplicidade", "description": "Retry manual somente de `failed` ou `manual_review`. Bloqueado em `leased`, `accepted_by_agent`, `sent_to_spooler` e `spooler_completed` para evitar impressão duplicada. Limite: 60 req/min.", "x-print-sta-permissions": [ "jobs:retry" ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryJobRequest" }, "example": { "reason": "Impressora voltou a ficar online." } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-list-webhooks": { "post": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "Listar Webhooks, entregas e catálogo de eventos", "description": "Retorna Webhooks ativos/pausados e as 50 entregas mais recentes do ambiente.", "x-print-sta-permissions": [ "webhooks:read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookContextRequest" } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-create-webhook": { "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Criar Webhook", "description": "O `secret` HMAC é devolvido somente nesta resposta. Endpoint deve ser HTTPS público, porta 443 e passar pelas proteções SSRF. Limite distribuído: 30 req/min.", "x-print-sta-permissions": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-update-webhook": { "post": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Atualizar Webhook ou rotacionar segredo", "description": "Com `rotate_secret=true`, a resposta inclui o novo segredo apenas uma vez. Limite: 60 req/min.", "x-print-sta-permissions": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-delete-webhook": { "post": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Excluir Webhook", "x-print-sta-permissions": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookRequest" } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-test-webhook": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Enviar evento `webhook.test`", "description": "Enfileira e tenta entregar imediatamente um evento de teste assinado. Limite: 30 req/min.", "x-print-sta-permissions": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookRequest" } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/print-sta-retry-webhook": { "post": { "tags": [ "Webhooks" ], "operationId": "retryWebhookDelivery", "summary": "Reprocessar entrega em retry/dead-letter", "description": "Aceita entrega em `retry_scheduled` ou `dead_letter` e tenta o processamento. Limite: 30 req/min.", "x-print-sta-permissions": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryWebhookRequest" } } } }, "responses": { "200": { "description": "Operação concluída", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRetryEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "PrintStaApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pst_test_... ou pst_live_...", "description": "API Key Print STA. O prefixo define o ambiente e não pode ser misturado com recursos de outro ambiente." } }, "parameters": { "PrinterId": { "name": "printer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "JobId": { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Chave entre 8 e 128 caracteres `[A-Za-z0-9._:-]`. Na criação, a mesma chave + mesmo payload retorna o job original; a mesma chave + payload diferente retorna HTTP 409. Janela mínima garantida: 24h e pelo menos até a expiração do job; o serviço pode reter a chave por mais tempo. Não reutilize intencionalmente uma chave antiga para outro trabalho.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "example": "pedido-987654-item-1" }, "CorrelationId": { "name": "X-Correlation-Id", "in": "header", "required": false, "description": "Identificador do seu fluxo. Se válido, é propagado. 8–128 caracteres: letras, números, ponto, underscore, dois-pontos e hífen.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{8,128}$" } }, "ComputerStatus": { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ComputerStatus" } }, "PrinterStatus": { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PrinterStatus" } }, "JobStatus": { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PrintJobStatus" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } }, "headers": { "PrintStaVersion": { "schema": { "type": "string" }, "description": "Versão do produto/runtime que respondeu." }, "PrintStaApiVersion": { "schema": { "type": "string" }, "description": "Versão do contrato público (v1)." }, "PrintStaRequestId": { "schema": { "type": "string" }, "description": "ID único gerado pelo Print STA para esta requisição." }, "PrintStaCorrelationId": { "schema": { "type": "string" }, "description": "ID de correlação recebido em X-Correlation-Id ou gerado pelo Print STA." } }, "responses": { "Error": { "description": "Erro padronizado. Use `code` para lógica de integração e preserve request_id/correlation_id no suporte.", "headers": { "X-Print-STA-Version": { "$ref": "#/components/headers/PrintStaVersion" }, "X-Print-STA-API-Version": { "$ref": "#/components/headers/PrintStaApiVersion" }, "X-Print-STA-Request-Id": { "$ref": "#/components/headers/PrintStaRequestId" }, "X-Print-STA-Correlation-Id": { "$ref": "#/components/headers/PrintStaCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalidKey": { "value": { "contract": "print_sta_api_error_v1", "code": "API_KEY_INVALID", "message": "API Key inválida, revogada ou expirada.", "status": 401, "retryable": false, "request_id": "req_abc123456789", "correlation_id": "cor_checkout_001" } }, "idemConflict": { "value": { "contract": "print_sta_api_error_v1", "code": "PRINT_STA_JOB_IDEMPOTENCY_CONFLICT", "message": "Idempotency-Key já usada com conteúdo diferente.", "status": 409, "retryable": false, "request_id": "req_def123456789", "correlation_id": "cor_checkout_001" } } } } } } }, "schemas": { "LogicalEnvironment": { "type": "string", "enum": [ "test", "live" ], "description": "Ambiente lógico isolado da API Key e dos recursos." }, "ApiKeyScope": { "type": "string", "enum": [ "account:read", "computers:read", "computers:write", "printers:read", "jobs:read", "jobs:create", "jobs:cancel", "jobs:retry", "webhooks:read", "webhooks:write" ] }, "AccountStatus": { "type": "string", "enum": [ "active", "suspended", "closed" ] }, "ComputerStatus": { "type": "string", "enum": [ "pending", "online", "offline", "disabled", "revoked" ] }, "PrinterStatus": { "type": "string", "enum": [ "online", "offline", "disabled", "removed" ] }, "PrintJobStatus": { "type": "string", "enum": [ "created", "queued", "leased", "accepted_by_agent", "sent_to_spooler", "spooler_completed", "failed", "manual_review", "cancelled", "expired" ], "description": "Estado oficial do trabalho. Fluxo normal da API pública: queued → leased → accepted_by_agent → sent_to_spooler → spooler_completed. Estados laterais: failed, manual_review, cancelled e expired. `created` existe no contrato interno/compatibilidade; a criação pela API pública já nasce em `queued`." }, "PrintJobRetryState": { "type": "string", "enum": [ "none", "scheduled", "submitted", "completed", "exhausted", "manual_review" ] }, "PrintJobFailureClass": { "type": "string", "enum": [ "temporary", "permanent", "ambiguous" ] }, "WebhookEventType": { "type": "string", "enum": [ "job.created", "job.queued", "job.leased", "job.accepted_by_agent", "job.sent_to_spooler", "job.spooler_completed", "job.failed", "job.manual_review", "job.cancelled", "job.expired", "computer.registered", "computer.pending", "computer.online", "computer.offline", "computer.disabled", "computer.revoked", "printer.detected", "printer.online", "printer.offline", "printer.removed", "printer.disabled", "printer.updated", "webhook.test" ] }, "WebhookStatus": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "WebhookDeliveryStatus": { "type": "string", "enum": [ "pending", "delivering", "retry_scheduled", "delivered", "dead_letter", "cancelled" ] }, "Account": { "type": "object", "required": [ "contract", "account_id", "name", "slug", "status", "environment", "environment_enabled", "virtual_printers_only", "created_at" ], "properties": { "contract": { "const": "print_sta_api_account_v1" }, "account_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "$ref": "#/components/schemas/AccountStatus" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "environment_enabled": { "type": "boolean" }, "virtual_printers_only": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Computer": { "type": "object", "required": [ "contract", "computer_id", "friendly_code", "environment", "name", "status", "created_at", "updated_at" ], "properties": { "contract": { "const": "print_sta_device_v1" }, "computer_id": { "type": "string", "format": "uuid" }, "friendly_code": { "type": "string", "example": "PSTD-76C74E14F0" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "name": { "type": "string" }, "hostname": { "type": "string" }, "operating_system": { "type": "string" }, "agent_version": { "type": "string" }, "installer_version": { "type": "string" }, "status": { "$ref": "#/components/schemas/ComputerStatus" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Printer": { "type": "object", "required": [ "contract", "printer_id", "printer_code", "computer_id", "computer_name", "environment", "name", "is_default", "is_virtual", "is_test", "enabled", "status", "updated_at" ], "properties": { "contract": { "const": "print_sta_printer_v1" }, "printer_id": { "type": "string", "format": "uuid" }, "printer_code": { "type": "string" }, "computer_id": { "type": "string", "format": "uuid" }, "computer_name": { "type": "string" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "name": { "type": "string" }, "driver": { "type": [ "string", "null" ] }, "port": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "is_virtual": { "type": "boolean" }, "is_test": { "type": "boolean" }, "enabled": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/PrinterStatus" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ComputerPage": { "type": "object", "required": [ "items", "count", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Computer" } }, "count": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "PrinterPage": { "type": "object", "required": [ "items", "count", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Printer" } }, "count": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "PrintJob": { "type": "object", "required": [ "contract", "job_id", "printer_id", "environment", "content_type", "content_hash", "content_size_bytes", "copies", "status", "attempt_count", "retry_count", "max_auto_retries", "retry_state", "created_at", "updated_at", "expires_at", "duration_ms", "is_final", "can_cancel", "can_retry" ], "properties": { "contract": { "const": "print_sta_job_v1" }, "job_id": { "type": "string", "format": "uuid" }, "printer_id": { "type": "string", "format": "uuid" }, "printer_code": { "type": "string" }, "printer_name": { "type": "string" }, "computer_name": { "type": "string" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "external_id": { "type": "string", "maxLength": 120 }, "title": { "type": "string", "maxLength": 160 }, "content_type": { "type": "string", "enum": [ "pdf", "raw", "text" ] }, "content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 hexadecimal do conteúdo." }, "content_size_bytes": { "type": "integer", "minimum": 1 }, "copies": { "type": "integer", "minimum": 1, "maximum": 20 }, "status": { "$ref": "#/components/schemas/PrintJobStatus" }, "attempt_count": { "type": "integer", "minimum": 0 }, "retry_count": { "type": "integer", "minimum": 0 }, "max_auto_retries": { "type": "integer", "minimum": 1, "maximum": 10 }, "retry_state": { "$ref": "#/components/schemas/PrintJobRetryState" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "last_attempt_at": { "type": "string", "format": "date-time" }, "last_failure_at": { "type": "string", "format": "date-time" }, "failure_code": { "type": "string" }, "failure_class": { "$ref": "#/components/schemas/PrintJobFailureClass" }, "failure_message": { "type": "string", "maxLength": 240 }, "manual_review_at": { "type": "string", "format": "date-time" }, "spooler_provider": { "type": "string" }, "spooler_job_id": { "type": "string", "maxLength": 128 }, "spooler_submitted_at": { "type": "string", "format": "date-time" }, "spooler_completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "cancelled_at": { "type": "string", "format": "date-time" }, "cancellation_reason": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "integer", "minimum": 0 }, "is_final": { "type": "boolean", "description": "true somente para spooler_completed, cancelled ou expired no contrato atual." }, "can_cancel": { "type": "boolean" }, "can_retry": { "type": "boolean" } }, "additionalProperties": false, "description": "Representação pública real de um trabalho. Propriedades sem valor podem ser omitidas pelo backend." }, "PrintJobPage": { "type": "object", "required": [ "items", "count", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrintJob" } }, "count": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "JobHistoryDetails": { "type": "object", "properties": { "reason": { "type": "string" }, "failure_code": { "type": "string" }, "failure_class": { "type": "string" }, "retry_delay_seconds": { "type": [ "string", "integer" ] }, "spooler_provider": { "type": "string" }, "physical_print_confirmed": { "type": [ "string", "boolean" ] } }, "additionalProperties": false }, "JobHistoryEvent": { "type": "object", "required": [ "event_id", "event_type", "outcome", "created_at" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "previous_status": { "$ref": "#/components/schemas/PrintJobStatus" }, "new_status": { "$ref": "#/components/schemas/PrintJobStatus" }, "outcome": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "details": { "$ref": "#/components/schemas/JobHistoryDetails" } }, "additionalProperties": false }, "PrintJobDetail": { "allOf": [ { "$ref": "#/components/schemas/PrintJob" }, { "type": "object", "required": [ "history_contract", "history" ], "properties": { "history_contract": { "const": "print_sta_job_history_v1" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/JobHistoryEvent" } } } } ] }, "TextPrintContent": { "type": "object", "required": [ "type", "encoding", "data" ], "properties": { "type": { "const": "text" }, "encoding": { "const": "utf8" }, "data": { "type": "string", "minLength": 1, "description": "Texto UTF-8 enviado ao provider de texto configurado na impressora." } }, "additionalProperties": false }, "PdfPrintContent": { "type": "object", "required": [ "type", "encoding", "data" ], "properties": { "type": { "const": "pdf" }, "encoding": { "const": "base64" }, "data": { "type": "string", "contentEncoding": "base64", "minLength": 4, "description": "Arquivo PDF inteiro em Base64. O binário deve iniciar com %PDF-." } }, "additionalProperties": false }, "RawPrintContent": { "type": "object", "required": [ "type", "encoding", "data" ], "properties": { "type": { "const": "raw" }, "encoding": { "const": "base64" }, "data": { "type": "string", "contentEncoding": "base64", "minLength": 4, "description": "Bytes RAW/ESC-POS em Base64; requer impressora/provider compatível." } }, "additionalProperties": false }, "PrintContent": { "oneOf": [ { "$ref": "#/components/schemas/TextPrintContent" }, { "$ref": "#/components/schemas/PdfPrintContent" }, { "$ref": "#/components/schemas/RawPrintContent" } ], "discriminator": { "propertyName": "type" } }, "CreatePrintJobRequest": { "type": "object", "required": [ "printer_id", "content" ], "properties": { "printer_id": { "type": "string", "format": "uuid" }, "content": { "$ref": "#/components/schemas/PrintContent" }, "copies": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 }, "external_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "expires_at": { "type": "string", "format": "date-time", "description": "Opcional. Se omitido, expira em 24h. Valor deve ficar entre mais de 1 minuto e no máximo 7 dias a partir da criação." } }, "additionalProperties": false }, "CancelJobRequest": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 240 } }, "additionalProperties": false }, "RetryJobRequest": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 240 } }, "additionalProperties": false }, "Webhook": { "type": "object", "required": [ "contract", "webhook_id", "account_id", "environment", "name", "url", "status", "events", "secret_hint", "secret_version", "created_at", "updated_at" ], "properties": { "contract": { "const": "print_sta_webhook_v1" }, "webhook_id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "$ref": "#/components/schemas/WebhookStatus" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "secret_hint": { "type": "string", "minLength": 4, "maxLength": 4 }, "secret_version": { "type": "integer", "minimum": 1 }, "last_success_at": { "type": "string", "format": "date-time" }, "last_failure_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "writeOnly": true, "description": "Só aparece em criação/rotação. Guarde imediatamente." }, "displayed_once": { "type": "boolean" } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "required": [ "delivery_id", "webhook_id", "event_id", "event_type", "status", "attempt_count", "max_attempts", "created_at" ], "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "webhook_name": { "type": "string" }, "event_id": { "type": "string", "format": "uuid" }, "event_type": { "$ref": "#/components/schemas/WebhookEventType" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempt_count": { "type": "integer", "minimum": 0 }, "max_attempts": { "type": "integer", "minimum": 1, "default": 6 }, "next_attempt_at": { "type": "string", "format": "date-time" }, "last_attempt_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": "string", "format": "date-time" }, "last_http_status": { "type": "integer", "minimum": 100, "maximum": 599 }, "failure_code": { "type": "string" }, "failure_message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "WebhookListData": { "type": "object", "required": [ "items", "deliveries", "available_events" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available_events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } } }, "additionalProperties": false }, "WebhookDeleteResult": { "type": "object", "required": [ "webhook_id", "status", "delete_replayed" ], "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "status": { "const": "deleted" }, "delete_replayed": { "type": "boolean" }, "cancelled_deliveries": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "WebhookTestResult": { "type": "object", "required": [ "delivery_id", "event_id", "webhook_id", "status", "product_version", "api_contract_version", "event_schema_version" ], "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "product_version": { "type": "string" }, "api_contract_version": { "type": "string" }, "event_schema_version": { "type": "string" }, "delivery": { "$ref": "#/components/schemas/WebhookDeliveryBatchResult" } }, "additionalProperties": false }, "WebhookRetryResult": { "type": "object", "required": [ "delivery_id", "status", "attempt_count", "max_attempts", "next_attempt_at" ], "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempt_count": { "type": "integer" }, "max_attempts": { "type": "integer" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "delivery": { "$ref": "#/components/schemas/WebhookDeliveryBatchResult" } }, "additionalProperties": false }, "WebhookContextRequest": { "type": "object", "required": [ "account_public_id", "environment" ], "properties": { "account_public_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" } }, "additionalProperties": false }, "CreateWebhookRequest": { "type": "object", "required": [ "account_public_id", "environment", "name", "url", "events" ], "properties": { "account_public_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "type": "array", "minItems": 1, "maxItems": 30, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } } }, "additionalProperties": false }, "UpdateWebhookRequest": { "type": "object", "required": [ "account_public_id", "environment", "webhook_id" ], "properties": { "account_public_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "webhook_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 100 }, "url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "paused", null ] }, "events": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 30, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "rotate_secret": { "type": "boolean", "default": false } }, "additionalProperties": false }, "DeleteWebhookRequest": { "type": "object", "required": [ "account_public_id", "environment", "webhook_id", "reason" ], "properties": { "account_public_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "webhook_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 5, "maxLength": 240 } }, "additionalProperties": false }, "TestWebhookRequest": { "type": "object", "required": [ "account_public_id", "environment", "webhook_id" ], "properties": { "account_public_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "webhook_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "RetryWebhookRequest": { "type": "object", "required": [ "account_public_id", "environment", "delivery_id", "reason" ], "properties": { "account_public_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "delivery_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 3, "maxLength": 240 } }, "additionalProperties": false }, "WebhookResource": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "job", "computer", "printer", "webhook" ] }, "id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "WebhookJobData": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "printer_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/PrintJobStatus" }, "previous_status": { "$ref": "#/components/schemas/PrintJobStatus" }, "state_event_id": { "type": "string", "format": "uuid" }, "state_event_type": { "type": "string" }, "correlation_id": { "type": "string" } }, "additionalProperties": false }, "WebhookEvent": { "type": "object", "required": [ "contract", "product_version", "api_contract_version", "event_schema_version", "event_id", "event_type", "occurred_at", "account_id", "environment", "resource", "data" ], "properties": { "contract": { "const": "print_sta_webhook_event_v1" }, "product_version": { "type": "string" }, "api_contract_version": { "const": "v1" }, "event_schema_version": { "const": "v1" }, "event_id": { "type": "string", "format": "uuid" }, "event_type": { "$ref": "#/components/schemas/WebhookEventType" }, "occurred_at": { "type": "string", "format": "date-time" }, "account_id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/LogicalEnvironment" }, "resource": { "$ref": "#/components/schemas/WebhookResource" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/WebhookJobData" }, { "$ref": "#/components/schemas/WebhookComputerData" }, { "$ref": "#/components/schemas/WebhookPrinterData" }, { "$ref": "#/components/schemas/WebhookTestData" } ] } }, "additionalProperties": false }, "AccountEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_ACCOUNT_OK" }, "message": { "type": "string", "example": "Conta carregada." }, "data": { "$ref": "#/components/schemas/Account" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "ComputersEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_COMPUTERS_OK" }, "message": { "type": "string", "example": "Computadores carregados." }, "data": { "$ref": "#/components/schemas/ComputerPage" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "PrintersEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_PRINTERS_OK" }, "message": { "type": "string", "example": "Impressoras carregadas." }, "data": { "$ref": "#/components/schemas/PrinterPage" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "JobEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_JOB_CREATED" }, "message": { "type": "string", "example": "Trabalho criado." }, "data": { "$ref": "#/components/schemas/PrintJob" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "JobListEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_JOBS_OK" }, "message": { "type": "string", "example": "Trabalhos carregados." }, "data": { "$ref": "#/components/schemas/PrintJobPage" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "JobDetailEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_JOB_OK" }, "message": { "type": "string", "example": "Trabalho carregado." }, "data": { "$ref": "#/components/schemas/PrintJobDetail" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "WebhookListEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "WEBHOOKS_OK" }, "message": { "type": "string", "example": "Webhooks carregados." }, "data": { "$ref": "#/components/schemas/WebhookListData" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "WebhookEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "WEBHOOK_CREATED" }, "message": { "type": "string", "example": "Webhook criado." }, "data": { "$ref": "#/components/schemas/Webhook" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "WebhookDeleteEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "WEBHOOK_DELETED" }, "message": { "type": "string", "example": "Webhook excluído." }, "data": { "$ref": "#/components/schemas/WebhookDeleteResult" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "WebhookTestEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "WEBHOOK_TEST_COMPLETED" }, "message": { "type": "string", "example": "Teste de Webhook processado." }, "data": { "$ref": "#/components/schemas/WebhookTestResult" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "WebhookRetryEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "WEBHOOK_RETRY_PROCESSED" }, "message": { "type": "string", "example": "Retry do Webhook processado." }, "data": { "$ref": "#/components/schemas/WebhookRetryResult" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "PrinterTestData": { "type": "object", "required": [ "test_request_id", "printer_id", "printer_code", "status", "execution" ], "properties": { "test_request_id": { "type": "string", "format": "uuid" }, "printer_id": { "type": "string", "format": "uuid" }, "printer_code": { "type": "string" }, "status": { "const": "accepted" }, "execution": { "const": "pending_agent" } }, "additionalProperties": false, "description": "Resposta real da solicitação de teste. O teste é assíncrono e fica pendente para o Agent." }, "PrinterTestEnvelope": { "type": "object", "required": [ "code", "message", "data", "request_id", "correlation_id" ], "properties": { "code": { "type": "string", "example": "API_PRINTER_TEST_ACCEPTED" }, "message": { "type": "string", "example": "Teste de impressora aceito." }, "data": { "$ref": "#/components/schemas/PrinterTestData" }, "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9]+$", "example": "req_1c3b62d1b5884ce9984a2f21012d8091" }, "correlation_id": { "type": "string", "example": "cor_checkout_20260814_001" } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "required": [ "contract", "code", "message", "status", "retryable", "request_id", "correlation_id" ], "properties": { "contract": { "const": "print_sta_api_error_v1" }, "code": { "type": "string", "example": "PRINT_STA_JOB_IDEMPOTENCY_CONFLICT" }, "message": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "retryable": { "type": "boolean" }, "request_id": { "type": "string" }, "correlation_id": { "type": "string" } }, "additionalProperties": false }, "WebhookComputerData": { "type": "object", "required": [ "computer_id", "friendly_code", "name", "status" ], "properties": { "computer_id": { "type": "string", "format": "uuid" }, "friendly_code": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/ComputerStatus" }, "agent_version": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "WebhookPrinterData": { "type": "object", "required": [ "printer_id", "friendly_code", "name", "status", "is_default", "is_virtual", "is_test" ], "properties": { "printer_id": { "type": "string", "format": "uuid" }, "friendly_code": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/PrinterStatus" }, "driver": { "type": [ "string", "null" ] }, "port": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "is_virtual": { "type": "boolean" }, "is_test": { "type": "boolean" } }, "additionalProperties": false }, "WebhookTestData": { "type": "object", "required": [ "message", "webhook_id" ], "properties": { "message": { "type": "string" }, "webhook_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "WebhookDeliveryProcessResult": { "type": "object", "required": [ "delivery_id", "event_type" ], "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "event_type": { "$ref": "#/components/schemas/WebhookEventType" }, "http_status": { "type": "integer", "minimum": 100, "maximum": 599 }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempt_count": { "type": "integer", "minimum": 0 }, "max_attempts": { "type": "integer", "minimum": 1 }, "next_attempt_at": { "type": "string", "format": "date-time" }, "replayed": { "type": "boolean" }, "error_code": { "type": "string" } }, "additionalProperties": false }, "WebhookDeliveryBatchResult": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryProcessResult" } } }, "additionalProperties": false } } }, "x-print-sta-docs-version": "2.0.27", "x-print-sta-product-version": "2.0.32", "x-print-sta-schema-version": 23, "x-print-sta-api-contract-version": "v1", "x-print-sta-idempotency": { "minimum_retention_hours": 24, "retained_at_least_until_job_expiry": true, "may_be_retained_longer": true }, "x-print-sta-rate-limits": { "account_per_minute": 120, "computers_list_per_minute": 120, "printers_list_per_minute": 120, "printer_test_per_minute": 20, "jobs_read_per_minute": 120, "jobs_create_per_minute": 60, "jobs_cancel_per_minute": 60, "jobs_retry_per_minute": 60, "webhook_create_per_minute": 30, "webhook_update_per_minute": 60, "webhook_test_per_minute": 30, "webhook_retry_per_minute": 30 }, "x-print-sta-effective-limits": { "max_public_content_bytes": 10485760, "max_json_request_bytes": 16000000, "max_copies": 20, "default_job_expiry_hours": 24, "max_job_expiry_days": 7, "max_page_size": 100, "webhook_timeout_seconds": 10, "webhook_max_attempts": 6 }, "x-print-sta-canonical-api-url": "https://api.print-sta.com.br/v1", "externalDocs": { "description": "Print STA Developers", "url": "https://print-sta.netlify.app/docs/" } }