{ "openapi": "3.1.0", "info": { "title": "EADPay API", "version": "1.0.0", "summary": "Checkout multi-gateway: pedidos, produtos, clientes, cupons, webhooks e eventos.", "description": "API REST do EADPay. JSON em camelCase, valores em centavos, datas ISO 8601 (UTC). Autentique com `Authorization: Bearer vt_live_…` (Painel › API). Limite de requisições por chave informado nos headers X-RateLimit-*.", "contact": { "name": "EADPay", "url": "https://checkout.eadmarketing.com.br/docs.html" } }, "servers": [ { "url": "https://checkout.eadmarketing.com.br", "description": "Sua conta EADPay" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Conta" }, { "name": "Pedidos" }, { "name": "Produtos" }, { "name": "Clientes" }, { "name": "Checkouts" }, { "name": "Cupons" }, { "name": "Webhooks" }, { "name": "Eventos" }, { "name": "Recuperação" } ], "paths": { "/api/v1/ping": { "get": { "tags": [ "Conta" ], "operationId": "ping", "summary": "Testar a chave", "responses": { "200": { "description": "Chave válida", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "account": { "type": "string" }, "key": { "type": "string" }, "time": { "type": "string", "format": "date-time" } }, "required": [ "ok" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/orders": { "get": { "tags": [ "Pedidos" ], "operationId": "listOrders", "summary": "Listar pedidos", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Um ou mais status separados por vírgula (pending, waiting_payment, paid, refused, refunded, canceled, chargeback, expired)" }, { "name": "method", "in": "query", "schema": { "enum": [ "card", "pix", "boleto" ] } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "checkoutId", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Criados a partir de (AAAA-MM-DD, horário de Brasília)" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Pedidos (mais recentes primeiro)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Pedidos" ], "operationId": "createOrder", "summary": "Criar pedido / cobrança", "description": "Cria o pedido e cobra no gateway conforme o roteamento. Envie Idempotency-Key para repetir com segurança.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 200 }, "description": "Mesma chave em 24 h devolve a mesma resposta (header Idempotent-Replayed: true)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "201": { "description": "Pedido criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreated" } } } }, "401": { "$ref": "#/components/responses/E401" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/orders/{id}": { "get": { "tags": [ "Pedidos" ], "operationId": "getOrder", "summary": "Consultar pedido", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID ou código do pedido" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/orders/{id}/refund": { "post": { "tags": [ "Pedidos" ], "operationId": "refundOrder", "summary": "Reembolsar pedido", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID ou código do pedido" } ], "responses": { "200": { "description": "Reembolsado", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/orders/{id}/cancel": { "post": { "tags": [ "Pedidos" ], "operationId": "cancelOrder", "summary": "Cancelar pedido pendente", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID ou código do pedido" } ], "responses": { "200": { "description": "Cancelado", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/products": { "get": { "tags": [ "Produtos" ], "operationId": "listProducts", "summary": "Listar produtos", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "active", "in": "query", "schema": { "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Produtos" ], "operationId": "createProduct", "summary": "Criar produto", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "201": { "description": "Criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/products/{id}": { "get": { "tags": [ "Produtos" ], "operationId": "getProduct", "summary": "Consultar produto", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do produto" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "tags": [ "Produtos" ], "operationId": "updateProduct", "summary": "Atualizar produto", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do produto" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Produtos" ], "operationId": "deleteProduct", "summary": "Excluir produto", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do produto" } ], "responses": { "200": { "description": "Excluído", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/customers": { "get": { "tags": [ "Clientes" ], "operationId": "listCustomers", "summary": "Listar clientes", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "email", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/customers/{id}": { "get": { "tags": [ "Clientes" ], "operationId": "getCustomer", "summary": "Consultar cliente (com pedidos)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do cliente" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } } } } ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/checkouts": { "get": { "tags": [ "Checkouts" ], "operationId": "listCheckouts", "summary": "Listar checkouts", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Checkout" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/checkouts/{id}": { "get": { "tags": [ "Checkouts" ], "operationId": "getCheckout", "summary": "Consultar checkout", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID ou slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Checkout" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/coupons": { "get": { "tags": [ "Cupons" ], "operationId": "listCoupons", "summary": "Listar cupons", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Cupons" ], "operationId": "createCoupon", "summary": "Criar cupom", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponInput" } } } }, "responses": { "201": { "description": "Criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Coupon" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/coupons/{id}": { "delete": { "tags": [ "Cupons" ], "operationId": "deleteCoupon", "summary": "Excluir cupom", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do cupom" } ], "responses": { "200": { "description": "Excluído", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "Listar webhooks", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Assinar eventos (criar webhook)", "description": "Cada entrega é um POST JSON (WebhookPayload) assinado: X-Voltra-Signature: t=,v1=HMAC-SHA256(secret, \".\"). Retentativas com espera exponencial.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Criado — guarde o secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Remover webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID do webhook" } ], "responses": { "200": { "description": "Removido", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/events": { "get": { "tags": [ "Eventos" ], "operationId": "listEvents", "summary": "Listar eventos", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filtra por tipo (ex.: order.paid)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/leads": { "get": { "tags": [ "Recuperação" ], "operationId": "listLeads", "summary": "Listar carrinhos (leads)", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "status", "in": "query", "schema": { "enum": [ "open", "abandoned", "recovered", "converted" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/payment-links": { "get": { "tags": [ "Payment-links" ], "operationId": "get_payment_links", "summary": "GET /api/v1/payment-links", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "tags": [ "Payment-links" ], "operationId": "post_payment_links", "summary": "POST /api/v1/payment-links", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/payment-links/{id}": { "get": { "tags": [ "Payment-links" ], "operationId": "get_payment_links_id", "summary": "GET /api/v1/payment-links/{id}", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } }, "delete": { "tags": [ "Payment-links" ], "operationId": "delete_payment_links_id", "summary": "DELETE /api/v1/payment-links/{id}", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/quotes": { "post": { "tags": [ "Quotes" ], "operationId": "post_quotes", "summary": "POST /api/v1/quotes", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/quotes/{id}": { "get": { "tags": [ "Quotes" ], "operationId": "get_quotes_id", "summary": "GET /api/v1/quotes/{id}", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/ticket-events": { "get": { "tags": [ "Ticket-events" ], "operationId": "get_ticket_events", "summary": "GET /api/v1/ticket-events", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/ticket-events/{id}/tickets": { "get": { "tags": [ "Ticket-events" ], "operationId": "get_ticket_events_id_tickets", "summary": "GET /api/v1/ticket-events/{id}/tickets", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/api/v1/tickets/checkin": { "post": { "tags": [ "Tickets" ], "operationId": "post_tickets_checkin", "summary": "POST /api/v1/tickets/checkin", "description": "Rota adicionada por um recurso do EADPay. Corpo e resposta em JSON no padrão { data } / { data, meta }.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } } }, "webhooks": { "order.created": { "post": { "summary": "Pedido criado", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.created" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.waiting_payment": { "post": { "summary": "Aguardando pagamento (PIX ou boleto gerado / cartão em análise)", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.waiting_payment" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.paid": { "post": { "summary": "Pagamento aprovado", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.paid" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.refused": { "post": { "summary": "Pagamento recusado", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.refused" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.refunded": { "post": { "summary": "Pedido reembolsado", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.refunded" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.canceled": { "post": { "summary": "Pedido cancelado", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.canceled" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.chargeback": { "post": { "summary": "Chargeback recebido", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.chargeback" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.expired": { "post": { "summary": "PIX/boleto expirado", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.expired" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "customer.created": { "post": { "summary": "Novo cliente", "description": "Grupo: Clientes. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "customer.created" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "cart.abandoned": { "post": { "summary": "Carrinho abandonado", "description": "Grupo: Recuperação. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "cart.abandoned" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "cart.recovered": { "post": { "summary": "Carrinho recuperado", "description": "Grupo: Recuperação. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "cart.recovered" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.review": { "post": { "summary": "Pedido retido para revisão antifraude", "description": "Grupo: Antifraude. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.review" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "fraud.blocked": { "post": { "summary": "Tentativa bloqueada pelo antifraude", "description": "Grupo: Antifraude. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "fraud.blocked" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.created": { "post": { "summary": "Assinatura criada (1ª cobrança aprovada ou teste grátis iniciado)", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.created" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.renewed": { "post": { "summary": "Assinatura renovada (cobrança recorrente aprovada)", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.renewed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.payment_failed": { "post": { "summary": "Falha na cobrança da assinatura (vai tentar de novo)", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.payment_failed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.canceled": { "post": { "summary": "Assinatura cancelada", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.canceled" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.paused": { "post": { "summary": "Assinatura pausada", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.paused" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.resumed": { "post": { "summary": "Assinatura reativada", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.resumed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.expired": { "post": { "summary": "Assinatura encerrada (limite de ciclos)", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.expired" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.shipped": { "post": { "summary": "Pedido enviado (código de rastreio informado)", "description": "Grupo: Entregas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.shipped" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.delivered": { "post": { "summary": "Pedido entregue", "description": "Grupo: Entregas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.delivered" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "affiliate.created": { "post": { "summary": "Novo afiliado cadastrado", "description": "Grupo: Afiliados. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "affiliate.created" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "affiliate.sale": { "post": { "summary": "Venda de afiliado aprovada", "description": "Grupo: Afiliados. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "affiliate.sale" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "commission.created": { "post": { "summary": "Comissão registrada", "description": "Grupo: Afiliados. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "commission.created" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "commission.available": { "post": { "summary": "Comissão liberada para pagamento", "description": "Grupo: Afiliados. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "commission.available" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "commission.paid": { "post": { "summary": "Comissão paga", "description": "Grupo: Afiliados. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "commission.paid" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "commission.reversed": { "post": { "summary": "Comissão revertida (reembolso/chargeback)", "description": "Grupo: Afiliados. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "commission.reversed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "invoice.issued": { "post": { "summary": "Nota fiscal emitida", "description": "Grupo: Notas fiscais. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "invoice.issued" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "invoice.failed": { "post": { "summary": "Falha na emissão da nota fiscal", "description": "Grupo: Notas fiscais. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "invoice.failed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "invoice.canceled": { "post": { "summary": "Nota fiscal cancelada", "description": "Grupo: Notas fiscais. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "invoice.canceled" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "alert.triggered": { "post": { "summary": "Alerta operacional disparado", "description": "Grupo: Alertas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "alert.triggered" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "download.completed": { "post": { "summary": "Arquivo baixado pelo comprador (link assinado)", "description": "Grupo: Entrega. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "download.completed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "refund.requested": { "post": { "summary": "Reembolso pedido pelo cliente na área do cliente", "description": "Grupo: Entrega. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "refund.requested" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "order.partially_refunded": { "post": { "summary": "Reembolso parcial (um dos cartões do pedido foi estornado)", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "order.partially_refunded" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "payment.retry_scheduled": { "post": { "summary": "Retentativa de cobrança agendada", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "payment.retry_scheduled" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "payment.recovered": { "post": { "summary": "Cobrança recuperada pela retentativa inteligente", "description": "Grupo: Pedidos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "payment.recovered" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "pix_automatic.authorized": { "post": { "summary": "Pix Automático autorizado pelo pagador", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "pix_automatic.authorized" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "pix_automatic.canceled": { "post": { "summary": "Pix Automático cancelado", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "pix_automatic.canceled" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "pix_automatic.refused": { "post": { "summary": "Pix Automático recusado ou expirado", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "pix_automatic.refused" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.plan_changed": { "post": { "summary": "Assinatura trocou de plano", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.plan_changed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "subscription.plan_change_scheduled": { "post": { "summary": "Troca de plano agendada para o fim do período", "description": "Grupo: Assinaturas. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "subscription.plan_change_scheduled" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "launch.waitlist_joined": { "post": { "summary": "Nova inscrição na lista de espera de um lançamento", "description": "Grupo: Lançamentos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "launch.waitlist_joined" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "launch.opened": { "post": { "summary": "Carrinho do lançamento abriu (lista de espera avisada)", "description": "Grupo: Lançamentos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "launch.opened" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "campaign.sent": { "post": { "summary": "Campanha de e-mail concluída", "description": "Grupo: Relacionamento. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "campaign.sent" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "campaign.clicked": { "post": { "summary": "Contato clicou numa campanha", "description": "Grupo: Relacionamento. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "campaign.clicked" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "contact.unsubscribed": { "post": { "summary": "Contato se descadastrou das campanhas", "description": "Grupo: Relacionamento. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "contact.unsubscribed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "referral.rewarded": { "post": { "summary": "Indicação recompensada", "description": "Grupo: Relacionamento. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "referral.rewarded" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "cashback.earned": { "post": { "summary": "Cashback liberado para o cliente", "description": "Grupo: Relacionamento. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "cashback.earned" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "payment_link.paid": { "post": { "summary": "Link de pagamento pago", "description": "Grupo: Canais de venda. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "payment_link.paid" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "quote.accepted": { "post": { "summary": "Orçamento aceito pelo cliente", "description": "Grupo: Canais de venda. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "quote.accepted" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "quote.declined": { "post": { "summary": "Orçamento recusado pelo cliente", "description": "Grupo: Canais de venda. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "quote.declined" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "quote.paid": { "post": { "summary": "Orçamento pago", "description": "Grupo: Canais de venda. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "quote.paid" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "ticket.issued": { "post": { "summary": "Ingresso emitido", "description": "Grupo: Ingressos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "ticket.issued" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "ticket.checked_in": { "post": { "summary": "Check-in de ingresso", "description": "Grupo: Ingressos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "ticket.checked_in" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "ticket.transferred": { "post": { "summary": "Ingresso transferido", "description": "Grupo: Ingressos. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "ticket.transferred" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "consent.updated": { "post": { "summary": "Consentimento de marketing alterado (LGPD)", "description": "Grupo: Privacidade. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "consent.updated" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "privacy.request": { "post": { "summary": "Pedido do titular registrado ou atualizado (LGPD)", "description": "Grupo: Privacidade. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "privacy.request" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "privacy.anonymized": { "post": { "summary": "Dados de um titular eliminados/anonimizados (LGPD)", "description": "Grupo: Privacidade. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "privacy.anonymized" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "dispute.opened": { "post": { "summary": "Disputa/chargeback aberta", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "dispute.opened" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "dispute.evidence_submitted": { "post": { "summary": "Provas da disputa enviadas", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "dispute.evidence_submitted" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "dispute.won": { "post": { "summary": "Disputa ganha", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "dispute.won" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "dispute.lost": { "post": { "summary": "Disputa perdida", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "dispute.lost" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "payout.paid": { "post": { "summary": "Repasse/transferência concluída", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "payout.paid" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "payout.failed": { "post": { "summary": "Repasse/transferência falhou", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "payout.failed" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } }, "finance.divergence": { "post": { "summary": "Divergência na conciliação", "description": "Grupo: Financeiro. Assinado com X-Voltra-Signature.", "parameters": [ { "name": "X-Voltra-Event", "in": "header", "schema": { "type": "string", "const": "finance.divergence" } }, { "name": "X-Voltra-Signature", "in": "header", "schema": { "type": "string" } }, { "name": "X-Voltra-Delivery", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Responda 2xx em até 10 s" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "vt_live_…", "description": "Também aceito no header X-Api-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Código estável do erro", "examples": [ "validation_error", "not_found", "unauthorized", "rate_limited" ] }, "message": { "type": "string", "description": "Mensagem em português para exibir" }, "fields": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Erros por campo (validação)" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 1 } }, "required": [ "page", "limit", "total", "pages" ] }, "Address": { "type": "object", "properties": { "zip": { "type": "string", "description": "CEP" }, "street": { "type": "string", "description": "Logradouro" }, "number": { "type": "string", "description": "Número" }, "complement": { "type": "string", "description": "Complemento" }, "neighborhood": { "type": "string", "description": "Bairro" }, "city": { "type": "string", "description": "Cidade" }, "state": { "type": "string", "description": "UF", "minLength": 2, "maxLength": 2 } }, "additionalProperties": true }, "CustomerInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome completo", "minLength": 3 }, "email": { "type": "string", "description": "E-mail", "format": "email" }, "document": { "type": "string", "description": "CPF ou CNPJ (só números ou formatado)" }, "phone": { "type": "string", "description": "Celular com DDD" }, "address": { "$ref": "#/components/schemas/Address" } }, "required": [ "name", "email" ] }, "OrderItem": { "type": "object", "properties": { "productId": { "type": "string", "description": "Produto" }, "name": { "type": "string", "description": "Nome do produto" }, "price": { "type": "integer", "description": "Preço unitário (centavos)", "examples": [ 49700 ] }, "quantity": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "description": "main | bump | item | shipping" } }, "required": [ "name", "price" ], "additionalProperties": true }, "Card": { "type": "object", "properties": { "brand": { "type": "string", "description": "Bandeira" }, "last4": { "type": "string", "description": "Últimos 4 dígitos" }, "holder": { "type": "string", "description": "Nome impresso" } }, "additionalProperties": true }, "Pix": { "type": "object", "properties": { "qrCode": { "type": "string", "description": "PIX copia e cola (EMV)" }, "qrCodeUrl": { "type": "string", "description": "Imagem do QR Code" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Validade" } }, "additionalProperties": true }, "Boleto": { "type": "object", "properties": { "line": { "type": "string", "description": "Linha digitável" }, "barcode": { "type": "string", "description": "Código de barras" }, "url": { "type": "string", "description": "Link do boleto" }, "dueDate": { "type": "string", "description": "Vencimento (AAAA-MM-DD)" } }, "additionalProperties": true }, "HistoryEntry": { "type": "object", "properties": { "status": { "enum": [ "pending", "waiting_payment", "paid", "refused", "refunded", "canceled", "chargeback", "expired" ] }, "at": { "type": "string", "format": "date-time" }, "note": { "type": "string", "description": "Registro" } }, "required": [ "status", "at" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do pedido", "examples": [ "ord_8f2k1x" ] }, "code": { "type": "string", "description": "Código curto exibido ao cliente", "examples": [ "VT-10482" ] }, "status": { "enum": [ "pending", "waiting_payment", "paid", "refused", "refunded", "canceled", "chargeback", "expired" ] }, "checkoutId": { "type": [ "string", "null" ] }, "checkoutName": { "type": [ "string", "null" ] }, "customerId": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] } }, "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "subtotal": { "type": "integer", "description": "Subtotal (centavos)", "examples": [ 49700 ] }, "discount": { "type": "integer", "description": "Descontos (centavos)", "examples": [ 49700 ] }, "interest": { "type": "integer", "description": "Juros do parcelamento (centavos)", "examples": [ 49700 ] }, "total": { "type": "integer", "description": "Total cobrado (centavos)", "examples": [ 49700 ] }, "currency": { "type": "string", "description": "Moeda ISO 4217", "examples": [ "BRL" ] }, "coupon": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "discount": { "type": "integer", "description": "Desconto do cupom (centavos)", "examples": [ 49700 ] } } }, { "type": "null" } ] }, "method": { "enum": [ "card", "pix", "boleto" ] }, "installments": { "type": "integer", "minimum": 1, "maximum": 12 }, "gatewayId": { "type": [ "string", "null" ] }, "gateway": { "type": [ "string", "null" ], "description": "pagarme | appmax | mercadopago | asaas | stripe | sandbox" }, "gatewayName": { "type": [ "string", "null" ] }, "transactionId": { "type": [ "string", "null" ] }, "pix": { "anyOf": [ { "$ref": "#/components/schemas/Pix" }, { "type": "null" } ] }, "boleto": { "anyOf": [ { "$ref": "#/components/schemas/Boleto" }, { "type": "null" } ] }, "card": { "anyOf": [ { "$ref": "#/components/schemas/Card" }, { "type": "null" } ] }, "utm": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "source": { "type": "string", "description": "checkout | api | subscription | …" }, "metadata": { "type": "object", "additionalProperties": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryEntry" } }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Aprovação" }, "refundedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Reembolso" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "code", "status", "total", "method", "createdAt" ], "additionalProperties": true, "description": "Pedido. Recursos podem acrescentar campos (ex.: invoice, subscriptionId, payments, tracking)." }, "OrderCreate": { "type": "object", "properties": { "checkoutId": { "type": "string", "description": "ID ou slug do checkout (usa produto, order bumps, métodos e parcelas do checkout)" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, "required": [ "productId" ] }, "description": "Sem checkout: produtos avulsos" }, "customer": { "$ref": "#/components/schemas/CustomerInput" }, "method": { "enum": [ "card", "pix", "boleto" ] }, "installments": { "type": "integer", "minimum": 1, "maximum": 12 }, "card": { "type": "object", "properties": { "number": { "type": "string", "description": "Número (só com PCI) — prefira tokens" }, "holder": { "type": "string" }, "expMonth": { "type": "string" }, "expYear": { "type": "string" }, "cvv": { "type": "string" }, "installments": { "type": "integer" }, "tokens": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Token do cartão por ID de gateway (VoltraCheckout.tokenize)" } } }, "coupon": { "type": "string", "description": "Código do cupom" }, "bumps": { "type": "array", "items": { "type": "string" }, "description": "IDs dos order bumps aceitos" }, "utm": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "content": { "type": "string" }, "term": { "type": "string" } } }, "metadata": { "type": "object", "additionalProperties": true }, "ip": { "type": "string", "description": "IP do comprador (antifraude)" } }, "required": [ "customer", "method" ] }, "OrderCreated": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" }, "message": { "type": "string", "description": "Mensagem para o comprador" }, "paymentUrl": { "type": "string", "description": "Página do pedido (PIX/boleto/3DS)", "format": "uri" } }, "required": [ "data" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "integer", "description": "Preço (centavos)", "examples": [ 49700 ] }, "description": { "type": "string" }, "type": { "enum": [ "digital", "physical", "service" ] }, "image": { "type": "string" }, "sku": { "type": "string" }, "deliveryUrl": { "type": "string" }, "active": { "type": "boolean" }, "ext": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "price" ], "additionalProperties": true }, "ProductInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 140 }, "price": { "type": "integer", "description": "Preço (centavos)", "examples": [ 49700 ] }, "description": { "type": "string" }, "type": { "enum": [ "digital", "physical", "service" ] }, "image": { "type": "string" }, "sku": { "type": "string" }, "deliveryUrl": { "type": "string", "format": "uri" }, "active": { "type": "boolean" } }, "required": [ "name", "price" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "ordersCount": { "type": "integer" }, "paidCount": { "type": "integer" }, "totalSpent": { "type": "integer", "description": "Total gasto (centavos)", "examples": [ 49700 ] }, "lastOrderAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Último pedido" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "email" ], "additionalProperties": true }, "OrderSummary": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "waiting_payment", "paid", "refused", "refunded", "canceled", "chargeback", "expired" ] }, "method": { "type": "string" }, "total": { "type": "integer", "description": "Total (centavos)", "examples": [ 49700 ] }, "installments": { "type": "integer" } }, "required": [ "id", "code", "status" ], "additionalProperties": true }, "Checkout": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productId": { "type": "string" }, "active": { "type": "boolean" }, "methods": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug" ], "additionalProperties": true }, "Coupon": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "type": { "enum": [ "percent", "fixed" ] }, "value": { "type": "number", "description": "percent: 1–100 · fixed: centavos" }, "active": { "type": "boolean" }, "maxUses": { "type": [ "integer", "null" ] }, "uses": { "type": "integer" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Validade" }, "checkoutIds": { "type": "array", "items": { "type": "string" } }, "state": { "enum": [ "active", "inactive", "expired", "exhausted" ] } }, "required": [ "id", "code", "type", "value" ], "additionalProperties": true }, "CouponInput": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{3,30}$" }, "type": { "enum": [ "percent", "fixed" ], "default": "percent" }, "value": { "type": "number" }, "active": { "type": "boolean" }, "maxUses": { "type": [ "integer", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "description": "AAAA-MM-DD ou ISO 8601" }, "checkoutIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "value" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "format": { "enum": [ "json", "discord", "slack" ] }, "active": { "type": "boolean" }, "secret": { "type": "string", "description": "Segredo HMAC (completo só na criação)" }, "checkoutIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events" ], "additionalProperties": true }, "WebhookInput": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Tipos de evento ou [\"*\"]" }, "format": { "enum": [ "json", "discord", "slack" ], "default": "json" }, "active": { "type": "boolean" }, "checkoutIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "examples": [ "order.paid" ] }, "data": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "createdAt" ], "additionalProperties": true }, "Lead": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": [ "open", "abandoned", "recovered", "converted" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "value": { "type": "integer", "description": "Valor do carrinho (centavos)", "examples": [ 49700 ] }, "checkoutId": { "type": [ "string", "null" ] }, "recoveryUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status" ], "additionalProperties": true }, "WebhookPayload": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do evento" }, "type": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "createdAt", "data" ] } }, "parameters": { "page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } }, "headers": { "RateLimitLimit": { "schema": { "type": "integer" }, "description": "Requisições permitidas na janela" }, "RateLimitRemaining": { "schema": { "type": "integer" }, "description": "Restantes na janela" }, "RateLimitReset": { "schema": { "type": "integer" }, "description": "Unix time do fim da janela" } }, "responses": { "E401": { "description": "Chave ausente ou inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Chave de API inválida" } } } } }, "E404": { "description": "Não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Pedido não encontrado" } } } } }, "E409": { "description": "Conflito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Produto em uso por checkouts" } } } } }, "E422": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "Confira os campos", "fields": { "customer.email": "E-mail inválido" } } } } } }, "E429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Muitas requisições — aguarde alguns segundos" } } } } } } } }