{ "openapi": "3.1.0", "info": { "title": "PrintBee - Webhooks", "description": "O PrintBee **envia** requisições HTTP POST para as URLs cadastradas nos CustomerWebhooks quando eventos ocorrem. **Não existe endpoint no PrintBee** — o sistema faz POST para a URL que você cadastrou.\n\nCadastre seus webhooks em `POST /api/v1/Customers/{customerId}/Webhooks` informando a URL (HTTPS) e os tipos de eventos desejados no campo `eventTypes` (`[]` = todos os eventos).\n\n## Envelope padrão\n\nTodo webhook outbound do PrintBee é entregue dentro do MESMO envelope, qualquer que seja o evento:\n\nO topo contém somente metadados de entrega. Identificadores de negócio, como `orderId`, ficam dentro de `data`. Por decisão do dono em 06/08/2026, esta reorganização foi aplicada antes de existir integrador consumidor e `payloadVersion` permaneceu 1.\n\n```json\n{\n \"eventType\": \"order.created\",\n \"occurredAt\": \"2026-07-25T14:32:10Z\",\n \"webhookSentId\": \"3f2504e0-4f89-11d3-9a0c-0305e82c3301\",\n \"payloadVersion\": 1,\n \"data\": {\n \"orderId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"...\": \"específico do evento\"\n }\n}\n```\n\n| Campo | Descrição |\n|---|---|\n| `eventType` | Tipo do evento — igual ao header `X-Webhook-Event` |\n| `occurredAt` | Data/hora UTC em que o evento ocorreu no PrintBee |\n| `webhookSentId` | Identificador do envio — igual ao header `X-Webhook-Id`; **estável entre as tentativas de retry do MESMO envio** (use para deduplicar) |\n| `payloadVersion` | Versão do contrato de `data` para este `eventType`; incrementada apenas em mudanças breaking |\n| `data` | Corpo específico do evento e seus identificadores de negócio — `orderId` é documentado no schema de cada evento |\n\n## Headers enviados em cada requisição\n\n| Header | Descrição |\n|--------|----------|\n| X-Webhook-Event | Tipo do evento (ex: order.tracking) — igual a `eventType` no corpo |\n| X-Webhook-Id | Identificador único do envio (GUID) — igual a `webhookSentId`; repete entre retries do mesmo envio |\n| X-Webhook-Timestamp | Timestamp Unix (segundos) no momento do envio HTTP |\n| X-Webhook-Signature | Assinatura HMAC-SHA256 (quando secret configurado): `t={timestamp},v1={hash}` |\n\n## Validando a assinatura (`X-Webhook-Signature`)\n\nQuando um secret é configurado no cadastro do webhook (gerado pelo PrintBee, formato `whsec_...`), toda requisição inclui `X-Webhook-Signature: t={timestamp},v1={hash}`. Para validar no seu servidor:\n\n1. Extraia `timestamp` e `hash` do header.\n2. Monte a string `{timestamp}.{corpo bruto da requisição}` — o corpo EXATO recebido em UTF-8, sem re-serializar.\n3. Calcule HMAC-SHA256 dessa string usando o secret como chave; compare o resultado (hex, minúsculo) com `hash` em tempo constante.\n4. Rejeite a requisição se a assinatura não bater. Opcionalmente, rejeite `timestamp` muito antigo para mitigar replay — o PrintBee não impõe uma janela de validade, a decisão é do seu endpoint.\n\n## Resposta esperada\n\nRetorne qualquer status **2xx** para confirmar o recebimento. Qualquer outra resposta (ou timeout) é tratada como falha e pode gerar retentativa — ver política abaixo.\n\n## Política de retry\n\nAté **10 tentativas** por envio, com backoff escalonado (~8 dias de janela total):\n\n| Tentativa | Atraso desde a tentativa anterior |\n|---|---|\n| 2 | 5 min |\n| 3 | 15 min |\n| 4 | 30 min |\n| 5 | 1 h |\n| 6 | 3 h |\n| 7 | 6 h |\n| 8 | 12 h |\n| 9 | 1 dia |\n| 10 | 2 dias |\n\nApós a 10ª tentativa sem sucesso, o envio é marcado como `Failed` e não é mais retentado.\n\n**Fail-fast (sem retry):** respostas HTTP 4xx — exceto `408`, `425` e `429`, tratadas como transientes — e falhas permanentes de conexão (certificado TLS inválido, DNS que não resolve) marcam o envio como `Failed` IMEDIATAMENTE, sem gastar as 10 tentativas. A causa normalmente é configuração incorreta do seu endpoint e só se resolve com intervenção manual.\n\n## Idempotência\n\nTrate toda entrega como potencialmente duplicada:\n- `webhookSentId` (= header `X-Webhook-Id`) é o MESMO em todas as tentativas de retry de um mesmo envio — grave os `webhookSentId` já processados e ignore repetições.\n- O PrintBee também deduplica no lado do servidor eventos idênticos (mesmo webhook + tipo + payload) disparados dentro de uma janela curta (60 s por padrão), mas isso não substitui a deduplicação no seu lado — falhas de rede podem fazer seu endpoint receber o mesmo `webhookSentId` mais de uma vez mesmo após você já ter respondido 2xx (ex.: a resposta se perdeu antes de chegar ao PrintBee).\n\n## Jornada: Pedido vindo da sua loja (Nuvemshop ou WooCommerce)\n\nCom a loja conectada, o pedido chega por webhook da plataforma. A API confere a assinatura, responde rápido e processa em segundo plano até virar rascunho para a sua equipe.\n\n![Diagrama de sequência do pedido vindo da loja: a loja envia POST /api/Webhooks/Nuvemshop/orders (ou /api/Webhooks/WooCommerce/orders); a API confere a assinatura HMAC-SHA256, responde 200 OK e enfileira o webhook; o processamento cria o rascunho e deduplica, resolvendo o cliente pela conexão registrada; o rascunho fica pronto no portal, onde sua equipe mapeia, define o frete e converte.](/openapi/diagrams/jornada-pedido-loja.svg)\n\nA vinculação do rascunho ao cliente é sempre resolvida pela conexão de loja cadastrada no portal — nunca pelo conteúdo do webhook recebido. Na Nuvemshop, só `order/paid` gera pedido: `order/created` é reconhecido e ignorado. Assinatura inválida devolve `401` e nada é gravado — a plataforma reenvia por conta própria; uma falha depois desse ponto marca o webhook como Erro e o reprocessamento é feito pelo portal.\n\n## Jornada: Quando a entrega de um webhook falha\n\nFalha temporária é reenviada com espera crescente; falha definitiva não é reenviada. Por isso o seu endpoint deve responder 2xx assim que receber o evento e processar depois.\n\n![Diagrama de sequência da falha de entrega: a plataforma envia o evento assinado com X-Webhook-Signature; o endpoint responde 500 Internal Server Error; a plataforma classifica como falha temporária (tentativa 1 de 10), reenvia em 5 minutos e segue com esperas crescentes até a décima tentativa, quando a entrega é marcada como Falhou; respostas 404 ou 401 são falha definitiva e param o reenvio na hora.](/openapi/diagrams/jornada-webhook-falha.svg)\n\nOs intervalos entre as tentativas estão em **Política de retry**, e as respostas que interrompem o reenvio já na primeira tentativa, em **Fail-fast (sem retry)**. Depois da 10ª tentativa não há novo reenvio automático — o reprocessamento é manual, pelo portal. Para não acumular retentativa por processamento lento, responda 2xx assim que receber o evento e trate o recebimento como idempotente pelo `webhookSentId` (header `X-Webhook-Id`).", "version": "1.6.0", "contact": { "name": "Suporte PrintBee", "url": "https://api.printbee.com.br" } }, "webhooks": { "order.created": { "post": { "tags": [ "Webhooks" ], "summary": "Pedido Criado", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando um pedido é **criado com sucesso** (inclusive pedidos originados de integração, após a conversão do rascunho em pedido real).\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Pedido criado\" nos tipos de eventos.\n\n**Mutuamente exclusivo com `order.status_changed`:** a criação do pedido dispara APENAS este evento. A partir daí, cada mudança de status subsequente é reportada por `order.status_changed` — este evento não dispara novamente para o mesmo pedido.\n\n**`orderNSU` é TEXTO, não número:** formato público do pedido — prefixo fixo `BEE` + NSU sequencial com 8 dígitos (ex.: `BEE00123457`).\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `OrderCreatedWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookOrderCreated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreatedEnvelope" }, "example": { "eventType": "order.created", "occurredAt": "2026-07-25T14:32:10Z", "webhookSentId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301", "payloadVersion": 1, "data": { "orderId": "550e8400-e29b-41d4-a716-446655440000", "orderNSU": "BEE00123457", "status": "Open", "amount": 249.9, "createdAt": "2026-07-25T14:32:09Z", "quantityItems": 2 } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "order.created", "x-webhook-payload-schema": "OrderCreatedEnvelope" } }, "order.status_changed": { "post": { "tags": [ "Webhooks" ], "summary": "Status do Pedido Alterado", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** a cada **mudança de status do pedido** após a criação — pagamento recebido, produção, despacho, trânsito, entregue, atendido, devolvido, extraviado, cancelado etc.\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Status do pedido alterado\" nos tipos de eventos.\n\n**Mutuamente exclusivo com `order.created`:** a criação do pedido NÃO dispara este evento — apenas transições de status posteriores à criação.\n\n**`data.previousStatus` pode vir `null`.** Duas rotinas internas do PrintBee podem gerar este evento para a mesma transição (uma delas não tem acesso ao status anterior); a deduplicação do servidor funde as duas em um único envio, mas qual das duas prevalece na corrida não é garantido — não dependa de `previousStatus` estar sempre preenchido, use `newStatus` como fonte confiável.\n\n**⚠️ Atenção ao formato de `status` — diferente de `order.tracking`:** aqui `previousStatus`/`newStatus` vêm no **nome do enum em C#** (`Open`, `WaitingPayment`, `PaymentReceived`, `ProductionQueue`, `Production`, `ProductionCompleted`, `WaitingFinalPayment`, `Dispatch`, `Transit`, `Delivered`, `Attended`, `Lost`, `Returned`, `Canceled`). Já em `order.tracking` (`data.tracking.orderStatus`) o MESMO status vem em MAIÚSCULAS sem separadores (ex.: `TRANSIT`, `PAYMENTRECEIVED`). É uma inconsistência conhecida do contrato atual — trate os dois formatos separadamente se sua integração consome ambos os eventos.\n\n**`orderNSU` é TEXTO, não número:** formato público do pedido — prefixo fixo `BEE` + NSU sequencial com 8 dígitos (ex.: `BEE00123457`).\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `OrderStatusChangedWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookOrderStatusChanged", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusChangedEnvelope" }, "example": { "eventType": "order.status_changed", "occurredAt": "2026-07-25T18:05:44Z", "webhookSentId": "9b74c1a2-3e4f-4d3e-8a2b-1234567890ab", "payloadVersion": 1, "data": { "orderId": "550e8400-e29b-41d4-a716-446655440000", "previousStatus": "Dispatch", "newStatus": "Transit", "orderNSU": "BEE00123457", "amount": 249.9, "updatedAt": "2026-07-25T18:05:44Z" } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "order.status_changed", "x-webhook-payload-schema": "OrderStatusChangedEnvelope" } }, "order.tracking": { "post": { "tags": [ "Webhooks" ], "summary": "Rastreio do Pedido", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando o **status do ENVIO (shipment/transportadora)** muda — não a cada atualização do pedido em geral. Cobre transições como: postado, em trânsito, entregue, extraviado, devolução.\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Webhook de rastreio de pedido\" nos tipos de eventos.\n\n**Mudança de comportamento (26/07/2026):** este evento passou a disparar **somente** quando o status do ENVIO (`ShipmentStatus`) muda — antes bastava qualquer atualização do pedido (ex.: só o código de rastreio mudando). E passou a disparar mesmo quando o envio avança **sem** o pedido mudar de status (ex.: `Posted → InTransit` com o pedido já em `Transit`) — antes esse caso não gerava evento nenhum, justamente o dado que o integrador espera receber.\n\n**`data` traz o pedido no primeiro nível + o rastreio em `data.tracking`.** Os campos do PEDIDO (`orderNSU`, `status`, `amount`, `quantityItems`, `createdAt`) ficam no mesmo nível e com os mesmos nomes de `order.created`/`order.status_changed`, para o integrador ler o pedido do mesmo jeito em qualquer evento. `data.tracking` (`OrderTrackingModel`) traz o rastreio (`trackingCode`, `trackingUrl`, `shipmentStatus`, `carrierName`, `serviceName`) e o destinatário/endereço de entrega — e, por ser ADITIVO (nenhum campo foi removido), também repete os dados do pedido no seu próprio nível (`orderNSU`, `amount`, `orderStatus`, ...). Ou seja, os dados do pedido aparecem DUAS vezes no payload (`data.*` e `data.tracking.*`) — redundância intencional para não quebrar integrações que já liam `data.tracking.*`. `data.orderNSU` e `data.tracking.orderNSU` são o MESMO pedido, MESMO formato (texto, `BEE` + 8 dígitos, ex.: `\"BEE00123457\"`) — use qualquer um dos dois.\n\n**⚠️ `status` do pedido em dois casings DIFERENTES no mesmo payload:** `data.status` vem no nome do enum em C# (ex.: `Transit`, igual a `order.status_changed`), enquanto `data.tracking.orderStatus` vem em MAIÚSCULAS sem separadores (ex.: `TRANSIT`). Mesmo valor, dois formatos — não é engano, é a forma como os dois modelos serializam hoje; trate cada caminho separadamente.\n\n**⚠️ Breaking change intencional (24/07/2026):** os campos de `data.tracking.*` passaram de PascalCase (`OrderNSU`, `OrderStatus`, `TrackingCode`, ...) para **camelCase** (`orderNSU`, `orderStatus`, `trackingCode`, ...) — correção de um bug em que o payload saía com casing híbrido (envelope em camelCase, `data.tracking` em PascalCase). Se sua integração ainda lê os nomes antigos em PascalCase, atualize o parser.\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `OrderTrackingWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookOrderTracking", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderTrackingEnvelope" }, "example": { "eventType": "order.tracking", "occurredAt": "2026-07-25T18:05:44Z", "webhookSentId": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "payloadVersion": 1, "data": { "orderId": "550e8400-e29b-41d4-a716-446655440000", "orderNSU": "BEE00123457", "status": "Transit", "amount": 249.9, "quantityItems": 2, "createdAt": "2026-07-20T10:30:00Z", "tracking": { "orderId": "550e8400-e29b-41d4-a716-446655440000", "orderNSU": "BEE00123457", "customerName": "Cliente Exemplo Ltda", "amount": 249.9, "orderStatus": "TRANSIT", "saleDate": "2026-07-20", "deliveryDate": "2026-08-01", "purchaseOrder": "PO-2026-001", "quantityItems": 2, "createdAt": "2026-07-20T10:30:00Z", "recipientName": "João Silva", "recipientTaxId": "123.456.789-00", "recipientPhone": "(11) 99999-9999", "recipientEmail": "joao@email.com", "zipCode": "01310-100", "street": "Av. Paulista", "number": "1000", "complement": "Sala 101", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "BR", "fullAddress": "Av. Paulista, 1000, Sala 101, Bela Vista, São Paulo, SP, 01310-100, BR", "trackingCode": "BR123456789BR", "trackingUrl": "https://correios.com.br/rastreio/BR123456789BR", "shipmentStatus": "INTRANSIT", "carrierName": "Correios", "serviceName": "SEDEX", "freightCost": 24.9, "postedAt": "2026-07-24T14:00:00Z", "deliveredAt": null } } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "order.tracking", "x-webhook-payload-schema": "OrderTrackingEnvelope" } }, "integration_order.received": { "post": { "tags": [ "Webhooks" ], "summary": "Pedido de Integração Recebido", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando um pedido chega de uma loja/API de integração e vira um rascunho (`CustomerOrderDraft`) — ainda ANTES de existir um pedido PrintBee de verdade.\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Pedido de integração recebido\" nos tipos de eventos.\n\n**NÃO é mutuamente exclusivo com `integration_order.converted`.** São momentos distintos do MESMO pedido — quem integra normalmente quer os dois: este avisa que o rascunho chegou, o outro avisa que virou pedido real.\n\n`data.orderId` e `data.orderNSU` vêm `null` — ainda não há pedido PrintBee vinculado. O elo de correlação é `data.draftId` (+ `data.platform`/`data.externalId`).\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `IntegrationOrderWebhookData` — mesmo shape dos outros 4 eventos `integration_order.*`, com preenchimento diferente por evento.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookIntegrationOrderReceived", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOrderReceivedEnvelope" }, "example": { "eventType": "integration_order.received", "occurredAt": "2026-07-25T09:10:00Z", "webhookSentId": "2a3b4c5d-6e7f-4a5b-8c9d-0e1f2a3b4c60", "payloadVersion": 1, "data": { "draftId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "orderId": null, "orderNSU": null, "status": "Pending", "platform": "Nuvemshop", "externalId": "998877", "convertedAt": null, "failureReason": null } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "integration_order.received", "x-webhook-payload-schema": "IntegrationOrderReceivedEnvelope" } }, "integration_order.converted": { "post": { "tags": [ "Webhooks" ], "summary": "Pedido de Integração Convertido", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando o rascunho de integração é convertido em um pedido PrintBee real.\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Pedido de integração convertido\" nos tipos de eventos.\n\n**NÃO é mutuamente exclusivo com `integration_order.received`** (nem com `order.created`) — a conversão dispara os TRÊS: `integration_order.received` já foi entregue antes; `order.created` dispara junto (a conversão CRIA um pedido real — quem assina só `order.created` também precisa saber); e este evento é o ÚNICO que carrega `draftId` + `orderId` + `orderNSU` juntos, o elo que permite correlacionar o rascunho devolvido na criação via API com o pedido real gerado.\n\n`data.orderId` e `data.orderNSU` (`BEE...`) vêm preenchidos a partir daqui.\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `IntegrationOrderWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookIntegrationOrderConverted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOrderConvertedEnvelope" }, "example": { "eventType": "integration_order.converted", "occurredAt": "2026-07-25T09:15:00Z", "webhookSentId": "3a4b5c6d-7e8f-4a5b-8c9d-0e1f2a3b4c61", "payloadVersion": 1, "data": { "draftId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "orderId": "550e8400-e29b-41d4-a716-446655440000", "orderNSU": "BEE00123457", "status": "Open", "platform": "Nuvemshop", "externalId": "998877", "convertedAt": "2026-07-25T09:15:00Z", "failureReason": null } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "integration_order.converted", "x-webhook-payload-schema": "IntegrationOrderConvertedEnvelope" } }, "integration_order.failed": { "post": { "tags": [ "Webhooks" ], "summary": "Pedido de Integração com Falha", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando a ingestão de um pedido de integração NÃO consegue ser normalizada — o rascunho já nasce em `Failed`.\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Pedido de integração com falha\" nos tipos de eventos.\n\n**Preenche um buraco real do contrato:** antes deste evento existir, quem enviava um pedido pela API e caía numa falha de normalização não recebia notificação NENHUMA — só descobria abrindo o portal. `integration_order.received` nunca dispara nesse caso (o rascunho não nasceu pronto); este evento é o único aviso.\n\n`data.failureReason` traz o motivo da falha (texto livre). `data.orderId`/`data.orderNSU` vêm `null` — não há pedido PrintBee vinculado.\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `IntegrationOrderWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookIntegrationOrderFailed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOrderFailedEnvelope" }, "example": { "eventType": "integration_order.failed", "occurredAt": "2026-07-25T09:10:00Z", "webhookSentId": "4a5b6c7d-8e9f-4a5b-8c9d-0e1f2a3b4c62", "payloadVersion": 1, "data": { "draftId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "orderId": null, "orderNSU": null, "status": "Failed", "platform": "Nuvemshop", "externalId": "998877", "convertedAt": null, "failureReason": "SKU do item 2 não corresponde a nenhum produto mapeado para este canal." } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "integration_order.failed", "x-webhook-payload-schema": "IntegrationOrderFailedEnvelope" } }, "integration_order.discarded": { "post": { "tags": [ "Webhooks" ], "summary": "Pedido de Integração Descartado", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando o cliente descarta o rascunho no portal — estado terminal, não haverá conversão.\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Pedido de integração descartado\" nos tipos de eventos.\n\nSem este evento, quem integra ficaria esperando indefinidamente uma conversão que nunca vai acontecer.\n\n`data.failureReason` vem `null` (não é uma falha — é uma decisão do cliente). `data.orderId`/`data.orderNSU` vêm `null`.\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `IntegrationOrderWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookIntegrationOrderDiscarded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOrderDiscardedEnvelope" }, "example": { "eventType": "integration_order.discarded", "occurredAt": "2026-07-25T11:40:00Z", "webhookSentId": "5a6b7c8d-9e0f-4a5b-8c9d-0e1f2a3b4c63", "payloadVersion": 1, "data": { "draftId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "orderId": null, "orderNSU": null, "status": "Discarded", "platform": "Nuvemshop", "externalId": "998877", "convertedAt": null, "failureReason": null } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "integration_order.discarded", "x-webhook-payload-schema": "IntegrationOrderDiscardedEnvelope" } }, "integration_order.reopened": { "post": { "tags": [ "Webhooks" ], "summary": "Pedido de Integração Reaberto", "security": [], "description": "**O PrintBee envia esta requisição para a URL que você cadastrou** quando um pedido PrintBee que tinha sido gerado por conversão é CANCELADO — o rascunho volta a `Ready` e o vínculo com aquele pedido é desfeito (uma nova conversão vai gerar um pedido NOVO).\n\nCadastre o webhook na [criação/atualização do Webhook em Integração](/customer/integrations/webhooks), selecionando \"Pedido de integração reaberto\" nos tipos de eventos.\n\nÉ o par do `order.status_changed` de cancelamento: sem este evento, o integrador vê o pedido PrintBee cancelado (via `order.status_changed`) e continua achando que o rascunho segue consumido/convertido.\n\n`data.orderId`/`data.orderNSU` vêm `null` — o vínculo com o pedido cancelado foi desfeito de propósito.\n\n**Método:** POST (o PrintBee envia para sua URL)\n**Content-Type:** application/json\n**Body:** Envelope padrão (ver descrição geral da API) com `data` no formato `IntegrationOrderWebhookData`.\n\nHeaders, assinatura, resposta esperada, retry e idempotência: ver descrição geral desta API (topo da página).", "operationId": "webhookIntegrationOrderReopened", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationOrderReopenedEnvelope" }, "example": { "eventType": "integration_order.reopened", "occurredAt": "2026-07-26T08:00:00Z", "webhookSentId": "6a7b8c9d-0e1f-4a5b-8c9d-0e1f2a3b4c64", "payloadVersion": 1, "data": { "draftId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "orderId": null, "orderNSU": null, "status": "Ready", "platform": "Nuvemshop", "externalId": "998877", "convertedAt": null, "failureReason": null } } } } }, "responses": { "2XX": { "$ref": "#/components/responses/WebhookAccepted" } }, "x-webhook-event": "integration_order.reopened", "x-webhook-payload-schema": "IntegrationOrderReopenedEnvelope" } } }, "components": { "schemas": { "WebhookEnvelopeBase": { "type": "object", "description": "Envelope HTTP comum a todos os webhooks outbound do PrintBee. Contém somente metadados de entrega; identificadores de negócio ficam em data.", "properties": { "eventType": { "type": "string", "description": "Tipo do evento — igual ao header X-Webhook-Event." }, "occurredAt": { "type": "string", "format": "date-time", "description": "Data/hora UTC em que o evento ocorreu no PrintBee." }, "webhookSentId": { "type": "string", "format": "uuid", "description": "Identificador do envio — igual ao header X-Webhook-Id. Estável entre as tentativas de retry do mesmo envio; use para deduplicar." }, "payloadVersion": { "type": "integer", "description": "Versão do contrato de data para este eventType; incrementada apenas em mudanças breaking." } }, "required": [ "eventType", "occurredAt", "webhookSentId", "payloadVersion" ] }, "OrderCreatedWebhookData": { "type": "object", "description": "Dados do evento order.created (OrderCreatedWebhookData no backend).", "properties": { "orderId": { "type": [ "string", "null" ], "format": "uuid", "description": "Identificador do pedido PrintBee ao qual o evento pertence. Fica dentro de data; em eventos order.* válidos vem preenchido." }, "orderNSU": { "type": "string", "description": "Numero publico do pedido — prefixo fixo BEE + NSU sequencial com 8 digitos zero-padded (ex.: BEE00123457). TEXTO, nao numero. Renomeado de orderNsu para orderNSU em 26/07/2026 (mesmo tipo/formato, so o nome mudou)." }, "status": { "type": "string", "enum": [ "Open", "WaitingPayment", "PaymentReceived", "ProductionQueue", "Production", "ProductionCompleted", "WaitingFinalPayment", "Dispatch", "Transit", "Delivered", "Attended", "Lost", "Returned", "Canceled" ], "description": "Status do pedido no momento da criacao. Nome do enum em C# (PascalCase) — ver nota sobre casing na descricao do evento." }, "amount": { "type": "number", "description": "Valor total do pedido." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data/hora de criacao do pedido." }, "quantityItems": { "type": "integer", "description": "Quantidade total de itens do pedido." } }, "required": [ "orderId", "orderNSU", "status", "amount", "createdAt", "quantityItems" ] }, "OrderCreatedEnvelope": { "description": "Envelope completo do evento order.created.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "order.created" }, "data": { "$ref": "#/components/schemas/OrderCreatedWebhookData" } }, "required": [ "data" ] } ] }, "OrderStatusChangedWebhookData": { "type": "object", "description": "Dados do evento order.status_changed (OrderStatusChangedWebhookData no backend).", "properties": { "orderId": { "type": [ "string", "null" ], "format": "uuid", "description": "Identificador do pedido PrintBee ao qual o evento pertence. Fica dentro de data; em eventos order.* válidos vem preenchido." }, "previousStatus": { "type": [ "string", "null" ], "enum": [ "Open", "WaitingPayment", "PaymentReceived", "ProductionQueue", "Production", "ProductionCompleted", "WaitingFinalPayment", "Dispatch", "Transit", "Delivered", "Attended", "Lost", "Returned", "Canceled", null ], "description": "Status anterior a transicao. Pode vir null — ver nota na descricao do evento. Nome do enum em C# (PascalCase)." }, "newStatus": { "type": "string", "enum": [ "Open", "WaitingPayment", "PaymentReceived", "ProductionQueue", "Production", "ProductionCompleted", "WaitingFinalPayment", "Dispatch", "Transit", "Delivered", "Attended", "Lost", "Returned", "Canceled" ], "description": "Status resultante da transicao. Nome do enum em C# (PascalCase)." }, "orderNSU": { "type": "string", "description": "Numero publico do pedido — prefixo fixo BEE + NSU sequencial com 8 digitos zero-padded (ex.: BEE00123457). TEXTO, nao numero. Renomeado de orderNsu para orderNSU em 26/07/2026 (mesmo tipo/formato, so o nome mudou)." }, "amount": { "type": "number", "description": "Valor total do pedido." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data/hora UTC da transicao de status." } }, "required": [ "orderId", "newStatus", "orderNSU", "amount", "updatedAt" ] }, "OrderStatusChangedEnvelope": { "description": "Envelope completo do evento order.status_changed.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "order.status_changed" }, "data": { "$ref": "#/components/schemas/OrderStatusChangedWebhookData" } }, "required": [ "data" ] } ] }, "OrderTrackingModel": { "type": "object", "description": "Dados combinados do pedido e do rastreio do envio associado (OrderTrackingModel no backend). Campos serializados em camelCase pelo WebhookPayloadSerializer.", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Identificador unico do pedido." }, "orderNSU": { "type": "string", "description": "Numero publico do pedido — prefixo fixo BEE + 8 digitos zero-padded (ex.: BEE00123457). TEXTO, nao numero. Mesmo pedido e mesmo formato de data.orderNSU (nivel superior do evento order.tracking) — os dois campos sao equivalentes." }, "customerName": { "type": [ "string", "null" ], "description": "Nome ou razao social do cliente." }, "amount": { "type": "number", "description": "Valor total do pedido." }, "orderStatus": { "type": "string", "enum": [ "OPEN", "WAITINGPAYMENT", "PAYMENTRECEIVED", "PRODUCTIONQUEUE", "PRODUCTION", "PRODUCTIONCOMPLETED", "WAITINGFINALPAYMENT", "DISPATCH", "TRANSIT", "DELIVERED", "ATTENDED", "LOST", "RETURNED", "CANCELED" ], "description": "Status atual do pedido — aqui em MAIUSCULAS sem separadores (EnumMember). Diferente do casing usado em order.created/order.status_changed (ver nota na descricao do evento order.status_changed)." }, "saleDate": { "type": "string", "format": "date", "description": "Data do pedido." }, "deliveryDate": { "type": "string", "format": "date", "description": "Previsao de entrega." }, "purchaseOrder": { "type": [ "string", "null" ], "description": "Numero da ordem de compra." }, "quantityItems": { "type": "integer", "description": "Quantidade total de itens do pedido." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora de criacao do pedido." }, "recipientName": { "type": [ "string", "null" ], "description": "Nome do destinatario." }, "recipientTaxId": { "type": [ "string", "null" ], "description": "CPF/CNPJ do destinatario." }, "recipientPhone": { "type": [ "string", "null" ], "description": "Telefone do destinatario." }, "recipientEmail": { "type": [ "string", "null" ], "description": "E-mail do destinatario." }, "zipCode": { "type": [ "string", "null" ], "description": "CEP de entrega." }, "street": { "type": [ "string", "null" ], "description": "Logradouro." }, "number": { "type": [ "string", "null" ], "description": "Numero." }, "complement": { "type": [ "string", "null" ], "description": "Complemento." }, "neighborhood": { "type": [ "string", "null" ], "description": "Bairro." }, "city": { "type": [ "string", "null" ], "description": "Cidade." }, "state": { "type": [ "string", "null" ], "description": "Estado (UF)." }, "country": { "type": "string", "description": "Pais." }, "fullAddress": { "type": "string", "readOnly": true, "description": "Endereco completo formatado — propriedade calculada, apenas leitura." }, "trackingCode": { "type": [ "string", "null" ], "description": "Codigo de rastreamento." }, "trackingUrl": { "type": [ "string", "null" ], "description": "URL de rastreamento." }, "shipmentStatus": { "type": [ "string", "null" ], "enum": [ "CREATED", "PENDING", "WAITINGPAYMENT", "PAID", "POSTED", "INTRANSIT", "OUTFORDELIVERY", "DELIVERED", "CANCELED", "LOST", "RETURNING", "RETURNED", "ERROR", null ], "description": "Status do envio — MAIUSCULAS sem separadores (EnumMember). Null quando o pedido ainda nao tem shipment associado." }, "carrierName": { "type": [ "string", "null" ], "description": "Nome da transportadora." }, "serviceName": { "type": [ "string", "null" ], "description": "Nome do servico de envio." }, "freightCost": { "type": "number", "description": "Valor do frete." }, "postedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data de postagem do envio." }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data de entrega do envio." } }, "required": [ "orderId", "orderNSU", "amount", "orderStatus", "quantityItems", "createdAt", "country", "freightCost" ] }, "OrderTrackingWebhookData": { "type": "object", "description": "Dados do evento order.tracking (OrderTrackingWebhookData no backend). Os dados do PEDIDO ficam no primeiro nivel — mesmos nomes/posicao de OrderCreatedWebhookData/OrderStatusChangedWebhookData — e o bloco tracking (OrderTrackingModel) traz o rastreio e o destinatario/endereco. Por ser ADITIVO, o pedido tambem aparece duplicado dentro de tracking (orderNSU, amount, orderStatus, ...) — mantido por compatibilidade com integracoes que ja liam esses campos ali. orderNSU aqui e tracking.orderNSU sao equivalentes: mesmo pedido, mesmo formato (texto, BEE...).", "properties": { "orderId": { "type": [ "string", "null" ], "format": "uuid", "description": "Identificador do pedido PrintBee ao qual o evento pertence. Fica dentro de data; em eventos order.* válidos vem preenchido." }, "orderNSU": { "type": "string", "description": "Numero publico do pedido — prefixo fixo BEE + NSU sequencial com 8 digitos zero-padded (ex.: BEE00123457). TEXTO, nao numero. Equivalente a tracking.orderNSU (mesmo pedido, mesmo formato)." }, "status": { "type": "string", "enum": [ "Open", "WaitingPayment", "PaymentReceived", "ProductionQueue", "Production", "ProductionCompleted", "WaitingFinalPayment", "Dispatch", "Transit", "Delivered", "Attended", "Lost", "Returned", "Canceled" ], "description": "Status do pedido (nao do envio — esse vai em tracking.shipmentStatus). Nome do enum em C# (PascalCase) — casing DIFERENTE de tracking.orderStatus (MAIUSCULAS), ver nota na descricao do evento." }, "amount": { "type": "number", "description": "Valor total do pedido." }, "quantityItems": { "type": "integer", "description": "Quantidade total de itens do pedido." }, "createdAt": { "type": "string", "format": "date-time", "description": "Data/hora de criacao do pedido." }, "tracking": { "$ref": "#/components/schemas/OrderTrackingModel" } }, "required": [ "orderId", "orderNSU", "status", "amount", "quantityItems", "createdAt", "tracking" ] }, "OrderTrackingEnvelope": { "description": "Envelope completo do evento order.tracking.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "order.tracking" }, "data": { "$ref": "#/components/schemas/OrderTrackingWebhookData" } }, "required": [ "data" ] } ] }, "IntegrationOrderWebhookData": { "type": "object", "description": "Dados compartilhados pelos 5 eventos integration_order.* (IntegrationOrderWebhookData no backend). O MESMO shape e usado por todos; o preenchimento varia por evento — ver tabela na descricao geral da API e a descricao de cada operacao.", "properties": { "draftId": { "type": "string", "format": "uuid", "description": "Identificador do rascunho de integracao (CustomerOrderDraft). Elo de correlacao presente em TODOS os eventos desta familia." }, "orderId": { "type": [ "string", "null" ], "format": "uuid", "description": "Pedido PrintBee real gerado a partir do rascunho. Null em received/failed/discarded/reopened (sem pedido vinculado no momento); preenchido em converted." }, "orderNSU": { "type": [ "string", "null" ], "description": "Numero publico do pedido — prefixo fixo BEE + 8 digitos (ex.: BEE00123457). Null (NAO \"BEE00000000\") quando nao ha pedido PrintBee vinculado — received, failed, discarded, reopened. Preenchido em converted. Renomeado de orderNsu para orderNSU em 26/07/2026." }, "status": { "type": "string", "description": "Status corrente do pedido real (quando existe) ou do rascunho, no nome do enum em C# (PascalCase) — ex.: Pending, Ready, Converted, Discarded, Failed." }, "platform": { "type": [ "string", "null" ], "description": "Plataforma de origem do rascunho (ex.: Nuvemshop, Other)." }, "externalId": { "type": [ "string", "null" ], "description": "Identificador do pedido na plataforma de origem." }, "convertedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data/hora UTC da conversao do rascunho em pedido real. Preenchido SOMENTE em integration_order.converted; null nos demais." }, "failureReason": { "type": [ "string", "null" ], "description": "Motivo da falha de ingestao/normalizacao (texto livre). Preenchido SOMENTE em integration_order.failed; null nos demais." } }, "required": [ "draftId", "status" ] }, "IntegrationOrderReceivedEnvelope": { "description": "Envelope completo do evento integration_order.received.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "integration_order.received" }, "data": { "$ref": "#/components/schemas/IntegrationOrderWebhookData" } }, "required": [ "data" ] } ] }, "IntegrationOrderConvertedEnvelope": { "description": "Envelope completo do evento integration_order.converted.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "integration_order.converted" }, "data": { "$ref": "#/components/schemas/IntegrationOrderWebhookData" } }, "required": [ "data" ] } ] }, "IntegrationOrderFailedEnvelope": { "description": "Envelope completo do evento integration_order.failed.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "integration_order.failed" }, "data": { "$ref": "#/components/schemas/IntegrationOrderWebhookData" } }, "required": [ "data" ] } ] }, "IntegrationOrderDiscardedEnvelope": { "description": "Envelope completo do evento integration_order.discarded.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "integration_order.discarded" }, "data": { "$ref": "#/components/schemas/IntegrationOrderWebhookData" } }, "required": [ "data" ] } ] }, "IntegrationOrderReopenedEnvelope": { "description": "Envelope completo do evento integration_order.reopened.", "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "eventType": { "type": "string", "const": "integration_order.reopened" }, "data": { "$ref": "#/components/schemas/IntegrationOrderWebhookData" } }, "required": [ "data" ] } ] } }, "responses": { "WebhookAccepted": { "description": "Seu servidor deve retornar 2xx para confirmar o recebimento. O PrintBee considera falha e agenda retentativas em caso de timeout, 4xx (exceto 408/425/429) ou 5xx — ver \"Política de retry\" na descrição geral desta API." } } } }