{ "openapi": "3.1.0", "info": { "title": "LoopPay API", "version": "1.0.0", "description": "API autenticada da aplicação: catálogo, entrega, Pix, saques, avaliações e dados. Documentação: /documentacao. Valores em centavos; listas paginadas; UTC. Não exponha a chave LoopPay no navegador do comprador." }, "servers": [ { "url": "https://flowpayments.net/api/v1", "description": "Domínio público temporário da LoopPay; ambiente definido pelo servidor." } ], "tags": [ { "name": "Catálogo" }, { "name": "Mídia" }, { "name": "Subprodutos" }, { "name": "Estoque e entrega" }, { "name": "Categorias" }, { "name": "Pagamentos Pix" }, { "name": "Saques" }, { "name": "Dados e relatórios" }, { "name": "Clientes e pedidos" }, { "name": "Avaliações" }, { "name": "Logs" }, { "name": "Webhooks" } ], "components": { "securitySchemes": { "LoopKey": { "type": "http", "scheme": "bearer", "bearerFormat": "loop + 16 caracteres aleatórios" } } }, "paths": { "/products": { "get": { "operationId": "get_products", "tags": [ "Catálogo" ], "summary": "Listar produtos", "description": "Produtos principais da aplicação. Use q para buscar pelo nome. Os subprodutos têm uma listagem própria. Permissão: products:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "delivery_type": { "type": "string" }, "stock_format": { "type": "string" }, "stock_count": { "type": "integer" }, "image_url": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "checkout_path": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Acesso mensal", "description": "Licença digital por 30 dias", "price_cents": 2500, "delivery_type": "automatic", "stock_format": "lines", "stock_count": 2, "image_url": "https://sua-loja.com/produto.png", "parent_id": null, "visible": true, "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "post": { "operationId": "post_products", "tags": [ "Catálogo" ], "summary": "Criar produto", "description": "Cria o produto no banco e retorna o endereço de checkout. Valores recebidos usam camelCase; projeções do banco usam snake_case. Permissão: products:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de 2 a 120 caracteres." }, "priceCents": { "type": "integer", "description": "Preço unitário em centavos. De 1 a 999999999; preço × quantidade mínima deve ser pelo menos 200." }, "description": { "type": "string", "description": "Descrição de até 10000 caracteres. Padrão: vazio." }, "slug": { "type": "string", "description": "Endereço com até 100 caracteres. Gerado a partir do nome se omitido." }, "comparePriceCents": { "type": [ "integer", "null" ], "description": "Preço anterior; deve ser igual ou maior que o preço atual. Padrão: null." }, "minQuantity": { "type": "integer", "description": "Quantidade mínima de 1 a 10000. Padrão: 1." }, "maxQuantity": { "type": "integer", "description": "Máximo por pedido, de minQuantity a 10000. Padrão: 10000." }, "deliveryType": { "type": "string", "enum": [ "manual", "automatic" ], "description": "manual: entrega pelo vendedor. automatic: consome o estoque após confirmação em produção. Padrão: manual." }, "stockFormat": { "type": "string", "enum": [ "lines", "block" ], "description": "lines: uma unidade por linha. block: todo o texto é uma unidade. Padrão: lines." }, "stockText": { "type": "string", "description": "Conteúdo privado de até 100000 caracteres. Exige também stock:write. Omitido na edição preserva o estoque." }, "instructions": { "type": "string", "description": "Instruções após pagamento, até 5000 caracteres. Nunca são enviadas ao comprador antes da confirmação." }, "imageUrl": { "type": "string", "description": "URL HTTPS pública, até 2000 caracteres. Também pode enviar a imagem em /image." }, "videoUrl": { "type": "string", "description": "URL HTTPS do vídeo, até 2000 caracteres." }, "categoryId": { "type": [ "string", "null" ], "format": "uuid", "description": "Categoria da mesma aplicação. Padrão: null." }, "visible": { "type": "boolean", "description": "Exibe e permite a compra quando true. Padrão: true. false preserva o histórico." } }, "required": [ "name", "priceCents" ] }, "example": { "name": "Acesso mensal", "priceCents": 2500, "description": "Licença por 30 dias", "deliveryType": "manual", "imageUrl": "https://sua-loja.com/produto.png" } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "delivery_type": { "type": "string" }, "stock_format": { "type": "string" }, "stock_count": { "type": "integer" }, "image_url": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "checkout_path": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Acesso mensal", "description": "Licença digital por 30 dias", "price_cents": 2500, "delivery_type": "automatic", "stock_format": "lines", "stock_count": 2, "image_url": "https://sua-loja.com/produto.png", "parent_id": null, "visible": true, "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/products/{id}": { "get": { "operationId": "get_products__id_", "tags": [ "Catálogo" ], "summary": "Consultar produto", "description": "Retorna nome, preço, descrição, foto, estoque disponível, entrega, categoria, parent_id e links. Não retorna conteúdo privado do estoque. Permissão: products:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "delivery_type": { "type": "string" }, "stock_format": { "type": "string" }, "stock_count": { "type": "integer" }, "image_url": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "checkout_path": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Acesso mensal", "description": "Licença digital por 30 dias", "price_cents": 2500, "delivery_type": "automatic", "stock_format": "lines", "stock_count": 2, "image_url": "https://sua-loja.com/produto.png", "parent_id": null, "visible": true, "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "patch": { "operationId": "patch_products__id_", "tags": [ "Catálogo" ], "summary": "Atualizar produto", "description": "Envie apenas os campos que deseja alterar. Para desativar sem apagar pedidos, envie visible: false. Ao mudar o formato do estoque ou o tipo de entrega, envie também stockText e tenha stock:write. Permissão: products:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de 2 a 120 caracteres." }, "priceCents": { "type": "integer", "description": "Preço unitário em centavos. De 1 a 999999999; preço × quantidade mínima deve ser pelo menos 200." }, "description": { "type": "string", "description": "Descrição de até 10000 caracteres. Padrão: vazio." }, "slug": { "type": "string", "description": "Endereço com até 100 caracteres. Gerado a partir do nome se omitido." }, "comparePriceCents": { "type": [ "integer", "null" ], "description": "Preço anterior; deve ser igual ou maior que o preço atual. Padrão: null." }, "minQuantity": { "type": "integer", "description": "Quantidade mínima de 1 a 10000. Padrão: 1." }, "maxQuantity": { "type": "integer", "description": "Máximo por pedido, de minQuantity a 10000. Padrão: 10000." }, "deliveryType": { "type": "string", "enum": [ "manual", "automatic" ], "description": "manual: entrega pelo vendedor. automatic: consome o estoque após confirmação em produção. Padrão: manual." }, "stockFormat": { "type": "string", "enum": [ "lines", "block" ], "description": "lines: uma unidade por linha. block: todo o texto é uma unidade. Padrão: lines." }, "stockText": { "type": "string", "description": "Conteúdo privado de até 100000 caracteres. Exige também stock:write. Omitido na edição preserva o estoque." }, "instructions": { "type": "string", "description": "Instruções após pagamento, até 5000 caracteres. Nunca são enviadas ao comprador antes da confirmação." }, "imageUrl": { "type": "string", "description": "URL HTTPS pública, até 2000 caracteres. Também pode enviar a imagem em /image." }, "videoUrl": { "type": "string", "description": "URL HTTPS do vídeo, até 2000 caracteres." }, "categoryId": { "type": [ "string", "null" ], "format": "uuid", "description": "Categoria da mesma aplicação. Padrão: null." }, "visible": { "type": "boolean", "description": "Exibe e permite a compra quando true. Padrão: true. false preserva o histórico." } } }, "example": { "name": "Acesso mensal Premium", "priceCents": 3000, "visible": true } } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "delivery_type": { "type": "string" }, "stock_format": { "type": "string" }, "stock_count": { "type": "integer" }, "image_url": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "checkout_path": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Acesso mensal", "description": "Licença digital por 30 dias", "price_cents": 2500, "delivery_type": "automatic", "stock_format": "lines", "stock_count": 2, "image_url": "https://sua-loja.com/produto.png", "parent_id": null, "visible": true, "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/products/{id}/image": { "post": { "operationId": "post_products__id__image", "tags": [ "Mídia" ], "summary": "Enviar foto", "description": "Valida a assinatura do arquivo, hospeda no bucket público product-media e vincula ao produto. Até 2 MB; PNG, JPEG ou WebP. Não envie arquivos de entrega neste bucket. Permissão: products:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base64": { "type": "string", "description": "Conteúdo do arquivo em base64, sem prefixo data:." }, "contentType": { "type": "string", "description": "image/png, image/jpeg ou image/webp; deve corresponder ao arquivo." } }, "required": [ "base64", "contentType" ] }, "example": { "base64": "BASE64_DO_ARQUIVO", "contentType": "image/png" } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "productId": { "type": "string" }, "imageUrl": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "productId": "00000000-0000-4000-8000-000000000001", "imageUrl": "https://seu-projeto.supabase.co/storage/v1/object/public/product-media/foto.png" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/products/{id}/subproducts": { "get": { "operationId": "get_products__id__subproducts", "tags": [ "Subprodutos" ], "summary": "Listar subprodutos", "description": "Opções independentes do produto principal. Cada opção tem id, nome, preço, descrição, foto e estoque próprios. Permissão: products:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "delivery_type": { "type": "string" }, "stock_format": { "type": "string" }, "stock_count": { "type": "integer" }, "image_url": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "visible": { "type": "boolean" }, "checkout_path": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Acesso mensal", "description": "Licença digital por 30 dias", "price_cents": 2500, "delivery_type": "automatic", "stock_format": "lines", "stock_count": 2, "image_url": "https://sua-loja.com/produto.png", "parent_id": null, "visible": true, "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "post": { "operationId": "post_products__id__subproducts", "tags": [ "Subprodutos" ], "summary": "Criar subproduto", "description": "Usa os mesmos campos de um produto. Até 50 opções por produto, sem níveis aninhados. Para editar depois, use PATCH /products/{id_do_subproduto}. Comprar usa productId do subproduto. O produto principal continua sendo uma opção. Permissão: products:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de 2 a 120 caracteres." }, "priceCents": { "type": "integer", "description": "Preço unitário em centavos. De 1 a 999999999; preço × quantidade mínima deve ser pelo menos 200." }, "description": { "type": "string", "description": "Descrição de até 10000 caracteres. Padrão: vazio." }, "slug": { "type": "string", "description": "Endereço com até 100 caracteres. Gerado a partir do nome se omitido." }, "comparePriceCents": { "type": [ "integer", "null" ], "description": "Preço anterior; deve ser igual ou maior que o preço atual. Padrão: null." }, "minQuantity": { "type": "integer", "description": "Quantidade mínima de 1 a 10000. Padrão: 1." }, "maxQuantity": { "type": "integer", "description": "Máximo por pedido, de minQuantity a 10000. Padrão: 10000." }, "deliveryType": { "type": "string", "enum": [ "manual", "automatic" ], "description": "manual: entrega pelo vendedor. automatic: consome o estoque após confirmação em produção. Padrão: manual." }, "stockFormat": { "type": "string", "enum": [ "lines", "block" ], "description": "lines: uma unidade por linha. block: todo o texto é uma unidade. Padrão: lines." }, "stockText": { "type": "string", "description": "Conteúdo privado de até 100000 caracteres. Exige também stock:write. Omitido na edição preserva o estoque." }, "instructions": { "type": "string", "description": "Instruções após pagamento, até 5000 caracteres. Nunca são enviadas ao comprador antes da confirmação." }, "imageUrl": { "type": "string", "description": "URL HTTPS pública, até 2000 caracteres. Também pode enviar a imagem em /image." }, "videoUrl": { "type": "string", "description": "URL HTTPS do vídeo, até 2000 caracteres." }, "categoryId": { "type": [ "string", "null" ], "format": "uuid", "description": "Categoria da mesma aplicação. Padrão: null." }, "visible": { "type": "boolean", "description": "Exibe e permite a compra quando true. Padrão: true. false preserva o histórico." } }, "required": [ "name", "priceCents" ] }, "example": { "name": "Acesso anual", "priceCents": 24000, "description": "12 meses de acesso", "deliveryType": "manual" } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "delivery_type": { "type": "string" }, "stock_format": { "type": "string" }, "stock_count": { "type": "integer" }, "image_url": { "type": "string" }, "parent_id": { "type": "string" }, "visible": { "type": "boolean" }, "checkout_path": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Acesso mensal", "description": "Licença digital por 30 dias", "price_cents": 2500, "delivery_type": "automatic", "stock_format": "lines", "stock_count": 2, "image_url": "https://sua-loja.com/produto.png", "parent_id": "00000000-0000-4000-8000-000000000001", "visible": true, "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/products/{id}/stock": { "get": { "operationId": "get_products__id__stock", "tags": [ "Estoque e entrega" ], "summary": "Consultar estoque privado", "description": "Retorna o conteúdo descriptografado somente para a integração autorizada. A versão deve acompanhar a substituição do estoque. Não exponha esta chamada no navegador do comprador. Permissão: stock:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "stock:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "productId": { "type": "string" }, "stockText": { "type": "string" }, "stockCount": { "type": "integer" }, "stockFormat": { "type": "string" }, "version": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "productId": "00000000-0000-4000-8000-000000000001", "stockText": "LICENCA-A\nLICENCA-B", "stockCount": 2, "stockFormat": "lines", "version": "2026-11-02T18:00:00.000Z" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "put": { "operationId": "put_products__id__stock", "tags": [ "Estoque e entrega" ], "summary": "Substituir estoque", "description": "Substitui todo o conteúdo, não acrescenta. Para repor, leia a versão atual e envie o conteúdo desejado. Se outra operação alterou o produto, retorna 409 stock_changed. Estoque automático é consumido uma única vez por pagamento confirmado. Permissão: stock:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "stock:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stockText": { "type": "string", "description": "Até 100000 caracteres; linhas vazias não contam." }, "stockFormat": { "type": "string", "enum": [ "lines", "block" ], "description": "Uma unidade por linha ou todo o conteúdo em uma unidade." }, "version": { "type": "string", "description": "Valor version da consulta de estoque." } }, "required": [ "stockText", "stockFormat", "version" ] }, "example": { "stockText": "LICENCA-A\nLICENCA-B", "stockFormat": "lines", "version": "2026-11-02T18:00:00.000Z" } } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "stock_count": { "type": "integer" }, "stock_format": { "type": "string" }, "updated_at": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "stock_count": 2, "stock_format": "lines", "updated_at": "2026-11-02T18:01:00Z" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/categories": { "get": { "operationId": "get_categories", "tags": [ "Categorias" ], "summary": "Listar categorias", "description": "Categorias da aplicação, paginadas. Permissão: products:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "visible": { "type": "boolean" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Licenças", "slug": "licencas", "visible": true } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "post": { "operationId": "post_categories", "tags": [ "Categorias" ], "summary": "Criar categoria", "description": "Organiza os produtos da aplicação. Permissão: products:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "2 a 80 caracteres; não pode ser Sem categoria." }, "subtitle": { "type": "string", "description": "Até 160 caracteres." }, "description": { "type": "string", "description": "Até 2000 caracteres." }, "slug": { "type": "string", "description": "Até 100 caracteres; gerado do nome se omitido." }, "visible": { "type": "boolean", "description": "Padrão: true." } }, "required": [ "name" ] }, "example": { "name": "Licenças", "subtitle": "Entrega digital", "visible": true } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "visible": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Licenças", "slug": "licencas", "visible": true }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/categories/{id}": { "patch": { "operationId": "patch_categories__id_", "tags": [ "Categorias" ], "summary": "Editar categoria", "description": "Aceita os mesmos campos da criação; envie somente as alterações. Permissão: products:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "Licenças digitais", "visible": true } } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "visible": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Licenças digitais", "visible": true }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "get": { "operationId": "get_categories__id_", "tags": [ "Categorias" ], "summary": "Consultar categorias por ID", "description": "Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Categorias da aplicação, paginadas. Permissão: products:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "products:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "visible": { "type": "boolean" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Licenças", "slug": "licencas", "visible": true } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/payments": { "post": { "operationId": "post_payments", "tags": [ "Pagamentos Pix" ], "summary": "Gerar pagamento", "description": "Gera cobrança Pix dinâmica na Woovi e salva a reserva na aplicação da chave. Informe productId e quantity para vender um produto/subproduto; o servidor determina o preço. Para cobrança avulsa, omita productId e informe title e amountCents. Moeda de recebimento: BRL. Permissão: payments:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "payments:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do comprador; 2 a 100 caracteres." }, "email": { "type": "string", "description": "E-mail válido, até 254 caracteres." }, "productId": { "type": "string", "format": "uuid", "description": "ID do produto ou subproduto da aplicação. Não enviar amountCents neste modo." }, "quantity": { "type": "integer", "description": "Padrão 1; deve respeitar os limites e o estoque do produto." }, "title": { "type": "string", "description": "Obrigatório para cobrança avulsa; 2 a 120 caracteres." }, "amountCents": { "type": "integer", "description": "Obrigatório para cobrança avulsa; 200 a 100000000 centavos." } }, "required": [ "name", "email" ] }, "example": { "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1, "name": "Cliente exemplo", "email": "cliente@exemplo.com" } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "environment": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "status": { "type": "string" }, "br_code": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "integer" }, "requestKey": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "environment": "sandbox", "amount_cents": 2500, "fee_cents": 100, "net_cents": 2400, "status": "pending", "br_code": "000201…", "expires_at": "2026-11-02T19:00:00Z", "paid_at": null, "kind": "product", "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1, "requestKey": "00000000-0000-4000-8000-000000000001" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "get": { "operationId": "get_payments", "tags": [ "Pagamentos Pix" ], "summary": "Listar pagamentos", "description": "Filtre por status (creating, pending, completed, expired) ou requestKey retornado na criação. Ambiente definido pelo servidor. A consulta não força confirmação na instituição. Permissão: payments:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "payments:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "creating", "pending", "completed", "expired" ] } }, { "name": "requestKey", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "environment": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "status": { "type": "string" }, "br_code": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "integer" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "environment": "sandbox", "amount_cents": 2500, "fee_cents": 100, "net_cents": 2400, "status": "pending", "br_code": "000201…", "expires_at": "2026-11-02T19:00:00Z", "paid_at": null, "kind": "product", "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1 } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/payments/{id}": { "get": { "operationId": "get_payments__id_", "tags": [ "Pagamentos Pix" ], "summary": "Consultar pagamento", "description": "Retorna o estado salvo. completed é confirmação; pending não libera saldo. Conteúdo de entrega fica na rota /delivery. Permissão: payments:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "payments:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "environment": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "status": { "type": "string" }, "br_code": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "environment": "sandbox", "amount_cents": 2500, "fee_cents": 100, "net_cents": 2400, "status": "pending", "br_code": "000201…", "expires_at": "2026-11-02T19:00:00Z", "paid_at": null, "kind": "product", "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/payments/{id}/refresh": { "post": { "operationId": "post_payments__id__refresh", "tags": [ "Pagamentos Pix" ], "summary": "Validar pagamento na instituição", "description": "Consulta a cobrança na Woovi e confere correlação, valor e ambiente. Somente uma confirmação válida credita a carteira; chamadas repetidas não duplicam crédito ou entrega. Não aceita status informado pelo cliente. Envie {} no corpo. Permissão: payments:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "payments:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "environment": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "status": { "type": "string" }, "br_code": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "type": "string" }, "kind": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "environment": "sandbox", "amount_cents": 2500, "fee_cents": 100, "net_cents": 2400, "status": "completed", "br_code": "000201…", "expires_at": "2026-11-02T19:00:00Z", "paid_at": "2026-11-02T18:02:00Z", "kind": "product", "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/payments/{id}/delivery": { "get": { "operationId": "get_payments__id__delivery", "tags": [ "Estoque e entrega" ], "summary": "Consultar entrega do pedido", "description": "Conteúdo e instruções ficam disponíveis após confirmação em produção. No modo automático, o comprador também os vê no checkout original. No sandbox, o estoque não é consumido e content é null. Permissão: orders:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "orders:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "content": { "type": "string" }, "instructions": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "status": "delivered", "content": "LICENCA-A", "instructions": "Use esta licença no seu aplicativo." }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "post": { "operationId": "post_payments__id__delivery", "tags": [ "Estoque e entrega" ], "summary": "Registrar entrega manual", "description": "Salva uma entrega privada para produto pago em produção com delivery_status waiting_seller. O conteúdo aparece no checkout do comprador. Não substitui uma entrega já concluída. Permissão: orders:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "orders:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Conteúdo de entrega com 1 a 100000 caracteres." } }, "required": [ "content" ] }, "example": { "content": "Seu acesso está disponível: instruções de ativação." } } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "delivery_status": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "delivery_status": "delivered" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/withdrawals": { "post": { "operationId": "post_withdrawals", "tags": [ "Saques" ], "summary": "Criar saque", "description": "Reserva saldo e cria a transferência sem aprová-la. Tarifa R$ 0,70; mínimo líquido R$ 10,00. O saldo é da conta do proprietário e é compartilhado entre lojas. O ambiente acompanha a configuração do servidor. Não é necessário chamar Account Data Check. Permissão: withdrawals:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "withdrawals:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyType": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "RANDOM" ], "description": "Tipo da chave Pix." }, "key": { "type": "string", "description": "Chave de destino; telefone em formato internacional. Guardada criptografada." }, "amountCents": { "type": "integer", "description": "Valor líquido, ou total caso deductFee seja true. Máximo 100000000." }, "deductFee": { "type": "boolean", "description": "false: soma tarifa ao total reservado. true: deduz tarifa do valor informado." } }, "required": [ "keyType", "key", "amountCents" ] }, "example": { "keyType": "EMAIL", "key": "financeiro@exemplo.com", "amountCents": 1000, "deductFee": false } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "pix_key_type": { "type": "string" }, "pix_key_mask": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "status": { "type": "string" }, "provider_status": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "pix_key_type": "EMAIL", "pix_key_mask": "•••• .com", "amount_cents": 1000, "fee_cents": 70, "total_cents": 1070, "status": "created", "provider_status": "CREATED" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "get": { "operationId": "get_withdrawals", "tags": [ "Saques" ], "summary": "Histórico de saques", "description": "Lista solicitações da aplicação no ambiente atual. As chaves Pix aparecem mascaradas. Permissão: withdrawals:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "withdrawals:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "environment": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "pix_key_type": { "type": "string" }, "pix_key_mask": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "status": { "type": "string" }, "provider_status": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "environment": "sandbox", "items": [ { "id": "00000000-0000-4000-8000-000000000001", "pix_key_type": "EMAIL", "pix_key_mask": "•••• .com", "amount_cents": 1000, "fee_cents": 70, "total_cents": 1070, "status": "created", "provider_status": "CREATED" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/withdrawals/{id}": { "get": { "operationId": "get_withdrawals__id_", "tags": [ "Saques" ], "summary": "Consultar saque", "description": "Consulta local paginada, com items contendo no máximo a solicitação informada. Permissão: withdrawals:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "withdrawals:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "environment": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "pix_key_type": { "type": "string" }, "pix_key_mask": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "status": { "type": "string" }, "provider_status": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "environment": "sandbox", "items": [ { "id": "00000000-0000-4000-8000-000000000001", "pix_key_type": "EMAIL", "pix_key_mask": "•••• .com", "amount_cents": 1000, "fee_cents": 70, "total_cents": 1070, "status": "created", "provider_status": "CREATED" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/withdrawals/{id}/approve": { "post": { "operationId": "post_withdrawals__id__approve", "tags": [ "Saques" ], "summary": "Aprovar envio", "description": "Autoriza o envio à chave cadastrada. Use uma chave com esta permissão apenas no servidor. CREATED ainda não é transferência concluída; completed exige CONFIRMED da instituição. Envie {}. Permissão: withdrawals_approval:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "withdrawals_approval:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "pix_key_type": { "type": "string" }, "pix_key_mask": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "status": { "type": "string" }, "provider_status": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "pix_key_type": "EMAIL", "pix_key_mask": "•••• .com", "amount_cents": 1000, "fee_cents": 70, "total_cents": 1070, "status": "processing", "provider_status": "APPROVED" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/withdrawals/{id}/refresh": { "post": { "operationId": "post_withdrawals__id__refresh", "tags": [ "Saques" ], "summary": "Conferir saque na instituição", "description": "Atualiza o estado pela Woovi. Falha definitiva libera a reserva uma única vez; resposta desconhecida mantém o valor reservado. Em produção, chamadas não retornam de completed para failed. Envie {}. Permissão: withdrawals:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "withdrawals:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "pix_key_type": { "type": "string" }, "pix_key_mask": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "status": { "type": "string" }, "provider_status": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "pix_key_type": "EMAIL", "pix_key_mask": "•••• .com", "amount_cents": 1000, "fee_cents": 70, "total_cents": 1070, "status": "completed", "provider_status": "CONFIRMED" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/balance": { "get": { "operationId": "get_balance", "tags": [ "Dados e relatórios" ], "summary": "Saldo disponível", "description": "Saldo em centavos como string. Em produção, considera a carteira real e reservas de saque. No sandbox, considera somente os pagamentos simulados e saques de teste. Permissão: metrics:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "metrics:read", "parameters": [], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currency": { "type": "string" }, "environment": { "type": "string" }, "availableCents": { "type": "string" }, "scope": { "type": "string" }, "sharedAcrossApplications": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "currency": "BRL", "environment": "sandbox", "availableCents": "2400", "scope": "owner_account", "sharedAcrossApplications": true }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/metrics": { "get": { "operationId": "get_metrics", "tags": [ "Dados e relatórios" ], "summary": "Receita, vendas e MRR", "description": "Parâmetros from e to em ISO 8601; início inclusivo e fim exclusivo. Padrão: últimos 30 dias. Receita exclui depósitos. MRR usa assinaturas ativas e pagas, normalizadas em 30 dias; é indicador de recorrência, não cobrança automática. Permissão: metrics:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "metrics:read", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Início inclusivo (UTC)." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Fim exclusivo (UTC)." } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currency": { "type": "string" }, "environment": { "type": "string" }, "grossCents": { "type": "string" }, "feeCents": { "type": "string" }, "netCents": { "type": "string" }, "approvedPayments": { "type": "integer" }, "sales": { "type": "integer" }, "pendingPayments": { "type": "integer" }, "mrrCents": { "type": "string" }, "mrrBasis": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "currency": "BRL", "environment": "production", "grossCents": "2500", "feeCents": "100", "netCents": "2400", "approvedPayments": 1, "sales": 1, "pendingPayments": 0, "mrrCents": "2500", "mrrBasis": "30_days_active_paid_subscriptions" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/reports": { "get": { "operationId": "get_reports", "tags": [ "Dados e relatórios" ], "summary": "Relatório de pagamentos", "description": "Exportação JSON paginada com valores brutos, taxas, líquidos, ambiente, datas e estado. Use from e to (ISO 8601). Datas UTC; centavos inteiros. Percorra as páginas até atingir total. Permissão: metrics:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "metrics:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Início inclusivo (UTC)." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Fim exclusivo (UTC)." } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "environment": { "type": "string" }, "amount_cents": { "type": "integer" }, "fee_cents": { "type": "integer" }, "net_cents": { "type": "integer" }, "status": { "type": "string" }, "br_code": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "integer" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "environment": { "type": "string" }, "currency": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "environment": "sandbox", "amount_cents": 2500, "fee_cents": 100, "net_cents": 2400, "status": "pending", "br_code": "000201…", "expires_at": "2026-11-02T19:00:00Z", "paid_at": null, "kind": "product", "productId": "00000000-0000-4000-8000-000000000001", "quantity": 1 } ], "total": 1, "page": 1, "limit": 20, "environment": "sandbox", "currency": "BRL" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/customers": { "get": { "operationId": "get_customers", "tags": [ "Clientes e pedidos" ], "summary": "Listar clientes", "description": "Clientes da aplicação, criados por compras reais ou pelo painel. Dados pessoais devem ser utilizados somente pela integração autorizada. Permissão: customers:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "customers:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "tags": { "type": "array", "items": {} } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Cliente exemplo", "email": "cliente@exemplo.com", "tags": [] } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/orders": { "get": { "operationId": "get_orders", "tags": [ "Clientes e pedidos" ], "summary": "Listar pedidos", "description": "Pedidos registrados em produção, com produto, valor, cliente, estado e referência. Pagamentos de sandbox não geram pedidos reais. Permissão: orders:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "orders:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "order_reference": { "type": "string" }, "product_name": { "type": "string" }, "amount_cents": { "type": "integer" }, "status": { "type": "string" }, "delivery_type": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "order_reference": "00000000-0000-4000-8000-000000000001", "product_name": "Acesso mensal", "amount_cents": 2500, "status": "approved", "delivery_type": "automatic" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/reviews": { "get": { "operationId": "get_reviews", "tags": [ "Avaliações" ], "summary": "Consultar avaliações", "description": "Filtro status: pending, published ou hidden. A API não fabrica avaliações: o envio pelo comprador continua exigindo uma compra verificada e autenticação. Permissão: reviews:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "reviews:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "published", "hidden" ] } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "display_name": { "type": "string" }, "rating": { "type": "integer" }, "body": { "type": "string" }, "status": { "type": "string" }, "owner_reply": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "product_id": "00000000-0000-4000-8000-000000000001", "display_name": "Cliente", "rating": 5, "body": "Entrega rápida.", "status": "pending", "owner_reply": null } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/reviews/{id}": { "patch": { "operationId": "patch_reviews__id_", "tags": [ "Avaliações" ], "summary": "Moderar e responder", "description": "Publica, oculta ou responde uma avaliação recebida. Não altera a nota nem o texto do comprador. Permissão: reviews:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "reviews:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "published", "hidden" ], "description": "Novo estado da moderação." }, "reply": { "type": "string", "description": "Resposta de até 2000 caracteres. Vazio remove a resposta." } } }, "example": { "status": "published", "reply": "Obrigado pela confiança!" } } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "owner_reply": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "status": "published", "owner_reply": "Obrigado pela confiança!" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "get": { "operationId": "get_reviews__id_", "tags": [ "Avaliações" ], "summary": "Consultar avaliações por ID", "description": "Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Filtro status: pending, published ou hidden. A API não fabrica avaliações: o envio pelo comprador continua exigindo uma compra verificada e autenticação. Permissão: reviews:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "reviews:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": "string" }, "display_name": { "type": "string" }, "rating": { "type": "integer" }, "body": { "type": "string" }, "status": { "type": "string" }, "owner_reply": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "product_id": "00000000-0000-4000-8000-000000000001", "display_name": "Cliente", "rating": 5, "body": "Entrega rápida.", "status": "pending", "owner_reply": null } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/logs": { "get": { "operationId": "get_logs", "tags": [ "Logs" ], "summary": "Consultar logs da API", "description": "Requisições autenticadas da aplicação: método, rota normalizada, HTTP status, duração, erro, ID da chave e requestId. Sem cabeçalhos de autenticação, corpo, conteúdo do estoque ou chave Pix. Também disponível em Fluxos → Logs → Requisições da API. Permissão: logs:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "logs:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "method": { "type": "string" }, "route": { "type": "string" }, "status": { "type": "integer" }, "duration_ms": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "method": "POST", "route": "/api/v1/payments", "status": 201, "duration_ms": 340, "error_code": null } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/customers/{id}": { "get": { "operationId": "get_customers__id_", "tags": [ "Clientes e pedidos" ], "summary": "Consultar clientes por ID", "description": "Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Clientes da aplicação, criados por compras reais ou pelo painel. Dados pessoais devem ser utilizados somente pela integração autorizada. Permissão: customers:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "tags": { "type": "array", "items": {} } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Cliente exemplo", "email": "cliente@exemplo.com", "tags": [] } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/orders/{id}": { "get": { "operationId": "get_orders__id_", "tags": [ "Clientes e pedidos" ], "summary": "Consultar pedidos por ID", "description": "Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Pedidos registrados em produção, com produto, valor, cliente, estado e referência. Pagamentos de sandbox não geram pedidos reais. Permissão: orders:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "orders:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "order_reference": { "type": "string" }, "product_name": { "type": "string" }, "amount_cents": { "type": "integer" }, "status": { "type": "string" }, "delivery_type": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "order_reference": "00000000-0000-4000-8000-000000000001", "product_name": "Acesso mensal", "amount_cents": 2500, "status": "approved", "delivery_type": "automatic" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhooks": { "get": { "operationId": "get_webhooks", "tags": [ "Webhooks" ], "summary": "Listar destinos", "description": "Lista destinos da aplicação, sem o segredo de assinatura. Até 10 destinos não arquivados. Permissão: webhooks:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "integer" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Sistema de pedidos", "url": "https://seu-sistema.com/webhooks/looppay", "events": [ "payment.completed", "delivery.completed" ], "environment": "sandbox", "enabled": true, "version": 1 } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "post": { "operationId": "post_webhooks", "tags": [ "Webhooks" ], "summary": "Cadastrar webhook", "description": "Cria um destino HTTPS público. Retorna o segredo apenas na resposta original, criptografado no banco. A repetição idempotente retorna metadados sem secret. Se perder o segredo, use /rotate. Permissão: webhooks:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de 2 a 80 caracteres." }, "url": { "type": "string", "description": "URL HTTPS pública na porta 443, até 2000 caracteres. Sem usuário, senha, fragmento ou IP literal. Segredos não devem ser colocados na URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Lista dos eventos documentados. Ao menos um. Ex.: payment.completed e delivery.completed." }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "description": "Filtra pagamentos e saques. Produtos e avaliações são eventos de catálogo, com environment null." }, "enabled": { "type": "boolean", "description": "true ativa; false pausa." } }, "required": [ "name", "url", "events", "environment", "enabled" ] }, "example": { "name": "Sistema de pedidos", "url": "https://seu-sistema.com/webhooks/looppay", "events": [ "payment.completed", "delivery.completed" ], "environment": "sandbox", "enabled": true } } } }, "responses": { "201": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "integer" }, "secret": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Sistema de pedidos", "url": "https://seu-sistema.com/webhooks/looppay", "events": [ "payment.completed", "delivery.completed" ], "environment": "sandbox", "enabled": true, "version": 1, "secret": "whsec_SEGREDO_DE_ASSINATURA" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhooks/{id}": { "get": { "operationId": "get_webhooks__id_", "tags": [ "Webhooks" ], "summary": "Consultar destino", "description": "Consulta nome, URL, eventos, ambiente, estado e versão. O segredo não é retornado. Permissão: webhooks:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Sistema de pedidos", "url": "https://seu-sistema.com/webhooks/looppay", "events": [ "payment.completed", "delivery.completed" ], "environment": "sandbox", "enabled": true, "version": 1 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "patch": { "operationId": "patch_webhooks__id_", "tags": [ "Webhooks" ], "summary": "Alterar ou pausar destino", "description": "Envie somente os campos desejados. Mudanças se aplicam às tentativas futuras; uma requisição já em andamento pode terminar no destino anterior. Tentativas de um destino pausado são canceladas ao serem processadas. Permissão: webhooks:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome de 2 a 80 caracteres." }, "url": { "type": "string", "description": "URL HTTPS pública na porta 443, até 2000 caracteres. Sem usuário, senha, fragmento ou IP literal. Segredos não devem ser colocados na URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Lista dos eventos documentados. Ao menos um. Ex.: payment.completed e delivery.completed." }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "description": "Filtra pagamentos e saques. Produtos e avaliações são eventos de catálogo, com environment null." }, "enabled": { "type": "boolean", "description": "true ativa; false pausa." } } }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Sistema de pedidos", "url": "https://seu-sistema.com/webhooks/looppay", "events": [ "payment.completed", "delivery.completed" ], "environment": "sandbox", "enabled": false, "version": 2 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } }, "delete": { "operationId": "delete_webhooks__id_", "tags": [ "Webhooks" ], "summary": "Arquivar destino", "description": "Arquiva e desativa o endpoint, preservando o histórico. Envie {} e um Idempotency-Key. Permissão: webhooks:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "archived": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "archived": true }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhooks/{id}/rotate": { "post": { "operationId": "post_webhooks__id__rotate", "tags": [ "Webhooks" ], "summary": "Trocar segredo de assinatura", "description": "Gera e retorna um novo secret apenas na resposta original. O antigo deixa de ser usado nos próximos envios. Atualize o receptor imediatamente; uma requisição já em andamento pode usar o segredo anterior. Permissão: webhooks:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "integer" }, "secret": { "type": "string" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "name": "Sistema de pedidos", "url": "https://seu-sistema.com/webhooks/looppay", "events": [ "payment.completed", "delivery.completed" ], "environment": "sandbox", "enabled": true, "version": 2, "secret": "whsec_NOVO_SEGREDO" }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhooks/{id}/test": { "post": { "operationId": "post_webhooks__id__test", "tags": [ "Webhooks" ], "summary": "Enfileirar evento de teste", "description": "Cria webhook.test para o destino ativo, independente dos eventos selecionados. Não gera pagamentos. HTTP 202 significa enfileirado; acompanhe a entrega. O worker precisa estar agendado. Permissão: webhooks:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "queued": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "eventId": "00000000-0000-4000-8000-000000000001", "queued": true }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "get_webhooks__id__deliveries", "tags": [ "Webhooks" ], "summary": "Listar entregas", "description": "Histórico paginado com HTTP status, tentativas, próxima tentativa e erro. Sem corpo da resposta remota ou segredos. Permissão: webhooks:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event_id": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "http_status": { "type": "integer" }, "error_code": { "type": "string" }, "next_attempt_at": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "items": [ { "id": "00000000-0000-4000-8000-000000000001", "endpoint_id": "00000000-0000-4000-8000-000000000001", "event_id": "00000000-0000-4000-8000-000000000001", "status": "retrying", "attempts": 1, "http_status": 500, "error_code": "http_error", "next_attempt_at": "2026-11-02T18:01:00Z" } ], "total": 1, "page": 1, "limit": 20 }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhook-deliveries/{id}": { "get": { "operationId": "get_webhook_deliveries__id_", "tags": [ "Webhooks" ], "summary": "Inspecionar entrega e tentativas", "description": "Retorna os metadados da entrega, payload do evento e histórico de tentativas. Status: pending, processing, retrying, succeeded, failed e cancelled. Permissão: webhooks:read.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "http_status": { "type": "integer" }, "duration_ms": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] } } } }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "environment": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "amount_cents": { "type": "integer" } } } } } } }, "requestId": { "type": "string" } } }, "example": { "data": { "id": "00000000-0000-4000-8000-000000000001", "status": "succeeded", "attempts": [ { "attempt": 1, "http_status": 200, "duration_ms": 130, "error_code": null } ], "payload": { "id": "00000000-0000-4000-8000-000000000001", "type": "payment.completed", "environment": "sandbox", "data": { "id": "00000000-0000-4000-8000-000000000001", "status": "completed", "amount_cents": 2500 } } }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } }, "/webhook-deliveries/{id}/retry": { "post": { "operationId": "post_webhook_deliveries__id__retry", "tags": [ "Webhooks" ], "summary": "Reprocessar entrega falha", "description": "Somente failed, destino ativo e no máximo 3 reprocessamentos manuais. Enfileira novo ciclo de até 8 tentativas. O event_id continua o mesmo: deduplique no receptor. Envie {}. Permissão: webhooks:write.", "security": [ { "LoopKey": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID único por operação; preserve em novas tentativas.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" } } }, "requestId": { "type": "string" } } }, "example": { "data": { "queued": true }, "requestId": "00000000-0000-4000-8000-000000000001" } } } }, "400": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "404": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "405": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "409": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "413": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "415": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "429": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } }, "503": { "description": "Erro identificado por código e requestId.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string", "format": "uuid" }, "operationId": { "type": "string", "format": "uuid" } } } } } } } } } } }