{ "openapi": "3.0.0", "paths": { "/v1/auth/login": { "post": { "description": "Autentica um usuario e devolve access token (curta duracao) e refresh token. Os escopos da sessao vem do papel do usuario. Esta rota e do painel: integracoes por API usam chave de API, nao login.", "operationId": "Auth_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "minLength": 1, "maxLength": 256 }, "mfaCode": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "email", "password" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "email": "admin@minstrel.local", "password": "Minstrel@2026" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Entrar no painel", "tags": [ "Autenticacao" ] } }, "/v1/auth/refresh": { "post": { "description": "Troca o refresh token por um novo par. O refresh token e rotacionado a cada uso, de modo que um token roubado tem janela curta de utilidade.", "operationId": "Auth_refresh", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 16, "maxLength": 2048 } }, "required": [ "refreshToken" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "summary": "Renovar a sessao", "tags": [ "Autenticacao" ] } }, "/v1/auth/me": { "get": { "description": "Usuario, organizacao e escopos efetivos da credencial em uso.", "operationId": "Auth_me", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Dados da sessao atual", "tags": [ "Autenticacao" ] } }, "/v1/auth/logout": { "post": { "description": "Invalida todos os refresh tokens do usuario de uma vez, avancando `tokensValidAfter`.", "operationId": "Auth_logout", "parameters": [], "responses": { "201": { "description": "" } }, "summary": "Encerrar todas as sessoes", "tags": [ "Autenticacao" ] } }, "/v1/auth/change-password": { "post": { "description": "Exige a senha atual. A troca encerra as outras sessoes: se foi motivada por suspeita de acesso indevido, manter as sessoes anularia o efeito.", "operationId": "Auth_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 }, "newPassword": { "type": "string", "minLength": 12, "maxLength": 256 } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "summary": "Trocar a propria senha", "tags": [ "Autenticacao" ] } }, "/health/live": { "get": { "operationId": "Health_live", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Liveness: o processo esta respondendo", "tags": [ "Saude" ] } }, "/health/ready": { "get": { "operationId": "Health_ready", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Readiness: dependencias disponiveis", "tags": [ "Saude" ] } }, "/health": { "get": { "description": "Versao da API, conectores carregados e cobertura da tabela de codigos de recusa. Util para confirmar o que esta de fato instalado.", "operationId": "Health_info", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Informacoes da instalacao", "tags": [ "Saude" ] } }, "/v1/connectors": { "get": { "description": "Parceiros que o Minstrel integra, com capacidades e o schema das credenciais de cada um. `available: false` indica parceiro em breve. Filtre por `kind` (ex.: `antifraud`) ou `capability`.", "operationId": "Connectors_catalog", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Catalogo de conectores", "tags": [ "Conectores" ] } }, "/v1/connectors/{slug}/verify": { "post": { "description": "Faz uma chamada leve ao parceiro com as credenciais informadas, sem grava-las. Resultado: `valid`, `invalid` (o parceiro recusou) ou `unreachable` (nao foi possivel contatar). Limite de 20 testes por minuto por organizacao.", "operationId": "Connectors_verifyUnsaved", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192 }, "default": {} }, "config": { "type": "object", "additionalProperties": {}, "default": {} } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "credentials": { "privateKey": "T00000111112222233333" } } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Testar credenciais antes de salvar", "tags": [ "Conectores" ] } }, "/v1/connector-accounts": { "get": { "description": "Contas do ambiente da credencial. Credenciais nunca sao devolvidas: cada campo informa apenas se esta preenchido, com um trecho mascarado quando nao e secreto. `capability` filtra pelas capacidades EFETIVAS da conta (`effectiveCapabilities`), nao pelas do catalogo. Cada conta traz `usedByFlows`: os fluxos publicados que a citam (enquanto houver um, a remocao e recusada).", "operationId": "Connectors_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar contas de conector", "tags": [ "Conectores" ] }, "post": { "description": "As credenciais sao validadas contra o schema do conector e gravadas cifradas (AES-256-GCM). Com `verify: true`, sao testadas no parceiro antes - se falharem, nada e gravado.", "operationId": "Connectors_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorSlug": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "credentials": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192 }, "default": {} }, "config": { "type": "object", "additionalProperties": {}, "default": {} }, "costBasisPoints": { "type": "integer", "minimum": 0, "maximum": 10000 }, "enabled": { "type": "boolean", "default": true }, "verify": { "type": "boolean", "default": false } }, "required": [ "connectorSlug", "name" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "connectorSlug": "konduto", "name": "Konduto - principal", "credentials": { "privateKey": "T00000111112222233333" }, "verify": true } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cadastrar uma conta de conector", "tags": [ "Conectores" ] } }, "/v1/connector-accounts/{id}": { "get": { "description": "Inclui os fluxos publicados que usam a conta (`usedByFlows`). Conta de outro ambiente responde 404.", "operationId": "Connectors_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar uma conta de conector", "tags": [ "Conectores" ] }, "patch": { "description": "Credencial omitida ou vazia mantem o valor atual. Trocar credencial zera o historico de saude da conta. `config` e mesclada com a atual (envie so o que mudou; `null` volta ao padrao) e validada contra o `configSchema` do conector.", "operationId": "Connectors_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "credentials": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 8192 } }, "config": { "type": "object", "additionalProperties": {} }, "costBasisPoints": { "type": "integer", "minimum": 0, "maximum": 10000, "nullable": true }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "enabled": false } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Atualizar uma conta de conector", "tags": [ "Conectores" ] }, "delete": { "description": "Recusado (409) quando a conta esta em fluxo publicado. Para tirar um parceiro do ar na hora, desabilite a conta.", "operationId": "Connectors_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Remover uma conta de conector", "tags": [ "Conectores" ] } }, "/v1/connector-accounts/{id}/verify": { "post": { "description": "Usa as credenciais gravadas e atualiza a saude exibida no painel.", "operationId": "Connectors_verifyStored", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Testar a conexao de uma conta salva", "tags": [ "Conectores" ] } }, "/v1/webhooks/event-types": { "get": { "description": "Eventos que um endpoint pode assinar, agrupados por recurso. Cada grupo traz o curinga (`payment.*`) que inclui os eventos atuais e futuros do recurso.", "operationId": "Webhooks_eventTypes", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Catalogo de eventos", "tags": [ "Webhooks" ] } }, "/v1/webhooks/summary": { "get": { "description": "Endpoints ativos, entregas e taxa de sucesso nas ultimas 24 horas comparadas as 24 anteriores.", "operationId": "Webhooks_summary", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Indicadores de entrega", "tags": [ "Webhooks" ] } }, "/v1/webhooks": { "get": { "description": "Inclui taxa de sucesso, entregas por hora nas ultimas 24 horas e a ultima entrega. Nunca inclui o segredo.", "operationId": "Webhooks_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar endpoints", "tags": [ "Webhooks" ] }, "post": { "description": "A resposta traz `secret` (whsec_...) uma unica vez: guarde-o para verificar o cabecalho `Minstrel-Signature`. Em producao a URL precisa ser https; em sandbox, http://localhost tambem e aceito.", "operationId": "Webhooks_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": { "type": "string", "maxLength": 500 }, "enabledEvents": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 100 }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 } }, "enabled": { "type": "boolean" } }, "required": [ "url", "enabledEvents" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "url": "https://api.sualoja.com.br/webhooks/minstrel", "description": "Confirma pedidos pagos e avisa recusas", "enabledEvents": [ "payment.captured", "payment.failed", "invoice.*" ], "customHeaders": { "X-Api-Key": "chave-do-seu-servidor" } } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cadastrar um endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}": { "get": { "operationId": "Webhooks_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um endpoint", "tags": [ "Webhooks" ] }, "patch": { "description": "Cabecalhos extras sao mesclados: texto cria ou substitui, `null` remove. Desativar cancela as entregas na fila; reativar zera as falhas seguidas.", "operationId": "Webhooks_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": { "type": "string", "maxLength": 500, "nullable": true }, "enabledEvents": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 100 }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024, "nullable": true } }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "enabledEvents": [ "*" ], "enabled": true } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Alterar um endpoint", "tags": [ "Webhooks" ] }, "delete": { "description": "Remocao logica: entregas e eventos continuam consultaveis. As entregas na fila sao canceladas.", "operationId": "Webhooks_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Remover um endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "description": "Gera um segredo novo, devolvido uma unica vez. Com `gracePeriod: 24h` (padrao) o segredo atual continua assinando por 24 horas junto com o novo; com `none` ele deixa de valer na hora.", "operationId": "Webhooks_rotateSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gracePeriod": { "type": "string", "enum": [ "24h", "none" ], "default": "24h" } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "gracePeriod": "24h" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Rotacionar o segredo", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/reveal-secret": { "post": { "description": "Fica registrado na auditoria da organizacao.", "operationId": "Webhooks_revealSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Revelar o segredo", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/test": { "post": { "description": "Cria um evento `webhook_endpoint.test` e o entrega na hora, assinado, so para este endpoint. A resposta e a entrega, com o status e o corpo devolvidos pelo seu servidor.", "operationId": "Webhooks_sendTest", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Enviar evento de teste", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "description": "Filtros: `status` (lista separada por virgula), `eventType` (aceita `payment.*`), periodo e id.", "operationId": "Webhooks_listDeliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Listar entregas de um endpoint", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/deliveries/{deliveryId}": { "get": { "description": "Corpo exato enviado (o que foi assinado), cabecalhos, resposta do endpoint truncada em 8 KB e tentativas.", "operationId": "Webhooks_getDelivery", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "deliveryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar uma entrega", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/retry": { "post": { "description": "Zera as tentativas e coloca a entrega na fila; ela sai em poucos segundos.", "operationId": "Webhooks_retryDelivery", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "deliveryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Reenviar uma entrega", "tags": [ "Webhooks" ] } }, "/v1/events": { "get": { "description": "Do mais novo para o mais antigo, no mesmo envelope entregue aos webhooks. Filtre por `type` (aceita `payment.*`), `objectType`, `objectId` e periodo. Com `webhooks:read`, cada evento traz a situacao das entregas.", "operationId": "EventLog_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar eventos", "tags": [ "Eventos" ] } }, "/v1/events/{id}": { "get": { "description": "Payload completo e, com `webhooks:read`, cada entrega do evento com o status por endpoint.", "operationId": "EventLog_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um evento", "tags": [ "Eventos" ] } }, "/v1/payments": { "post": { "description": "Cria e processa um pagamento. O roteamento entre adquirentes segue o fluxo publicado no ambiente. Envie o header `Idempotency-Key` para que uma repeticao por falha de rede nao gere cobranca duplicada. Dados sensiveis de cartao (numero, CVV) sao recusados com HTTP 422: use o token do cofre. Com `methodType: pix` ou `boleto`, o pagamento volta `requires_action` com o QR Code ou a linha digitavel em `nextAction` e so vira `captured` quando o banco confirma (webhook conferido na consulta, ou a consulta periodica). Pix e boleto exigem `customerId` com nome e CPF/CNPJ valido (boleto, tambem o endereco completo). Cartao sem `card` e sem `paymentMethodId` e o checkout transparente: o pagamento nasce `requires_payment_method` (nada vai ao adquirente) e a resposta traz `clientSecret`, que o navegador do portador usa para tokenizar o cartao e confirmar. `tokenizationAccountId` escolhe a conta que tokeniza e cobra; sem ele, vale a unica conta habilitada que tokeniza no navegador (nenhuma ou mais de uma e erro 422). O pagamento vence em 24 horas.", "operationId": "Payments_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 }, "currency": { "type": "string", "enum": [ "BRL", "USD", "EUR", "GBP", "ARS", "CLP", "MXN" ], "default": "BRL" }, "methodType": { "type": "string", "enum": [ "card", "pix", "boleto" ], "default": "card" }, "pix": { "type": "object", "properties": { "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 3600 } }, "additionalProperties": false }, "boleto": { "type": "object", "properties": { "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "daysAfterDue": { "type": "integer", "minimum": 0, "maximum": 60, "default": 0 }, "instructions": { "type": "string", "maxLength": 255 }, "fineBps": { "type": "integer", "minimum": 0, "maximum": 2000 }, "interestMonthlyBps": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "additionalProperties": false }, "customerId": { "type": "string", "maxLength": 64 }, "paymentMethodId": { "type": "string", "maxLength": 64 }, "tokenizationAccountId": { "type": "string", "maxLength": 64 }, "card": { "type": "object", "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 256 }, "isNetworkToken": { "type": "boolean", "default": false }, "brand": { "type": "string", "maxLength": 32 }, "bin": { "type": "string", "pattern": "^\\d{6,8}$" }, "last4": { "type": "string", "pattern": "^\\d{4}$" }, "expMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "expYear": { "type": "integer", "minimum": 2024, "maximum": 2099 }, "holderName": { "type": "string", "maxLength": 120 }, "connectorAccountId": { "type": "string", "maxLength": 64 } }, "required": [ "token" ], "additionalProperties": false }, "captureMethod": { "type": "string", "enum": [ "automatic", "manual" ], "default": "automatic" }, "installments": { "type": "integer", "minimum": 1, "maximum": 24, "default": 1 }, "initiator": { "type": "string", "enum": [ "customer", "merchant" ], "default": "customer" }, "mitType": { "type": "string", "enum": [ "recurring", "installment", "unscheduled", "reauthorization", "resubmission", "delayed_charge", "incremental", "no_show" ] }, "softDescriptor": { "type": "string", "maxLength": 22 }, "description": { "type": "string", "maxLength": 255 }, "externalId": { "type": "string", "maxLength": 128 }, "splits": { "type": "array", "items": { "type": "object", "properties": { "recipientId": { "type": "string", "maxLength": 64 }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "integer", "minimum": 0 }, "liableForChargeback": { "type": "boolean" }, "chargeProcessingFee": { "type": "boolean" } }, "required": [ "recipientId", "type", "value" ], "additionalProperties": false }, "maxItems": 20 }, "splitRemainderRecipientId": { "type": "string", "maxLength": 64 }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 } }, "required": [ "name", "quantity", "amount" ], "additionalProperties": false }, "maxItems": 100 }, "clientIp": { "type": "string", "maxLength": 64 }, "clientUserAgent": { "type": "string", "maxLength": 512 }, "flowId": { "type": "string", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "amount" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "amount": 14990, "currency": "BRL", "customerId": "cus_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "paymentMethodId": "pm_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "captureMethod": "automatic", "installments": 1, "initiator": "customer", "softDescriptor": "MINHALOJA", "description": "Pedido 1234", "externalId": "pedido-1234", "metadata": { "canal": "app", "campanha": "black-friday" } } } } } } }, "responses": { "201": { "description": "Pagamento criado e processado. Recusa do emissor nao e erro HTTP: o pagamento volta com `status: failed` e o motivo em `decline` (classificacao ABECS)." }, "409": { "description": "Conflito de idempotencia." }, "422": { "description": "Dados invalidos ou dado sensivel de cartao recusado." } }, "summary": "Criar um pagamento", "tags": [ "Pagamentos" ] }, "get": { "description": "Lista paginada por cursor, do mais recente para o mais antigo. Cada item traz o resumo das tentativas: quantas foram, o conector que decidiu, se houve fallback e o motivo da ultima recusa. Use `declineReason` para investigar recusas por motivo canonico (ex.: INSUFFICIENT_FUNDS). A primeira pagina traz `totalCount` com o total do recorte.", "operationId": "Payments_list", "parameters": [ { "name": "startingAfter", "required": false, "in": "query", "description": "Cursor: id do ultimo item da pagina anterior.", "schema": {} }, { "name": "limit", "required": false, "in": "query", "description": "De 1 a 100. Padrao 25.", "schema": {} }, { "name": "createdBefore", "required": false, "in": "query", "description": "Data/hora ISO 8601.", "schema": {} }, { "name": "createdAfter", "required": false, "in": "query", "description": "Data/hora ISO 8601.", "schema": {} }, { "name": "hasFallback", "required": false, "in": "query", "description": "true: so pagamentos com mais de uma tentativa.", "schema": {} }, { "name": "search", "required": false, "in": "query", "description": "Id, externalId, descricao, nome/e-mail/documento do cliente, final do cartao, NSU, TID ou codigo de autorizacao.", "schema": {} }, { "name": "amountMax", "required": false, "in": "query", "description": "Valor maximo, em centavos.", "schema": {} }, { "name": "amountMin", "required": false, "in": "query", "description": "Valor minimo, em centavos.", "schema": {} }, { "name": "initiator", "required": false, "in": "query", "description": "CIT (customer) ou MIT (merchant).", "schema": { "enum": [ "customer", "merchant" ], "type": "string" } }, { "name": "methodType", "required": false, "in": "query", "description": "Meio de pagamento. Ex.: card,pix.", "schema": {} }, { "name": "brand", "required": false, "in": "query", "description": "Bandeira do cartao. Ex.: visa,mastercard.", "schema": {} }, { "name": "connector", "required": false, "in": "query", "description": "Slug do conector (todas as contas dele). Ex.: cielo.", "schema": {} }, { "name": "connectorAccountId", "required": false, "in": "query", "description": "Conta(s) de conector com ao menos uma tentativa no pagamento.", "schema": {} }, { "name": "status", "required": false, "in": "query", "description": "Um ou mais status separados por virgula. Ex.: captured,authorized.", "schema": {} } ], "responses": { "200": { "description": "" } }, "summary": "Listar pagamentos", "tags": [ "Pagamentos" ] } }, "/v1/payments/summary": { "get": { "description": "Total, aprovadas, recusadas, taxa de aprovacao (basis points), volume capturado, ticket medio, estornos e valor recuperado por fallback ou retentativa no periodo, com os mesmos numeros do periodo anterior de igual duracao e uma serie (por hora ate 2 dias, por dia acima disso) para minigraficos. Inclui o desempenho por conta de conector. Sem `from`, considera os ultimos 30 dias.", "operationId": "Payments_summary", "parameters": [ { "name": "to", "required": false, "in": "query", "description": "Fim do periodo (ISO 8601). Padrao: agora.", "schema": {} }, { "name": "from", "required": false, "in": "query", "description": "Inicio do periodo (ISO 8601).", "schema": {} } ], "responses": { "200": { "description": "" } }, "summary": "Indicadores de pagamentos", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}": { "get": { "description": "Devolve o pagamento com todas as tentativas (conector acionado, codigo bruto do emissor, classificacao ABECS e latencia de cada uma), o motivo de o roteamento ter parado onde parou, a execucao do fluxo passo a passo, a analise antifraude, as operacoes (captura, cancelamento, estorno), splits, estornos, contestacoes, a linha do tempo de eventos e as acoes possiveis no estado atual. Traz `clientSecret` enquanto o pagamento esta `requires_payment_method` ou `requires_action` (nulo depois).", "operationId": "Payments_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um pagamento", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}/confirm": { "post": { "description": "Checkout transparente pelo servidor do lojista: confirma um pagamento `requires_payment_method` com o token de uso unico que o navegador gerou, e o processa (fluxo publicado ou roteamento direto) como cobranca com o cliente presente. `saveCard: true` e o consentimento do portador para guardar o cartao: exige `customerId` no pagamento e, aprovado, o token vira cartao salvo na carteira do cliente. Recusa do emissor nao e erro HTTP: o pagamento volta `failed` com `decline`, e uma nova tentativa e um novo pagamento. Responde 409 se o pagamento nao aguarda mais o cartao e 410 se o prazo terminou (o pagamento e cancelado). Envie `Idempotency-Key`: confirmar autoriza e pode cobrar.", "operationId": "Payments_confirm", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "type": "object", "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 256 }, "brand": { "type": "string", "maxLength": 32 }, "bin": { "type": "string", "pattern": "^\\d{6,8}$" }, "last4": { "type": "string", "pattern": "^\\d{4}$" }, "expMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "expYear": { "type": "integer", "minimum": 2024, "maximum": 2099 }, "holderName": { "type": "string", "maxLength": 120 } }, "required": [ "token" ], "additionalProperties": false }, "saveCard": { "type": "boolean", "default": false }, "device": { "type": "object", "properties": { "userAgent": { "type": "string", "maxLength": 512 }, "language": { "type": "string", "maxLength": 35 }, "screenWidth": { "type": "integer", "minimum": 0, "maximum": 100000 }, "screenHeight": { "type": "integer", "minimum": 0, "maximum": 100000 }, "colorDepth": { "type": "integer", "minimum": 0, "maximum": 64 }, "timezoneOffset": { "type": "integer", "minimum": -1440, "maximum": 1440 }, "javaEnabled": { "type": "boolean" }, "javascriptEnabled": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "card" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "card": { "token": "5f4d6a0a-9e7f-4d49-8d3c-0d6c2d3b7a11", "brand": "visa", "bin": "411111", "last4": "1111", "expMonth": 12, "expYear": 2030, "holderName": "MARIA SILVA" }, "saveCard": false, "device": { "userAgent": "Mozilla/5.0", "language": "pt-BR", "screenWidth": 1440, "screenHeight": 900, "colorDepth": 24, "timezoneOffset": 180, "javaEnabled": false, "javascriptEnabled": true } } } } } } }, "responses": { "409": { "description": "O pagamento nao aguarda mais o cartao." }, "410": { "description": "O prazo do pagamento terminou; ele foi cancelado." }, "422": { "description": "Dados invalidos, ou saveCard sem customerId no pagamento." } }, "summary": "Confirmar um pagamento com o token do cartao", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}/review": { "post": { "description": "Aprova ou recusa um pagamento parado na etapa \"Revisao manual\" de um fluxo. O fluxo continua pela saida Aprovado ou Recusado a partir de onde parou - aprovar pode disparar a autorizacao no adquirente. Responde 409 se o pagamento nao esta em revisao ou se a revisao acabou de ser decidida.", "operationId": "Payments_review", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "decline" ] }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "decision" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "decision": "approve", "note": "Cliente confirmou a compra por telefone." } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Decidir uma revisao manual", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}/capture": { "post": { "description": "Captura total ou parcial de um pagamento criado com `captureMethod: manual`. Captura parcial libera o saldo restante.", "operationId": "Payments_capture", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "amount": 14990 } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Capturar um pagamento autorizado", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}/void": { "post": { "description": "Cartao: cancela (void) um pagamento autorizado e ainda nao capturado, no mesmo conector que o autorizou. O limite do portador e liberado sem lancamento na fatura dele. Para devolver um valor ja capturado, use o estorno. Emite `payment.voided`. Responde 409 se o pagamento nao estiver autorizado. Pix e boleto: tira a cobranca do banco antes do pagamento (remove o Pix, da baixa no boleto) e emite `payment.canceled`. O banco e consultado antes: se o pagador acabou de pagar, o pagamento e confirmado e a resposta e 409. Checkout transparente: um pagamento `requires_payment_method` (o portador nao informou o cartao) vira `canceled` sem chamar conector algum, e emite `payment.canceled`.", "operationId": "Payments_void", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 255 } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "reason": "Pedido cancelado antes do envio" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cancelar uma autorizacao ou uma cobranca Pix/boleto", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}/simulate": { "post": { "description": "So no ambiente sandbox e so para Pix ou boleto emitido pelo Minstrel Sandbox. `paid` confirma o pagamento; `expired` vence a cobranca. O resultado segue o MESMO caminho da consulta periodica e do webhook do banco: fluxo retomado pela saida Aprovado, `payment.captured` ou `payment.canceled`. Responde 409 se a cobranca nao estiver aguardando pagamento.", "operationId": "Payments_simulate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "paid", "expired" ] } }, "required": [ "outcome" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "outcome": "paid" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Simular o banco (sandbox)", "tags": [ "Pagamentos" ] } }, "/v1/payments/{id}/refund": { "post": { "description": "Estorno total ou parcial. Varios estornos parciais sao permitidos ate o valor capturado. Pix: devolucao pelo PSP que recebeu. Boleto nao tem estorno automatico: responde 409 com a orientacao (devolver por Pix ou TED e registrar).", "operationId": "Payments_refund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 }, "reason": { "type": "string", "maxLength": 255 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "amount": 5000, "reason": "Devolucao parcial" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Estornar um pagamento", "tags": [ "Pagamentos" ] } }, "/v1/public/payments/{id}": { "get": { "description": "Visao publica do pagamento para a tela de checkout: valor, loja, situacao, se pode salvar cartao, a acao pendente (Pix, boleto), o prazo e, em recusa, o motivo e a frase para o comprador. Autenticada so pelo header `Minstrel-Client-Secret`. Nao expoe ids internos nem dados do conector.", "operationId": "PublicPayments_view", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "minstrel-client-secret", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "Minstrel-Client-Secret", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Client secret invalido." }, "429": { "description": "Limite de requisicoes excedido (header Retry-After)." } }, "summary": "Consultar o pagamento (navegador)", "tags": [ "Checkout transparente (navegador)" ] } }, "/v1/public/payments/{id}/tokenization-session": { "post": { "description": "Credencial de uso unico do adquirente para o script de tokenizacao no navegador (`provider` diz qual: `cielo_sop`, `minstrel_sandbox`). O numero do cartao vai do navegador direto ao adquirente e nunca passa pelo Minstrel. So enquanto o pagamento aguarda o cartao e dentro do prazo. Limite: 10 por hora por pagamento.", "operationId": "PublicPayments_tokenizationSession", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "minstrel-client-secret", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "Minstrel-Client-Secret", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Client secret invalido." }, "409": { "description": "O pagamento nao aguarda mais o cartao." }, "410": { "description": "O prazo do pagamento terminou; ele foi cancelado." }, "429": { "description": "Limite de requisicoes excedido (header Retry-After)." } }, "summary": "Abrir a sessao de tokenizacao (navegador)", "tags": [ "Checkout transparente (navegador)" ] } }, "/v1/public/payments/{id}/confirm": { "post": { "description": "Envia o token de uso unico gerado no navegador e processa o pagamento (fluxo publicado ou roteamento direto), como cobranca com o cliente presente. `saveCard: true` e o consentimento do portador para guardar o cartao e exige que o pagamento tenha cliente. Recusa do emissor nao e erro HTTP: o pagamento volta `failed` com `decline`. Limite: 5 por hora por pagamento.", "operationId": "PublicPayments_confirm", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "minstrel-client-secret", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "idempotency-key", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Repetir a chamada com a mesma chave devolve o resultado original, sem cobrar duas vezes.", "required": false, "schema": { "type": "string" } }, { "name": "Minstrel-Client-Secret", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "type": "object", "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 256 }, "brand": { "type": "string", "maxLength": 32 }, "bin": { "type": "string", "pattern": "^\\d{6,8}$" }, "last4": { "type": "string", "pattern": "^\\d{4}$" }, "expMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "expYear": { "type": "integer", "minimum": 2024, "maximum": 2099 }, "holderName": { "type": "string", "maxLength": 120 } }, "required": [ "token" ], "additionalProperties": false }, "saveCard": { "type": "boolean", "default": false }, "device": { "type": "object", "properties": { "userAgent": { "type": "string", "maxLength": 512 }, "language": { "type": "string", "maxLength": 35 }, "screenWidth": { "type": "integer", "minimum": 0, "maximum": 100000 }, "screenHeight": { "type": "integer", "minimum": 0, "maximum": 100000 }, "colorDepth": { "type": "integer", "minimum": 0, "maximum": 64 }, "timezoneOffset": { "type": "integer", "minimum": -1440, "maximum": 1440 }, "javaEnabled": { "type": "boolean" }, "javascriptEnabled": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "card" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "card": { "token": "5f4d6a0a-9e7f-4d49-8d3c-0d6c2d3b7a11", "brand": "visa", "bin": "411111", "last4": "1111", "expMonth": 12, "expYear": 2030, "holderName": "MARIA SILVA" }, "saveCard": false, "device": { "userAgent": "Mozilla/5.0", "language": "pt-BR", "screenWidth": 1440, "screenHeight": 900, "colorDepth": 24, "timezoneOffset": 180, "javaEnabled": false, "javascriptEnabled": true } } } } } } }, "responses": { "401": { "description": "Client secret invalido." }, "409": { "description": "O pagamento nao aguarda mais o cartao." }, "410": { "description": "O prazo do pagamento terminou; ele foi cancelado." }, "422": { "description": "Dados invalidos, ou saveCard sem cliente no pagamento." }, "429": { "description": "Limite de requisicoes excedido (header Retry-After)." } }, "summary": "Confirmar o pagamento com o token do cartao (navegador)", "tags": [ "Checkout transparente (navegador)" ] } }, "/v1/connector-webhooks/{connectorAccountId}/{token}": { "post": { "description": "Endereco cadastrado no portal do banco ou PSP (veja `webhookUrl` na conta do plugin). Responde 200 assim que le o aviso e confere cada cobranca citada na consulta ao banco logo depois: um aviso forjado nao paga nada. Token invalido ou conta inexistente: 404.", "operationId": "ConnectorWebhooks_receive", "parameters": [ { "name": "connectorAccountId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Receber aviso de Pix ou boleto do banco", "tags": [ "Webhooks de entrada (bancos e PSPs)" ] } }, "/v1/flows/builder-metadata": { "get": { "description": "Paleta de nos, portas de saida, campos disponiveis em regras, operadores e templates prontos.", "operationId": "Flows_builderMetadata", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Metadados do construtor de fluxos", "tags": [ "Fluxos" ] } }, "/v1/flows": { "get": { "operationId": "Flows_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar fluxos do ambiente", "tags": [ "Fluxos" ] }, "post": { "description": "Cria em rascunho. Use `template` para partir de um fluxo pronto.", "operationId": "Flows_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "triggerEvent": { "type": "string", "enum": [ "payment.authorization_requested", "invoice.payment_due", "subscription.renewal", "payment.retry_requested", "manual" ], "default": "payment.authorization_requested" }, "template": { "type": "string", "enum": [ "roteamento-por-ticket", "recorrencia-com-retentativa", "marketplace-split" ] }, "graph": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "trigger", "condition", "switch", "set_variable", "antifraud", "zero_auth", "three_ds", "review", "route", "capture", "split", "retry", "delay", "webhook", "approve", "decline" ] }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "data": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "type", "position" ], "additionalProperties": false }, "minItems": 1, "maxItems": 120 }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "source": { "type": "string", "minLength": 1, "maxLength": 64 }, "target": { "type": "string", "minLength": 1, "maxLength": 64 }, "sourceHandle": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 80 } }, "required": [ "id", "source", "target" ], "additionalProperties": false }, "maxItems": 300 }, "viewport": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "zoom": { "type": "number", "minimum": 0.1, "maximum": 4 } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false } }, "required": [ "nodes", "edges" ], "additionalProperties": false } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Roteamento por ticket", "triggerEvent": "payment.authorization_requested", "template": "roteamento-por-ticket" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar um fluxo", "tags": [ "Fluxos" ] } }, "/v1/flows/{id}": { "get": { "description": "Inclui a versao ativa e o historico das 20 versoes mais recentes.", "operationId": "Flows_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um fluxo", "tags": [ "Fluxos" ] }, "patch": { "description": "Altera nome e descricao. Nao cria versao: o grafo continua o mesmo.", "operationId": "Flows_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500, "nullable": true } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Roteamento por ticket" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Renomear um fluxo", "tags": [ "Fluxos" ] } }, "/v1/flows/{id}/draft": { "put": { "description": "Cria uma nova versao sem publicar. Aceita grafo com problemas e devolve a lista deles, para o editor exibir enquanto o usuario trabalha.", "operationId": "Flows_saveDraft", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "trigger", "condition", "switch", "set_variable", "antifraud", "zero_auth", "three_ds", "review", "route", "capture", "split", "retry", "delay", "webhook", "approve", "decline" ] }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "data": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "type", "position" ], "additionalProperties": false }, "minItems": 1, "maxItems": 120 }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "source": { "type": "string", "minLength": 1, "maxLength": 64 }, "target": { "type": "string", "minLength": 1, "maxLength": 64 }, "sourceHandle": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 80 } }, "required": [ "id", "source", "target" ], "additionalProperties": false }, "maxItems": 300 }, "viewport": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "zoom": { "type": "number", "minimum": 0.1, "maximum": 4 } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false } }, "required": [ "nodes", "edges" ], "additionalProperties": false } }, "required": [ "graph" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "" } }, "summary": "Salvar rascunho", "tags": [ "Fluxos" ] } }, "/v1/flows/{id}/publish": { "post": { "description": "Valida schema, estrutura do grafo e existencia das contas de conector e recebedores citados. Publicar move o ponteiro da versao ativa; a versao publicada fica imutavel.", "operationId": "Flows_publish", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flowVersionId": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "summary": "Publicar um fluxo", "tags": [ "Fluxos" ] } }, "/v1/flows/{id}/rollback/{versionId}": { "post": { "description": "Restaura instantaneamente uma versao anterior ja publicada.", "operationId": "Flows_rollback", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "versionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Voltar para uma versao publicada", "tags": [ "Fluxos" ] } }, "/v1/flows/validate": { "post": { "description": "Usado pelo editor a cada alteracao, para apontar problemas em tempo real.", "operationId": "Flows_validate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "trigger", "condition", "switch", "set_variable", "antifraud", "zero_auth", "three_ds", "review", "route", "capture", "split", "retry", "delay", "webhook", "approve", "decline" ] }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "data": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "type", "position" ], "additionalProperties": false }, "minItems": 1, "maxItems": 120 }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "source": { "type": "string", "minLength": 1, "maxLength": 64 }, "target": { "type": "string", "minLength": 1, "maxLength": 64 }, "sourceHandle": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 80 } }, "required": [ "id", "source", "target" ], "additionalProperties": false }, "maxItems": 300 }, "viewport": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "zoom": { "type": "number", "minimum": 0.1, "maximum": 4 } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false } }, "required": [ "nodes", "edges" ], "additionalProperties": false } }, "required": [ "graph" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "summary": "Validar um grafo sem salvar", "tags": [ "Fluxos" ] } }, "/v1/flows/simulate": { "post": { "description": "Percorre o grafo com um contexto hipotetico e devolve o caminho que a transacao seguiria, com a explicacao de cada decisao. Nao aciona conector nem grava nada.", "operationId": "Flows_simulate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graph": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "trigger" ] }, "data": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "payment.authorization_requested", "invoice.payment_due", "subscription.renewal", "payment.retry_requested", "manual" ] } }, "required": [ "event" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "condition" ] }, "data": { "type": "object", "properties": { "rules": { "type": "object", "properties": { "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "predicates": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "starts_with", "ends_with", "between", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" } ] }, "maxItems": 200 }, { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } ] } }, "required": [ "field", "operator" ], "additionalProperties": false }, "maxItems": 50, "default": [] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "predicates": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "starts_with", "ends_with", "between", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" } ] }, "maxItems": 200 }, { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } ] } }, "required": [ "field", "operator" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "predicates" ], "additionalProperties": false }, "maxItems": 20, "default": [] } }, "additionalProperties": false } }, "required": [ "rules" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "switch" ] }, "data": { "type": "object", "properties": { "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "maxLength": 120 }, "rules": { "type": "object", "properties": { "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "predicates": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "starts_with", "ends_with", "between", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" } ] }, "maxItems": 200 }, { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } ] } }, "required": [ "field", "operator" ], "additionalProperties": false }, "maxItems": 50, "default": [] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "predicates": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "starts_with", "ends_with", "between", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" } ] }, "maxItems": 200 }, { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } ] } }, "required": [ "field", "operator" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "predicates" ], "additionalProperties": false }, "maxItems": 20, "default": [] } }, "additionalProperties": false } }, "required": [ "id", "label", "rules" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 } }, "required": [ "cases" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "antifraud" ] }, "data": { "type": "object", "properties": { "connectorAccountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "connectorSlug": { "type": "string", "maxLength": 64 }, "decisionMode": { "type": "string", "enum": [ "score", "recommendation" ], "default": "score" }, "approveBelow": { "type": "integer", "minimum": 0, "maximum": 100, "default": 40 }, "declineAbove": { "type": "integer", "minimum": 0, "maximum": 100, "default": 80 }, "timeoutMs": { "type": "integer", "minimum": 500, "maximum": 30000, "default": 8000 } }, "required": [ "connectorAccountId" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "zero_auth" ] }, "data": { "type": "object", "properties": { "reuseWithinDays": { "type": "integer", "minimum": 0, "maximum": 365, "default": 30 }, "connectorAccountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "connectorSlug": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "three_ds" ] }, "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "frictionless_preferred", "challenge_required", "data_only" ], "default": "frictionless_preferred" }, "onUnavailable": { "type": "string", "enum": [ "continue", "decline" ], "default": "continue" }, "connectorAccountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "connectorSlug": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "route" ] }, "data": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "priority", "weighted", "least_cost", "round_robin" ], "default": "priority" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "connectorAccountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "connectorSlug": { "type": "string", "maxLength": 64 }, "priority": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 }, "weight": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100 } }, "required": [ "connectorAccountId" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 }, "fallbackOnReversibleDecline": { "type": "boolean", "default": true }, "fallbackOnConnectorFailure": { "type": "boolean", "default": true }, "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 5, "default": 2 } }, "required": [ "candidates" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "split" ] }, "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "recipientId": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "integer", "minimum": 0 }, "liableForChargeback": { "type": "boolean", "default": false }, "chargeProcessingFee": { "type": "boolean", "default": false } }, "required": [ "recipientId", "type", "value" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 }, "remainderRecipientId": { "type": "string", "maxLength": 64 } }, "required": [ "rules" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "retry" ] }, "data": { "type": "object", "properties": { "policyPreset": { "type": "string", "enum": [ "padrao-7-dias", "conservadora-3-tentativas", "persistente-15-dias" ] }, "retryPolicyId": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "delay" ] }, "data": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 1, "maximum": 43200 } }, "required": [ "minutes" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "capture" ] }, "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "immediate", "delayed" ], "default": "immediate" }, "delayHours": { "type": "integer", "minimum": 0, "maximum": 720, "default": 0 } }, "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "webhook" ] }, "data": { "type": "object", "properties": { "webhookEndpointId": { "type": "string", "maxLength": 64 }, "eventName": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$" } }, "required": [ "eventName" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "review" ] }, "data": { "type": "object", "properties": { "queue": { "type": "string", "minLength": 1, "maxLength": 64, "default": "default" }, "slaHours": { "type": "integer", "minimum": 1, "maximum": 240, "default": 24 }, "onSlaBreach": { "type": "string", "enum": [ "approve", "decline" ], "default": "decline" } }, "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "set_variable" ] }, "data": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "value": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "name", "value" ], "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "approve" ] }, "data": { "type": "object", "properties": {}, "additionalProperties": false, "default": {} } }, "required": [ "id", "position", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "label": { "type": "string", "maxLength": 120 }, "notes": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": [ "decline" ] }, "data": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 120, "default": "blocked_by_flow" }, "customerMessage": { "type": "string", "maxLength": 240 } }, "additionalProperties": false } }, "required": [ "id", "position", "type", "data" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 120 }, "edges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "source": { "type": "string", "minLength": 1, "maxLength": 64 }, "target": { "type": "string", "minLength": 1, "maxLength": 64 }, "sourceHandle": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 80 } }, "required": [ "id", "source", "target" ], "additionalProperties": false }, "maxItems": 300 }, "viewport": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "zoom": { "type": "number", "minimum": 0.1, "maximum": 4 } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false } }, "required": [ "nodes", "edges" ], "additionalProperties": false }, "context": { "type": "object", "additionalProperties": {} }, "assume": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 64 } } }, "required": [ "graph", "context" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "context": { "payment.amount": 150000, "card.brand": "visa", "risk.score": 20 } } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Simular a execucao de um grafo", "tags": [ "Fluxos" ] } }, "/v1/flows/{id}/runs": { "get": { "description": "Cada execucao traz os passos percorridos e a explicacao de cada decisao.", "operationId": "Flows_runs", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Historico de execucoes de um fluxo", "tags": [ "Fluxos" ] } }, "/v1/customers": { "post": { "description": "Informe `externalId` para tornar o cadastro idempotente: reenviar o mesmo cliente devolve o registro existente em vez de duplicar. CPF e CNPJ (inclusive o alfanumerico) tem o digito verificador conferido.", "operationId": "Customers_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 32 }, "documentType": { "type": "string", "enum": [ "cpf", "cnpj", "passport", "other" ] }, "document": { "type": "string", "maxLength": 32 }, "birthDate": { "type": "string", "format": "date-time" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 48 }, "maxItems": 30 }, "groupIds": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, "locale": { "type": "string", "maxLength": 16, "default": "pt-BR" }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "streetNumber": { "type": "string", "maxLength": 32 }, "district": { "type": "string", "maxLength": 120 }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "state": { "type": "string", "minLength": 2, "maxLength": 64 }, "postalCode": { "type": "string", "minLength": 5, "maxLength": 16 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR" } }, "required": [ "line1", "city", "state", "postalCode" ], "additionalProperties": false }, "notes": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "externalId": "cliente-1234", "name": "Maria Oliveira", "email": "maria.oliveira@exemplo.com.br", "phone": "+5511999990000", "documentType": "cpf", "document": "529.982.247-25", "tags": [ "assinante", "plano-gold" ], "address": { "line1": "Avenida Paulista", "streetNumber": "1000", "district": "Bela Vista", "city": "Sao Paulo", "state": "SP", "postalCode": "01310-100", "country": "BR" } } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cadastrar um cliente", "tags": [ "Clientes" ] }, "get": { "description": "Lista paginada por cursor. Filtre por grupo (`groupId`), etiqueta, bloqueio ou busque por nome, e-mail e documento.", "operationId": "Customers_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar clientes", "tags": [ "Clientes" ] } }, "/v1/customers/summary": { "get": { "description": "Total, novos em 30 dias, assinantes, inadimplentes e bloqueados.", "operationId": "Customers_summary", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Resumo da base de clientes", "tags": [ "Clientes" ] } }, "/v1/customers/{id}": { "get": { "description": "Inclui grupos, endereco, meios de pagamento (apenas dados de exibicao) e indicadores: MRR, valor do cliente, faturas em aberto e vencidas.", "operationId": "Customers_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um cliente", "tags": [ "Clientes" ] }, "patch": { "description": "`groupIds` substitui os grupos; `address: null` remove o endereco.", "operationId": "Customers_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "phone": { "type": "string", "maxLength": 32, "nullable": true }, "documentType": { "type": "string", "enum": [ "cpf", "cnpj", "passport", "other" ], "nullable": true }, "document": { "type": "string", "maxLength": 32, "nullable": true }, "birthDate": { "type": "string", "format": "date-time", "nullable": true }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 48 }, "maxItems": 30 }, "groupIds": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, "locale": { "type": "string", "maxLength": 16 }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "streetNumber": { "type": "string", "maxLength": 32 }, "district": { "type": "string", "maxLength": 120 }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "state": { "type": "string", "minLength": 2, "maxLength": 64 }, "postalCode": { "type": "string", "minLength": 5, "maxLength": 16 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR" } }, "required": [ "line1", "city", "state", "postalCode" ], "additionalProperties": false, "nullable": true }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "blocked": { "type": "boolean" }, "blockedReason": { "type": "string", "maxLength": 255 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "tags": [ "vip" ], "groupIds": [ "cgr_01HQ8M5X7P2K3N4R5T6V7W8X9Y" ] } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Atualizar um cliente", "tags": [ "Clientes" ] }, "delete": { "description": "Remocao logica: o historico de pagamentos e preservado por obrigacao fiscal. Exige que nao haja assinatura em andamento.", "operationId": "Customers_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Remover um cliente", "tags": [ "Clientes" ] } }, "/v1/customers/{id}/payment-methods": { "get": { "description": "Inclui os invalidados pelo emissor, com o motivo.", "operationId": "Customers_listPaymentMethods", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Listar os cartoes do cliente", "tags": [ "Clientes" ] }, "post": { "description": "Recebe o TOKEN do cofre e dados de exibicao. Numero do cartao e CVV sao recusados antes da validacao. O primeiro cartao do cliente vira o padrao; reenviar o mesmo token devolve o cartao existente. Com `verify: true` (ou com \"Validar ao salvar cartao\" ligado na conta onde o cartao foi gerado) o cartao e validado sem cobranca (Zero Auth) antes de ser salvo: recusado pelo emissor, nao e salvo (422, com o codigo e a classificacao). Validacao indisponivel recusa o cadastro com `verify: true` e salva o cartao quando vem do padrao da conta.", "operationId": "Customers_attachPaymentMethod", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card": { "type": "object", "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 256 }, "isNetworkToken": { "type": "boolean", "default": false }, "brand": { "type": "string", "maxLength": 32 }, "bin": { "type": "string", "pattern": "^[0-9]{6,8}$" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" }, "expMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "expYear": { "type": "integer", "minimum": 2024, "maximum": 2099 }, "holderName": { "type": "string", "maxLength": 120 }, "connectorAccountId": { "type": "string", "maxLength": 64 } }, "required": [ "token" ], "additionalProperties": false }, "setDefault": { "type": "boolean", "default": false }, "verify": { "type": "boolean" } }, "required": [ "card" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "card": { "token": "tok_...", "brand": "visa", "last4": "4242", "expMonth": 12, "expYear": 2029 } } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Vincular um cartao tokenizado", "tags": [ "Clientes" ] } }, "/v1/customers/{id}/payment-methods/test-card": { "post": { "description": "Cria um cartao com resultado fixo: `aprova`, `51` (saldo insuficiente), `41` (cartao perdido), `R0` (suspensao de recorrencia) ou `acao` (3DS). Use para testar retentativa e regua de ponta a ponta. Recusado em producao.", "operationId": "Customers_createTestCard", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scenario": { "type": "string", "enum": [ "41", "51", "aprova", "R0", "acao" ], "default": "aprova" }, "brand": { "type": "string", "enum": [ "visa", "mastercard", "elo", "amex", "hipercard" ], "default": "visa" }, "setDefault": { "type": "boolean", "default": true } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "scenario": "51", "brand": "visa" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Gerar cartao de teste (sandbox)", "tags": [ "Clientes" ] } }, "/v1/customers/{id}/payment-methods/{paymentMethodId}/default": { "post": { "description": "Cartao usado nas cobrancas sem cartao definido na assinatura.", "operationId": "Customers_setDefaultPaymentMethod", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "paymentMethodId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Definir o cartao padrao", "tags": [ "Clientes" ] } }, "/v1/customers/{id}/payment-methods/{paymentMethodId}": { "delete": { "description": "Recusado enquanto alguma assinatura em andamento cobra nele.", "operationId": "Customers_detachPaymentMethod", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "paymentMethodId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Remover um cartao", "tags": [ "Clientes" ] } }, "/v1/customer-groups": { "post": { "description": "Grupos segmentam a base (\"Clientes B2B\", \"Parceiros\") e entram nas regras de fluxo como `customer.groups`, pelo id.", "operationId": "CustomerGroups_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "type": "string", "maxLength": 255 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Clientes B2B", "color": "#1a6cff" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar um grupo de clientes", "tags": [ "Clientes" ] }, "get": { "description": "Com a quantidade de membros de cada um.", "operationId": "CustomerGroups_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar grupos de clientes", "tags": [ "Clientes" ] } }, "/v1/customer-groups/{id}": { "get": { "operationId": "CustomerGroups_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um grupo de clientes", "tags": [ "Clientes" ] }, "patch": { "operationId": "CustomerGroups_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "type": "string", "maxLength": 255, "nullable": true }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Parceiros", "color": "#10b981" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Alterar um grupo de clientes", "tags": [ "Clientes" ] }, "delete": { "description": "Exclusao definitiva: os clientes saem do grupo e regras de fluxo que o citam deixam de casar.", "operationId": "CustomerGroups_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Excluir um grupo de clientes", "tags": [ "Clientes" ] } }, "/v1/customer-groups/{id}/members": { "post": { "description": "Ate 500 por chamada. Quem ja e membro e ignorado.", "operationId": "CustomerGroups_addMembers", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerIds": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "minItems": 1, "maxItems": 500 } }, "required": [ "customerIds" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "customerIds": [ "cus_01HQ8M5X7P2K3N4R5T6V7W8X9Y" ] } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Incluir clientes no grupo", "tags": [ "Clientes" ] } }, "/v1/customer-groups/{id}/members/remove": { "post": { "description": "Ate 500 por chamada.", "operationId": "CustomerGroups_removeMembers", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerIds": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "minItems": 1, "maxItems": 500 } }, "required": [ "customerIds" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "customerIds": [ "cus_01HQ8M5X7P2K3N4R5T6V7W8X9Y" ] } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Retirar clientes do grupo", "tags": [ "Clientes" ] } }, "/v1/recipients": { "post": { "description": "Recebedores recebem parte do valor de um pagamento via split. CPF e CNPJ (inclusive o alfanumerico) tem o digito verificador conferido; banco, agencia e conta vem juntos; a chave Pix pode ser CPF, CNPJ, e-mail, celular com +55 ou chave aleatoria. Informe `externalRecipientId` quando o recebedor ja existe no subadquirente.", "operationId": "Recipients_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "documentType": { "type": "string", "enum": [ "cpf", "cnpj", "passport", "other" ] }, "document": { "type": "string", "maxLength": 32 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "connectorAccountId": { "type": "string", "maxLength": 64 }, "externalRecipientId": { "type": "string", "minLength": 1, "maxLength": 128 }, "bankCode": { "type": "string", "pattern": "^\\d{3}$" }, "bankBranch": { "type": "string", "pattern": "^\\d{1,5}(-?[\\dXx])?$" }, "bankAccount": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^\\d{1,20}-?[\\dX]$" } ] }, "bankAccountType": { "type": "string", "enum": [ "checking", "savings" ] }, "pixKey": { "type": "string", "maxLength": 140 }, "defaultSplitType": { "type": "string", "enum": [ "percentage", "fixed" ] }, "defaultSplitValue": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "liableForChargeback": { "type": "boolean", "default": false }, "chargeProcessingFee": { "type": "boolean", "default": false }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Loja do Vendedor ME", "documentType": "cnpj", "document": "12.345.678/0001-95", "email": "financeiro@lojadovendedor.com.br", "bankCode": "341", "bankBranch": "1234", "bankAccount": "56789-0", "bankAccountType": "checking", "pixKey": "12345678000195", "defaultSplitType": "percentage", "defaultSplitValue": 9000, "liableForChargeback": true, "chargeProcessingFee": true } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cadastrar um recebedor", "tags": [ "Recebedores" ] }, "get": { "description": "Documento, conta e chave Pix saem mascarados (`masked: true`). Cada linha traz o volume dividido no periodo (`from`/`to`, padrao 30 dias) e o valor a receber, com a fonte do numero (`ledger` ou `estimate`).", "operationId": "Recipients_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar recebedores", "tags": [ "Recebedores" ] } }, "/v1/recipients/summary": { "get": { "description": "Recebedores ativos, volume dividido no periodo e no periodo anterior de mesma duracao, total a repassar, proximos repasses e maiores recebedores. Sem `from`, os ultimos 30 dias.", "operationId": "Recipients_summary", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Resumo de split do periodo", "tags": [ "Recebedores" ] } }, "/v1/recipients/split-preview": { "post": { "description": "Calcula a divisao de um valor com o mesmo algoritmo do motor de pagamentos, sem gravar nada. Regras sem `type`/`value` usam a regra padrao do recebedor. Configuracao que o pagamento recusaria volta com `valid: false` e a lista de problemas em `issues`.", "operationId": "Recipients_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 }, "currency": { "type": "string", "enum": [ "BRL", "USD", "EUR", "GBP", "ARS", "CLP", "MXN" ], "default": "BRL" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "recipientId": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 120 }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "integer", "minimum": 0, "maximum": 9999999999 }, "liableForChargeback": { "type": "boolean" }, "chargeProcessingFee": { "type": "boolean" } }, "additionalProperties": false }, "minItems": 1, "maxItems": 20 }, "remainderRecipientId": { "type": "string", "maxLength": 64 } }, "required": [ "amount", "rules" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "amount": 14990, "rules": [ { "recipientId": "rcp_01HQ8VENDEDOR000000000000", "type": "percentage", "value": 9000 }, { "label": "Plataforma", "type": "percentage", "value": 1000 } ] } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Simular um split", "tags": [ "Recebedores" ] } }, "/v1/recipients/{id}": { "get": { "description": "Dados completos (documento, conta e chave Pix sem mascara), totais (volume dividido, a receber, repassado, tarifas) e os fluxos publicados que usam o recebedor. Recebedor removido volta com `deleted: true`.", "operationId": "Recipients_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um recebedor", "tags": [ "Recebedores" ] }, "patch": { "description": "Edicao parcial: campo ausente fica como esta, `null` apaga. Troca de banco ou Pix vai para a trilha de auditoria. Desativar recebedor usado num fluxo publicado e recusado.", "operationId": "Recipients_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "documentType": { "type": "string", "enum": [ "cpf", "cnpj", "passport", "other" ], "nullable": true }, "document": { "type": "string", "maxLength": 32, "nullable": true }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "connectorAccountId": { "type": "string", "maxLength": 64, "nullable": true }, "externalRecipientId": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true }, "bankCode": { "type": "string", "pattern": "^\\d{3}$", "nullable": true }, "bankBranch": { "type": "string", "pattern": "^\\d{1,5}(-?[\\dXx])?$", "nullable": true }, "bankAccount": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^\\d{1,20}-?[\\dX]$" } ], "nullable": true }, "bankAccountType": { "type": "string", "enum": [ "checking", "savings" ], "nullable": true }, "pixKey": { "type": "string", "maxLength": 140, "nullable": true }, "defaultSplitType": { "type": "string", "enum": [ "percentage", "fixed" ], "nullable": true }, "defaultSplitValue": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "liableForChargeback": { "type": "boolean" }, "chargeProcessingFee": { "type": "boolean" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "pixKey": "+5511987654321", "active": true } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Atualizar um recebedor", "tags": [ "Recebedores" ] }, "delete": { "description": "Remocao logica: os splits historicos sao preservados para conciliacao. Exige que nao haja repasse em andamento nem fluxo publicado usando o recebedor.", "operationId": "Recipients_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Remover um recebedor", "tags": [ "Recebedores" ] } }, "/v1/recipients/{id}/splits": { "get": { "description": "Parcelas do recebedor por pagamento, da mais recente para a mais antiga, com o efeito no saldo.", "operationId": "Recipients_splits", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Splits do recebedor", "tags": [ "Recebedores" ] } }, "/v1/recipients/{id}/ledger": { "get": { "description": "Lancamentos da conta `recipient:` no razao contabil, com o saldo (creditos menos debitos).", "operationId": "Recipients_ledger", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Extrato do recebedor no razao", "tags": [ "Recebedores" ] } }, "/v1/recipients/{id}/payouts": { "get": { "operationId": "Recipients_payouts", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Repasses do recebedor", "tags": [ "Recebedores" ] } }, "/v1/products": { "post": { "description": "Um produto e o que o cliente contrata. Os precos e ritmos de cobranca ficam nos planos, o que permite ter mensal e anual do mesmo produto.", "operationId": "Billing_createProduct", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 500 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Plano Minstrel" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar um produto", "tags": [ "Assinaturas" ] }, "get": { "operationId": "Billing_listProducts", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar produtos com seus planos", "tags": [ "Assinaturas" ] } }, "/v1/plans": { "post": { "description": "Define valor, intervalo e periodo de teste. `billingDay` fixa o dia da cobranca (1 a 28); acima de 28 nao existe em todo mes, o que reintroduziria a ambiguidade que o dia fixo resolve.", "operationId": "Billing_createPlan", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 }, "currency": { "type": "string", "enum": [ "BRL", "USD", "EUR", "GBP", "ARS", "CLP", "MXN" ], "default": "BRL" }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "intervalCount": { "type": "integer", "minimum": 1, "maximum": 36, "default": 1 }, "totalCycles": { "type": "integer", "minimum": 1, "maximum": 999 }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 365, "default": 0 }, "billingDay": { "type": "integer", "minimum": 1, "maximum": 28 }, "invoiceLeadDays": { "type": "integer", "minimum": 0, "maximum": 30, "default": 3 }, "billingTiming": { "type": "string", "enum": [ "start", "end" ], "default": "start" }, "retryPolicyId": { "type": "string", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "productId", "name", "amount", "interval" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "productId": "prod_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "name": "Mensal R$ 149,90", "amount": 14990, "currency": "BRL", "interval": "month", "intervalCount": 1, "trialDays": 7, "invoiceLeadDays": 3 } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar um plano", "tags": [ "Assinaturas" ] }, "get": { "operationId": "Billing_listPlans", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar planos", "tags": [ "Assinaturas" ] } }, "/v1/plans/{id}": { "get": { "operationId": "Billing_getPlan", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um plano", "tags": [ "Assinaturas" ] }, "patch": { "description": "Nome, dias de teste e antecedencia da fatura valem para as proximas adesoes e faturas. Preco e intervalo nao mudam: crie outro plano e migre as assinaturas.", "operationId": "Billing_updatePlan", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "invoiceLeadDays": { "type": "integer", "minimum": 0, "maximum": 30 }, "retryPolicyId": { "type": "string", "maxLength": 64, "nullable": true }, "active": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Mensal - 2026", "invoiceLeadDays": 5 } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Alterar um plano", "tags": [ "Assinaturas" ] } }, "/v1/billing/summary": { "get": { "description": "MRR, ARR, ARPA, churn de 30 dias, assinaturas por status e faturas em aberto, vencidas, a vencer em 7 dias e pagas no mes.", "operationId": "Billing_billingSummary", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Indicadores da recorrencia", "tags": [ "Assinaturas" ] } }, "/v1/plans/{id}/archive": { "post": { "description": "Impede novas assinaturas e mantem as existentes cobrando. Nao ha exclusao: apagar o plano deixaria assinaturas sem referencia de preco.", "operationId": "Billing_archivePlan", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Arquivar um plano", "tags": [ "Assinaturas" ] } }, "/v1/subscriptions": { "post": { "description": "Plano pre-pago (padrao): a fatura do primeiro ciclo nasce junto e e cobrada na hora quando ha cartao; a assinatura fica `incomplete` ate ela ser paga e entao passa a `active`. Plano pos-pago: nasce `active` e a primeira fatura vence no fim do periodo. Com periodo de teste, nasce `trialing` e a primeira cobranca acontece no fim do teste. Sem meio de pagamento, a cobranca espera o cartao - o checkout em duas etapas.", "operationId": "Billing_createSubscription", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "maxLength": 64 }, "planId": { "type": "string", "maxLength": 64 }, "paymentMethodId": { "type": "string", "maxLength": 64 }, "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 }, "startAt": { "type": "string", "format": "date-time" }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "retryPolicyId": { "type": "string", "maxLength": 64 }, "externalId": { "type": "string", "maxLength": 128 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "customerId", "planId" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "customerId": "cus_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "planId": "plan_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "paymentMethodId": "pm_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "externalId": "assinatura-1234" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar uma assinatura", "tags": [ "Assinaturas" ] }, "get": { "operationId": "Billing_listSubscriptions", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar assinaturas", "tags": [ "Assinaturas" ] } }, "/v1/subscriptions/{id}": { "get": { "description": "Inclui plano, meio de pagamento e as 12 ultimas faturas com o status de cada uma.", "operationId": "Billing_getSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar uma assinatura", "tags": [ "Assinaturas" ] }, "patch": { "description": "Trocar o meio de pagamento de uma assinatura em atraso a reativa: cartao invalido e a causa mais comum de atraso.", "operationId": "Billing_updateSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "string", "maxLength": 64 }, "amount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 }, "retryPolicyId": { "type": "string", "maxLength": 64 }, "cancelAtPeriodEnd": { "type": "boolean", "enum": [ false ] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "paymentMethodId": "pm_..." } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Atualizar uma assinatura", "tags": [ "Assinaturas" ] } }, "/v1/subscriptions/{id}/cancel": { "post": { "description": "Por padrao cancela ao fim do periodo ja pago. Cancelar imediatamente (`atPeriodEnd: false`) corta o acesso de um periodo que o cliente pagou, o que costuma gerar contestacao.", "operationId": "Billing_cancelSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "atPeriodEnd": { "type": "boolean", "default": true }, "reason": { "type": "string", "maxLength": 255 } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "atPeriodEnd": true } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cancelar uma assinatura", "tags": [ "Assinaturas" ] } }, "/v1/subscriptions/{id}/pause": { "post": { "operationId": "Billing_pauseSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resumesAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "" } }, "summary": "Pausar uma assinatura", "tags": [ "Assinaturas" ] } }, "/v1/subscriptions/{id}/resume": { "post": { "description": "O periodo e reancorado na data da retomada. Continuar de onde parou cobraria um periodo que o cliente passou sem acesso.", "operationId": "Billing_resumeSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Retomar uma assinatura pausada", "tags": [ "Assinaturas" ] } }, "/v1/subscriptions/{id}/renew": { "post": { "description": "Antecipa a geracao da proxima fatura, ignorando a antecedencia do plano. O periodo NAO avanca: a virada acontece quando ele termina. Idempotente por ciclo - chamar de novo devolve 409 em vez de gerar outra fatura. Normalmente feito pelo worker.", "operationId": "Billing_renewSubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Gerar a proxima fatura agora", "tags": [ "Assinaturas" ] } }, "/v1/invoices": { "post": { "description": "Fatura sem assinatura, para cobranca pontual. Nao e cobrada sozinha: sem acordo de recorrencia, cobrar o cartao salvo por iniciativa da loja (MIT) nao e permitido. O cliente paga pelo link de pagamento (`POST /v1/invoices/:id/payment-links`), ou voce cobra com ele presente no seu checkout (`POST /v1/invoices/:id/charge` com `customerPresent: true`).", "operationId": "Billing_createInvoice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "maxLength": 64 }, "dueDate": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "enum": [ "BRL", "USD", "EUR", "GBP", "ARS", "CLP", "MXN" ], "default": "BRL" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1 }, "unitAmount": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 9999999999 } }, "required": [ "description", "unitAmount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "discountAmount": { "type": "integer", "minimum": 0, "default": 0 }, "taxAmount": { "type": "integer", "minimum": 0, "default": 0 }, "retryPolicyId": { "type": "string", "maxLength": 64 }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] } } }, "required": [ "customerId", "items" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "customerId": "cus_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "items": [ { "description": "Servico de implantacao", "quantity": 1, "unitAmount": 250000 } ] } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar uma fatura avulsa", "tags": [ "Assinaturas" ] }, "get": { "description": "Use `status=past_due` para inadimplencia e `dueBefore` para o que vence no periodo.", "operationId": "Billing_listInvoices", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar faturas", "tags": [ "Assinaturas" ] } }, "/v1/invoices/{id}": { "get": { "description": "Inclui o historico de retentativas com o codigo do emissor, a classificacao ABECS e o motivo de cada decisao - inclusive quando a decisao foi nao retentar.", "operationId": "Billing_getInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar uma fatura", "tags": [ "Assinaturas" ] } }, "/v1/invoices/{id}/charge": { "post": { "description": "Cobra o cartao salvo imediatamente, sem esperar o agendamento. Fatura de assinatura: a cobranca vai como MIT recorrente e, em caso de recusa, a classificacao ABECS decide se e quando havera nova tentativa. Fatura avulsa: so com `customerPresent: true` - o cliente esta pagando agora no seu checkout (CIT), sem retentativa automatica. Sem isso a API responde 409: sem acordo de recorrencia, a fatura avulsa e paga pelo link de pagamento (`POST /v1/invoices/:id/payment-links`).", "operationId": "Billing_chargeInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerPresent": { "type": "boolean" } }, "additionalProperties": false, "default": {} }, "examples": { "padrao": { "value": { "customerPresent": true } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Cobrar uma fatura agora", "tags": [ "Assinaturas" ] } }, "/v1/invoices/{id}/mark-paid": { "post": { "description": "Para dinheiro que entrou fora do Minstrel: Pix direto na conta, deposito, acordo. A fatura fica paga com `paidOutOfBand: true` e a nota informada, e a assinatura dela e reativada como numa cobranca aprovada. Nao cria transacao - a conciliacao nao deve procurar uma.", "operationId": "Billing_markInvoicePaid", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paidAt": { "type": "string", "format": "date-time" }, "note": { "type": "string", "minLength": 3, "maxLength": 255 } }, "required": [ "note" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "note": "Pix recebido direto na conta em 14/10" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Registrar pagamento manual (baixa)", "tags": [ "Assinaturas" ] } }, "/v1/invoices/{id}/void": { "post": { "description": "Fatura paga nao pode ser cancelada: use o estorno do pagamento.", "operationId": "Billing_voidInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Cancelar uma fatura", "tags": [ "Assinaturas" ] } }, "/v1/dunning/variables": { "get": { "description": "Catalogo fechado de variaveis. Nao usamos motor de template (Handlebars, Liquid) de proposito: o modelo e escrito pelo cliente, e motor com execucao significaria rodar codigo do usuario no servidor.", "operationId": "Dunning_variables", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Variaveis disponiveis nos modelos", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/templates": { "post": { "description": "Use as variaveis do catalogo. Variavel desconhecida e recusada no cadastro, porque viraria texto vazio na mensagem enviada ao cliente.", "operationId": "Dunning_createTemplate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-z0-9-]+$" }, "channel": { "type": "string", "enum": [ "email", "sms", "whatsapp", "push", "webhook" ] }, "subject": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "bodyText": { "type": "string", "maxLength": 20000 }, "locale": { "type": "string", "maxLength": 16, "default": "pt-BR" } }, "required": [ "name", "channel", "body" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "pre-vencimento", "channel": "email", "subject": "Sua assinatura vence em {{fatura.dias_para_vencer}} dias", "body": "Ola {{cliente.nome}},\n\nA cobranca de {{fatura.total}} sera realizada em {{fatura.vencimento}} no cartao {{cartao.descricao}}.\n\nPara atualizar o cartao, acesse {{fatura.link}}." } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar um modelo de mensagem", "tags": [ "Regua de cobranca" ] }, "get": { "operationId": "Dunning_listTemplates", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar modelos de mensagem", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/templates/{id}": { "patch": { "description": "As mesmas validacoes do cadastro: e-mail exige assunto e variavel desconhecida e recusada.", "operationId": "Dunning_updateTemplate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-z0-9-]+$" }, "channel": { "type": "string", "enum": [ "email", "sms", "whatsapp", "push", "webhook" ] }, "subject": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "bodyText": { "type": "string", "maxLength": 20000 }, "locale": { "type": "string", "maxLength": 16, "default": "pt-BR" }, "active": { "type": "boolean" } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "subject": "Sua fatura vence em {{fatura.dias_para_vencer}} dias" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Alterar um modelo de mensagem", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/templates/render": { "post": { "description": "Usado pelo editor do painel para mostrar a mensagem como o cliente vai ler, e apontar variaveis inexistentes antes de salvar.", "operationId": "Dunning_renderSample", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "body" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "body": "Ola {{cliente.primeiro_nome}}, sua fatura de {{fatura.total}} vence em {{fatura.vencimento}}." } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Renderizar um texto com dados de exemplo", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/rules": { "post": { "description": "Ancora a mensagem em um evento com deslocamento em dias. Negativo antecipa: -3 e tres dias antes do vencimento.", "operationId": "Dunning_createRule", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "anchorEvent": { "type": "string", "enum": [ "invoice.created", "invoice.payment_due", "invoice.past_due", "payment.failed", "retry.exhausted", "subscription.trial_will_end" ] }, "offsetDays": { "type": "integer", "minimum": -60, "maximum": 180, "default": 0 }, "sendHourLocal": { "type": "integer", "minimum": 0, "maximum": 23, "default": 10 }, "channel": { "type": "string", "enum": [ "email", "sms", "whatsapp", "push", "webhook" ] }, "templateId": { "type": "string", "maxLength": 64 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 100 }, "skipIfPaid": { "type": "boolean", "default": true }, "active": { "type": "boolean", "default": true } }, "required": [ "name", "anchorEvent", "channel", "templateId" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Aviso 3 dias antes do vencimento", "anchorEvent": "invoice.payment_due", "offsetDays": -3, "sendHourLocal": 10, "channel": "email", "templateId": "tpl_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "priority": 10 } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar uma regra da regua", "tags": [ "Regua de cobranca" ] }, "get": { "description": "Devolve tambem a linha de tempo ordenada pelo momento do disparo, que e como o operador raciocina sobre a sequencia.", "operationId": "Dunning_listRules", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar as regras da regua", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/rules/{id}": { "patch": { "operationId": "Dunning_updateRule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "anchorEvent": { "type": "string", "enum": [ "invoice.created", "invoice.payment_due", "invoice.past_due", "payment.failed", "retry.exhausted", "subscription.trial_will_end" ] }, "offsetDays": { "type": "integer", "minimum": -60, "maximum": 180, "default": 0 }, "sendHourLocal": { "type": "integer", "minimum": 0, "maximum": 23, "default": 10 }, "channel": { "type": "string", "enum": [ "email", "sms", "whatsapp", "push", "webhook" ] }, "templateId": { "type": "string", "maxLength": 64 }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 100 }, "skipIfPaid": { "type": "boolean", "default": true }, "active": { "type": "boolean", "default": true } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "active": false } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Atualizar uma regra", "tags": [ "Regua de cobranca" ] }, "delete": { "description": "Desativa em vez de apagar: as mensagens enviadas referenciam a regra, e saber qual regra disparou cada mensagem e essencial no suporte.", "operationId": "Dunning_deleteRule", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Desativar uma regra", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/preview": { "post": { "description": "Renderiza cada mensagem com os dados reais da fatura e informa em que data sairia. Nao envia nada.", "operationId": "Dunning_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string", "maxLength": 64 } }, "required": [ "invoiceId" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "invoiceId": "inv_..." } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Pre-visualizar a regua para uma fatura", "tags": [ "Regua de cobranca" ] } }, "/v1/dunning/messages": { "get": { "description": "Use status=scheduled para ver o que ainda vai sair e cancelar se necessario.", "operationId": "Dunning_listMessages", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar mensagens da regua", "tags": [ "Regua de cobranca" ] } }, "/v1/analytics/overview": { "get": { "description": "Volume capturado, taxa de aprovacao, ticket medio, valor recuperado por fallback e retentativa, estornos, serie diaria (ou por hora, em `today`), principais motivos de recusa pela tabela ABECS, desempenho por conector, mix por bandeira, meio e parcelamento, retrato da recorrencia e alertas que pedem acao. Cada total vem com o periodo anterior de mesma duracao, para calcular a variacao. Valores em centavos; taxas em basis points (9240 = 92,4%). As ultimas transacoes so vem para credenciais com `payments:read`.", "operationId": "Analytics_overview", "parameters": [ { "name": "period", "required": false, "in": "query", "description": "today (hoje ate agora, por hora), 7d, 30d (padrao) ou 90d. Os dias sao contados no fuso da organizacao.", "schema": { "enum": [ "today", "7d", "30d", "90d" ], "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Visao geral do periodo", "tags": [ "Indicadores" ] } }, "/v1/platform-billing/overview": { "get": { "description": "Plano contratado, uso de producao do mes com as linhas calculadas, fatura parcial, projecao ate o fim do mes no ritmo atual, comparacao com o mes anterior, uso do sandbox (informativo: o sandbox nao e cobrado), proxima fatura a pagar e historico mensal. Nao depende do ambiente selecionado: a conta e da organizacao.", "operationId": "PlatformBilling_overview", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Resumo do financeiro da plataforma", "tags": [ "Financeiro da plataforma" ] } }, "/v1/platform-billing/invoices": { "get": { "description": "Faturas mensais da Minstrel para a organizacao, da mais recente para a mais antiga. `status=overdue` inclui a fatura em aberto cujo vencimento ja passou.", "operationId": "PlatformBilling_listInvoices", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar as faturas da plataforma", "tags": [ "Financeiro da plataforma" ] } }, "/v1/platform-billing/invoices/{id}": { "get": { "description": "Inclui as linhas do calculo (quantidade x preco unitario) e, enquanto houver valor a pagar, as instrucoes de pagamento (linha digitavel e Pix copia e cola). Fora de producao as instrucoes sao ficticias e vem marcadas com `sample: true`.", "operationId": "PlatformBilling_getInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar uma fatura da plataforma", "tags": [ "Financeiro da plataforma" ] } }, "/v1/settings/organization": { "get": { "description": "Nome, razao social, CNPJ, MCC, fuso horario, e-mail de suporte e site.", "operationId": "Settings_getOrganization", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Perfil da organizacao", "tags": [ "Configuracoes" ] }, "patch": { "description": "Envie so os campos que mudam; `null` apaga um campo opcional. O CNPJ tem o digito verificador conferido (o alfanumerico e aceito) e o fuso precisa ser um nome IANA. Cada alteracao fica na trilha de auditoria com o valor anterior e o novo.", "operationId": "Settings_updateOrganization", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "legalName": { "type": "string", "minLength": 2, "maxLength": 255, "nullable": true }, "document": { "type": "string", "maxLength": 32, "nullable": true }, "mcc": { "type": "string", "pattern": "^\\d{4}$", "nullable": true }, "timezone": { "type": "string", "maxLength": 64 }, "supportEmail": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "website": { "type": "string", "maxLength": 255, "format": "uri", "nullable": true } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Minstrel Demo", "legalName": "Minstrel Demonstracao Ltda", "document": "00.000.000/0001-91", "mcc": "5399", "timezone": "America/Sao_Paulo", "supportEmail": "suporte@empresa.com.br", "website": "https://empresa.com.br" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Atualizar o perfil da organizacao", "tags": [ "Configuracoes" ] } }, "/v1/settings/roles": { "get": { "description": "Os escopos de cada papel do painel e quais papeis exigem MFA. E a mesma tabela usada na autorizacao das sessoes.", "operationId": "Settings_roles", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Papeis e escopos", "tags": [ "Configuracoes" ] } }, "/v1/settings/security": { "get": { "description": "Regras de senha, bloqueio por tentativas, duracao da sessao e adesao da equipe ao MFA.", "operationId": "Settings_security", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Politica de seguranca", "tags": [ "Configuracoes" ] } }, "/v1/settings/account": { "get": { "description": "O membro da sessao atual: papel, MFA, ultimo acesso e se ainda usa a senha temporaria (`passwordChangeRequired`). Exige sessao do painel.", "operationId": "Settings_account", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Sua conta", "tags": [ "Configuracoes" ] } }, "/v1/settings/account/password": { "post": { "description": "Exige a senha atual e encerra TODAS as sessoes, inclusive a atual. Mesma regra de `POST /v1/auth/change-password` (minimo de 12 caracteres); aqui as senhas vao aninhadas em `password`, que o log de requisicoes redige por inteiro.", "operationId": "Settings_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "object", "properties": { "current": { "type": "string", "minLength": 1, "maxLength": 256 }, "next": { "type": "string", "minLength": 12, "maxLength": 256 } }, "required": [ "current", "next" ], "additionalProperties": false } }, "required": [ "password" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "password": { "current": "senha-atual", "next": "uma frase longa e facil de lembrar" } } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Trocar a propria senha", "tags": [ "Configuracoes" ] } }, "/v1/settings/users": { "get": { "description": "Membros com papel, MFA, ultimo acesso e situacao (`active`, `invited`, `locked`, `inactive`). `passwordChangeRequired` indica quem ainda usa a senha temporaria.", "operationId": "Team_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar a equipe", "tags": [ "Configuracoes" ] }, "post": { "description": "Cria o acesso com o papel escolhido e devolve uma senha temporaria UMA unica vez, para o administrador repassar (nao ha envio de e-mail). A pessoa troca a senha no primeiro acesso. Somente um proprietario concede o papel de proprietario.", "operationId": "Team_invite", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "finance", "support", "viewer" ] } }, "required": [ "name", "email", "role" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Ana Souza", "email": "ana@empresa.com.br", "role": "developer" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Convidar um membro", "tags": [ "Configuracoes" ] } }, "/v1/settings/users/{id}": { "patch": { "description": "Rebaixar (perder qualquer escopo ou deixar de ser proprietario) encerra as sessoes do membro. Nao e possivel alterar o proprio papel nem rebaixar o ultimo proprietario ativo.", "operationId": "Team_changeRole", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "developer", "finance", "support", "viewer" ] } }, "required": [ "role" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "role": "finance" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Alterar o papel de um membro", "tags": [ "Configuracoes" ] } }, "/v1/settings/users/{id}/deactivate": { "post": { "description": "Bloqueia o acesso e encerra as sessoes na hora, sem apagar o historico. Nao e possivel desativar a si mesmo nem o ultimo proprietario ativo.", "operationId": "Team_deactivate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Desativar um membro", "tags": [ "Configuracoes" ] } }, "/v1/settings/users/{id}/reactivate": { "post": { "description": "Devolve o acesso com o mesmo papel e zera o bloqueio por tentativas.", "operationId": "Team_reactivate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Reativar um membro", "tags": [ "Configuracoes" ] } }, "/v1/settings/users/{id}/reset-password": { "post": { "description": "Para quem esqueceu a senha ou perdeu o convite. Devolve a senha UMA unica vez, encerra as sessoes do membro e desfaz o bloqueio por tentativas.", "operationId": "Team_resetPassword", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Gerar nova senha temporaria", "tags": [ "Configuracoes" ] } }, "/v1/settings/api-keys": { "get": { "description": "Chaves de um ambiente (`environment`; padrao, o da credencial em uso), sem o segredo: prefixo, escopos, IPs, ultimo uso, expiracao e situacao. `status=active` mostra so as que autenticam agora.", "operationId": "ApiKeys_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Listar chaves de API", "tags": [ "Configuracoes" ] }, "post": { "description": "O segredo (`secret`) volta UMA unica vez, nesta resposta; guardamos apenas o hash. A chave fica presa ao ambiente escolhido. `allowedIps` aceita IP ou faixa CIDR IPv4; vazio aceita qualquer origem.", "operationId": "ApiKeys_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "payments:read", "payments:write", "customers:read", "customers:write", "payment_methods:read", "payment_methods:write", "subscriptions:read", "subscriptions:write", "invoices:read", "invoices:write", "flows:read", "flows:write", "connectors:read", "connectors:write", "recipients:read", "recipients:write", "webhooks:read", "webhooks:write", "events:read", "reports:read", "settings:read", "settings:write", "billing:read" ] }, "minItems": 1, "maxItems": 23 }, "allowedIps": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50, "default": [] }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 100000, "nullable": true } }, "required": [ "name", "environment", "scopes" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "name": "Backend de producao", "environment": "live", "scopes": [ "payments:read", "payments:write", "customers:read", "customers:write" ], "allowedIps": [ "203.0.113.0/24" ], "expiresAt": "2027-10-15T00:00:00.000Z", "rateLimitPerMinute": 600 } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Criar uma chave de API", "tags": [ "Configuracoes" ] } }, "/v1/settings/api-keys/{id}/revoke": { "post": { "description": "A chave para de autenticar na hora (401 `api_key_revoked`). O motivo fica na chave e na auditoria.", "operationId": "ApiKeys_revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 255 } }, "required": [ "reason" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "reason": "Servidor desativado" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Revogar uma chave", "tags": [ "Configuracoes" ] } }, "/v1/settings/api-keys/{id}/rotate": { "post": { "description": "Cria a substituta com os mesmos escopos, IPs e limite e devolve o segredo UMA unica vez. A antiga continua valendo por `graceHours` (padrao 24) para a troca sem parar a integracao; `0` revoga a antiga na hora.", "operationId": "ApiKeys_rotate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "graceHours": { "type": "integer", "minimum": 0, "maximum": 168, "default": 24 }, "reason": { "type": "string", "maxLength": 255 } }, "additionalProperties": false }, "examples": { "padrao": { "value": { "graceHours": 24, "reason": "Rotacao periodica" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Rotacionar uma chave", "tags": [ "Configuracoes" ] } }, "/v1/settings/audit-logs": { "get": { "description": "Acoes administrativas (login, equipe, chaves de API, perfil, conectores, recebedores, webhooks), da mais recente para a mais antiga, paginadas por cursor. Filtre por `userId`, `action` (exata, ou o grupo terminado em ponto: `api_key.`), `resourceType`, `resourceId` e periodo (`from`, `to`). A trilha e append-only: nao ha como alterar nem apagar um registro.", "operationId": "Audit_list", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Trilha de auditoria", "tags": [ "Configuracoes" ] } }, "/v1/invoices/{id}/payment-links": { "post": { "description": "Gera o link no plugin escolhido; o cliente paga na pagina do parceiro, como transacao iniciada por ele (CIT), e o Minstrel nunca ve o cartao. E o caminho da fatura avulsa, que nao tem acordo de recorrencia para cobrar o cartao salvo. A conta precisa ser do ambiente, estar ligada e ter a capacidade `payment_link` (senao, 422). Meios: so os que o plugin oferece; parcelas de 1 a 12, so com cartao; validade padrao de 7 dias, maximo de 30. Uma fatura tem no maximo um link ativo: gerar outro cancela o anterior (evento `payment_link.canceled`). O endereco vai para `hostedInvoiceUrl` da fatura, o `{{fatura.link}}` da regua.", "operationId": "PaymentLinks_create", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectorAccountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "card", "pix", "boleto" ] }, "minItems": 1, "maxItems": 3 }, "maxInstallments": { "type": "integer", "minimum": 1, "maximum": 12 }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 } }, "required": [ "connectorAccountId" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "connectorAccountId": "ca_01HQ8M5X7P2K3N4R5T6V7W8X9Y", "methods": [ "card", "pix" ], "maxInstallments": 3, "expiresInDays": 7 } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Gerar o link de pagamento de uma fatura", "tags": [ "Links de pagamento" ] }, "get": { "description": "Do mais novo para o mais antigo, com o ativo (se houver) e o historico: pagos, vencidos e cancelados.", "operationId": "PaymentLinks_listForInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Listar os links de pagamento de uma fatura", "tags": [ "Links de pagamento" ] } }, "/v1/payment-links/{id}": { "get": { "operationId": "PaymentLinks_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Consultar um link de pagamento", "tags": [ "Links de pagamento" ] } }, "/v1/payment-links/{id}/cancel": { "post": { "description": "Desliga o link no parceiro e aqui. Se o parceiro informar que o cliente acabou de pagar, o pagamento e registrado e a API responde 409.", "operationId": "PaymentLinks_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Cancelar um link de pagamento", "tags": [ "Links de pagamento" ] } }, "/v1/payment-links/{id}/refresh": { "post": { "description": "Consulta o parceiro sem esperar o worker. Pago, registra o pagamento (CIT) e quita a fatura; vencido ou cancelado no parceiro, atualiza aqui.", "operationId": "PaymentLinks_refresh", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "summary": "Verificar o pagamento agora", "tags": [ "Links de pagamento" ] } }, "/v1/public/checkout/sandbox/{externalId}": { "get": { "description": "Usado pela pagina publica de checkout simulado do painel. Devolve o que o cliente precisa ver - loja, fatura, valor, meios e validade - e nada do cliente.", "operationId": "SandboxCheckout_summary", "parameters": [ { "name": "externalId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Resumo do link de pagamento simulado", "tags": [ "Checkout simulado (Sandbox)" ] } }, "/v1/public/checkout/sandbox/{externalId}/pay": { "post": { "description": "Faz as vezes do webhook do parceiro: o pagamento aprovado segue o mesmo caminho da consulta do worker - link pago, pagamento CIT e fatura quitada na mesma transacao. Sem numero de cartao: o cenario escolhe o resultado. `card`: `approve` ou `decline_insufficient_funds` (recusa 51); `pix`: `pix_paid`; `boleto`: `boleto_paid`.", "operationId": "SandboxCheckout_pay", "parameters": [ { "name": "externalId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "idempotency-key", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "card", "pix", "boleto" ] }, "scenario": { "type": "string", "enum": [ "approve", "decline_insufficient_funds", "pix_paid", "boleto_paid" ] }, "installments": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1 } }, "required": [ "method", "scenario" ], "additionalProperties": false }, "examples": { "padrao": { "value": { "method": "pix", "scenario": "pix_paid" } } } } } }, "responses": { "200": { "description": "" } }, "summary": "Simular o pagamento do link", "tags": [ "Checkout simulado (Sandbox)" ] } } }, "info": { "title": "Minstrel API", "description": "\nAPI de orquestracao de pagamentos do Minstrel.\n\n## Autenticacao\n\nEnvie sua chave no header `Authorization`:\n\n```\nAuthorization: Bearer mk_sandbox_a1b2c3d4_sua-chave-secreta\n```\n\nO ambiente (sandbox ou producao) vem da propria chave. Nao existe parametro\npara trocar de ambiente, o que torna impossivel cobrar em producao usando\ncredencial de teste.\n\n## Idempotencia\n\nToda operacao que move dinheiro aceita o header `Idempotency-Key`:\n\n```\nIdempotency-Key: idem_01HQ8M5X7P2K3N4R5T6V7W8X9Y\n```\n\nRepetir a chamada com a mesma chave devolve a resposta original, sem cobrar de\nnovo. Chaves valem 24 horas. Reutilizar a mesma chave com um corpo diferente\ndevolve HTTP 409 - protecao contra o erro mais perigoso da categoria.\n\n## Dados de cartao\n\nA API **recusa** numero de cartao, CVV, trilha e PIN com HTTP 422. Tokenize o\ncartao no cofre e envie apenas o token. Guardamos BIN, ultimos 4 digitos,\nbandeira e validade - o suficiente para exibir, rotear e cobrar de novo.\n\n## Recusas\n\nToda recusa e classificada pelo **Normativo nº 021 da ABECS**, que separa\nrecusas REVERSIVEIS (o emissor pode aprovar depois) de IRREVERSIVEIS (o emissor\nnunca aprovara sem alteracao de campo). A resposta traz `decline.reversibility`\ne `decline.retryAction`, para que a sua retentativa nao gere custo sem chance\nde aprovacao.\n\n## Erros\n\nTodos os erros seguem o mesmo envelope:\n\n```json\n{\n \"error\": {\n \"type\": \"card_error\",\n \"code\": \"insufficient_funds\",\n \"message\": \"Saldo ou limite insuficiente.\",\n \"requestId\": \"req_01HQ8M5X7P2K3N4R5T6V7W8X9Y\",\n \"docsUrl\": \"https://docs.minstrel.com.br/errors/insufficient_funds\"\n }\n}\n```\n\nGuarde o `requestId`: com ele o suporte localiza a requisicao exata.\n\n## Paginacao\n\nListagens usam cursor. Passe o `nextCursor` da resposta anterior em\n`startingAfter` para avancar.\n", "version": "2026-01-01", "contact": { "name": "Suporte Minstrel", "url": "https://minstrel.com.br", "email": "dev@minstrel.com.br" } }, "tags": [ { "name": "Pagamentos", "description": "Criar, consultar, capturar e estornar pagamentos." }, { "name": "Checkout transparente (navegador)", "description": "Rotas chamadas pelo navegador do portador, sem chave de API: autenticam so pelo header Minstrel-Client-Secret. O cartao vai do navegador direto ao adquirente e o Minstrel recebe apenas o token." }, { "name": "Clientes", "description": "Cadastro de clientes e meios de pagamento tokenizados." }, { "name": "Fluxos", "description": "Construtor de fluxos de roteamento, validacao e simulacao." }, { "name": "Assinaturas", "description": "Planos, assinaturas e faturas recorrentes." }, { "name": "Webhooks", "description": "Endpoints, entregas e reenvio de eventos." }, { "name": "Saude", "description": "Sondas de liveness e readiness." } ], "servers": [ { "url": "https://api.minstrel.com.br", "description": "Producao" }, { "url": "https://sandbox.api.minstrel.com.br", "description": "Sandbox" }, { "url": "http://localhost:3333", "description": "Local" } ], "components": { "securitySchemes": { "ApiKey": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Chave de API no formato mk___." } }, "schemas": {} }, "x-minstrel-events": [ { "type": "payment.created", "object": "payment", "description": "Pagamento criado e aceito para processamento.", "deprecated": false }, { "type": "payment.requires_action", "object": "payment", "description": "Pagamento aguarda o pagador: QR Code do Pix ou boleto emitido (data.object.nextAction) ou desafio 3DS.", "deprecated": false }, { "type": "payment.authorized", "object": "payment", "description": "Autorizacao aprovada pelo emissor. O valor ainda nao foi capturado.", "deprecated": false }, { "type": "payment.captured", "object": "payment", "description": "Valor capturado. E o evento que confirma a venda.", "deprecated": false }, { "type": "payment.failed", "object": "payment", "description": "Tentativa recusada. Inclui a classificacao ABECS em data.object.decline.", "deprecated": false }, { "type": "payment.canceled", "object": "payment", "description": "Pagamento cancelado sem liquidar: Pix ou boleto vencido ou cancelado, com o motivo em data.object.cancellation.", "deprecated": false }, { "type": "payment.voided", "object": "payment", "description": "Autorizacao cancelada antes da captura.", "deprecated": false }, { "type": "payment.authorization_expiring", "object": "payment", "description": "Pre-autorizacao perto do fim do prazo de captura (Mastercard 7 dias, demais bandeiras 15). Traz o prazo em data.object.authorizationExpiresAt e a acao tomada em data.object.expiryAction: notify (so avisa), capture ou void.", "deprecated": false }, { "type": "payment.refunded", "object": "payment", "description": "Pagamento estornado integralmente.", "deprecated": false }, { "type": "payment.partially_refunded", "object": "payment", "description": "Pagamento estornado parcialmente.", "deprecated": false }, { "type": "payment.attempt.created", "object": "payment_attempt", "description": "Nova tentativa iniciada contra um conector. Util para observar roteamento.", "deprecated": false }, { "type": "dispute.opened", "object": "dispute", "description": "Contestacao aberta pelo portador.", "deprecated": false }, { "type": "dispute.won", "object": "dispute", "description": "Contestacao decidida a favor do estabelecimento.", "deprecated": false }, { "type": "dispute.lost", "object": "dispute", "description": "Contestacao decidida contra o estabelecimento.", "deprecated": false }, { "type": "chargeback.received", "object": "dispute", "description": "Chargeback efetivado e debitado.", "deprecated": false }, { "type": "customer.created", "object": "customer", "description": "Cliente cadastrado.", "deprecated": false }, { "type": "customer.updated", "object": "customer", "description": "Dados do cliente alterados.", "deprecated": false }, { "type": "customer.deleted", "object": "customer", "description": "Cliente removido.", "deprecated": false }, { "type": "payment_method.created", "object": "payment_method", "description": "Meio de pagamento tokenizado e vinculado a um cliente.", "deprecated": false }, { "type": "payment_method.updated", "object": "payment_method", "description": "Meio de pagamento atualizado, incluindo atualizacao automatica de validade.", "deprecated": false }, { "type": "payment_method.expiring", "object": "payment_method", "description": "Cartao vence nos proximos 30 dias. Use para antecipar a troca em assinaturas.", "deprecated": false }, { "type": "payment_method.verified", "object": "payment_method", "description": "Cartao validado sem cobranca (Zero Auth). O resultado vem em data.object.verification.status: valid, invalid ou unavailable (servico fora do ar ou nao habilitado, o que nao diz nada sobre o cartao).", "deprecated": false }, { "type": "payment_method.detached", "object": "payment_method", "description": "Meio de pagamento desvinculado ou invalidado.", "deprecated": false }, { "type": "subscription.created", "object": "subscription", "description": "Assinatura criada.", "deprecated": false }, { "type": "subscription.activated", "object": "subscription", "description": "Assinatura ativada apos o primeiro pagamento.", "deprecated": false }, { "type": "subscription.updated", "object": "subscription", "description": "Plano, valor ou ciclo alterados.", "deprecated": false }, { "type": "subscription.paused", "object": "subscription", "description": "Cobrancas suspensas temporariamente.", "deprecated": false }, { "type": "subscription.resumed", "object": "subscription", "description": "Cobrancas retomadas.", "deprecated": false }, { "type": "subscription.canceled", "object": "subscription", "description": "Assinatura cancelada.", "deprecated": false }, { "type": "subscription.canceled_by_issuer", "object": "subscription", "description": "Cancelada por determinacao do emissor (Visa R0/R1/R3 ou MAC 21). Nao deve ser retentada.", "deprecated": false }, { "type": "subscription.past_due", "object": "subscription", "description": "Assinatura com fatura em atraso.", "deprecated": false }, { "type": "subscription.trial_will_end", "object": "subscription", "description": "Periodo de teste termina em 3 dias.", "deprecated": false }, { "type": "invoice.created", "object": "invoice", "description": "Fatura criada em rascunho.", "deprecated": false }, { "type": "invoice.finalized", "object": "invoice", "description": "Fatura fechada e pronta para cobranca.", "deprecated": false }, { "type": "invoice.payment_due", "object": "invoice", "description": "Fatura entrou na data de cobranca.", "deprecated": false }, { "type": "invoice.payment_succeeded", "object": "invoice", "description": "Fatura paga.", "deprecated": false }, { "type": "invoice.payment_failed", "object": "invoice", "description": "Cobranca da fatura falhou. Inclui a decisao de retentativa.", "deprecated": false }, { "type": "invoice.past_due", "object": "invoice", "description": "Fatura venceu sem pagamento.", "deprecated": false }, { "type": "invoice.uncollectible", "object": "invoice", "description": "Fatura marcada como nao recuperavel apos esgotar a regua.", "deprecated": false }, { "type": "invoice.voided", "object": "invoice", "description": "Fatura cancelada.", "deprecated": false }, { "type": "payment_link.created", "object": "payment_link", "description": "Link de pagamento gerado no plugin escolhido para uma fatura.", "deprecated": false }, { "type": "payment_link.paid", "object": "payment_link", "description": "O cliente pagou pelo link (CIT). A fatura vira paga e o pagamento aparece em data.object.paymentId.", "deprecated": false }, { "type": "payment_link.expired", "object": "payment_link", "description": "O link venceu sem pagamento.", "deprecated": false }, { "type": "payment_link.canceled", "object": "payment_link", "description": "O link foi cancelado, a mao ou porque outro link foi gerado para a mesma fatura.", "deprecated": false }, { "type": "retry.scheduled", "object": "retry_attempt", "description": "Retentativa agendada, com data calculada e motivo da recusa anterior.", "deprecated": false }, { "type": "retry.exhausted", "object": "retry_attempt", "description": "Politica de retentativa esgotada sem aprovacao.", "deprecated": false }, { "type": "recipient.created", "object": "recipient", "description": "Recebedor de split cadastrado.", "deprecated": false }, { "type": "recipient.updated", "object": "recipient", "description": "Dados do recebedor alterados.", "deprecated": false }, { "type": "recipient.deleted", "object": "recipient", "description": "Recebedor removido. Splits ja gravados continuam no historico; novos pagamentos nao podem usa-lo.", "deprecated": false }, { "type": "payout.created", "object": "payout", "description": "Repasse criado.", "deprecated": false }, { "type": "payout.paid", "object": "payout", "description": "Repasse liquidado.", "deprecated": false }, { "type": "payout.failed", "object": "payout", "description": "Repasse falhou.", "deprecated": false }, { "type": "flow.published", "object": "flow_version", "description": "Nova versao de fluxo publicada e em vigor.", "deprecated": false }, { "type": "flow.notification", "object": "payment", "description": "Emitido por um no \"Notificar webhook\" do fluxo. O nome escolhido no no vem em data.name.", "deprecated": false }, { "type": "webhook_endpoint.test", "object": "webhook_endpoint", "description": "Evento de teste pedido no painel ou em POST /v1/webhooks/{id}/test. Vai so para o endpoint testado, nunca para os demais inscritos.", "deprecated": false }, { "type": "connector_account.health_changed", "object": "connector_account", "description": "Mudanca de saude de um conector (degradado, indisponivel ou recuperado).", "deprecated": false }, { "type": "antifraud.assessment_completed", "object": "antifraud_assessment", "description": "Avaliacao de antifraude concluida com score e recomendacao.", "deprecated": false }, { "type": "communication.sent", "object": "message", "description": "Mensagem da regua de cobranca enviada.", "deprecated": false }, { "type": "communication.failed", "object": "message", "description": "Falha no envio de uma mensagem da regua.", "deprecated": false } ] }