{ "item": [ { "name": "Autenticação", "description": "Obtenção e validação de tokens de acesso.", "item": [ { "id": "32b52730-5107-4b78-86d3-bda5a3a1206e", "name": "Obter token de acesso", "request": { "name": "Obter token de acesso", "description": { "content": "Troca `client_id` e `client_secret` por um JWT com validade de 1 hora.\n\nAceita dois formatos de envio das credenciais:\n\n- **Basic Auth** (recomendado): header `Authorization: Basic base64(client_id:client_secret)`\n e body com apenas `grant_type`.\n- **Body**: `client_id`, `client_secret` e `grant_type` no JSON da requisição.\n\nO token emitido herda automaticamente as permissões configuradas para a sua\naplicação. Para descobrir quais escopos sua aplicação tem, use `GET /auth/me`.\n", "type": "text/plain" }, "url": { "path": [ "auth", "token" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"\",\n \"client_secret\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "6587b1d8-8c33-4449-9150-f9af0cda4ba2", "name": "Token emitido.", "originalRequest": { "url": { "path": [ "auth", "token" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"\",\n \"client_secret\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"access_token\": \"\",\n \"token_type\": \"\",\n \"expires_in\": \"\",\n \"scope\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "311a03cd-a7ab-41ab-8020-a214bd074ebf", "name": "Credenciais inválidas.", "originalRequest": { "url": { "path": [ "auth", "token" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"\",\n \"client_secret\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "82819bfd-7bbd-4d6f-b14d-b0f0f8eddbb8", "name": "Payload inválido.", "originalRequest": { "url": { "path": [ "auth", "token" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"\",\n \"client_secret\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "e80e83cc-9847-43dd-818e-a5d606c861fc", "name": "Informações da aplicação autenticada", "request": { "name": "Informações da aplicação autenticada", "description": { "content": "Retorna os metadados da PartnerApplication associada ao token corrente.\n\nUse para validar token ativo, descobrir escopos concedidos ou verificar\nse há restrição por loja configurada (`manages_all_stores`).\n", "type": "text/plain" }, "url": { "path": [ "auth", "me" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "d6af0743-1faa-4787-9f55-6085efecf941", "name": "Dados da aplicação.", "originalRequest": { "url": { "path": [ "auth", "me" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"name\": \"\",\n \"environment\": \"test\",\n \"scopes\": [\n \"\",\n \"\"\n ],\n \"rate_limit_per_minute\": \"\",\n \"manages_all_stores\": \"\",\n \"stores_count\": \"\",\n \"created_at\": \"\",\n \"last_used_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f939c3b1-34e3-46c0-996f-8aa4645fedd7", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "auth", "me" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0b7c0095-2dec-45bc-93c8-9b187c6758a0", "name": "Health check", "request": { "name": "Health check", "description": { "content": "Endpoint público para verificar disponibilidade da API. Não requer autenticação.\n", "type": "text/plain" }, "url": { "path": [ "ping" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "0c4cd5b0-69e5-4308-b1fd-c9c7dcdcf7c6", "name": "API operacional.", "originalRequest": { "url": { "path": [ "ping" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": \"\",\n \"timestamp\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "Carrinhos", "description": "Criação e gestão de vendas.", "item": [ { "id": "50da368c-fde2-408f-b48f-90a9989cb515", "name": "Criar venda", "request": { "name": "Criar venda", "description": { "content": "Cria uma nova venda na loja indicada por `store.cnpj`.\n\nA criação é uma operação composta que executa, na ordem:\n\n1. Resolve a loja pelo CNPJ\n2. Localiza ou cria o cliente pelo telefone\n3. Valida o método de pagamento contra os gateways da loja\n4. Persiste a venda com status inicial apropriado\n5. Quando `is_for_delivery=true`, calcula o frete via transportadora\n6. Quando aplicável, gera link de checkout encurtado\n7. Aplica giftback se solicitado\n8. Dispara evento `cart.created` para webhooks configurados\n\n## Status inicial da venda\n\nO status inicial depende do `payment_method`:\n\n| Método | Status inicial |\n|--------|----------------|\n| `prepaid` | Pago (a venda já nasce concluída) |\n| `pix`, `credit_card`, `link` | Aguardando pagamento |\n| `pos_*` | Aguardando pagamento (cobrança presencial) |\n\n## Entregas e disponibilidade de métodos\n\nQuando `is_for_delivery=true`, o método informado em `delivery.method` precisa\nestar configurado na loja. Cada transportadora (UBER, ENTREGA99, LALAMOVE, BEE,\nCORREIOS) exige credenciais e contrato próprios na conta Viddy. `PROPRIA` é a\nopção quando a loja realiza a entrega com recursos próprios.\n\n**Antes de criar uma venda com entrega, consulte\n`GET /stores/{cnpj}/delivery-methods`** para descobrir quais métodos estão\nativos naquela loja. Se enviar um método não configurado, a API retorna `400`\ncom `error_type=delivery_method_not_available` e a lista dos disponíveis.\n\nNo ambiente sandbox, a disponibilidade de transportadoras depende das credenciais\nprovisionadas pela equipe Viddy no momento do cadastro da sua aplicação.\n\n## Idempotência\n\nUse o header `Idempotency-Key` para garantir que retries por timeout ou falha\nde rede não criem vendas duplicadas. A mesma chave em até 24h retorna a\nresposta original.\n\n## Valor da venda\n\nVocê pode informar o valor de duas formas:\n\n- `products[]` com `amount` e `unit_price` por item — o total é calculado\n- `amount` direto com o valor total da venda\n\nSe enviar os dois, `products[]` tem precedência.\n\n## Webhook\nEsta operação dispara o evento `cart.created` para os webhooks configurados\nque escutam esse tipo de evento.\n", "type": "text/plain" }, "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "6835cdf7-2141-4878-9c10-965521d8dfd3", "name": "Venda criada com sucesso.", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"\",\n \"order_number\": \"\",\n \"status\": \"\",\n \"total\": \"\",\n \"checkout_url\": \"\",\n \"checkout_channel\": {\n \"method\": \"pos\",\n \"message\": \"\"\n },\n \"created_at\": \"\",\n \"updated_at\": \"\"\n },\n \"warnings\": [\n {\n \"code\": \"\",\n \"reason\": \"\",\n \"detail\": \"\"\n },\n {\n \"code\": \"\",\n \"reason\": \"\",\n \"detail\": \"\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8c5242cb-9039-41e3-9ce6-d30273b7b564", "name": "Erro de regra de negócio ou `Idempotency-Key` ausente/inválido. Tipos possíveis:\n\n- `missing_idempotency_key` — header `Idempotency-Key` ausente ou inválido\n- `delivery_method_not_available` — método de entrega não configurado na loja\n- `delivery_freight_calculation_failed` — falha ao calcular frete (verifique endereço e método)\n- `max_installments_exceeded` — `max_installments` solicitado excede o máximo da loja\n- `giftback_amount_exceeds_cart` — valor de giftback maior que o valor da venda\n- `giftback_amount_exceeds_balance` — valor de giftback maior que o saldo disponível", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a4a49b71-0325-42cc-af4f-17d8775fc7f3", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "260bd7d5-08bf-4732-879d-dd7323d9fcf3", "name": "Loja não encontrada ou fora do escopo da aplicação (`store_not_found`).\n\nOcorre quando o CNPJ não existe, ou existe mas a sua PartnerApplication\nnão tem acesso a essa loja (quando `manages_all_stores=false`).", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "342dbb96-5b3d-43c4-9dda-5b14016bc3e1", "name": "A `Idempotency-Key` enviada já foi usada anteriormente com um payload diferente\n(`error_type=idempotency_key_conflict`). Gere uma nova chave e tente novamente.", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c16627be-5fbb-4e2c-b28e-2b3a68387aa7", "name": "Payload inválido (campos obrigatórios faltando ou com formato incorreto).\nQuando `payment_method` é incompatível com a gateway configurada na loja,\nretorna `payment_method_unavailable`.", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\"\n },\n \"client\": {\n \"telephone\": \"\",\n \"name\": \"\",\n \"cpf\": \"\",\n \"email\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"payment_method\": \"pix\",\n \"is_for_delivery\": \"\",\n \"amount\": \"\",\n \"products\": [\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n },\n {\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"code\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\"\n }\n ],\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"free_freight\": \"\",\n \"max_installments\": \"\",\n \"observation\": \"\",\n \"delivery\": {\n \"method\": \"ENTREGA99\",\n \"vehicle\": \"M\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"scheduled_to\": \"\",\n \"observation\": \"\"\n },\n \"giftback\": {\n \"use\": \"\",\n \"amount\": \"\"\n },\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "5f075d01-3ab7-4626-9533-a67635248b59", "name": "Listar vendas", "request": { "name": "Listar vendas", "description": { "content": "Lista as vendas criadas pela aplicação autenticada, com paginação por cursor.\n\nApenas vendas criadas pela própria aplicação são retornadas — vendas criadas\nno painel da Viddy ou por outras integrações ficam fora do resultado.\n\nOrdenação: mais recentes primeiro (`created_at` desc).\n", "type": "text/plain" }, "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da página seguinte (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Filtra por código interno de status.", "type": "text/plain" }, "key": "status", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por número de pedido.", "type": "text/plain" }, "key": "order_number", "value": "" }, { "disabled": false, "description": { "content": "Filtra vendas criadas a partir desta data. Use formato RFC 3339 com timezone\n(`YYYY-MM-DDTHH:MM:SSZ` em UTC ou `YYYY-MM-DDTHH:MM:SS±HH:MM` com offset).\n", "type": "text/plain" }, "key": "created_after", "value": "" }, { "disabled": false, "description": { "content": "Filtra vendas criadas até esta data. Use formato RFC 3339 com timezone\n(`YYYY-MM-DDTHH:MM:SSZ` em UTC ou `YYYY-MM-DDTHH:MM:SS±HH:MM` com offset).\n", "type": "text/plain" }, "key": "created_before", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "688b5e80-1a52-499f-9509-a7a563c1c5f6", "name": "Lista paginada de vendas.", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da página seguinte (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Filtra por código interno de status.", "type": "text/plain" }, "key": "status", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por número de pedido.", "type": "text/plain" }, "key": "order_number", "value": "" }, { "disabled": false, "description": { "content": "Filtra vendas criadas a partir desta data. Use formato RFC 3339 com timezone\n(`YYYY-MM-DDTHH:MM:SSZ` em UTC ou `YYYY-MM-DDTHH:MM:SS±HH:MM` com offset).\n", "type": "text/plain" }, "key": "created_after", "value": "" }, { "disabled": false, "description": { "content": "Filtra vendas criadas até esta data. Use formato RFC 3339 com timezone\n(`YYYY-MM-DDTHH:MM:SSZ` em UTC ou `YYYY-MM-DDTHH:MM:SS±HH:MM` com offset).\n", "type": "text/plain" }, "key": "created_before", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"\",\n \"order_number\": \"\",\n \"status\": \"\",\n \"payment_method\": \"pos_debit\",\n \"total\": \"\",\n \"is_for_delivery\": \"\",\n \"client\": {\n \"id\": \"\",\n \"name\": \"\",\n \"telephone\": \"\"\n },\n \"store\": {\n \"id\": \"\",\n \"fantasy_name\": \"\"\n },\n \"created_at\": \"\",\n \"updated_at\": \"\"\n },\n {\n \"id\": \"\",\n \"order_number\": \"\",\n \"status\": \"\",\n \"payment_method\": \"pos_credit\",\n \"total\": \"\",\n \"is_for_delivery\": \"\",\n \"client\": {\n \"id\": \"\",\n \"name\": \"\",\n \"telephone\": \"\"\n },\n \"store\": {\n \"id\": \"\",\n \"fantasy_name\": \"\"\n },\n \"created_at\": \"\",\n \"updated_at\": \"\"\n }\n ],\n \"pagination\": {\n \"limit\": \"\",\n \"next_cursor\": \"\",\n \"has_more\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9dccc85c-4e1b-40f9-ad3f-114912772a3f", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "carts" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da página seguinte (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Filtra por código interno de status.", "type": "text/plain" }, "key": "status", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por número de pedido.", "type": "text/plain" }, "key": "order_number", "value": "" }, { "disabled": false, "description": { "content": "Filtra vendas criadas a partir desta data. Use formato RFC 3339 com timezone\n(`YYYY-MM-DDTHH:MM:SSZ` em UTC ou `YYYY-MM-DDTHH:MM:SS±HH:MM` com offset).\n", "type": "text/plain" }, "key": "created_after", "value": "" }, { "disabled": false, "description": { "content": "Filtra vendas criadas até esta data. Use formato RFC 3339 com timezone\n(`YYYY-MM-DDTHH:MM:SSZ` em UTC ou `YYYY-MM-DDTHH:MM:SS±HH:MM` com offset).\n", "type": "text/plain" }, "key": "created_before", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "616c0cfd-4950-42ae-a1d6-8d60143e93ff", "name": "Detalhe da venda", "request": { "name": "Detalhe da venda", "description": { "content": "Retorna o detalhe completo de uma venda, incluindo cliente, loja, produtos,\nentrega e metadados.\n", "type": "text/plain" }, "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "fee63ce6-19dd-4880-bf0d-a2ad6defc296", "name": "Detalhe da venda.", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"order_number\": \"\",\n \"status\": \"\",\n \"payment_method\": \"pos_pix\",\n \"subtotal\": \"\",\n \"discount\": \"\",\n \"freight\": \"\",\n \"freight_amount\": \"\",\n \"total\": \"\",\n \"is_for_delivery\": \"\",\n \"delivery_method\": \"\",\n \"delivery_vehicle\": \"M\",\n \"delivery_scheduled_to\": \"\",\n \"delivery_address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"complement\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"additional_information\": \"\"\n },\n \"checkout_url\": \"\",\n \"client\": {\n \"id\": \"\",\n \"name\": \"\",\n \"email\": \"\",\n \"cpf\": \"\",\n \"telephone\": \"\",\n \"birth_date\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"complement\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"additional_information\": \"\"\n }\n },\n \"store\": {\n \"id\": \"\",\n \"cnpj\": \"\",\n \"fantasy_name\": \"\",\n \"email\": \"\",\n \"telephone\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"complement\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"lat\": \"\",\n \"long\": \"\"\n },\n \"payment_capabilities\": {\n \"link_payment\": \"\",\n \"pix\": \"\",\n \"giftback\": \"\"\n },\n \"business_rules\": {\n \"max_installments\": \"\",\n \"installment_floor\": \"\",\n \"online_payments_limit\": \"\",\n \"default_freight\": \"\",\n \"uses_automatic_freight\": \"\"\n }\n },\n \"products\": [\n {\n \"id\": \"\",\n \"code\": \"\",\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"line_total\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\",\n \"is_gift\": \"\"\n },\n {\n \"id\": \"\",\n \"code\": \"\",\n \"name\": \"\",\n \"amount\": \"\",\n \"unit_price\": \"\",\n \"line_total\": \"\",\n \"size\": \"\",\n \"color\": \"\",\n \"observation\": \"\",\n \"is_gift\": \"\"\n }\n ],\n \"delivery\": {\n \"id\": \"\",\n \"cart_id\": \"\",\n \"delivery_type\": \"shipping\",\n \"status\": \"\",\n \"tracking_url\": \"\",\n \"freight\": \"\",\n \"distance_km\": \"\",\n \"estimated_time\": \"\",\n \"scheduled_to\": \"\",\n \"status_updated_at\": \"\",\n \"courier\": {\n \"name\": \"\",\n \"phone\": \"\"\n },\n \"pickup_code\": \"\",\n \"delivery_code\": \"\",\n \"was_dispatched\": \"\",\n \"cancellation_reason\": \"\",\n \"finalization_reason\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\",\n \"canceled_at\": \"\"\n },\n \"metadata\": {\n \"key_0\": 1206,\n \"key_1\": false\n },\n \"observation\": \"\",\n \"cancellation_reason\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\",\n \"cancelled_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fb9949ca-f0b5-424f-96ca-61b3d9b1dfe7", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3090d7b7-1b05-45b9-bc1e-75d7c81f1a1d", "name": "Venda não encontrada (`cart_not_found`). Inclui também o caso em que a\nvenda existe mas pertence a outra aplicação — não vazamos a existência.", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "36fc98e0-e9f3-46ad-b521-ecf6f942bf21", "name": "Atualizar venda", "request": { "name": "Atualizar venda", "description": { "content": "Atualiza campos editáveis de uma venda existente. Apenas os campos enviados\nsão modificados (PATCH parcial).\n\n**Não é possível alterar via PATCH:** produtos, cliente, loja, método de\npagamento ou status. Para mudanças estruturais, cancele a venda e crie uma nova.\n", "type": "text/plain" }, "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" } } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"observation\": \"\",\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"delivery_scheduled_to\": \"\",\n \"metadata\": {\n \"key_0\": 6960\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "b87cd0cb-63e0-453a-b426-f2ac015bbfbc", "name": "Venda atualizada.", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"observation\": \"\",\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"delivery_scheduled_to\": \"\",\n \"metadata\": {\n \"key_0\": 6960\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"order_number\": \"\",\n \"status\": \"\",\n \"total\": \"\",\n \"checkout_url\": \"\",\n \"checkout_channel\": {\n \"method\": \"pos\",\n \"message\": \"\"\n },\n \"created_at\": \"\",\n \"updated_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2e7dc6cd-50c1-41fc-af8b-68d5ff7a20b9", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"observation\": \"\",\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"delivery_scheduled_to\": \"\",\n \"metadata\": {\n \"key_0\": 6960\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b3cf0cd5-6cbe-43e9-bd3d-1cd0d6ad6eda", "name": "Venda não encontrada (`cart_not_found`).", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"observation\": \"\",\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"delivery_scheduled_to\": \"\",\n \"metadata\": {\n \"key_0\": 6960\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e42516e3-3324-4399-a1a7-0756f64e1d9d", "name": "Payload inválido.", "originalRequest": { "url": { "path": [ "carts", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"observation\": \"\",\n \"discount\": \"\",\n \"percentage_discount\": \"\",\n \"delivery_scheduled_to\": \"\",\n \"metadata\": {\n \"key_0\": 6960\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "21472267-3d1b-4175-a2a3-23be92baab62", "name": "Cancelar venda", "request": { "name": "Cancelar venda", "description": { "content": "Cancela uma venda existente, registrando o motivo informado. Após cancelada,\na venda não pode mais ser modificada.\n\n## Webhook\nEsta operação dispara o evento `cart.cancelled` para os webhooks configurados\nque escutam esse tipo de evento.\n\n## Idempotência\nUse o header `Idempotency-Key` para evitar cancelamento duplicado em caso\nde retry por falha de rede.\n", "type": "text/plain" }, "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "0cfc2ce9-0b98-4a8e-9ce5-67288ef82915", "name": "Venda cancelada.", "originalRequest": { "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"order_number\": \"\",\n \"status\": \"\",\n \"total\": \"\",\n \"checkout_url\": \"\",\n \"checkout_channel\": {\n \"method\": \"pos\",\n \"message\": \"\"\n },\n \"created_at\": \"\",\n \"updated_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "16db6ecd-e1fd-4470-8c4f-da1e111b9255", "name": "`Idempotency-Key` ausente ou inválido.", "originalRequest": { "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "083635cb-a17b-4a60-8f37-c70eaf4bccb2", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a58e4e7d-3cef-4254-a8d5-e4bccdcf3e14", "name": "Venda não encontrada (`cart_not_found`).", "originalRequest": { "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a576da72-9516-4628-b065-01791cd9516a", "name": "A `Idempotency-Key` enviada já foi usada anteriormente com um payload diferente\n(`error_type=idempotency_key_conflict`). Gere uma nova chave e tente novamente.", "originalRequest": { "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6bcb2ef0-8d88-4b99-a111-9a89b2cc79ac", "name": "Payload inválido (motivo de cancelamento obrigatório).", "originalRequest": { "url": { "path": [ "carts", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) UUID do carrinho.", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"cancellation_reason\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "Lojas", "description": "Consulta de lojas, parcelamento, giftback e métodos de entrega.", "item": [ { "id": "4dfc850c-4bbe-4de9-a246-ff39aa89887e", "name": "Listar lojas", "request": { "name": "Listar lojas", "description": { "content": "Lista as lojas acessíveis pela aplicação autenticada, com paginação por cursor.\n\nQuando `manages_all_stores: true` (consulte em `GET /auth/me`), retorna todas\nas lojas do subscriber. Quando `false`, retorna apenas as lojas explicitamente\natribuídas à aplicação.\n\nUse esta listagem para descobrir CNPJs antes de chamar endpoints que recebem\n`store.cnpj` como parâmetro (criação de venda, consulta de parcelamento, etc).\n\nOrdenação: por `fantasy_name` ascendente.\n", "type": "text/plain" }, "url": { "path": [ "stores" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pelo nome fantasia da loja.", "type": "text/plain" }, "key": "fantasy_name", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por CNPJ. Aceita com ou sem máscara.", "type": "text/plain" }, "key": "cnpj", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pela cidade.", "type": "text/plain" }, "key": "city", "value": "" }, { "disabled": false, "description": { "content": "Filtro exato pelo estado (sigla UF, 2 caracteres).", "type": "text/plain" }, "key": "state", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "22317b10-ec10-4bce-a667-d02b9deaf1e2", "name": "Lista paginada de lojas.", "originalRequest": { "url": { "path": [ "stores" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pelo nome fantasia da loja.", "type": "text/plain" }, "key": "fantasy_name", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por CNPJ. Aceita com ou sem máscara.", "type": "text/plain" }, "key": "cnpj", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pela cidade.", "type": "text/plain" }, "key": "city", "value": "" }, { "disabled": false, "description": { "content": "Filtro exato pelo estado (sigla UF, 2 caracteres).", "type": "text/plain" }, "key": "state", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"\",\n \"cnpj\": \"\",\n \"fantasy_name\": \"\",\n \"city\": \"\",\n \"state\": \"\"\n },\n {\n \"id\": \"\",\n \"cnpj\": \"\",\n \"fantasy_name\": \"\",\n \"city\": \"\",\n \"state\": \"\"\n }\n ],\n \"pagination\": {\n \"limit\": \"\",\n \"next_cursor\": \"\",\n \"has_more\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c4087c1b-b2d2-4f42-813f-0064f79cbcb3", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "stores" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pelo nome fantasia da loja.", "type": "text/plain" }, "key": "fantasy_name", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por CNPJ. Aceita com ou sem máscara.", "type": "text/plain" }, "key": "cnpj", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pela cidade.", "type": "text/plain" }, "key": "city", "value": "" }, { "disabled": false, "description": { "content": "Filtro exato pelo estado (sigla UF, 2 caracteres).", "type": "text/plain" }, "key": "state", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9b1d067d-114d-4a6a-a5e4-27f4cf9c83fe", "name": "Parâmetros inválidos.", "originalRequest": { "url": { "path": [ "stores" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página (retornado em `pagination.next_cursor`).", "type": "text/plain" }, "key": "cursor", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pelo nome fantasia da loja.", "type": "text/plain" }, "key": "fantasy_name", "value": "" }, { "disabled": false, "description": { "content": "Busca exata por CNPJ. Aceita com ou sem máscara.", "type": "text/plain" }, "key": "cnpj", "value": "" }, { "disabled": false, "description": { "content": "Busca parcial case-insensitive pela cidade.", "type": "text/plain" }, "key": "city", "value": "" }, { "disabled": false, "description": { "content": "Filtro exato pelo estado (sigla UF, 2 caracteres).", "type": "text/plain" }, "key": "state", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "7e901bd8-c4ec-4711-b72d-e14c99107753", "name": "Detalhe da loja", "request": { "name": "Detalhe da loja", "description": { "content": "Retorna o detalhe completo de uma loja, incluindo endereço, capabilities\nde pagamento e regras de negócio.\n\nÚtil para validar configurações antes de criar uma venda:\n\n- `payment_capabilities` mostra quais métodos a loja aceita\n- `business_rules.max_installments` indica o máximo de parcelas permitido\n- `business_rules.installment_floor` indica o valor mínimo por parcela\n- `business_rules.online_payments_limit` indica o limite por venda online\n", "type": "text/plain" }, "url": { "path": [ "stores", ":cnpj" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "cnpj", "disabled": false, "description": { "content": "(Required) CNPJ da loja. **Use apenas dígitos** (sem máscara) — pontos e barras\nquebram o roteamento da URL.\n", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "8efa2bee-d1d7-4eb0-89d0-dc21331c105c", "name": "Detalhe da loja.", "originalRequest": { "url": { "path": [ "stores", ":cnpj" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja. **Use apenas dígitos** (sem máscara) — pontos e barras\nquebram o roteamento da URL.\n", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"cnpj\": \"\",\n \"fantasy_name\": \"\",\n \"email\": \"\",\n \"telephone\": \"\",\n \"address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"complement\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"lat\": \"\",\n \"long\": \"\"\n },\n \"payment_capabilities\": {\n \"link_payment\": \"\",\n \"pix\": \"\",\n \"giftback\": \"\"\n },\n \"business_rules\": {\n \"max_installments\": \"\",\n \"installment_floor\": \"\",\n \"online_payments_limit\": \"\",\n \"default_freight\": \"\",\n \"uses_automatic_freight\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b530f5a7-a981-4cc1-b1c7-0b41333aec9d", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "stores", ":cnpj" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja. **Use apenas dígitos** (sem máscara) — pontos e barras\nquebram o roteamento da URL.\n", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1a5e22d0-0b27-4055-a28a-bfc69df8d9d1", "name": "Loja não encontrada ou fora do escopo da aplicação (`store_not_found`).\nOcorre quando o CNPJ não existe ou existe mas sua PartnerApplication\nnão tem acesso a essa loja.", "originalRequest": { "url": { "path": [ "stores", ":cnpj" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja. **Use apenas dígitos** (sem máscara) — pontos e barras\nquebram o roteamento da URL.\n", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f43cd04a-59a2-452c-af59-8acc6a86d508", "name": "Calcular parcelamento", "request": { "name": "Calcular parcelamento", "description": { "content": "Calcula a tabela de parcelamento disponível para um valor de venda nesta loja.\n\nO `max_installments` retornado já considera todas as regras aplicáveis (limite\nconfigurado para a loja, valor mínimo por parcela, limite máximo do sistema).\nUse este endpoint **antes** de criar uma venda com `payment_method: credit_card`\npara mostrar opções ao cliente final ou validar a quantidade de parcelas pretendida.\n\n## Arredondamento\n\nQuando o valor da venda não é divisível exatamente pelo número de parcelas, a\núltima parcela carrega o ajuste de centavos para que o somatório feche com o\nvalor total. Nesses casos, `has_rounding_adjustment: true` e o campo\n`last_installment_value` é retornado com o valor da última parcela.\n", "type": "text/plain" }, "url": { "path": [ "stores", ":cnpj", "installments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Valor total da venda em reais (já incluindo frete, se houver).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "type": "any", "value": "", "key": "cnpj", "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "b3d85213-3c96-41ef-a88c-1e0b2b0e636a", "name": "Tabela de parcelamento calculada.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "installments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Valor total da venda em reais (já incluindo frete, se houver).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"amount\": \"\",\n \"max_installments\": \"\",\n \"installments\": [\n {\n \"installments\": \"\",\n \"installment_value\": \"\",\n \"total\": \"\",\n \"last_installment_value\": \"\",\n \"has_rounding_adjustment\": \"\"\n },\n {\n \"installments\": \"\",\n \"installment_value\": \"\",\n \"total\": \"\",\n \"last_installment_value\": \"\",\n \"has_rounding_adjustment\": \"\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2b3929fc-9a43-4024-9db2-b93137873d79", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "installments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Valor total da venda em reais (já incluindo frete, se houver).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3b8c9c07-6919-4f74-aed7-2edd62a72440", "name": "Loja não encontrada ou fora do escopo da aplicação (`store_not_found`).", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "installments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Valor total da venda em reais (já incluindo frete, se houver).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c61e6214-a223-450c-b7a5-034b8e5f9ffc", "name": "Parâmetro `amount` ausente ou inválido.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "installments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Valor total da venda em reais (já incluindo frete, se houver).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "48f2d575-609a-4c24-9628-302366bc7af3", "name": "Consultar saldo de giftback", "request": { "name": "Consultar saldo de giftback", "description": { "content": "Consulta o saldo de giftback disponível para um cliente nesta loja, considerando\num valor de venda. Use este endpoint **antes** de incluir o bloco `giftback` no\n`POST /carts` — assim você sabe quanto pode aplicar e evita erros.\n\nO response sempre traz `can_apply`. Quando `false`, o campo `reason` explica\no motivo (loja sem programa, cliente não identificado, saldo insuficiente, etc.).\n\n## Identificação do cliente\n\nO cliente é localizado pelo telefone (campo `client_telephone`). O telefone é\nnormalizado para dígitos antes da busca — aceita `(62) 98285-7486`, `62982857486`\nou `+5562982857486` indistintamente.\n\nSe o cliente não existir, o response indica `client_identified: false` e\n`reason: client_not_found` — sem erro 404.\n", "type": "text/plain" }, "url": { "path": [ "stores", ":cnpj", "giftback" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Telefone do cliente para identificação. Aceita com ou sem máscara.\n", "type": "text/plain" }, "key": "client_telephone", "value": "" }, { "disabled": false, "description": { "content": "(Required) Valor da venda em reais (usado para calcular saldo aplicável).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "type": "any", "value": "", "key": "cnpj", "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "98660317-41e0-4bc9-ac5a-4d318498f69b", "name": "Saldo de giftback consultado com sucesso.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "giftback" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Telefone do cliente para identificação. Aceita com ou sem máscara.\n", "type": "text/plain" }, "key": "client_telephone", "value": "" }, { "disabled": false, "description": { "content": "(Required) Valor da venda em reais (usado para calcular saldo aplicável).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"giftback_enabled\": \"\",\n \"client_identified\": \"\",\n \"available_amount\": \"\",\n \"can_apply\": \"\",\n \"total_amount\": \"\",\n \"min_purchase\": \"\",\n \"expiration_date\": \"\",\n \"service_unavailable\": \"\",\n \"reason\": \"amount_below_min_purchase\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "11d4a0e9-b050-4cdc-88a2-9b6f345da692", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "giftback" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Telefone do cliente para identificação. Aceita com ou sem máscara.\n", "type": "text/plain" }, "key": "client_telephone", "value": "" }, { "disabled": false, "description": { "content": "(Required) Valor da venda em reais (usado para calcular saldo aplicável).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "84287bed-4c8e-47f6-b966-369046dba989", "name": "Loja não encontrada ou fora do escopo da aplicação (`store_not_found`).", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "giftback" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Telefone do cliente para identificação. Aceita com ou sem máscara.\n", "type": "text/plain" }, "key": "client_telephone", "value": "" }, { "disabled": false, "description": { "content": "(Required) Valor da venda em reais (usado para calcular saldo aplicável).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "26b07d2c-b385-4725-a621-ea1db3814027", "name": "Parâmetros obrigatórios ausentes ou inválidos (`client_telephone` e/ou `amount`).", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "giftback" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "(Required) Telefone do cliente para identificação. Aceita com ou sem máscara.\n", "type": "text/plain" }, "key": "client_telephone", "value": "" }, { "disabled": false, "description": { "content": "(Required) Valor da venda em reais (usado para calcular saldo aplicável).", "type": "text/plain" }, "key": "amount", "value": "" } ], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "296891ad-9e90-4907-a553-31234a549ceb", "name": "Listar métodos de entrega disponíveis", "request": { "name": "Listar métodos de entrega disponíveis", "description": { "content": "Retorna os métodos de entrega ativos nesta loja, com os veículos aceitos\npor cada método.\n\nUse **antes** de criar uma venda com `is_for_delivery: true` para escolher\num `delivery.method` válido. Se enviar um método não disponível no `POST /carts`,\na resposta será `400` com `error_type: delivery_method_not_available`.\n\nQuando a lista vier vazia (`available_methods: []`), a loja não tem nenhuma\ntransportadora configurada — vendas com entrega não podem ser criadas nesta\nloja até que pelo menos um método seja configurado pela equipe Viddy.\n", "type": "text/plain" }, "url": { "path": [ "stores", ":cnpj", "delivery-methods" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "cnpj", "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "6cec3b93-eea9-403f-a6c0-92e4b0430586", "name": "Métodos de entrega disponíveis.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "delivery-methods" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"store_cnpj\": \"\",\n \"available_methods\": [\n {\n \"code\": \"PROPRIA\",\n \"vehicles\": [\n \"M\",\n \"C\"\n ]\n },\n {\n \"code\": \"BEE\",\n \"vehicles\": [\n \"C\",\n \"C\"\n ]\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e89b71a6-77e5-41fc-85b7-03052076d062", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "delivery-methods" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e3f8c0ef-e0aa-4f9e-9f39-0371101ed671", "name": "Loja não encontrada ou fora do escopo da aplicação (`store_not_found`).", "originalRequest": { "url": { "path": [ "stores", ":cnpj", "delivery-methods" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) CNPJ da loja (apenas dígitos).", "type": "text/plain" }, "type": "any", "value": "", "key": "cnpj" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "Entregas", "description": "Cotação de frete via transportadoras integradas. Consulte antes de criar\numa venda pra descobrir opções de carrier, veículos e valores.\n", "item": [ { "id": "59c06561-b9c4-46b9-a668-aa417f064f83", "name": "Cotar frete", "request": { "name": "Cotar frete", "description": { "content": "Cota valores de frete em uma ou mais transportadoras simultaneamente.\n\nCada request retorna um array agrupado por carrier, com uma entrada por\nveículo suportado. Erros isolados de um carrier (fora do ar, endereço não\natendido) não impedem cotações dos outros — aparecem como `available=false`\nno veículo específico.\n\n**Fluxo típico de uso:**\n1. Chame `POST /delivery/quotes` com o endereço do cliente\n2. Exiba as opções pro usuário final\n3. Ao criar a venda com `POST /carts`, passe:\n - `delivery.method` e `delivery.vehicle` da opção escolhida\n - `delivery.freight` com o valor cotado (opcional, pra reconciliação)\n - `delivery.freight_amount` com o valor que vai cobrar do cliente\n\n**Cotação de devolução:** passe `type: return` para cotar o percurso\ninverso (cliente → loja). O `delivery_address` continua sendo o endereço\ndo cliente (agora tratado como origem, não destino).\n\n**Cotação é read-only** e não deixa side effects (não cria registros,\nnão vincula lojas em transportadoras). Pode ser chamada quantas vezes\nprecisar sem impacto.\n\n**Correios NÃO é coberto por este endpoint** — Correios tem fluxo próprio\ncom pacote (dimensões/peso) e serviço (PAC/SEDEX) que serão expostos em\nendpoint dedicado futuro.\n", "type": "text/plain" }, "url": { "path": [ "delivery", "quotes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\",\n \"id\": \"\"\n },\n \"delivery_address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"type\": \"shipping\",\n \"carriers\": [\n \"propria\",\n \"bee\"\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "55eac8c7-fc24-4b6a-8f83-ec1952195b85", "name": "Cotações realizadas.", "originalRequest": { "url": { "path": [ "delivery", "quotes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\",\n \"id\": \"\"\n },\n \"delivery_address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"type\": \"shipping\",\n \"carriers\": [\n \"propria\",\n \"bee\"\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"carrier\": \"uber\",\n \"vehicles\": [\n {\n \"vehicle\": \"UV_FIORINO\",\n \"available\": \"\",\n \"vehicle_display_name\": \"\",\n \"freight\": \"\",\n \"error\": \"\"\n },\n {\n \"vehicle\": \"M\",\n \"available\": \"\",\n \"vehicle_display_name\": \"\",\n \"freight\": \"\",\n \"error\": \"\"\n }\n ],\n \"carrier_display_name\": \"\"\n },\n {\n \"carrier\": \"bee\",\n \"vehicles\": [\n {\n \"vehicle\": \"UV_FIORINO\",\n \"available\": \"\",\n \"vehicle_display_name\": \"\",\n \"freight\": \"\",\n \"error\": \"\"\n },\n {\n \"vehicle\": \"C\",\n \"available\": \"\",\n \"vehicle_display_name\": \"\",\n \"freight\": \"\",\n \"error\": \"\"\n }\n ],\n \"carrier_display_name\": \"\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cc221ad1-cfb9-4952-af36-c73caaf6beea", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "delivery", "quotes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\",\n \"id\": \"\"\n },\n \"delivery_address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"type\": \"shipping\",\n \"carriers\": [\n \"propria\",\n \"bee\"\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c0d74fd9-4833-4b7b-97d0-90cd192a5e87", "name": "Loja não encontrada ou fora do escopo da aplicação (`store_not_found`).", "originalRequest": { "url": { "path": [ "delivery", "quotes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\",\n \"id\": \"\"\n },\n \"delivery_address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"type\": \"shipping\",\n \"carriers\": [\n \"propria\",\n \"bee\"\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9a6f1e43-780c-4f6b-99d9-534dcb11afd9", "name": "Payload inválido. Casos comuns:\n- Endereço incompleto (campos obrigatórios ausentes)\n- `store.cnpj` inválido ou nenhum identificador de loja informado\n- `carriers` com valores inválidos que resultaram em lista vazia após filtro", "originalRequest": { "url": { "path": [ "delivery", "quotes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"store\": {\n \"cnpj\": \"\",\n \"id\": \"\"\n },\n \"delivery_address\": {\n \"cep\": \"\",\n \"street_name\": \"\",\n \"number\": \"\",\n \"neighborhood\": \"\",\n \"city\": \"\",\n \"state\": \"\",\n \"complement\": \"\",\n \"additional_information\": \"\"\n },\n \"type\": \"shipping\",\n \"carriers\": [\n \"propria\",\n \"bee\"\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "Webhooks", "description": "Cadastro e gestão de webhooks para receber notificações de eventos.", "item": [ { "id": "200e5665-5e5c-4645-ad1c-088ef2e697b2", "name": "Cadastrar webhook", "request": { "name": "Cadastrar webhook", "description": { "content": "Cria um webhook para receber notificações de eventos. O response contém um campo\n`secret` em texto claro — **armazene imediatamente em local seguro**. Este é o\núnico momento em que o secret aparece na API; se perder, gere um novo via\n`POST /webhooks/{id}/rotate-secret`.\n\n## Assinatura HMAC\n\nCada entrega de webhook inclui o header `Viddy-Signature` com a assinatura\nHMAC-SHA256 do corpo da requisição usando o `secret`. **Valide a assinatura\nantes de processar** o payload:\n\n```\nexpected = HMAC-SHA256(secret, request_body)\nassert hmac_compare(expected, received_signature)\n```\n\n## Eventos suportados\n\n- `cart.created` — venda criada via POST /carts ou painel Viddy\n- `cart.paid` — venda confirmada como paga\n- `cart.cancelled` — venda cancelada\n- `delivery.status_changed` — entrega mudou de status\n\n## Limites\n\nExiste um limite de webhooks por aplicação parceira. Se atingir, recebe `400` com\n`error_type=webhook_limit_exceeded` — delete um webhook existente antes de criar\nnovos. Valor padrão sob consulta com a equipe Viddy.\n", "type": "text/plain" }, "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.created\"\n ],\n \"description\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "d70bbd9d-0fe7-49c2-8305-d4d2c519ebeb", "name": "Webhook criado. **`secret` aparece neste response apenas.**", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.created\"\n ],\n \"description\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"secret\": \"\",\n \"created_at\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b3dc209a-85e5-4faf-99c4-5485137a758d", "name": "Erro de validação ou limite excedido. Tipos possíveis:\n\n- `webhook_limit_exceeded` — quantidade máxima de webhooks da aplicação atingida\n- `missing_idempotency_key` — header `Idempotency-Key` ausente ou inválido", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.created\"\n ],\n \"description\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "836d60e1-f4d4-4da6-aa4a-34168cb95b28", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.created\"\n ],\n \"description\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8db240ea-8145-4167-b853-306d90adcf07", "name": "A `Idempotency-Key` enviada já foi usada anteriormente com um payload diferente\n(`error_type=idempotency_key_conflict`). Gere uma nova chave e tente novamente.", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.created\"\n ],\n \"description\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f1c96e73-7d2b-4158-820b-8ac7aa5ae36c", "name": "Payload inválido. Casos comuns:\n\n- `url` ausente, malformada ou não-HTTPS\n- `events` ausente, vazio ou com valor não suportado\n- `events` com mais de 20 itens", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.created\"\n ],\n \"description\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "076d7578-68d2-4fd5-bddb-64ab2551cb3a", "name": "Listar webhooks", "request": { "name": "Listar webhooks", "description": { "content": "Lista os webhooks cadastrados pela aplicação autenticada, com paginação por cursor.\nWebhooks deletados (soft-delete) não aparecem.\n", "type": "text/plain" }, "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página.", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "5def15ac-b32b-40b2-95ff-931bb97e091b", "name": "Lista paginada de webhooks.", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página.", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"auto_disabled_at\": \"\",\n \"created_at\": \"\"\n },\n {\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"auto_disabled_at\": \"\",\n \"created_at\": \"\"\n }\n ],\n \"pagination\": {\n \"limit\": \"\",\n \"next_cursor\": \"\",\n \"has_more\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b34d8157-6b92-4775-8791-adfd42f56c01", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Quantidade de itens por página (1 a 100).", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Cursor opaco da próxima página.", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "283199c5-92b6-4d93-b837-5dfe061eaf6c", "name": "Detalhe do webhook", "request": { "name": "Detalhe do webhook", "description": { "content": "Retorna o detalhe completo de um webhook, incluindo estatísticas de entrega\n(contador de falhas, último sucesso, última falha).\n\n**Não inclui o `secret`** — para recuperá-lo, rotacione via\n`POST /webhooks/{id}/rotate-secret`.\n", "type": "text/plain" }, "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "2feb3114-8559-46d5-ba76-afd6c28223cb", "name": "Detalhe do webhook.", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"auto_disabled_at\": \"\",\n \"consecutive_failures\": \"\",\n \"last_success_at\": \"\",\n \"last_failure_at\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c845b407-9e3f-4250-b5ee-925af37185d5", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f76585db-755f-4cfe-b04c-efbfb1756296", "name": "Webhook não encontrado (`webhook_not_found`).", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "c1199680-bab6-4917-b3df-6a89e543624d", "name": "Atualizar webhook", "request": { "name": "Atualizar webhook", "description": { "content": "Atualização parcial. Apenas os campos enviados são modificados.\n\n## Casos especiais\n\n- **Reativar webhook manualmente desabilitado** (`enabled: false`, `auto_disabled_at: null`):\n envie `{\"enabled\": true}`.\n- **Reativar webhook auto-desabilitado** (15 falhas, `auto_disabled_at` preenchido):\n **não use PATCH** — use `POST /webhooks/{id}/reactivate`. Tentativas via PATCH\n retornam `422` com `cannot_reactivate_auto_disabled_webhook`.\n- **Trocar URL ou eventos:** sempre permitido, exceto se o webhook estiver auto-disabled.\n", "type": "text/plain" }, "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.cancelled\"\n ],\n \"description\": \"\",\n \"enabled\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "cba03cf6-752e-415a-9704-8012487fdecc", "name": "Webhook atualizado.", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.cancelled\"\n ],\n \"description\": \"\",\n \"enabled\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"auto_disabled_at\": \"\",\n \"consecutive_failures\": \"\",\n \"last_success_at\": \"\",\n \"last_failure_at\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b0d791e5-586a-497c-8a42-7af522fb2f0e", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.cancelled\"\n ],\n \"description\": \"\",\n \"enabled\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "48d381b6-c81c-4697-a49f-1caca368477e", "name": "Webhook não encontrado (`webhook_not_found`).", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.cancelled\"\n ],\n \"description\": \"\",\n \"enabled\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d6be0885-702c-413f-909d-aa1d9260247e", "name": "Payload inválido ou regra de negócio violada. Casos:\n\n- URL malformada, não-HTTPS ou eventos inválidos\n- `cannot_reactivate_auto_disabled_webhook` — tentou reativar um webhook\n auto-desabilitado via PATCH (use `/reactivate`)", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"events\": [\n \"cart.cancelled\"\n ],\n \"description\": \"\",\n \"enabled\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "2265518e-4166-4177-aff2-18cd08ef51c0", "name": "Remover webhook", "request": { "name": "Remover webhook", "description": { "content": "Remove o webhook (soft-delete). Após removido, nenhum evento futuro será enviado\npara esta URL, mas o histórico de entregas (`webhook_dispatches`) permanece\nconsultável.\n", "type": "text/plain" }, "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" } ], "method": "DELETE", "body": {}, "auth": null }, "response": [ { "id": "d10b03fe-8a6d-43bc-836d-a488befe4fee", "name": "Webhook removido. Sem body.", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "DELETE", "body": {} }, "status": "No Content", "code": 204, "header": [], "cookie": [], "_postman_previewlanguage": "text" }, { "id": "574842fe-8361-49ba-a136-7fae0f801d27", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "DELETE", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "27a43365-fd74-43d9-8230-32fae5ca5602", "name": "Webhook não encontrado (`webhook_not_found`).", "originalRequest": { "url": { "path": [ "webhooks", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "DELETE", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "75c4af6f-b6e9-4a8d-9f9e-3dacb854e45f", "name": "Rotacionar secret", "request": { "name": "Rotacionar secret", "description": { "content": "Gera um novo `secret` para o webhook e invalida o anterior **imediatamente**.\n\nUse quando suspeitar que o secret atual foi vazado, ou para rotação periódica\npor política de segurança. O response retorna o novo secret em texto claro —\n**única oportunidade** de obtê-lo. Armazene imediatamente em local seguro.\n\n## Impacto operacional\n\n- Eventos disparados **após** a rotação serão assinados com o novo secret.\n- Eventos já enfileirados aguardando retry também usarão o novo secret na próxima tentativa.\n- O secret anterior é descartado e **não pode ser recuperado**.\n\nAtualize a configuração do seu endpoint para validar com o novo secret antes\nde rotacionar, ou tolere uma pequena janela de falhas durante a transição.\n", "type": "text/plain" }, "url": { "path": [ "webhooks", ":id", "rotate-secret" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {}, "auth": null }, "response": [ { "id": "85192c1b-fc4e-41e1-a7eb-dc92a7b433ef", "name": "Secret rotacionado. **Novo `secret` aparece apenas neste response.**", "originalRequest": { "url": { "path": [ "webhooks", ":id", "rotate-secret" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"secret\": \"\",\n \"created_at\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8984a8db-33ee-4423-90d6-611f8e0ca56b", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks", ":id", "rotate-secret" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cc6022d3-bc8a-4475-88d1-be0c64b43623", "name": "Webhook não encontrado (`webhook_not_found`).", "originalRequest": { "url": { "path": [ "webhooks", ":id", "rotate-secret" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3392b528-17c5-4ee9-add6-f5db7eba6a9a", "name": "Reativar webhook auto-desabilitado", "request": { "name": "Reativar webhook auto-desabilitado", "description": { "content": "Reativa um webhook que foi automaticamente desabilitado após 15 falhas consecutivas\nde entrega (`auto_disabled_at` preenchido). Reseta o contador `consecutive_failures`\npara zero e marca `enabled: true`.\n\n## Quando usar\n\nUse este endpoint **apenas** para webhooks auto-desabilitados. Para webhooks que\nvocê desabilitou manualmente (`enabled: false` sem `auto_disabled_at`), use\n`PATCH /webhooks/{id}` com `{\"enabled\": true}`.\n\nAntes de reativar, **corrija o problema que causou as falhas** (endpoint fora do ar,\ncertificado expirado, validação errada de assinatura, etc.). Caso contrário o webhook\nvai cair de novo no mesmo ciclo de auto-disable.\n\n## Eventos perdidos\n\nEventos que ocorreram **enquanto** o webhook estava auto-desabilitado **não são\nre-enfileirados automaticamente**. Use `GET /webhook_dispatches` para identificar\nentregas falhadas no período e `POST /webhook_dispatches/{id}/replay` para forçar\nnovas tentativas onde fizer sentido.\n", "type": "text/plain" }, "url": { "path": [ "webhooks", ":id", "reactivate" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {}, "auth": null }, "response": [ { "id": "856b2247-7556-41f1-a2dd-de5e5844f609", "name": "Webhook reativado.", "originalRequest": { "url": { "path": [ "webhooks", ":id", "reactivate" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"url\": \"\",\n \"events\": [\n \"\",\n \"\"\n ],\n \"description\": \"\",\n \"enabled\": \"\",\n \"auto_disabled_at\": \"\",\n \"consecutive_failures\": \"\",\n \"last_success_at\": \"\",\n \"last_failure_at\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "87d87f22-b99a-4eaf-a6b2-6702072b29ce", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhooks", ":id", "reactivate" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "61b5e5f7-a64f-46cf-8103-e939eb653787", "name": "Webhook não encontrado (`webhook_not_found`).", "originalRequest": { "url": { "path": [ "webhooks", ":id", "reactivate" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2b1cb41a-edf4-48fc-9149-ee36a1f81199", "name": "Webhook não está auto-desabilitado (`webhook_not_auto_disabled`). Use\n`PATCH /webhooks/{id}` com `{\"enabled\": true}` para reativar manualmente.", "originalRequest": { "url": { "path": [ "webhooks", ":id", "reactivate" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "Histórico de webhooks", "description": "Consulta do histórico de entregas e replay manual de eventos.", "item": [ { "id": "6187972f-70f9-45e8-80de-aebc672af157", "name": "Listar tentativas de entrega", "request": { "name": "Listar tentativas de entrega", "description": { "content": "Lista tentativas de entrega de webhooks, paginadas por cursor. Inclui entregas\nbem-sucedidas, pendentes, em retry e falhas permanentes.\n\nCada evento de negócio (identificado por `event_id`) pode gerar várias linhas\nem `webhook_dispatches` se houver retentativas — uma por tentativa.\n\n## Filtros\n\n- `webhook_id`: limita a um webhook específico\n- `event_type`: filtra por tipo de evento (`cart.created`, `cart.paid`, etc.)\n- `status`: filtra por estado da entrega\n\nUse este endpoint para auditar entregas e diagnosticar falhas no seu endpoint.\n", "type": "text/plain" }, "url": { "path": [ "webhook_dispatches" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Filtra dispatches de um webhook específico.", "type": "text/plain" }, "key": "webhook_id", "value": "" }, { "disabled": false, "description": { "content": "Filtra por tipo de evento. (This can only be one of cart.created,cart.paid,cart.cancelled,delivery.status_changed)", "type": "text/plain" }, "key": "event_type", "value": "cart.created" }, { "disabled": false, "description": { "content": " (This can only be one of delivered,pending,failed_permanently,in_flight)", "type": "text/plain" }, "key": "status", "value": "delivered" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "24b648d1-d801-4f86-905a-e4a3eacce08e", "name": "Lista paginada de dispatches.", "originalRequest": { "url": { "path": [ "webhook_dispatches" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Filtra dispatches de um webhook específico.", "type": "text/plain" }, "key": "webhook_id", "value": "" }, { "disabled": false, "description": { "content": "Filtra por tipo de evento. (This can only be one of cart.created,cart.paid,cart.cancelled,delivery.status_changed)", "type": "text/plain" }, "key": "event_type", "value": "cart.created" }, { "disabled": false, "description": { "content": " (This can only be one of delivered,pending,failed_permanently,in_flight)", "type": "text/plain" }, "key": "status", "value": "delivered" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"\",\n \"event_id\": \"\",\n \"event_type\": \"cart.paid\",\n \"partner_webhook_id\": \"\",\n \"status\": \"delivered\",\n \"attempt_count\": \"\",\n \"response_status\": \"\",\n \"delivered_at\": \"\",\n \"next_retry_at\": \"\",\n \"failed_permanently\": \"\",\n \"failure_reason\": \"\",\n \"created_at\": \"\"\n },\n {\n \"id\": \"\",\n \"event_id\": \"\",\n \"event_type\": \"cart.cancelled\",\n \"partner_webhook_id\": \"\",\n \"status\": \"in_flight\",\n \"attempt_count\": \"\",\n \"response_status\": \"\",\n \"delivered_at\": \"\",\n \"next_retry_at\": \"\",\n \"failed_permanently\": \"\",\n \"failure_reason\": \"\",\n \"created_at\": \"\"\n }\n ],\n \"pagination\": {\n \"limit\": \"\",\n \"next_cursor\": \"\",\n \"has_more\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6ea7e31f-7409-4577-bdac-1a7add44c6ed", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhook_dispatches" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Filtra dispatches de um webhook específico.", "type": "text/plain" }, "key": "webhook_id", "value": "" }, { "disabled": false, "description": { "content": "Filtra por tipo de evento. (This can only be one of cart.created,cart.paid,cart.cancelled,delivery.status_changed)", "type": "text/plain" }, "key": "event_type", "value": "cart.created" }, { "disabled": false, "description": { "content": " (This can only be one of delivered,pending,failed_permanently,in_flight)", "type": "text/plain" }, "key": "status", "value": "delivered" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7131ccee-88fb-4772-84ff-76d966c470fa", "name": "Parâmetros de filtro inválidos.", "originalRequest": { "url": { "path": [ "webhook_dispatches" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "Filtra dispatches de um webhook específico.", "type": "text/plain" }, "key": "webhook_id", "value": "" }, { "disabled": false, "description": { "content": "Filtra por tipo de evento. (This can only be one of cart.created,cart.paid,cart.cancelled,delivery.status_changed)", "type": "text/plain" }, "key": "event_type", "value": "cart.created" }, { "disabled": false, "description": { "content": " (This can only be one of delivered,pending,failed_permanently,in_flight)", "type": "text/plain" }, "key": "status", "value": "delivered" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "cursor", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "91888d29-9271-46de-b3df-68eafda4d57f", "name": "Detalhe da tentativa de entrega", "request": { "name": "Detalhe da tentativa de entrega", "description": { "content": "Retorna o detalhe completo de uma tentativa, incluindo `payload` enviado e\n`response_body` recebido do seu endpoint. Use para diagnosticar exatamente o\nque foi enviado e o que o seu endpoint respondeu.\n", "type": "text/plain" }, "url": { "path": [ "webhook_dispatches", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "8f77211f-6d6a-4e7c-b67c-7093ab40a886", "name": "Detalhe do dispatch.", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"\",\n \"event_id\": \"\",\n \"event_type\": \"\",\n \"partner_webhook_id\": \"\",\n \"status\": \"pending\",\n \"attempt_count\": \"\",\n \"response_status\": \"\",\n \"response_body\": \"\",\n \"delivered_at\": \"\",\n \"next_retry_at\": \"\",\n \"failed_permanently\": \"\",\n \"failure_reason\": \"\",\n \"payload\": {},\n \"created_at\": \"\",\n \"updated_at\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dd5b1075-cbb3-417c-8f68-993f17615c6b", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "81efd548-8c3b-49bf-9b6e-a8dba471af57", "name": "Dispatch não encontrado (`webhook_dispatch_not_found`).", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "05a4a514-b861-4277-961d-38f2bf23abf1", "name": "Reenviar tentativa", "request": { "name": "Reenviar tentativa", "description": { "content": "Cria uma nova tentativa de entrega a partir de um dispatch anterior, com o\n**mesmo payload** e o **mesmo `event_id`**. O dispatch original permanece\nintocado no histórico — o replay gera uma nova linha em `webhook_dispatches`.\n\n## Quando usar\n\n- Seu endpoint estava fora do ar quando recebeu um evento e você quer reprocessar\n- Você corrigiu um bug no seu endpoint e quer revalidar entregas anteriores\n- Você quer reentregar eventos perdidos durante uma janela de auto-disable\n\n## Idempotência no seu lado\n\nO `event_id` enviado é **o mesmo** do dispatch original. Use-o para deduplicar\nno seu endpoint — se você já processou esse `event_id` antes, ignore o replay.\n\n## Resposta\n\nRetorna `202 Accepted` — a entrega é assíncrona. Acompanhe pelo `id` retornado\nconsultando `GET /webhook_dispatches/{id}`.\n", "type": "text/plain" }, "url": { "path": [ "webhook_dispatches", ":id", "replay" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {}, "auth": null }, "response": [ { "id": "2b724409-71e5-4276-b739-f0ac00fb83ff", "name": "Replay enfileirado. Acompanhe pelo novo dispatch retornado.", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id", "replay" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Accepted", "code": 202, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"\",\n \"event_id\": \"\",\n \"event_type\": \"\",\n \"partner_webhook_id\": \"\",\n \"status\": \"delivered\",\n \"attempt_count\": \"\",\n \"response_status\": \"\",\n \"response_body\": \"\",\n \"delivered_at\": \"\",\n \"next_retry_at\": \"\",\n \"failed_permanently\": \"\",\n \"failure_reason\": \"\",\n \"payload\": {},\n \"created_at\": \"\",\n \"updated_at\": \"\"\n },\n \"replayed_from\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "17da8702-f276-436e-9ba9-87dd3df7fe9b", "name": "Token inválido ou expirado.", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id", "replay" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5c92b699-9314-4c11-b3f4-211136d0a378", "name": "Dispatch original não encontrado (`webhook_dispatch_not_found`).", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id", "replay" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b9ce28c6-ab1a-42de-9153-f1a09cf575d5", "name": "Não é possível dar replay neste dispatch. Casos possíveis:\n\n- O webhook foi removido (soft-deleted) — `webhook_not_found`\n- O webhook está desabilitado — `cannot_replay_disabled_webhook`", "originalRequest": { "url": { "path": [ "webhook_dispatches", ":id", "replay" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Chave única gerada pelo cliente (recomendado UUID v4) para garantir\nidempotência em retries.\n\n**Gere uma chave diferente para cada operação distinta.** Reusar a mesma chave\nem duas operações lógicas (ex: criar venda + cancelar venda) retorna `409 Conflict`.\n\nMesma chave + mesmo body em até 24h retorna a resposta original sem reprocessar.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/problem+json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/problem+json" } ], "body": "{\n \"type\": \"\",\n \"title\": \"\",\n \"status\": \"\",\n \"detail\": \"\",\n \"request_id\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ], "auth": { "type": "bearer", "bearer": [ { "type": "any", "value": "{{bearerToken}}", "key": "token" } ] }, "event": [], "variable": [ { "key": "baseUrl", "value": "https://api-sandbox.viddy.com.br/public/v1" } ], "info": { "_postman_id": "bb13a0dc-ec33-4b40-843f-dc90958bde81", "name": "Viddy API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "Bem-vindo à documentação da API Viddy.\n\nEsta é a porta de entrada para integrar seu sistema à plataforma Viddy. Aqui você encontra\ntudo que precisa para criar e gerenciar vendas, consultar lojas e métodos de pagamento, e\nreceber notificações em tempo real via webhooks.\n\nA API segue o padrão REST, usa OAuth2 (`client_credentials`) para autenticação, e retorna\nJSON em todas as respostas — exceto erros, que seguem o formato Problem Details (RFC 7807).\n\n## Como começar\n\nPara usar a API Viddy você precisa de credenciais (`client_id` e `client_secret`)\nassociadas a uma aplicação parceira cadastrada na nossa plataforma.\n\n**Para solicitar credenciais de sandbox**, envie um e-mail para\n[fernando@viddy.com.br](mailto:fernando@viddy.com.br) com:\n\n- Nome da sua empresa\n- Descrição da integração que pretende construir\n- Quais escopos você precisa (`carts:write`, `stores:read`, `webhooks:write`, etc.)\n\nVocê receberá `client_id` e `client_secret` por canal seguro, junto com um subscriber sandbox\ndedicado para seus testes. Com as credenciais em mãos, você pode testar imediatamente\nusando o botão **Test Request** desta documentação — ou no seu próprio código.\n\nQuando a integração estiver pronta para produção, solicite as credenciais de produção pelo\nmesmo canal.\n\n## Ambientes\n\n| Ambiente | URL base |\n|----------|----------|\n| Sandbox | `https://api-sandbox.viddy.com.br/public/v1` |\n| Produção | `https://api.viddy.com.br/public/v1` |\n\nUse sandbox para desenvolver e testar. As credenciais de sandbox são fornecidas\nseparadamente das de produção e operam sobre dados isolados.\n\n## Autenticação\n\nToda chamada (exceto `/ping`) requer um JWT no header `Authorization`:\n\n```\nAuthorization: Bearer {access_token}\n```\n\nO token é obtido em `POST /auth/token` enviando `client_id` e `client_secret`.\nValidade de 1 hora. Renove antes de expirar.\n\n## Idempotência\n\nTodos os endpoints `POST` exigem o header `Idempotency-Key` — uma string única gerada\npelo cliente, **uma por requisição** (recomendado UUID v4).\n\nComo funciona:\n\n- **Mesma chave + mesmo body** dentro de 24h → retorna a resposta original sem reprocessar\n (útil para retry seguro em caso de timeout ou falha de rede).\n- **Mesma chave + body diferente** → retorna `409 Conflict` indicando que a chave já foi\n usada com outro payload.\n- **Sem chave** → retorna `400 Bad Request`.\n\n> **Importante:** gere uma chave **diferente para cada operação distinta**. Reutilizar a\n> mesma chave entre operações lógicas distintas (ex: criar venda e depois cancelar)\n> causa conflito. A regra prática é: uma chave por intenção do usuário.\n\n## Webhooks\n\nConfigure URLs em `POST /webhooks` para receber notificações de eventos como criação e\npagamento de vendas. Cada entrega chega no seu endpoint via `POST` JSON com headers de\nautenticação que permitem validar a origem da mensagem.\n\n### Headers enviados em cada webhook\n\n| Header | Descrição |\n|--------|-----------|\n| `Viddy-Signature` | Assinatura HMAC-SHA256 do payload. Formato: `t=,v1=` |\n| `Viddy-Event-Id` | Identificador único do evento (deduplique pelo lado do seu endpoint usando este valor) |\n| `Viddy-Event-Type` | Tipo do evento: `cart.created`, `cart.paid`, `cart.cancelled`, `delivery.status_changed` |\n| `Viddy-Delivery-Attempt` | Número da tentativa de entrega (1 na primeira) |\n\n### Validação da assinatura HMAC\n\nPara garantir que o webhook recebido veio realmente da Viddy (e não foi forjado), **valide\na assinatura HMAC-SHA256 antes de processar o payload**. O algoritmo:\n\n1. Extraia `t` (timestamp) e `v1` (assinatura) do header `Viddy-Signature`\n2. Monte a string assinada como `\"{timestamp}.{corpo_raw_da_request}\"`\n3. Recompute HMAC-SHA256 dessa string usando o `secret` do webhook como chave\n4. Compare a assinatura recomputada com `v1` em **tempo constante** (evita timing attacks)\n5. Rejeite se o timestamp for muito antigo (proteção contra replay attack — recomendamos\n tolerância máxima de 5 minutos)\n\n#### Exemplo em PHP\n\n```php\n$secret = 'whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';\n$rawBody = file_get_contents('php://input');\n$header = $_SERVER['HTTP_VIDDY_SIGNATURE'] ?? '';\n\n// 1. Extrai timestamp e signature\nif (!preg_match('/t=(\\d+),v1=([a-f0-9]+)/', $header, $matches)) {\n http_response_code(401);\n exit('Invalid signature header');\n}\n[$_, $timestamp, $signatureReceived] = $matches;\n\n// 2. Proteção contra replay attack\nif (abs(time() - (int) $timestamp) > 300) {\n http_response_code(401);\n exit('Request too old');\n}\n\n// 3. Recomputa a assinatura\n$signedPayload = $timestamp . '.' . $rawBody;\n$signatureExpected = hash_hmac('sha256', $signedPayload, $secret);\n\n// 4. Comparação em tempo constante\nif (!hash_equals($signatureExpected, $signatureReceived)) {\n http_response_code(401);\n exit('Invalid signature');\n}\n\n// 5. Assinatura válida — processa o webhook\n$event = json_decode($rawBody, true);\n// ... sua lógica de negócio\nhttp_response_code(200);\n```\n\n### Idempotência no seu endpoint\n\nUse o `Viddy-Event-Id` para deduplicar. Se sua aplicação processar o mesmo `event_id`\nduas vezes (por causa de retentativas, replay manual, ou rede instável), **deduplique\ndescartando a segunda ocorrência** — mas ainda retorne `200 OK`. Caso contrário a Viddy\nvai considerar como falha e tentar reentregar.\n\n### Ordem dos eventos\n\nA entrega de webhooks segue a ordem em que os eventos foram gerados. Para uma venda\ntípica, a sequência canônica é:\n\n1. `cart.created` — venda foi criada (qualquer `payment_method`, qualquer status inicial)\n2. `cart.paid` — pagamento confirmado (quando aplicável)\n3. `cart.cancelled` — caso a venda seja cancelada\n\nVendas criadas com `payment_method: prepaid` (pagamento já realizado fora da Viddy)\ngeram **dois webhooks em sequência imediata**:\n\n- `cart.created` — registro de criação da venda\n- `cart.paid` — confirmação do pagamento já consumado\n\nO `cart.paid` permanece como evento canônico de \"venda foi paga\" em todos os cenários,\nindependente de como o pagamento aconteceu. Isso permite que seu código tenha um único\ncaminho de processamento de pagamento, sem precisar tratar `prepaid` como caso especial.\nSe você não quer receber `cart.paid` para vendas prepaid, basta não inscrever neste evento\nao cadastrar o webhook em `POST /webhooks` — você ainda receberá `cart.created` com todos\nos dados da venda (incluindo `payment_method` e `status`).\n\n### Retentativas\n\nFalhas temporárias (HTTP 5xx, timeout, erro de conexão) são reentregues com backoff\nexponencial: 30s, 1min, 5min, 30min, 2h, 6h, 12h. Após 15 falhas consecutivas o\nwebhook é **automaticamente desabilitado** (`auto_disabled_at` preenchido) — reative\nvia `POST /webhooks/{id}/reactivate` após corrigir o problema.\n\nErros do seu endpoint (`4xx`) são considerados falhas permanentes — sem retry. Verifique\no `response_status` e `response_body` em `GET /webhook_dispatches/{id}` para diagnosticar.\n\n## Segurança\n\nA segurança da API é construída em múltiplas camadas:\n\n| Camada | Como funciona |\n|--------|---------------|\n| **HTTPS obrigatório** | Toda comunicação trafega sobre TLS. Requisições em `http://` são rejeitadas. |\n| **Autenticação JWT** | Tokens emitidos via OAuth2 `client_credentials` com validade de 1 hora. Sem token válido, retorna `401`. |\n| **Rate limit** | Cada aplicação tem um limite de requisições por minuto (padrão 60 req/min, ajustável sob demanda). Quando atinge o limite, retorna `429 Too Many Requests`. |\n| **Idempotência** | Operações `POST` aceitam `Idempotency-Key` para garantir que retries não criem duplicidades. |\n| **Sandbox isolado** | Sandbox e produção rodam em ambientes completamente separados — dados, credenciais e logs não se misturam. |\n| **Rotação de credenciais** | `client_secret` pode ser rotacionado sob demanda. O secret antigo é invalidado imediatamente. |\n| **Firewall** | Requisições passam por um firewall de aplicação que bloqueia padrões maliciosos conhecidos antes de chegar à aplicação. |\n\n### Boas práticas\n\n- **Nunca exponha o `client_secret`** em código client-side, repositórios públicos ou logs.\n- **Renove o token antes de expirar** (recomendado: renovar quando faltar menos de 5 minutos para expirar).\n- **Use `Idempotency-Key`** em todas as criações de venda para evitar duplicidade em retries.\n- **Valide a assinatura HMAC** dos webhooks antes de confiar no payload.\n- **Use scopes mínimos** — peça apenas os escopos necessários para a integração.\n\n## Testando endpoints na documentação\n\nCada endpoint tem um botão **Test Request** que abre o cliente embutido. O fluxo\ncompleto de teste é:\n\n### Passo 1 — Solicite credenciais\n\nEnvie um e-mail para [fernando@viddy.com.br](mailto:fernando@viddy.com.br) seguindo\nas instruções da seção [Como começar](#section/Como-comecar). Você receberá\n`client_id` e `client_secret`.\n\n### Passo 2 — Gere um token de acesso\n\n1. Vá no endpoint `POST /auth/token` no menu lateral.\n2. Clique no botão **Test Request** (canto inferior direito do bloco de exemplo).\n3. No painel que abre, preencha o body com seu `client_id` e `client_secret`.\n4. Clique em **Send**.\n5. No response, copie o valor do campo `access_token`.\n\n### Passo 3 — Cole o token globalmente\n\n1. Volte para a página **Introdução** no menu lateral.\n2. No painel direito, encontre o card **Autenticação Obrigatório**.\n3. Cole o token copiado no campo **Token de acesso**.\n\nA partir desse momento, **todos os endpoints autenticados usam esse token\nautomaticamente** — você não precisa colar de novo em cada Test Request. O\ntoken tem validade de 1 hora; quando expirar, repita os passos 2 e 3.\n\n### Passo 4 — Teste qualquer endpoint\n\n1. Navegue até o endpoint desejado.\n2. Clique em **Test Request**.\n3. Ajuste o body conforme necessário (já vem pré-preenchido com um exemplo).\n4. Para endpoints `POST`, o header **Idempotency-Key** é preenchido automaticamente\n com um UUID — em código real, gere um UUID v4 por requisição.\n5. Clique em **Send**. A resposta aparece logo abaixo.\n\nO cliente embutido mostra abas para Headers, Cookies e Query Parameters — em geral\nvocê só usa o **Body** e o token global (configurado no Passo 3). Cookies não são\nusados em chamadas autenticadas.\n\n## Cotação de frete\n\nAntes de criar uma venda com `is_for_delivery: true`, você pode cotar o frete\nem múltiplas transportadoras via `POST /delivery/quotes`. O endpoint retorna\nvalores agrupados por carrier e veículo, permitindo que seu sistema escolha\n(ou deixe o cliente escolher) a melhor opção.\n\nO fluxo end-to-end é:\n\n1. `POST /delivery/quotes` — cota fretes disponíveis\n2. Escolhe carrier e veículo\n3. `POST /carts` com `delivery.method`, `delivery.vehicle`, `delivery.freight`\n (valor cotado, opcional) e `delivery.freight_amount` (valor a cobrar do cliente)\n4. `GET /carts/{id}` — consulta a venda criada com todos os detalhes de entrega\n\nUber, Lalamove, Entrega99 e Bee Delivery estão suportados. Correios tem fluxo\npróprio (pacote/dimensões) e será exposto em endpoint dedicado futuro.\n\n> **Atenção sobre `Idempotency-Key` ao testar:** a documentação **reutiliza a mesma chave**\n> em todas as chamadas dentro de uma sessão de Test Request. Se você executar duas\n> vezes o mesmo `POST` (ex: criar dois webhooks sequenciais), a segunda chamada\n> retorna o resultado da primeira sem reprocessar — pode parecer que \"nada mudou\"\n> ou que o cadastro veio com dados antigos.\n>\n> Para forçar uma nova operação: edite manualmente o campo `Idempotency-Key` na aba\n> **Headers** do Test Request antes de cada `Send`, gerando um UUID diferente. Em\n> código real, sua aplicação deve gerar um UUID v4 novo por requisição.\n\n\nContact Support:\n Name: Falar com Suporte", "type": "text/plain" } } }