{ "openapi": "3.1.0", "info": { "title": "API Aprovei", "version": "1.0.0", "description": "API Aprovei para catálogo, pedidos, criação de checkout, PIX e webhooks.\n\n**Autenticação:** API Key Bearer (criada no painel em API Keys) + header `X-Store-Slug` em todas as requisições. A loja alvo é definida por requisição via `X-Store-Slug`.\n\n**Rate limits:** leitura (store, products, search, webhooks) 300 req/min por token+loja; escrita (create-checkout, pix, webhooks) 60 req/min por token+loja; pedidos (orders) compartilham 60 req/min por token+loja; teto global de 600 req/min por IP. Ao receber 429, respeite o header `Retry-After`.\n\n**Webhooks destrutivos:** `webhooks:update` e `webhooks:delete` precisam estar explícitos no token; a ability `*` não cobre essas ações.\n\n**Identificadores:** `productId` e `variantId` compartilham o mesmo espaço de identificadores e são sempre strings. O slug da loja é o identificador público da loja; productId e variantId identificam produtos.", "contact": { "name": "Aprovei Checkout", "url": "https://app.aproveicheckout.com.br/docs" } }, "servers": [ { "url": "https://api.aproveicheckout.com.br/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/orders": { "get": { "operationId": "listOrders", "summary": "Pesquisar pedidos por e-mail ou CPF", "description": "Consulta somente de leitura, isolada por loja. Exige orders:read explícito; * não basta. Reutiliza restrições de IP e vínculo ativo. Limite compartilhado de 60/min por chave+loja nas duas rotas de pedidos, além de 600/min por IP. Cache-Control: no-store. Não registrar credenciais, cabeçalhos de e-mail/CPF ou conteúdo das respostas. Valores em centavos, datas UTC e ausências como null. Não calcula elegibilidade nem vigência de assinatura. Exatamente um dos cabeçalhos X-Customer-Email e X-Customer-CPF é obrigatório. E-mail: trim e minúsculas, comparação exata preservando pontos e +. CPF: 11 dígitos válidos com ou sem máscara, normalizando também dados armazenados. Reúne todos os cadastros correspondentes na loja. Todos os status, criação DESC e ID DESC, sem corte de histórico. Não expandir e-mail para outros e-mails do mesmo CPF.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "X-Customer-Email", "in": "header", "required": false, "description": "Obrigatório se X-Customer-CPF não for enviado; envio simultâneo retorna 422. Não registrar.", "schema": { "type": "string", "format": "email", "maxLength": 254 } }, { "name": "X-Customer-CPF", "in": "header", "required": false, "description": "Obrigatório se X-Customer-Email não for enviado; aceita CPF com máscara ou 11 dígitos válidos, preservando zeros iniciais. CNPJ não é aceito. Não registrar.", "schema": { "type": "string", "pattern": "^(?:[0-9]{11}|[0-9]{3}\\.[0-9]{3}\\.[0-9]{3}-[0-9]{2})$", "example": "012.345.678-90" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Pedidos e paginação. Sem correspondência retorna orders vazio com 200.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Contém no-store." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "orders", "pagination" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "ORDERS_UNAVAILABLE — falha de consulta, inclusive parcial; nunca interpretar como ausência de pedidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl 'https://api.aproveicheckout.com.br/v1/orders?page=1&per_page=20' -H 'Authorization: Bearer CREDENCIAL_FICTICIA' -H 'X-Store-Slug: minha-loja' -H 'Accept: application/json' -H 'X-Customer-Email: cliente@example.com'" } ] } }, "/orders/{orderId}": { "get": { "operationId": "getOrder", "summary": "Consultar pedido por ID", "description": "Consulta somente de leitura, isolada por loja. Exige orders:read explícito; * não basta. Reutiliza restrições de IP e vínculo ativo. Limite compartilhado de 60/min por chave+loja nas duas rotas de pedidos, além de 600/min por IP. Cache-Control: no-store. Não registrar credenciais, cabeçalhos de e-mail/CPF ou conteúdo das respostas. Valores em centavos, datas UTC e ausências como null. Não calcula elegibilidade nem vigência de assinatura. orderId é o ID interno orders.id. Não exige identificador do cliente. Inclui dados completos de atendimento: customer do cadastro atual, shippingAddress do pedido, itens históricos e pagamentos. productId é público (string); internalProductId e parentKitId são internos. Nome/SKU priorizam o histórico e podem vir do cadastro quando ausentes. Preço unitário usa unit_price, price_final, promotional_price ou price do item, nessa ordem; total usa total_price. Nunca usar preço atual do catálogo. Produtos excluídos não removem itens. Pagamentos em criação ASC/ID ASC; gatewayStatus é o valor original, sem conversão. Não expõe dados de cartão, payloads internos, IPs, custos ou comissões.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Detalhe do pedido.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Contém no-store." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/OrderDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "ORDERS_UNAVAILABLE — falha de consulta, inclusive parcial; nunca interpretar como ausência de pedidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "ORDER_NOT_FOUND — pedido inexistente ou pertencente a outra loja.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl 'https://api.aproveicheckout.com.br/v1/orders/123' -H 'Authorization: Bearer CREDENCIAL_FICTICIA' -H 'X-Store-Slug: minha-loja' -H 'Accept: application/json'" } ] } }, "/store": { "get": { "operationId": "getStore", "summary": "Dados públicos da loja", "description": "Retorna os dados públicos da loja associada ao header `X-Store-Slug`. Requer a ability `storefront:read`.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" } ], "responses": { "200": { "description": "Dados da loja", "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/products": { "get": { "operationId": "listProducts", "summary": "Lista o catálogo paginado", "description": "Requer a ability `storefront:read`.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["created_at", "title", "price"] } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Catálogo paginado", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/products/{productId}": { "get": { "operationId": "getProduct", "summary": "Detalhe de um produto", "description": "Requer a ability `storefront:read`.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Produto", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "PRODUCT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/search": { "get": { "operationId": "searchProducts", "summary": "Busca produtos por termo", "description": "Busca por nome, descrição, SKU ou barcode. Requer a ability `storefront:read`.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Resultado da busca", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/cart/create-checkout": { "post": { "operationId": "createCheckout", "summary": "Cria um link de checkout", "description": "Cria um checkout com os itens informados e retorna a URL para redirecionar o comprador. Requer a ability `checkout:create` e o header `Idempotency-Key` (reenviar a mesma chave com o mesmo body faz replay da resposta original). Nenhum campo além de `items` é aceito no body. Cria somente o link/token de checkout; não cria pedido nem cobra o cliente automaticamente.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "additionalProperties": false, "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": ["variantId", "quantity"], "additionalProperties": false, "properties": { "variantId": { "type": "string", "maxLength": 100, "description": "variantId comprável retornado pelo catálogo público" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } } } } } } }, "responses": { "200": { "description": "Checkout criado (ou replay idempotente)", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "skip_cart": { "type": "boolean" }, "checkout_direct_url": { "type": "string", "format": "uri" }, "checkoutUrl": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "IDEMPOTENCY_KEY_MISSING ou STOCK_UNAVAILABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "PRODUCT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "IDEMPOTENCY_KEY_CONFLICT — mesma chave com body diferente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE — Content-Type deve ser application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR ou CHECKOUT_DOMAIN_NOT_CONFIGURED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "Lista os webhooks da loja", "description": "O secret completo nunca é retornado (apenas `secret_preview`). Requer a ability `webhooks:read`.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" } ], "responses": { "200": { "description": "Webhooks da loja", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createWebhook", "summary": "Cria um webhook", "description": "Máximo de 10 webhooks por loja. O secret completo é retornado somente nesta resposta de criação. Em produção a URL deve ser https. Requer a ability `webhooks:create`.\n\n**Entrega:** assinatura no header `X-Aprovei-Signature: sha256=` (HMAC-SHA256 sobre o body JSON bruto, usando o secret); timeout de 5s; até 5 tentativas com backoff de 1min, 5min, 30min e 2h; qualquer resposta 2xx conta como sucesso.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "events"], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } } } } } } }, "responses": { "201": { "description": "Webhook criado — armazene o secret, ele não será exibido novamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR ou WEBHOOK_LIMIT_EXCEEDED (máximo de 10 webhooks por loja)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{webhook}": { "patch": { "operationId": "updateWebhook", "summary": "Edita um webhook", "description": "Atualiza URL, eventos ou status de um webhook da loja. Requer a ability explícita `webhooks:update`; tokens com `*` não autorizam esta ação. O secret não é rotacionado e nunca é retornado completo.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do webhook" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Webhook atualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "WEBHOOK_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteWebhook", "summary": "Deleta um webhook", "description": "Remove um webhook da loja com soft delete. Requer a ability explícita `webhooks:delete`; tokens com `*` não autorizam esta ação. Repetir a exclusão de webhook já deletado da mesma loja retorna 204.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do webhook" } ], "responses": { "204": { "description": "Webhook deletado ou já deletado" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "WEBHOOK_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/pix": { "post": { "operationId": "createPixCharge", "summary": "Cria uma cobrança PIX", "description": "Cria uma cobrança PIX para a loja do header `X-Store-Slug`. Requer a ability `pix:create`.", "parameters": [ { "$ref": "#/components/parameters/StoreSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customer", "items", "payment"], "properties": { "customer": { "type": "object", "required": ["name", "email", "document", "phone"], "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "document": { "type": "string", "maxLength": 20 }, "phone": { "type": "string", "maxLength": 20 }, "address": { "type": "object", "description": "Obrigatório quando algum item tiver isDigital=false.", "properties": { "street": { "type": "string", "maxLength": 255 }, "number": { "type": "string", "maxLength": 20 }, "district": { "type": "string", "maxLength": 100 }, "city": { "type": "string", "maxLength": 100 }, "state": { "type": "string", "maxLength": 2 }, "zipCode": { "type": "string", "maxLength": 10 }, "complement": { "type": "string", "maxLength": 255 } } } } }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["externalRef", "title", "unitPrice", "quantity", "isDigital"], "properties": { "externalRef": { "type": "string", "maxLength": 50 }, "title": { "type": "string", "maxLength": 255 }, "unitPrice": { "type": "integer", "minimum": 1, "description": "Preço unitário em centavos." }, "quantity": { "type": "integer", "minimum": 1 }, "isDigital": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "imageUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "fileUrl": { "type": "string", "format": "uri", "maxLength": 500 } } } }, "payment": { "type": "object", "required": ["paymentMethod", "amount", "freightValue", "discountValue", "currency"], "properties": { "paymentMethod": { "type": "string", "enum": ["pix"] }, "amount": { "type": "integer", "minimum": 1, "description": "Valor total em centavos." }, "freightValue": { "type": "integer", "minimum": 0, "description": "Deve ser 0 em pedidos 100% digitais." }, "discountValue": { "type": "integer", "minimum": 0 }, "externalRef": { "type": "string", "maxLength": 50 }, "currency": { "type": "string", "enum": ["BRL", "USD", "EUR"] } } }, "postbackUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "src": { "type": "string", "maxLength": 100 }, "utm_source": { "type": "string", "maxLength": 100 }, "utm_medium": { "type": "string", "maxLength": 100 }, "utm_campaign": { "type": "string", "maxLength": 100 }, "utm_content": { "type": "string", "maxLength": 100 }, "utm_term": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Cobrança PIX criada", "content": { "application/json": { "schema": { "type": "object", "required": ["data", "message", "status"], "properties": { "data": { "type": "object", "properties": { "transactionToken": { "type": "string" }, "externalRef": { "type": "string", "nullable": true }, "amount": { "type": "integer", "description": "Valor total em centavos." }, "paymentMethod": { "type": "string", "enum": ["pix"] }, "paymentStatus": { "type": "string", "enum": ["pending"] }, "pixCopyPaste": { "type": "string", "nullable": true }, "pixQrCode": { "type": "string", "nullable": true } } }, "message": { "type": "string" }, "status": { "type": "string", "enum": ["success"] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR ou PIX_GATEWAY_NOT_CONFIGURED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API Key criada no painel pelo avatar/menu do usuário > API Keys." } }, "parameters": { "StoreSlug": { "name": "X-Store-Slug", "in": "header", "required": true, "description": "Slug da loja alvo. O dono do token precisa ter vínculo ativo com a loja.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Chave única por checkout. Reenviar a mesma chave com o mesmo body faz replay da resposta original; com body diferente retorna 409.", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "AUTH_MISSING_BEARER_TOKEN ou AUTH_INVALID_BEARER_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "AUTH_STORE_FORBIDDEN (loja sem vínculo ou ability ausente) ou AUTH_IP_NOT_ALLOWED. AUTH_STORE_HEADER_MISSING (400) quando X-Store-Slug está ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "VALIDATION_ERROR — parâmetros inválidos; veja o objeto errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "RATE_LIMIT_EXCEEDED — respeite o header Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "OrderItemSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "productId", "internalProductId", "parentKitId", "quantity" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": [ "string", "null" ] }, "internalProductId": { "type": [ "integer", "null" ] }, "parentKitId": { "type": [ "integer", "null" ] }, "quantity": { "type": [ "integer", "null" ] } } }, "OrderItemDetail": { "type": "object", "additionalProperties": false, "required": [ "id", "productId", "internalProductId", "parentKitId", "quantity", "name", "sku", "unitPriceInCents", "totalPriceInCents", "externalProductId", "externalVariantId", "isCrossSell", "isOrderBump", "isUpsell" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "productId": { "type": [ "string", "null" ] }, "internalProductId": { "type": [ "integer", "null" ] }, "parentKitId": { "type": [ "integer", "null" ] }, "quantity": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "unitPriceInCents": { "type": [ "integer", "null" ] }, "totalPriceInCents": { "type": [ "integer", "null" ] }, "externalProductId": { "type": [ "string", "null" ] }, "externalVariantId": { "type": [ "string", "null" ] }, "isCrossSell": { "type": [ "boolean", "null" ] }, "isOrderBump": { "type": [ "boolean", "null" ] }, "isUpsell": { "type": [ "boolean", "null" ] } } }, "OrderSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "transactionId", "status", "currency", "totalInCents", "createdAt", "updatedAt", "paidAt", "refundedAt", "items" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "transactionId": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "currency": { "type": [ "string", "null" ] }, "totalInCents": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$", "description": "Primeiro orders_payments.paid_at registrado; pode permanecer após estorno." }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItemSummary" } } } }, "OrderShipment": { "type": "object", "required": [ "id", "status", "carrier", "tracking", "postedAt", "deliveredAt", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "waiting_shipping", "in_transit", "delivered" ] }, "carrier": { "type": [ "string", "null" ] }, "tracking": { "type": "array", "items": { "type": "object", "required": [ "number", "url" ], "properties": { "number": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri" } } } }, "postedAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "required": [ "orderItemId", "quantity", "name" ], "properties": { "orderItemId": { "type": "integer" }, "quantity": { "type": "integer", "minimum": 1 }, "name": { "type": [ "string", "null" ], "description": "Nome histórico do item, quando disponível." } } } } } }, "OrderDetail": { "type": "object", "additionalProperties": false, "required": [ "id", "transactionId", "status", "currency", "totalInCents", "createdAt", "updatedAt", "paidAt", "refundedAt", "items", "subtotalInCents", "discountInCents", "shippingInCents", "customer", "shippingAddress", "trackingCode", "deliveryStatus", "payments", "shipments" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "transactionId": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "currency": { "type": [ "string", "null" ] }, "totalInCents": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$", "description": "Primeiro orders_payments.paid_at registrado; pode permanecer após estorno." }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItemDetail" } }, "subtotalInCents": { "type": [ "integer", "null" ] }, "discountInCents": { "type": [ "integer", "null" ] }, "shippingInCents": { "type": [ "integer", "null" ] }, "customer": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "name", "email", "cpf", "phone" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "cpf": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "shippingAddress": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "zipcode", "street", "number", "complement", "neighborhood", "city", "state", "country" ], "properties": { "zipcode": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "complement": { "type": [ "string", "null" ] }, "neighborhood": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "shipments": { "type": "array", "description": "Envios físicos ativos; pagamento e entrega têm estados independentes.", "items": { "$ref": "#/components/schemas/OrderShipment" } }, "trackingCode": { "type": [ "string", "null" ] }, "deliveryStatus": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPayment" } } } }, "OrderPayment": { "type": "object", "additionalProperties": false, "required": [ "id", "method", "gatewayStatus", "amountInCents", "installments", "createdAt", "paidAt" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "method": { "type": [ "string", "null" ] }, "gatewayStatus": { "type": [ "string", "null" ] }, "amountInCents": { "type": [ "integer", "null" ] }, "installments": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" } } }, "Error": { "type": "object", "required": ["status", "code", "message"], "properties": { "status": { "type": "string", "const": "error" }, "code": { "type": "string", "description": "Código estável do erro", "examples": [ "AUTH_MISSING_BEARER_TOKEN", "AUTH_INVALID_BEARER_TOKEN", "AUTH_STORE_HEADER_MISSING", "AUTH_STORE_FORBIDDEN", "AUTH_IP_NOT_ALLOWED", "UNSUPPORTED_MEDIA_TYPE", "VALIDATION_ERROR", "IDEMPOTENCY_KEY_MISSING", "IDEMPOTENCY_KEY_CONFLICT", "CHECKOUT_DOMAIN_NOT_CONFIGURED", "PRODUCT_NOT_FOUND", "STOCK_UNAVAILABLE", "WEBHOOK_LIMIT_EXCEEDED", "RATE_LIMIT_EXCEEDED", "NOT_FOUND", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "errors": { "type": "object", "description": "Detalhes por campo; presente apenas em VALIDATION_ERROR", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "Store": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "domain": { "type": ["string", "null"], "description": "Host do domínio de vendas ativo" }, "logo": { "type": ["string", "null"], "format": "uri" }, "currency": { "type": "object", "properties": { "id": { "type": ["integer", "null"] }, "code": { "type": ["string", "null"] }, "symbol": { "type": ["string", "null"] } } }, "language": { "type": "object", "properties": { "id": { "type": ["integer", "null"] }, "code": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] } } }, "settings": { "type": "object", "properties": { "header": { "type": "object" }, "footer": { "type": "object" }, "cart": { "type": "object", "properties": { "skip_cart": { "type": "boolean" }, "checkoutUrl": { "type": ["string", "null"], "format": "uri" } } }, "theme": { "type": "object" } } } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "Igual a productId" }, "productId": { "type": "string" }, "handle": { "type": "string", "description": "Igual a productId; não use slug de produto" }, "title": { "type": "string" }, "description": { "type": ["string", "null"] }, "image": { "type": ["string", "null"], "format": "uri" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "sku": { "type": ["string", "null"] }, "barcode": { "type": ["string", "null"] }, "productType": { "type": "string", "enum": ["physical", "digital"] }, "availableForSale": { "type": "boolean" }, "priceInCents": { "type": "integer", "description": "Preço efetivo (promocional quando existir)" }, "compareAtPriceInCents": { "type": ["integer", "null"], "description": "Preço cheio quando há promoção; null caso contrário" }, "inventoryQuantity": { "type": ["integer", "null"], "description": "null quando a loja não controla estoque" }, "variants": { "type": "array", "description": "Produtos sem variações expõem a si mesmos como única variante", "items": { "$ref": "#/components/schemas/Variant" } }, "createdAt": { "type": ["string", "null"], "format": "date-time" }, "updatedAt": { "type": ["string", "null"], "format": "date-time" } } }, "Variant": { "type": "object", "properties": { "id": { "type": "string", "description": "Igual a variantId" }, "variantId": { "type": "string", "description": "Use este valor em items[].variantId do create-checkout" }, "title": { "type": "string" }, "sku": { "type": ["string", "null"] }, "barcode": { "type": ["string", "null"] }, "image": { "type": ["string", "null"], "format": "uri" }, "availableForSale": { "type": "boolean" }, "priceInCents": { "type": "integer" }, "compareAtPriceInCents": { "type": ["integer", "null"] }, "inventoryQuantity": { "type": ["integer", "null"] } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret_preview": { "type": "string", "description": "Prévia do secret; o valor completo só é retornado na criação" } } }, "WebhookEvent": { "type": "string", "enum": [ "order.created", "payment.pix.created", "payment.boleto.created", "order.paid", "order.processing", "order.refused", "order.cancelled", "order.chargeback", "order.refunded", "order.expired", "cart.abandoned" ] } } } }