{"openapi":"3.1.0","info":{"title":"ValidaPay API","version":"1.0.0","description":"API REST da ValidaPay para Pix, checkout, assinaturas, split, subcontas, saques, devoluções e notas fiscais.\n\n**Regras gerais**\n\n- Valores monetários em reais (BRL), nunca em centavos. Duas casas decimais com ponto (`10.00`).\n- Autenticação OAuth2 `client_credentials`; envie `Authorization: Bearer {access_token}`.\n- Peça apenas os scopes necessários, separados por espaço.\n- Use `externalId` como chave de idempotência em cobranças transparentes; duplicata retorna `409 DUPLICATE_CHARGE`.\n- Header opcional `X-Sub-Account: {numero}` opera sobre uma subconta.\n- Webhooks devem responder HTTP 200 rapidamente; não bloqueie o handler.\n\n**Ambientes**\n\n| | API | OAuth |\n|---|---|---|\n| Produção | `https://api.validapay.com.br` | `https://oauth2.validapay.com.br/auth/token` |\n| Sandbox | `https://sandbox.validapay.com.br` | `https://oauth2-sandbox.validapay.com.br/auth/token` |\n","contact":{"name":"Suporte ValidaPay","email":"contato@validapay.com.br","url":"https://docs.validapay.com.br"},"license":{"name":"Uso restrito a clientes ValidaPay","url":"https://docs.validapay.com.br"}},"servers":[{"url":"https://api.validapay.com.br","description":"Produção"},{"url":"https://sandbox.validapay.com.br","description":"Sandbox"}],"tags":[{"name":"Geral","description":"Autenticação e rotas transversais."},{"name":"Pix","description":"Cobranças Pix imediatas com QR Code e código copia e cola."},{"name":"Split de pagamentos","description":"Divisão automática do valor de uma cobrança entre contas recebedoras."},{"name":"Subcontas ValidaPay","description":"Onboarding de subcontas, propostas e consulta de contas vinculadas."},{"name":"Produtos","description":"Cadastro de produtos e preços, avulsos ou recorrentes."},{"name":"Links de pagamento","description":"Links e sessões de checkout hospedados pela ValidaPay."},{"name":"Checkout Transparente","description":"Cobranças criadas na sua própria interface, por Pix, boleto ou cartão."},{"name":"Simular pagamentos","description":"Simulação de pagamento em sandbox."},{"name":"Saques","description":"Transferência de saldo para conta de mesma titularidade."},{"name":"Extratos","description":"Saldo e extrato de movimentações da carteira."},{"name":"Devolução Pix","description":"Devolução total ou parcial de uma cobrança Pix."},{"name":"Estorno Cartão","description":"Estorno de uma cobrança paga com cartão."},{"name":"Clientes","description":"Cadastro e consulta de clientes."},{"name":"Assinaturas","description":"Gestão de assinaturas existentes, itens e pro-rata."},{"name":"Notas Fiscais","description":"Emissão, cancelamento e configuração de notas fiscais de serviço."}],"security":[{"oauth2":[]}],"paths":{"/auth/token":{"post":{"operationId":"post-autenticacao","summary":"Autenticação","tags":["Geral"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"expires_in":{"type":"number"},"token_type":{"type":"string"}}},"example":{"access_token":"eyJraWQiOiJleGVtcGxvIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJ0b2tlbl91c2UiOiJhY2Nlc3MiLCJzY29wZSI6ImFjY291bnQvcmVhZCIsImNsaWVudF9pZCI6ImV4ZW1wbG9jbGllbnRpZDEyMzQ1Njc4OTAiLCJpc3MiOiJodHRwczovL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tL3VzLWVhc3QtMV9FWEVNUExPIiwiZXhwIjoxOTAwMDAwMDAwLCJpYXQiOjE4OTk5OTY0MDB9.ASSINATURA_DE_EXEMPLO","expires_in":3600,"token_type":"Bearer"}}}},"400":{"description":"grant_type diferente de client_credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"Unsupported grant_type"}}}},"401":{"description":"client_id ou client_secret inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"Invalid credentials"}}}},"403":{"description":"Scope solicitado não liberado para estas credenciais","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"Unauthorized scope"}}}}},"servers":[{"url":"https://oauth2.validapay.com.br","description":"Produção"},{"url":"https://oauth2-sandbox.validapay.com.br","description":"Sandbox"}]}},"/v1/charges/{chargeId}":{"get":{"operationId":"get-status-de-cobranca","summary":"Status de cobrança · Status de cobrança com split","tags":["Pix"],"parameters":[{"name":"chargeId","in":"path","required":true,"description":"Identificador retornado no ato da geraçao da cobrança","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"chargeId":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number"},"paymentType":{"type":"string"},"masterAccointId":{"type":"string"},"subaccountId":{"type":"string"},"emv":{"type":"string"},"paidAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"example":{"chargeId":"cha_1771453171013_fp6iocaxb","status":"PAID","amount":0.2,"paymentType":"PIX","masterAccointId":"2345567893","subaccountId":"987654322","emv":"00020101021226910014br.gov.bcb.pix…","paidAt":"2026-02-18T22:22:50.031Z","createdAt":"2026-02-18T22:19:31.013Z"}}}},"400":{"description":"`MISSING_CHARGE_ID` — chargeId não informado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`CHARGE_NOT_FOUND` — Cobrança não encontrada  \n`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"oauth2":["pix.cob/read"]}]}},"/v1/charges/pix":{"post":{"operationId":"post-cobranca-imediata","summary":"Cobrança imediata · Cobrança imediata com split · Split para Conta Master","tags":["Pix"],"parameters":[{"name":"X-Sub-Account","in":"header","required":true,"description":"Subconta da cobrança","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"chargeId":{"type":"string"},"emv":{"type":"string"}}},"example":{"chargeId":"cha_15631511282731_9p1wo5ghu","emv":"00020101021226910014br.gov.bcb.pix…"}}}},"400":{"description":"`SPLIT_EXCEEDS_NET_AMOUNT` — A soma dos splits excede o valor líquido da cobrança","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHORIZED` — Sem permissão para criar cobrança nesta subconta  \n`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`NOT_FOUND` — A subconta informada em X-Sub-Account não existe  \n`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Com esta funcionalidade você pode criar um QR Code de cobrança imediata.\n\n**Case de uso:**\n\n_Como SaaS, quero gerar cobranças preenchendo apenas o valor do produto e nada mais_\n\n**Regras condicionais (COBV):** `name` e `cep` do `customer` só são aceitos junto com `expiration`. Havendo `expiration` e `customer`, o trio `documentNumber`, `name` e `cep` passa a ser obrigatório em bloco.\n\n**Resposta:** os campos vêm na raiz — `emv` e `qrCode`, não aninhados sob `pix`. O `qrCode` já é uma data URL PNG pronta para exibir; não é preciso gerar a imagem no seu lado.\n\n**Correlação com o pedido:** envie `metadata` na criação e ele volta na resposta e no payload do webhook `payment.success`. É a forma recomendada de amarrar o pagamento ao seu pedido.\n\n> ⚠️ **Esta rota não tem idempotência.** `externalId` é aceito e descartado; duas chamadas iguais criam **duas cobranças**. Controle duplicidade no seu lado (índice `pedido → cobrança`) ou use `POST /v1/charges`, que responde `409 DUPLICATE_CHARGE`. O campo `externalTxid` documentado aqui identifica loja, caixa ou vendedor — não serve como chave de idempotência.\n\nCom esta funcionalidade você pode criar um QR Code de cobrança na sua conta e fazer split para outras contas ValidaPay.\n\n**Case de uso:**\n\n_Como SaaS, tenho parceiros/afiliados PF ou PJ. Quero gerar cobranças na minha conta preenchendo apenas o valor do produto e fazer split para as contas dos meus parceiros._\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\nCom esta funcionalidade você pode criar um QR Code de cobrança na conta de um _Seller_ e fazer split para a sua conta.\n\n**Case de uso:**\n\n_Como SaaS tenho vários Sellers, cada um deles possui uma subconta ValidaPay. Quero gerar cobranças para qualquer subconta preenchendo apenas o valor do produto e fazer split para a minha conta Master_\n\n> ⚠️ **Atenção:** O número da subconta é retornado via webhook quando a subconta é aprovada.\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","multipleOf":0.01},"paymentMethod":{"type":"string","enum":["pix"],"description":"Fixo \"pix\"; o padrao ja e pix"},"expiration":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento (COBV). Nao aceita data passada"},"externalTxid":{"type":"string","maxLength":100},"metadata":{"type":"object","properties":{"orderId":{"type":"string"}}},"customer":{"type":"object","properties":{"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF ou CNPJ do pagador"},"name":{"type":"string","description":"Exige expiration (COBV)"},"cep":{"type":"string","description":"Exige expiration (COBV)"},"phone":{"type":"string","description":"Telefone no formato E.164"},"email":{"type":"string","format":"email","description":"E-mail do pagador"}},"description":"Dados do pagador. Com expiration, vira COBV"},"split":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"]},"amount":{"type":"number","minimum":0.01},"accountNumber":{"type":"string"}}}}},"required":["amount"]},"examples":{"cobranca-imediata":{"summary":"Cobrança imediata","value":{"amount":10,"paymentMethod":"pix","expiration":"2026-12-31","externalTxid":"loja-01-caixa-03","metadata":{"orderId":"pedido-1001"},"customer":{"documentNumber":"12345678901","name":"Joao da Silva","cep":"01310100","phone":"+5511999998888","email":"joao@email.com"},"split":[{"type":"fixed","accountNumber":"896532569","amount":0.1}]}},"cobranca-imediata-com-split":{"summary":"Cobrança imediata com split","value":{"amount":1,"externalTxid":"loja-01-caixa-03","split":[{"type":"fixed","accountNumber":"896532569","amount":0.1},{"type":"fixed","accountNumber":"125485692","amount":0.1}]}},"split-para-conta-master":{"summary":"Split para Conta Master","value":{"amount":1,"externalTxid":"loja-01-caixa-03","split":[{"type":"fixed","amount":0.1}]}}}}}},"security":[{"oauth2":["pix.cob/write"]}]}},"/v1/proposals":{"post":{"operationId":"post-criar-subconta-pf","summary":"Criar subconta PF · Criar subconta PJ","tags":["Subcontas ValidaPay"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"formId":{"type":"string","format":"uuid"}}},"example":{"status":"FINISHED","message":"Formulário criado com sucesso","formId":"8f82a068-ff1a-45b7-8f98-71f07176e0dd"}}}},"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"formId":{"type":"string","format":"uuid"}}},"example":{"status":"UNFINISHED","message":"Formulário criado com sucesso","formId":"fb8cbb9d-d376-4604-940c-957e76e3dcbb"}}}},"400":{"description":"`DOCUMENT_NUMBER_REQUIRED` — documentNumber é obrigatório  \n`INVALID_DOCUMENT` — CPF ou CNPJ inválido\n\nEsta rota responde em dois formatos: validações lançadas retornam o envelope `error`; recusas de proposta retornam `{ message, code }` sem envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/SimpleError"}]}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário\n\nEsta rota responde em dois formatos: validações lançadas retornam o envelope `error`; recusas de proposta retornam `{ message, code }` sem envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/SimpleError"}]}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas\n\nEsta rota responde em dois formatos: validações lançadas retornam o envelope `error`; recusas de proposta retornam `{ message, code }` sem envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/SimpleError"}]}}}}},"description":"Com esta funcionalidade você pode criar subcontas Pessoa Física na ValidaPay. Ao criar a subconta ela ficará associada à sua conta (chamaremos de conta Master).\n\nCase de uso:\n\n_Como SaaS tenho vários Sellers, preciso gerar cobranças para esses Sellers e receber split em cada venda._\n\n> ⚠️ **Atenção:** Não é possivel criar uma subconta com mesmo email e telefone da _master account._ \n  \n> ⚠️ **Atenção:** Dados de renda/faturamento no campo financialDetails são obrigatórios. Os respectivos códigos estão descritos no apêndice Campos Financeiros ao final da sessão Subcontas ValidaPay\n\nCom esta funcionalidade você pode criar subcontas Pessoa Jurídica na ValidaPay. Ao criar a subconta ela ficará associada à sua conta (chamaremos de conta Master).\n\nCase de uso:\n\n_Como SaaS tenho vários Sellers, preciso gerar cobranças para esses Sellers e receber split em cada venda._\n\n> ⚠️ **Atenção:** Não é possivel criar uma subconta com mesmo email e telefone da _master account_ \n  \n> ⚠️ **Atenção:** Dados de renda/faturamento no campo financialDetails são obrigatórios. Os respectivos códigos estão descritos no apêndice Campos Financeiros ao final da sessão Subcontas ValidaPay","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$"},"phoneNumber":{"type":"string","description":"Número de telefone do titular"},"email":{"type":"string","format":"email","description":"email do titular"},"motherName":{"type":"string"},"fullName":{"type":"string","description":"Nome completo do titular"},"birthDate":{"type":"string","description":"Data de nascimento do titular"},"isPoliticallyExposedPerson":{"type":"boolean"},"socialName":{"type":"string"},"address":{"type":"object","properties":{"postalCode":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"addressComplement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}}},"financialDetails":{"type":"object","properties":{"declaredIncome":{"type":"string"},"occupation":{"type":"string"},"netWorth":{"type":"string"}}},"webhookUrl":{"type":"string","description":"URL onde você gostaria de receber a notificação de criação de conta"},"contactNumber":{"type":"string","description":"Telefone da empresa"},"businessEmail":{"type":"string","format":"email","description":"email da empresa"},"businessName":{"type":"string","description":"Razão social"},"tradingName":{"type":"string","description":"Nome fantasia"},"companyType":{"type":"string","description":"PJ, MEI ou ME"},"owner":{"type":"array","items":{"type":"object","properties":{"ownerType":{"type":"string"},"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$"},"fullName":{"type":"string"},"phoneNumber":{"type":"string"},"email":{"type":"string","format":"email"},"motherName":{"type":"string"},"socialName":{"type":"string"},"birthDate":{"type":"string"},"address":{"type":"object","properties":{"postalCode":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"addressComplement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}}},"isPoliticallyExposedPerson":{"type":"boolean"},"financialOwnerDetails":{"type":"object","properties":{"ownerDeclaredIncome":{"type":"string"},"ownerDeclaredRevenue":{"type":"string"}}}}}},"businessAddress":{"type":"object","properties":{"postalCode":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"addressComplement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}}}},"required":["documentNumber"]},"examples":{"criar-subconta-pf":{"summary":"Criar subconta PF","value":{"documentNumber":"11122233396","phoneNumber":"+5511912345678","email":"empresa@exemplo.com.br","motherName":"Teste Mãe","fullName":"Richard Feynman","socialName":"","birthDate":"31-12-2000","address":{"postalCode":"06455030","street":"Alameda Xingu","number":"350","addressComplement":"","neighborhood":"Alphaville Industrial","city":"Barueri","state":"SP"},"isPoliticallyExposedPerson":false,"financialDetails":{"declaredIncome":"1DINP02","occupation":"ONP07","netWorth":"NWNP02"},"webhookUrl":"https://api.teste.com.br"}},"criar-subconta-pj":{"summary":"Criar subconta PJ","value":{"contactNumber":"+5511912345678","documentNumber":"99665544000130","businessEmail":"empresa@exemplo.com.br","businessName":"Empresa Exemplo LTDA","tradingName":"Empresa Exemplo","companyType":"PJ","owner":[{"ownerType":"SOCIO","documentNumber":"22233344405","fullName":"Cesar Lattes ","phoneNumber":"+5511912345128","email":"socio@exemplo.com.br","motherName":"Marie Curie","socialName":"Nome","birthDate":"02-02-1990","address":{"postalCode":"06455030","street":"Alameda Xingu","number":"50","addressComplement":"","neighborhood":"Alphaville Industrial","city":"Barueri","state":"SP"},"isPoliticallyExposedPerson":false,"financialOwnerDetails":{"ownerDeclaredIncome":"ODIB02","ownerDeclaredRevenue":"ODRB02"}}],"businessAddress":{"postalCode":"06455030","street":"Alamed Xingu","number":"350","addressComplement":"","neighborhood":"Alphaville Industrial","city":"Barueri","state":"SP"},"webhookUrl":"https://api.teste.com.br"}}}}}},"security":[{"oauth2":["proposals/write"]}]}},"/v1/proposals/{formId}":{"get":{"operationId":"get-status-de-subconta","summary":"Status de subconta","tags":["Subcontas ValidaPay"],"parameters":[{"name":"formId","in":"path","required":true,"description":"Identificador único retornado no ato do envio da proposta","schema":{"type":"string"}}],"responses":{"200":{"description":"PJ 200","content":{"application/json":{"schema":{"type":"object","properties":{"documentNumber":{"type":"string"},"type":{"type":"string"},"businessName":{"type":"string"},"tradingName":{"type":"string"},"businessEmail":{"type":"string","format":"email"},"contactNumber":{"type":"string"},"businessAddress":{"type":"object","properties":{"number":{"type":"string"},"addressComplement":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"postalCode":{"type":"string"},"neighborhood":{"type":"string"},"state":{"type":"string"}}},"financialCompanyDetails":{"type":"object","properties":{"declaredCompanyRevenue":{"type":"string"}}},"owner":{"type":"array","items":{"type":"object","properties":{"ownerType":{"type":"string"},"address":{"type":"object","properties":{"number":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"postalCode":{"type":"string"},"neighborhood":{"type":"string"},"state":{"type":"string"},"complement":{"type":"string"}}},"financialOwnerDetails":{"type":"object","properties":{"ownerDeclaredIncome":{"type":"string"}}},"phoneNumber":{"type":"string"},"isPoliticallyExposedPerson":{"type":"boolean"},"documentNumber":{"type":"string"},"motherName":{"type":"string"},"fullName":{"type":"string"},"type":{"type":"string"},"birthDate":{"type":"string"},"email":{"type":"string","format":"email"}}}},"proposalId":{"type":"string","format":"uuid"},"metaData":{"type":"object","properties":{"formId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"origin":{"type":"string"}}},"proposalStatus":{"type":"object","properties":{"form":{"type":"string"},"sendStatus":{"type":"string"},"proposal":{"type":"string"},"documents":{"type":"string"},"urlDocumentscopy":{}}}}},"example":{"documentNumber":"99776655000113","type":"PJ","businessName":"FULANO SILVA PUBLICIDADE, PROMOCAO E PRODUCAO DE EVENTOS ESPORTIVOS LTDA","tradingName":"NEY SILVA","businessEmail":"titular@exemplo.com.br","contactNumber":"+558145630249","businessAddress":{"number":"10","addressComplement":"CXPST 2","city":"CHA GRANDE","street":"ANTONIO","postalCode":"55636000","neighborhood":"CAMELA","state":"PE"},"financialCompanyDetails":{"declaredCompanyRevenue":"DCRB02"},"owner":[{"ownerType":"SOCIO","address":{"number":"10","city":"CHA GRANDE","street":"Av. Sao Jose","postalCode":"55636000","neighborhood":"Chã Grande","state":"PE","complement":""},"financialOwnerDetails":{"ownerDeclaredIncome":"ODIB04"},"phoneNumber":"+558112345689","isPoliticallyExposedPerson":false,"documentNumber":"55566677720","motherName":"SELMA MARIA DA SILVA","fullName":"FUNANO CRISTOVAO DA SILVA","type":"PF","birthDate":"30-11-1991","email":"contato@exemplo.com.br"}],"proposalId":"d0c39afa-d034-4330-8d57-527eacca88c6","metaData":{"formId":"31aa2217-a149-40ba-847f-c23500a635c7","createdAt":"2026-02-24T02:18:55.257Z","updatedAt":"2026-02-24T02:29:04.911Z","origin":"API"},"proposalStatus":{"form":"FINISHED","sendStatus":"SENT","proposal":"PENDING","documents":"PENDING","urlDocumentscopy":null}}}}},"400":{"description":"`MISSING_FORM_ID` — formId não informado\n\nEsta rota responde em dois formatos: validações lançadas retornam o envelope `error`; recusas de proposta retornam `{ message, code }` sem envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/SimpleError"}]}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário\n\nEsta rota responde em dois formatos: validações lançadas retornam o envelope `error`; recusas de proposta retornam `{ message, code }` sem envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/SimpleError"}]}}}},"404":{"description":"`FORM_NOT_FOUND` — Formulário não encontrado para o formId informado  \n`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas\n\nEsta rota responde em dois formatos: validações lançadas retornam o envelope `error`; recusas de proposta retornam `{ message, code }` sem envelope.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/SimpleError"}]}}}}},"description":"@botton  \nQuando a conta for aprovada, será enviado um evento na URL de webhook cadastrada nas rotas de criação de conta PF e PJ. O evento segue o seguinte layout:\n\n``` json\n{\n  \"event\": \"account_approved\",\n  \"status\": \"CONFIRMED\",\n  \"account\": {\n    \"account\": \"123456\",\n    \"branch\": \"0001\",\n    \"documentNumber\": \"123456789\",\n    \"ispb\": \"13935893\",\n    \"name\": \"Werner Heisenberg\"\n  },\n  \"onboardingId\": \"fc0e6dab-8210-4f2d-8fce-2e94990b63ef\",\n  \"documentNumber\": \"1234567889\",\n  \"formId\": \"7b83fcb4-fe9c-4ad3-8d3a-621fe9c9ffc1\",\n  \"createdAt\": \"2025-06-02T17:46:10.1120909\"\n}\n\n ```","security":[{"oauth2":["proposals/write"]}]}},"/v1/accounts/subaccounts":{"get":{"operationId":"get-listar-subcontas","summary":"Listar subcontas","tags":["Subcontas ValidaPay"],"parameters":[{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","example":"2026-02-01T00:00:00.000Z"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","example":"2026-02-23T23:59:59.999Z"}},{"name":"page","in":"query","required":false,"schema":{"type":"string","example":"1"}},{"name":"perPage","in":"query","required":false,"schema":{"type":"string","example":"15"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"masterAccountId":{"type":"string"},"subAccounts":{"type":"array","items":{"type":"object","properties":{"documentNumber":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"status":{"type":"string"},"onboardingId":{"type":"string","format":"uuid"},"name":{"type":"string"},"dailyWithdrawalLimit":{"type":"number"},"balance":{"type":"number"}}}},"page":{"type":"number"},"perPage":{"type":"number"},"hasMore":{"type":"boolean"},"dateFrom":{"type":"string","format":"date-time"},"dateTo":{"type":"string","format":"date-time"}}},"example":{"masterAccountId":"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6","subAccounts":[{"documentNumber":"66677788830","createdAt":"2026-02-23T22:29:52.537Z","accountNumber":"4960589","status":"CONFIRMED","onboardingId":"b9790268-a770-4aec-8fe5-d891f17e8007","name":"Friedrich Nietzsche","dailyWithdrawalLimit":3000,"balance":0},{"documentNumber":"33344455508","createdAt":"2026-02-17T20:38:45.664Z","accountNumber":"4949228","status":"CONFIRMED","onboardingId":"30608b18-7258-437d-a6cb-63e5882e4fb7","name":"Tales de Mileto","dailyWithdrawalLimit":3000,"balance":170.9}],"page":1,"perPage":15,"hasMore":false,"dateFrom":"2026-02-01T00:00:00.000Z","dateTo":"2026-02-23T23:59:59.999Z"}}}},"400":{"description":"`NEXT_PAGE_TOKEN_REQUIRED` — Para page maior que 1 é obrigatório enviar nextPageToken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Com esta rota você poderá listar todas as subcontas associadas à sua _master account_","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","multipleOf":0.01,"description":"Valor com precisão de duas casas decimais separado por ponto"},"split":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"]},"amount":{"type":"number","minimum":0.01}}}}},"required":["amount"]},"example":{"amount":1,"split":[{"type":"fixed","amount":0.1}]}}}},"security":[{"oauth2":["subaccounts/read"]}]}},"/v1/charges":{"get":{"operationId":"get-listar-cobrancas","summary":"Listar cobranças","tags":["Subcontas ValidaPay"],"parameters":[{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","example":"2026-02-01T00:00:00.000Z"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","example":"2026-02-23T23:59:59.999Z"}},{"name":"page","in":"query","required":false,"schema":{"type":"string","example":"1"}},{"name":"perPage","in":"query","required":false,"schema":{"type":"string","example":"15"}},{"name":"X-Sub-Account","in":"header","required":true,"description":"Subconta da qual você quer listar as cobranças","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"chargeId":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"masterAccountId":{"type":"string"},"amount":{"type":"number"},"attempts":{"type":"number"},"emvQrCode":{"type":"string"},"paymentType":{"type":"string"},"subAccountId":{"type":"string"}}}},"totalItems":{"type":"number"},"totalPages":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"dateFrom":{"type":"string","format":"date-time"},"dateTo":{"type":"string","format":"date-time"}}},"example":{"data":[{"status":"PENDING","createdAt":"2026-02-23T18:46:22.652Z","chargeId":"cha_1771872382645_qe5j0ohge","updatedAt":"2026-02-23T18:46:22.652Z","masterAccountId":"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6","amount":39.9,"attempts":1,"emvQrCode":"00020101021226930014br.gov.bcb.pix…","paymentType":"PIX","subAccountId":"4949228"},{"status":"PENDING","createdAt":"2026-02-23T18:34:13.130Z","chargeId":"cha_1771871653130_pzzsyzeha","updatedAt":"2026-02-23T18:34:13.130Z","masterAccountId":"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6","amount":39.9,"attempts":1,"emvQrCode":"00020101021226930014br.gov.bcb.pix…","paymentType":"PIX","subAccountId":"4949228"},{"status":"PENDING","createdAt":"2026-02-23T18:34:09.892Z","chargeId":"cha_1771871649852_mm0luemzr","updatedAt":"2026-02-23T18:34:09.892Z","masterAccountId":"SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6","amount":39.9,"attempts":1,"emvQrCode":"00020101021226930014br.gov.bcb.pix…","paymentType":"PIX","subAccountId":"4949228"}],"totalItems":23,"totalPages":2,"page":1,"limit":15,"dateFrom":"2026-02-01T00:00:00.000Z","dateTo":"2026-02-23T23:59:59.999Z"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Com esta rota você poderá listar todas as cobranças que a sua _master account_ gerou em uma subcontas","security":[{"oauth2":["subaccounts/read"]}]},"post":{"operationId":"post-gerar-cobranca-pix","summary":"Gerar cobrança PIX · Gerar cobrança Pix Automático · Gerar cobrança Boleto · Gerar cobrança Cartão","tags":["Checkout Transparente"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"customerId":{"type":"string"},"chargeId":{"type":"string"},"status":{"type":"string"}}},"example":{"success":true,"customerId":"cus_xxx","chargeId":"cha_abc123","status":"paid"}}}},"400":{"description":"MISSING_CARD_DATA","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"tokenId, card ou paymentMethodId é obrigatório","code":"MISSING_CARD_DATA"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardDeclined"},"example":{"success":false,"chargeId":"cha_1784065113577_5dw2oyfic","status":"failed","error":"Cartão recusado"}}}},"404":{"description":"PRICE_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Preço não encontrado","code":"PRICE_NOT_FOUND"}}}}},"409":{"description":"DUPLICATE_CHARGE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Cobrança duplicada: já existe uma cobrança para este pedido","code":"DUPLICATE_CHARGE","details":{"chargeId":"cha_1784065113577_5dw2oyfic"},"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Gera uma cobrança **PIX** pelo checkout transparente. O cliente informa os dados diretamente na sua própria interface e você os envia para a API.\n\nEnvie os dados do comprador e os itens da compra. A resposta traz o código `emv` (copia e cola) e o QR Code para pagamento.\n\nProduto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.pix.generated` (envia o QR Code ao comprador assim que a cobrança é criada), `oneoff.payment.success` (confirmação ao comprador quando o Pix compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `404 PRICE_NOT_FOUND` (preço inexistente) e `400 INVALID_DATA` (campo inválido).\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\n### Emitindo nota fiscal na cobrança\n\nEnvie `nfConfigId` com o identificador de uma configuração fiscal criada em `POST /v1/invoices/notas/config`. Com ele presente:\n\n- `customer.address` passa a ser **obrigatório** — a nota precisa do endereço do tomador. Sem ele: `400 INVALID_DATA`.\n- O momento da emissão vem da configuração, não da cobrança: `invoiceTiming` aceita `IMMEDIATE` (padrão), `AFTER_CONFIRMATION` e `DAYS_AFTER_CONFIRMATION`; neste último, `daysAfterConfirmation` define em quantos dias (padrão 1).\n- O `cityCode` (IBGE) do endereço é resolvido a partir do CEP e é necessário para a NFS-e.\n\nO mesmo campo existe em produtos (`POST /v1/products`) e nas configurações de assinatura, para emitir nota a cada ciclo sem repetir o `nfConfigId` em cada cobrança.\n\nInicia uma assinatura com **Pix Automático** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.\n\nA resposta traz `pix.emv` (copia e cola) e `pix.recurrencyId`.\n\nEnquanto o banco do pagador não confirma a autorização, a assinatura fica com status `PENDING`.\n\nRequisitos:\n\n- conta ValidaPay cadastrada como **PJ** (CNPJ)\n- `items` com preço **recorrente** (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY); não use `amount` avulso\n- valor mínimo de **R$ 4,99** por cobrança\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.payment.success` (confirmação ao comprador quando o Pix compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF), `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo), `409 DUPLICATE_CHARGE` (externalId já utilizado) e `404 PRICE_NOT_FOUND` (preço inexistente).\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\nGera uma cobrança via **boleto** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.\n\nPara boleto, o **endereço completo do comprador é obrigatório**. Você pode personalizar vencimento, multa, juros e desconto por meio de `boletoInstructions`.\n\nProduto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.boleto.generated` (envia o boleto ao comprador assim que a cobrança é criada), `oneoff.payment.success` (confirmação ao comprador quando o boleto compensa) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `404 PRICE_NOT_FOUND` (preço inexistente) e `400 INVALID_DATA` (campo inválido — inclui endereço ausente).\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.\n\nGera uma cobrança via **cartão de crédito** pelo checkout transparente. O cliente informa os dados na sua própria interface e você os envia para a API.\n\nEnvie os dados do cartão no objeto `card` (dados brutos) ou use `paymentMethodId`/`tokenId` de um cartão tokenizado. É possível parcelar (`installments`) e repassar as taxas ao comprador.\n\nProduto ou valor: envie `items` com os produtos OU `amount` para uma cobrança avulsa.\n\nNotificações por e-mail: use `notifications` para escolher quais e-mails saem nesta cobrança. Eventos aceitos aqui: `oneoff.payment.success` (confirmação ao comprador quando o cartão é aprovado), `oneoff.payment.failed` (aviso ao comprador quando o cartão é recusado) e `new.sale` (avisa você, vendedor, da venda paga). Os eventos destinados ao comprador exigem `customer.email`. Sem o campo, uma cobrança avulsa (enviada com `amount`) não dispara e-mail nenhum; com `items` de um produto, vale a configuração de notificações do produto, e `notifications` no payload tem precedência sobre ela.\n\n> ⚠️ **Atenção:** envie o campo `externalId` como chave de idempotência (idempotencyKey). Se duas cobranças forem enviadas com o mesmo `externalId`, a segunda é recusada com `409 DUPLICATE_CHARGE`, retornando o `chargeId` da cobrança original.\n\nErros comuns: `409 DUPLICATE_CHARGE` (externalId já utilizado), `402` (pagamento recusado pelo banco), `400 MISSING_CARD_DATA` (faltam dados do cartão) e `404 PRICE_NOT_FOUND` (preço inexistente).\n\n**Cartões de teste (sandbox):** em conta de sandbox nenhuma cobrança chega ao adquirente — o número do cartão é que define o resultado:\n\n- `4111111111111111` — pagamento aprovado\n- `4000000000000002` — recusado pela operadora (`card_declined`)\n- `4000000000000004` — saldo insuficiente (`insufficient_funds`)\n- `4000000000000006` — cartão expirado (`expired_card`)\n- `4000000000000008` — CVV inválido (`invalid_cvv`)\n- `4000000000000010` — suspeita de fraude (`fraud_suspected`)\n\nQualquer outro número de 16 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. Em produção o número não muda nada: quem decide é o emissor do cartão.\n\nUse `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.\n\n**Correlação com o pedido:** use `externalId` — ele é persistido e devolvido. O campo `metadata` é aceito nesta rota mas **não é gravado na cobrança** nem volta no webhook; ele só é persistido em `POST /v1/charges/pix`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"Gerar cobrança PIX","type":"object","properties":{"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Forma de pagamento (fixo: pix)"},"customer":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo"},"email":{"type":"string","format":"email","description":"E-mail"},"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14 dígitos)"},"phone":{"type":"string","description":"Telefone"},"cep":{"type":"string","description":"CEP (necessário para PIX com dados do pagador)"}},"required":["name","email","documentNumber"],"description":"Dados do comprador"},"externalId":{"type":"string","maxLength":100,"description":"Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)"},"externalTxid":{"type":"string","maxLength":100,"description":"Identifica a loja, o caixa ou o vendedor responsável pela cobrança"},"items":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^price_","description":"ID do preço do produto"},"quantity":{"type":"integer","minimum":1,"description":"Quantidade (default 1)"}},"required":["priceId"]},"description":"Produtos da compra (ou use amount para cobrança avulsa)"},"expiration":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiração do QR Code PIX (YYYY-MM-DD)"},"couponCode":{"type":"string","description":"Código de cupom de desconto"},"metadata":{"type":"object","properties":{"referencia":{"type":"string"}}},"description":{"type":"string","description":"Descricao livre da cobranca"},"split":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"]},"accountNumber":{"type":"string"},"amount":{"type":"number","minimum":0.01}}},"description":"Divisao do valor. Nao suportado em creditcard nem pix_automatico"},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"Parcelas no cartao, de 1 a 12"},"freeInstallments":{"type":"integer","minimum":0,"maximum":12,"description":"Parcelas sem juros para o comprador, de 0 a 12"},"passFeesToCustomer":{"type":"boolean","description":"Repassa a taxa de parcelamento ao comprador"},"allowedPaymentMethods":{"type":"array","items":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"]}},"nfConfigId":{"type":"string","minLength":1,"description":"Emite nota fiscal com esta configuracao. Exige customer.address"},"notifications":{"type":"array","items":{"type":"string","enum":["oneoff.pix.generated","oneoff.boleto.generated","oneoff.payment.success","oneoff.payment.failed","new.sale","seller.charge.pending"]}},"discounts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENTAGE","FIXED","percentage","fixed"],"description":"Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais"},"value":{"type":"number","description":"Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed"},"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Aplica o desconto so neste metodo de pagamento"},"fromCycle":{"type":"number","description":"Primeiro ciclo em que o desconto vale, em cobrancas recorrentes"},"toCycle":{"type":"number","description":"Ultimo ciclo; null mantem o desconto ate o fim da assinatura"},"durationMonths":{"type":"number","description":"Alternativa a toCycle: por quantos meses o desconto vale"}},"required":["type","value"]},"description":"Descontos aplicados a cobranca"},"tokenId":{"type":"string","description":"Alternativa a card e a paymentMethodId no cartao"},"productId":{"type":"string","pattern":"^prod_","description":"Cria a cobranca a partir de um produto"},"recurrencyStartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Primeira cobranca da recorrencia (YYYY-MM-DD)"},"prorataStartDate":{"type":"string","format":"date","description":"Inicio do calculo pro rata"},"prorataDueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento da cobranca pro rata (YYYY-MM-DD)"},"mergeWithNextCycle":{"type":"boolean","description":"Junta a pro rata com o proximo ciclo em vez de cobrar agora"}},"required":["paymentMethod","customer"]},{"title":"Gerar cobrança Pix Automático","type":"object","properties":{"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Forma de pagamento (fixo: pix_automatico)"},"customer":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo"},"email":{"type":"string","format":"email","description":"E-mail"},"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14 dígitos)"},"phone":{"type":"string","description":"Telefone"}},"required":["name","email","documentNumber"],"description":"Dados do comprador"},"items":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^price_","description":"ID do preço recorrente (valor mínimo de R$ 4,99)"},"quantity":{"type":"integer","minimum":1,"description":"Quantidade (default 1)"}},"required":["priceId"]},"description":"Itens da assinatura; o preço precisa ser recorrente"},"externalId":{"type":"string","maxLength":100,"description":"Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)"},"externalTxid":{"type":"string","maxLength":100,"description":"Identifica a loja, o caixa ou o vendedor responsável pela cobrança"},"billingDay":{"type":"number","minimum":1,"maximum":31,"description":"Dia do mês das cobranças seguintes (1 a 31)"},"couponCode":{"type":"string","description":"Código de cupom de desconto"},"metadata":{"type":"object","properties":{"referencia":{"type":"string"}}},"description":{"type":"string","description":"Descricao livre da cobranca"},"split":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"]},"accountNumber":{"type":"string"},"amount":{"type":"number","minimum":0.01}}},"description":"Divisao do valor. Nao suportado em creditcard nem pix_automatico"},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"Parcelas no cartao, de 1 a 12"},"freeInstallments":{"type":"integer","minimum":0,"maximum":12,"description":"Parcelas sem juros para o comprador, de 0 a 12"},"passFeesToCustomer":{"type":"boolean","description":"Repassa a taxa de parcelamento ao comprador"},"allowedPaymentMethods":{"type":"array","items":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"]}},"nfConfigId":{"type":"string","minLength":1,"description":"Emite nota fiscal com esta configuracao. Exige customer.address"},"notifications":{"type":"array","items":{"type":"string","enum":["oneoff.pix.generated","oneoff.boleto.generated","oneoff.payment.success","oneoff.payment.failed","new.sale","seller.charge.pending"]}},"discounts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENTAGE","FIXED","percentage","fixed"],"description":"Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais"},"value":{"type":"number","description":"Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed"},"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Aplica o desconto so neste metodo de pagamento"},"fromCycle":{"type":"number","description":"Primeiro ciclo em que o desconto vale, em cobrancas recorrentes"},"toCycle":{"type":"number","description":"Ultimo ciclo; null mantem o desconto ate o fim da assinatura"},"durationMonths":{"type":"number","description":"Alternativa a toCycle: por quantos meses o desconto vale"}},"required":["type","value"]},"description":"Descontos aplicados a cobranca"},"tokenId":{"type":"string","description":"Alternativa a card e a paymentMethodId no cartao"},"productId":{"type":"string","pattern":"^prod_","description":"Cria a cobranca a partir de um produto"},"recurrencyStartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Primeira cobranca da recorrencia (YYYY-MM-DD)"},"prorataStartDate":{"type":"string","format":"date","description":"Inicio do calculo pro rata"},"prorataDueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento da cobranca pro rata (YYYY-MM-DD)"},"mergeWithNextCycle":{"type":"boolean","description":"Junta a pro rata com o proximo ciclo em vez de cobrar agora"}},"required":["paymentMethod","customer","items"]},{"title":"Gerar cobrança Boleto","type":"object","properties":{"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Forma de pagamento (fixo: boleto)"},"customer":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo"},"email":{"type":"string","format":"email","description":"E-mail"},"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14 dígitos)"},"address":{"type":"object","properties":{"street":{"type":"string","description":"Rua ou logradouro"},"number":{"type":"string","description":"Número"},"neighborhood":{"type":"string","description":"Bairro"},"city":{"type":"string","description":"Cidade"},"state":{"type":"string","description":"UF com 2 letras"},"zipCode":{"type":"string","description":"CEP com 8 dígitos"},"complement":{"type":"string","description":"Complemento"},"country":{"type":"string","description":"País (default BR)"},"cityCode":{"type":"string","description":"Código IBGE (necessário para nota fiscal)"}},"required":["street","number","neighborhood","city","state","zipCode"],"description":"Endereço do comprador (obrigatório para boleto)"},"phone":{"type":"string","description":"Telefone"}},"required":["name","email","documentNumber","address"],"description":"Dados do comprador"},"externalId":{"type":"string","maxLength":100,"description":"Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)"},"externalTxid":{"type":"string","maxLength":100,"description":"Identifica a loja, o caixa ou o vendedor responsável pela cobrança"},"items":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^price_","description":"ID do preço do produto"},"quantity":{"type":"integer","minimum":1,"description":"Quantidade (default 1)"}},"required":["priceId"]},"description":"Produtos da compra (ou use amount para cobrança avulsa)"},"dueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento do boleto (YYYY-MM-DD, maior que hoje)"},"boletoDueDays":{"type":"integer","minimum":1,"description":"Dias até o vencimento (mín. 1; ignorado se dueDate informado)"},"expirationAfterDueDate":{"type":"integer","minimum":0,"maximum":60,"description":"Dias para cancelar o boleto após o vencimento (0 a 60)"},"boletoInstructions":{"type":"object","properties":{"fine":{"type":"number","description":"Multa por atraso em % (0.1 a 100; fine + interest <= 60)"},"interest":{"type":"number","description":"Juros mensais por atraso em % (0.1 a 100)"},"discount":{"type":"object","properties":{"amount":{"type":"number","multipleOf":0.01,"description":"Valor do desconto"},"modality":{"type":"string","description":"fixed (R$) ou percent (%)"},"limitDate":{"type":"string","format":"date","description":"Data limite do desconto (antes de dueDate)"}},"description":"Desconto para pagamento antecipado"}},"description":"Regras de multa/juros/desconto do boleto"},"couponCode":{"type":"string","description":"Código de cupom de desconto"},"metadata":{"type":"object","properties":{"referencia":{"type":"string"}}},"description":{"type":"string","description":"Descricao livre da cobranca"},"split":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"]},"accountNumber":{"type":"string"},"amount":{"type":"number","minimum":0.01}}},"description":"Divisao do valor. Nao suportado em creditcard nem pix_automatico"},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"Parcelas no cartao, de 1 a 12"},"freeInstallments":{"type":"integer","minimum":0,"maximum":12,"description":"Parcelas sem juros para o comprador, de 0 a 12"},"passFeesToCustomer":{"type":"boolean","description":"Repassa a taxa de parcelamento ao comprador"},"allowedPaymentMethods":{"type":"array","items":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"]}},"nfConfigId":{"type":"string","minLength":1,"description":"Emite nota fiscal com esta configuracao. Exige customer.address"},"notifications":{"type":"array","items":{"type":"string","enum":["oneoff.pix.generated","oneoff.boleto.generated","oneoff.payment.success","oneoff.payment.failed","new.sale","seller.charge.pending"]}},"discounts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENTAGE","FIXED","percentage","fixed"],"description":"Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais"},"value":{"type":"number","description":"Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed"},"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Aplica o desconto so neste metodo de pagamento"},"fromCycle":{"type":"number","description":"Primeiro ciclo em que o desconto vale, em cobrancas recorrentes"},"toCycle":{"type":"number","description":"Ultimo ciclo; null mantem o desconto ate o fim da assinatura"},"durationMonths":{"type":"number","description":"Alternativa a toCycle: por quantos meses o desconto vale"}},"required":["type","value"]},"description":"Descontos aplicados a cobranca"},"tokenId":{"type":"string","description":"Alternativa a card e a paymentMethodId no cartao"},"productId":{"type":"string","pattern":"^prod_","description":"Cria a cobranca a partir de um produto"},"recurrencyStartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Primeira cobranca da recorrencia (YYYY-MM-DD)"},"prorataStartDate":{"type":"string","format":"date","description":"Inicio do calculo pro rata"},"prorataDueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento da cobranca pro rata (YYYY-MM-DD)"},"mergeWithNextCycle":{"type":"boolean","description":"Junta a pro rata com o proximo ciclo em vez de cobrar agora"}},"required":["paymentMethod","customer"]},{"title":"Gerar cobrança Cartão","type":"object","properties":{"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Forma de pagamento (fixo: creditcard)"},"customer":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo"},"email":{"type":"string","format":"email","description":"E-mail"},"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14 dígitos)"},"phone":{"type":"string","description":"Telefone"}},"required":["name","email","documentNumber"],"description":"Dados do comprador"},"card":{"type":"object","properties":{"number":{"type":"string","description":"Número do cartão (13 a 19 dígitos)"},"cvv":{"type":"string","description":"Código de segurança (3 ou 4 dígitos)"},"name":{"type":"string","description":"Nome como está no cartão"},"expiration":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Validade no formato MM/YYYY"}},"required":["number","cvv","name","expiration"],"description":"Dados do cartão (ou use paymentMethodId/tokenId de um cartão salvo)"},"externalId":{"type":"string","maxLength":100,"description":"Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)"},"externalTxid":{"type":"string","maxLength":100,"description":"Identifica a loja, o caixa ou o vendedor responsável pela cobrança"},"paymentMethodId":{"type":"string","description":"Cartão tokenizado (alternativa ao objeto card)"},"items":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^price_","description":"ID do preço do produto"},"quantity":{"type":"integer","minimum":1,"description":"Quantidade (default 1)"}},"required":["priceId"]},"description":"Produtos da compra (ou use amount para cobrança avulsa)"},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"Parcelas no cartao, de 1 a 12"},"passFeesToCustomer":{"type":"boolean","description":"Repassa a taxa de parcelamento ao comprador"},"freeInstallments":{"type":"integer","minimum":0,"maximum":12,"description":"Parcelas sem juros para o comprador, de 0 a 12"},"couponCode":{"type":"string","description":"Código de cupom de desconto"},"metadata":{"type":"object","properties":{"referencia":{"type":"string"}}},"description":{"type":"string","description":"Descricao livre da cobranca"},"split":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["percentage","fixed"]},"accountNumber":{"type":"string"},"amount":{"type":"number","minimum":0.01}}},"description":"Divisao do valor. Nao suportado em creditcard nem pix_automatico"},"allowedPaymentMethods":{"type":"array","items":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"]}},"nfConfigId":{"type":"string","minLength":1,"description":"Emite nota fiscal com esta configuracao. Exige customer.address"},"notifications":{"type":"array","items":{"type":"string","enum":["oneoff.pix.generated","oneoff.boleto.generated","oneoff.payment.success","oneoff.payment.failed","new.sale","seller.charge.pending"]}},"discounts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENTAGE","FIXED","percentage","fixed"],"description":"Tipo do desconto: percentual sobre o valor ou abatimento fixo em reais"},"value":{"type":"number","description":"Percentual de 0 a 100 quando type e percentage; valor em reais quando fixed"},"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Aplica o desconto so neste metodo de pagamento"},"fromCycle":{"type":"number","description":"Primeiro ciclo em que o desconto vale, em cobrancas recorrentes"},"toCycle":{"type":"number","description":"Ultimo ciclo; null mantem o desconto ate o fim da assinatura"},"durationMonths":{"type":"number","description":"Alternativa a toCycle: por quantos meses o desconto vale"}},"required":["type","value"]},"description":"Descontos aplicados a cobranca"},"tokenId":{"type":"string","description":"Alternativa a card e a paymentMethodId no cartao"},"productId":{"type":"string","pattern":"^prod_","description":"Cria a cobranca a partir de um produto"},"recurrencyStartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Primeira cobranca da recorrencia (YYYY-MM-DD)"},"prorataStartDate":{"type":"string","format":"date","description":"Inicio do calculo pro rata"},"prorataDueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento da cobranca pro rata (YYYY-MM-DD)"},"mergeWithNextCycle":{"type":"boolean","description":"Junta a pro rata com o proximo ciclo em vez de cobrar agora"}},"required":["paymentMethod","customer","card"]}]},"examples":{"gerar-cobranca-pix":{"summary":"Gerar cobrança PIX","value":{"paymentMethod":"pix","externalId":"pedido-2026-0001","externalTxid":"loja-01-caixa-03","customer":{"name":"João da Silva","email":"joao@email.com","documentNumber":"12345678901","phone":"+5511999998888","cep":"01310100"},"items":[{"priceId":"price_abc123","quantity":1}],"expiration":"2026-07-30","couponCode":"PROMO10","metadata":{"referencia":"pedido-001"},"description":"Assinatura Premium","split":[{"type":"fixed","accountNumber":"896532569","amount":0.1}],"installments":1,"freeInstallments":1,"passFeesToCustomer":false,"allowedPaymentMethods":["pix","creditcard"],"nfConfigId":"nfc_1788364755079_psuecwgdc","notifications":["oneoff.pix.generated","oneoff.payment.success","new.sale"],"discounts":[{"type":"percentage","value":10,"paymentMethod":"pix","fromCycle":1,"toCycle":3,"durationMonths":3}],"tokenId":"tok_abc123","productId":"prod_123456_example","recurrencyStartDate":"2026-10-01","prorataStartDate":"2026-09-15","prorataDueDate":"2026-09-20","mergeWithNextCycle":false}},"gerar-cobranca-pix-automatico":{"summary":"Gerar cobrança Pix Automático","value":{"paymentMethod":"pix_automatico","externalId":"assinatura-2026-0001","externalTxid":"loja-01-caixa-03","customer":{"name":"João da Silva","email":"joao@email.com","documentNumber":"12345678901","phone":"+5511999998888"},"items":[{"priceId":"price_abc123","quantity":1}],"billingDay":15,"couponCode":"PROMO10","metadata":{"referencia":"assinatura-001"},"description":"Assinatura Premium","split":[{"type":"fixed","accountNumber":"896532569","amount":0.1}],"installments":1,"freeInstallments":1,"passFeesToCustomer":false,"allowedPaymentMethods":["pix","creditcard"],"nfConfigId":"nfc_1788364755079_psuecwgdc","notifications":["oneoff.pix.generated","new.sale"],"discounts":[{"type":"percentage","value":10,"paymentMethod":"pix","fromCycle":1,"toCycle":3,"durationMonths":3}],"tokenId":"tok_abc123","productId":"prod_123456_example","recurrencyStartDate":"2026-10-01","prorataStartDate":"2026-09-15","prorataDueDate":"2026-09-20","mergeWithNextCycle":false}},"gerar-cobranca-boleto":{"summary":"Gerar cobrança Boleto","value":{"paymentMethod":"boleto","externalId":"pedido-2026-0001","externalTxid":"loja-01-caixa-03","customer":{"name":"João da Silva","email":"joao@email.com","documentNumber":"12345678901","phone":"+5511999998888","address":{"street":"Av. Paulista","number":"1000","complement":"Apto 52","neighborhood":"Bela Vista","city":"São Paulo","state":"SP","zipCode":"01310100","country":"BR","cityCode":"3550308"}},"items":[{"priceId":"price_abc123","quantity":1}],"dueDate":"2026-07-30","boletoDueDays":7,"expirationAfterDueDate":30,"boletoInstructions":{"fine":2,"interest":1,"discount":{"amount":10,"modality":"fixed","limitDate":"2026-07-28"}},"couponCode":"PROMO10","metadata":{"referencia":"pedido-001"},"description":"Assinatura Premium","split":[{"type":"fixed","accountNumber":"896532569","amount":0.1}],"installments":1,"freeInstallments":1,"passFeesToCustomer":false,"allowedPaymentMethods":["pix","creditcard"],"nfConfigId":"nfc_1788364755079_psuecwgdc","notifications":["oneoff.pix.generated","oneoff.payment.success","new.sale"],"discounts":[{"type":"percentage","value":10,"paymentMethod":"pix","fromCycle":1,"toCycle":3,"durationMonths":3}],"tokenId":"tok_abc123","productId":"prod_123456_example","recurrencyStartDate":"2026-10-01","prorataStartDate":"2026-09-15","prorataDueDate":"2026-09-20","mergeWithNextCycle":false}},"gerar-cobranca-cartao":{"summary":"Gerar cobrança Cartão","value":{"paymentMethod":"creditcard","externalId":"pedido-2026-0001","externalTxid":"loja-01-caixa-03","customer":{"name":"João da Silva","email":"joao@email.com","documentNumber":"12345678901","phone":"+5511999998888"},"card":{"number":"4111111111111111","cvv":"123","name":"JOAO DA SILVA","expiration":"12/2027"},"paymentMethodId":"pm_abc123","items":[{"priceId":"price_abc123","quantity":1}],"installments":1,"passFeesToCustomer":false,"freeInstallments":1,"couponCode":"PROMO10","metadata":{"referencia":"pedido-001"},"description":"Assinatura Premium","split":[{"type":"fixed","accountNumber":"896532569","amount":0.1}],"allowedPaymentMethods":["pix","creditcard"],"nfConfigId":"nfc_1788364755079_psuecwgdc","notifications":["oneoff.pix.generated","oneoff.payment.success","new.sale"],"discounts":[{"type":"percentage","value":10,"paymentMethod":"pix","fromCycle":1,"toCycle":3,"durationMonths":3}],"tokenId":"tok_abc123","productId":"prod_123456_example","recurrencyStartDate":"2026-10-01","prorataStartDate":"2026-09-15","prorataDueDate":"2026-09-20","mergeWithNextCycle":false}}}}}},"security":[{"oauth2":["checkouts/write"]}]}},"/v1/wallet/balance":{"get":{"operationId":"get-saldo-subcontas","summary":"Saldo subcontas","tags":["Subcontas ValidaPay"],"parameters":[{"name":"accountId","in":"query","required":true,"description":"Número da subconta. Para consultar o saldo de várias subcontas envie separado por virgula","schema":{"type":"string","example":"9489623"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"masterAccountId":{"type":"string"},"balances":{"type":"array","items":{"type":"object","properties":{"accountNumber":{"type":"string"},"name":{"type":"string"},"balance":{"type":"number"}}}}}},"example":{"masterAccountId":"429131313","balances":[{"accountNumber":"459013888","name":"VALIDAPAY PAGAMENTOS TECNOLOGIA E SERVICOS","balance":54.81},{"accountNumber":"460851986","name":"VALIDA PIX","balance":196.82}]}}}},"401":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Subconta 436514888 nao pertence a esta conta master","code":"UNAUTHORIZED_SUBACCOUNT","details":null,"timestamp":"2026-03-17T03:45:53.738Z"}}}}},"404":{"description":"Subconta não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Subconta 459013666 nao encontrada","code":"SUBACCOUNT_NOT_FOUND","details":null,"timestamp":"2026-03-17T03:46:49.577Z"}}}}}},"description":"Com esta funcionalidade você pode verificar o saldo de uma ou várias subcontas\n\n> ⚠️ **Atenção:** Para consultar o saldo de várias subcontas envie o header acoountId com o número das subcontas separado por vírgula, por exemplo: 9489623,9489624,9489625","security":[{"oauth2":["wallet/read"]}]}},"/v1/products":{"post":{"operationId":"post-criar-produto","summary":"Criar Produto","tags":["Produtos"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"checkoutUrl":{"type":"string"}}}}}},"example":{"productId":"prod_xxx","name":"Plano Premium","prices":[{"priceId":"price_xxx","amount":99.9,"checkoutUrl":"https://app.validapay.com.br/pagamento/pl_xxx"}]}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"O campo name é obrigatório","code":"INVALID_PRODUCT_DATA","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Cria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência.\n\nOs produtos criados ficam disponíveis no painel administrativo e podem ser utilizados tanto no checkout transparente (via API) quanto no checkout pro (link de pagamento).\n\nTipos de recorrência em prices[].recurrenceType:\n\n- ONE_TIME → Avulsa\n- WEEKLY → Semanal\n- MONTHLY → Mensal\n- QUARTERLY → Trimestral\n- SEMIANNUAL → Semestral\n- YEARLY → Anual\n\nCase de uso:\n\n_Como SaaS, quero cadastrar meus planos como produtos com preços recorrentes, para que meus clientes possam assinar diretamente pelo checkout pro ou pela minha própria interface._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome do produto"},"prices":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"amount":{"type":"number","multipleOf":0.01,"description":"Valor em reais (> 0)"},"recurrenceType":{"type":"string","enum":["ONE_TIME","DAILY","WEEKLY","MONTHLY","QUARTERLY","SEMIANNUAL","YEARLY"],"description":"WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, YEARLY ou ONE_TIME"},"currency":{"type":"string","enum":["BRL"]},"recurrenceInterval":{"type":"number","description":"min 1 (ex: 2 = bimestral)"},"trialDays":{"type":"number"},"compareAtPrice":{"type":"number","description":"Preço \"de\""}},"required":["title","amount","recurrenceType"]}},"description":{"type":"string"},"type":{"type":"string","description":"RECURRING ou ONE_TIME (default RECURRING)"},"statementDescriptor":{"type":"string","description":"max 22 caracteres"},"isActive":{"type":"boolean"},"metadata":{"type":"object","properties":{}}},"required":["name","prices"]},"example":{"name":"Plano Premium","description":"Acesso completo à plataforma","type":"RECURRING","statementDescriptor":"VALIDAPAY PREMIUM","isActive":true,"metadata":{},"prices":[{"title":"Mensal","amount":99.9,"currency":"BRL","recurrenceType":"MONTHLY","recurrenceInterval":1,"trialDays":7,"compareAtPrice":129.9},{"title":"Anual","amount":899,"currency":"BRL","recurrenceType":"YEARLY","recurrenceInterval":1}]}}}},"security":[{"oauth2":["products/write"]}]},"get":{"operationId":"get-listar-produtos","summary":"Listar Produtos","tags":["Produtos"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página (default 50) - optional","schema":{"type":"string","example":"50"}},{"name":"lastKey","in":"query","required":true,"description":"base64 - optional","schema":{"type":"string"}},{"name":"status","in":"query","required":true,"description":"active | inactive - optional","schema":{"type":"string"}},{"name":"search","in":"query","required":true,"description":"busca por nome - optional","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"}}}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"hasMore":{"type":"boolean"},"lastKey":{}}}}},"example":{"items":[{"productId":"prod_xxx","name":"Plano Premium"}],"pagination":{"total":10,"hasMore":false,"lastKey":null}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Lista todos os produtos cadastrados com suporte a filtros por status e paginação.","security":[{"oauth2":["products/read"]}]}},"/v1/products/{id}":{"get":{"operationId":"get-buscar-produto","summary":"Buscar Produto","tags":["Produtos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"}}}}}},"example":{"productId":"prod_xxx","name":"Plano Premium","prices":[{"priceId":"price_xxx","amount":99.9}]}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Produto não encontrado","code":"PRODUCT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Retorna todos os detalhes de um produto específico, incluindo preço e configurações.","security":[{"oauth2":["products/read"]}]},"put":{"operationId":"put-atualizar-produto","summary":"Atualizar Produto","tags":["Produtos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"newPrices":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string"}}}}}},"example":{"productId":"prod_xxx","name":"Plano Premium Plus","newPrices":[{"priceId":"price_yyy"}]}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Produto não encontrado","code":"PRODUCT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Atualiza as informações de um produto, como nome, descrição ou preço.\nMesmos campos de POST (todos opcionais). Para atualizar preço existente, inclua `priceId` no item de `prices[]`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"statementDescriptor":{"type":"string"},"isActive":{"type":"boolean"},"metadata":{"type":"object","properties":{}},"prices":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","description":"ID do preço existente"},"amount":{"type":"number","multipleOf":0.01},"recurrenceType":{"type":"string","enum":["ONE_TIME","DAILY","WEEKLY","MONTHLY","QUARTERLY","SEMIANNUAL","YEARLY"]},"recurrenceInterval":{"type":"number"},"trialDays":{"type":"number"},"compareAtPrice":{"type":"number"},"title":{"type":"string","description":"Novo preço"}}},"description":"Para atualizar preço existente, inclua priceId no item"}}},"example":{"name":"Plano Premium Plus","description":"Acesso completo à plataforma","type":"RECURRING","statementDescriptor":"VALIDAPAY PREMIUM","isActive":true,"metadata":{},"prices":[{"priceId":"price_xxx","amount":109.9,"recurrenceType":"MONTHLY","recurrenceInterval":1,"trialDays":7,"compareAtPrice":129.9},{"title":"Trimestral","amount":279,"recurrenceType":"QUARTERLY","recurrenceInterval":1}]}}}},"security":[{"oauth2":["products/write"]}]},"delete":{"operationId":"delete-remover-produto","summary":"Remover Produto","tags":["Produtos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"productId":{"type":"string"}}},"example":{"deleted":true,"productId":"prod_xxx"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Não é possível deletar um produto que possui assinaturas vinculadas","code":"PRODUCT_HAS_SUBSCRIPTIONS","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Produto não encontrado","code":"PRODUCT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Remove um produto que não esteja vinculado a assinaturas ativas.","security":[{"oauth2":["products/write"]}]}},"/v1/products/{id}/archive":{"post":{"operationId":"post-arquivar-produto","summary":"Arquivar Produto","tags":["Produtos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"archivedAt":{"type":"string","format":"date-time"},"checkoutsDeactivated":{"type":"number"}}},"example":{"productId":"prod_xxx","archivedAt":"2024-01-20T10:00:00Z","checkoutsDeactivated":3}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Produto não encontrado","code":"PRODUCT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Guarda o produto sem excluí-lo, mantendo o histórico de cobranças vinculadas.","security":[{"oauth2":["products/write"]}]}},"/v1/checkouts":{"post":{"operationId":"post-criar-link-de-pagamento","summary":"Criar link de pagamento","tags":["Links de pagamento"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"priceId":{"type":"string"}}},"example":{"id":"pl_xxx","url":"https://app.validapay.com.br/pagamento/pl_xxx","priceId":"price_xxx"}}}},"400":{"description":"`PRODUCT_DATA_REQUIRED` — Informe priceId ou os dados do produto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`PRICE_NOT_FOUND` — Preço não encontrado  \n`PRODUCT_NOT_FOUND` — Produto não encontrado  \n`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Cria uma página de pagamento (payment link) configurável, com produtos, formas de pagamento aceitas, cupons e aparência personalizada. O link é reutilizável e não fica vinculado a um cliente específico.\n\nÉ obrigatório informar `priceId` (preço já cadastrado) ou `product` (produto com preços inline).\n\nFormas de pagamento suportadas: pix, creditcard, boleto e pix_automatico.\n\n**Pix Automático** está disponível apenas para **contas PJ** (conta ValidaPay cadastrada com CNPJ) e só é aceito em preços recorrentes (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY). O cliente autoriza a recorrência uma única vez no aplicativo do banco e as cobranças seguintes são debitadas automaticamente, sem novo QR Code a cada ciclo. Até o banco do pagador confirmar a autorização, a assinatura fica com status `PENDING`.\n\nO valor mínimo por cobrança é de **R$ 4,99**.\n\nErros: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF) e `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo).\n\nAo informar `termsOfServiceUrl` e/ou `privacyPolicyUrl`, o checkout exibe um aceite obrigatório com os links: o cliente só consegue finalizar a compra depois de marcar que leu e concorda. O texto do aceite se adapta a um ou aos dois links. Sem esses campos, nenhum aceite é exibido.\n\nCase de uso:\n\n_Como SaaS, quero criar um link de pagamento reutilizável para uma oferta — definindo cores, parcelamento e order bumps — e compartilhá-lo com vários clientes._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","description":"ID do preço já cadastrado (obrigatório priceId OU product)"},"allowedPaymentMethods":{"type":"array","items":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"]},"description":"Formas de pagamento aceitas: pix, creditcard, boleto, pix_automatico (só conta PJ, em preço recorrente)"},"successUrl":{"type":"string","description":"Redireciona após pagamento aprovado"},"cancelUrl":{"type":"string","description":"Redireciona ao cancelar"},"redirectAfterPaymentUrl":{"type":"string","description":"URL de redirecionamento pós-pagamento"},"termsOfServiceUrl":{"type":"string","description":"Termos de serviço exibidos no checkout para aceite do cliente"},"privacyPolicyUrl":{"type":"string","description":"Política de privacidade exibida no checkout para aceite do cliente"},"successMessage":{"type":"string","description":"Mensagem exibida após o pagamento"},"maxInstallments":{"type":"number","description":"Limite de parcelas (1 a 12)"},"freeInstallments":{"type":"integer","minimum":0,"maximum":12,"description":"Parcelas sem juros (1 a 12, default 1)"},"passFeesToCustomer":{"type":"boolean","description":"Repassa as taxas ao cliente (default false)"},"checkoutName":{"type":"string","description":"Nome interno do checkout"},"primaryColor":{"type":"string","description":"Cor primária em hex"},"secondaryColor":{"type":"string","description":"Cor secundária em hex"},"fontColor":{"type":"string","description":"Cor do texto em hex"},"showProductImage":{"type":"boolean","description":"Exibir imagem do produto (default true)"},"metadata":{"type":"object","properties":{}},"orderBumps":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","description":"priceId do produto adicional"},"label":{"type":"string","description":"Texto exibido"},"displayMode":{"type":"string","description":"Modo de exibição"}},"required":["priceId"]},"description":"Produtos adicionais oferecidos no checkout"}},"required":["priceId","allowedPaymentMethods"]},"example":{"priceId":"price_xxx","allowedPaymentMethods":["pix","creditcard","boleto","pix_automatico"],"successUrl":"https://meusite.com/obrigado","cancelUrl":"https://meusite.com/cancelado","redirectAfterPaymentUrl":"https://meusite.com/redirect","termsOfServiceUrl":"https://meusite.com/termos-de-servico","privacyPolicyUrl":"https://meusite.com/politica-de-privacidade","successMessage":"Obrigado pela compra!","maxInstallments":12,"freeInstallments":1,"passFeesToCustomer":false,"checkoutName":"Oferta Black Friday","primaryColor":"#7C3AED","secondaryColor":"#EDE9FE","fontColor":"#1F2937","showProductImage":true,"metadata":{},"orderBumps":[{"priceId":"price_yyy","label":"Adicionar suporte premium","displayMode":"checkbox"}]}}}},"security":[{"oauth2":["checkouts/write"]}]},"get":{"operationId":"get-listar-links-de-pagamento","summary":"Listar links de pagamento","tags":["Links de pagamento"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página (default 15) - optional","schema":{"type":"string","example":"15"}},{"name":"lastKey","in":"query","required":true,"description":"base64 - optional","schema":{"type":"string"}},{"name":"status","in":"query","required":true,"description":"Filtra por status do checkout - optional","schema":{"type":"string"}},{"name":"search","in":"query","required":true,"description":"Busca por texto - optional","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"hasMore":{"type":"boolean"}}}}},"example":{"items":[{"id":"pl_xxx","url":"https://app.validapay.com.br/pagamento/pl_xxx"}],"pagination":{"total":5,"hasMore":false}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Lista todas as páginas de pagamento (checkouts) criadas, com seus status e configurações. Suporta paginação e filtros por status e busca textual.","security":[{"oauth2":["checkouts/read"]}]}},"/v1/checkouts/{id}":{"get":{"operationId":"get-buscar-link-de-pagamento","summary":"Buscar link de pagamento","tags":["Links de pagamento"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID do checkout / payment link (ex: pl_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"priceId":{"type":"string"}}},"example":{"id":"pl_xxx","status":"ACTIVE","priceId":"price_xxx"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Checkout não encontrado","code":"CHECKOUT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Retorna os detalhes completos de uma página de pagamento, incluindo produtos e formas de pagamento aceitas.\n\nO identificador aceita diferentes prefixos: `cha_` (cobrança), `cs_` (sessão), `price_` (preço) e `pl_` (payment link). A autenticação é opcional — o checkout pode ser consultado publicamente.","security":[{"oauth2":["checkouts/read"]}]},"put":{"operationId":"put-atualizar-link-de-pagamento","summary":"Atualizar link de pagamento","tags":["Links de pagamento"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID do checkout / payment link (ex: pl_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"priceId":{"type":"string"}}},"example":{"id":"pl_xxx","priceId":"price_yyy"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Checkout não encontrado","code":"CHECKOUT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Atualiza as configurações de uma página de pagamento, como preço vinculado, parcelamento ou aparência. Todos os campos são opcionais — envie apenas o que deseja alterar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","description":"Novo preço vinculado ao checkout"},"discounts":{"type":"array","items":{}},"maxInstallments":{"type":"number","description":"Limite de parcelas (1 a 12)"},"primaryColor":{"type":"string","description":"Cor primária em hex"},"showProductImage":{"type":"boolean","description":"Exibir imagem do produto"},"termsOfServiceUrl":{"type":"string","description":"Termos de serviço exibidos no checkout para aceite do cliente"},"privacyPolicyUrl":{"type":"string","description":"Política de privacidade exibida no checkout para aceite do cliente"},"applyBrandingToAllPrices":{"type":"boolean","description":"Aplica a identidade visual a todos os preços"}}},"example":{"priceId":"price_yyy","discounts":[],"maxInstallments":6,"primaryColor":"#FF0000","showProductImage":false,"termsOfServiceUrl":"https://meusite.com/termos-de-servico","privacyPolicyUrl":"https://meusite.com/politica-de-privacidade","applyBrandingToAllPrices":true}}}},"security":[{"oauth2":["checkouts/write"]}]}},"/v1/checkout-sessions":{"post":{"operationId":"post-criar-sessao-de-pagamento","summary":"Criar sessão de pagamento","tags":["Links de pagamento"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"priceId":{"type":"string"}}},"example":{"id":"cs_abc123","url":"https://app.validapay.com.br/pagamento/cs_abc123","priceId":"price_abc123"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_DATA","message":"Campo inválido","details":[]}}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Você não tem permissão para usar este produto","code":"FORBIDDEN","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Preço não encontrado","code":"PRICE_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Cria um acesso temporário e seguro a uma página de pagamento, com cliente e configurações pré-preenchidos. É de uso único: expira após o pagamento.\n\nInforme o `priceId` de um preço já cadastrado. Opcionalmente, envie os dados do cliente, restrinja as formas de pagamento e personalize a aparência.\n\nA resposta inclui o `id` da sessão e a `url` de pagamento hospedada pela ValidaPay.\n\nFormas de pagamento aceitas em `allowedPaymentMethods`: pix, creditcard, boleto e pix_automatico. O **Pix Automático** está disponível apenas para **contas PJ** (conta ValidaPay cadastrada com CNPJ) e exige um preço recorrente (`recurrenceType` WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY): o cliente autoriza a recorrência uma única vez no aplicativo do banco e os ciclos seguintes são debitados automaticamente. Enquanto a autorização não é confirmada pelo banco do pagador, a assinatura fica com status `PENDING`. O valor mínimo por cobrança é de **R$ 4,99**.\n\nErros: `400 PIX_AUTOMATICO_PJ_ONLY` (conta PF) e `400 PIX_AUTOMATICO_MIN_AMOUNT` (valor abaixo do mínimo).\n\nAo informar `termsOfServiceUrl` e/ou `privacyPolicyUrl`, o checkout exibe um aceite obrigatório com os links: o cliente só consegue finalizar a compra depois de marcar que leu e concorda. O texto do aceite se adapta a um ou aos dois links. Sem esses campos, nenhum aceite é exibido.\n\nCase de uso:\n\n_Como SaaS, quero gerar um link de pagamento nominal para cada cliente no momento da contratação, com uso único para evitar cobranças duplicadas._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","description":"Preço da sessão (deve começar com price_)"},"allowedPaymentMethods":{"type":"array","items":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"]},"description":"Métodos exibidos: pix, creditcard, boleto, pix_automatico (só conta PJ; omitir usa o padrão do price)"},"customer":{"type":"object","properties":{"name":{"type":"string","description":"Nome exibido"},"email":{"type":"string","format":"email","description":"Usado para localizar cliente existente"},"documentNumber":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14 dígitos)"},"phone":{"type":"string","description":"Telefone"},"address":{"type":"object","properties":{"type":{"type":"string","enum":["BILLING","SHIPPING"],"description":"Tipo do endereço"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"country":{"type":"string"},"cityCode":{"type":"string","description":"Código IBGE (necessário para nota fiscal)"}},"description":"Endereço (obrigatório para boleto no pagamento)"}},"description":"Pré-preenche os dados do cliente no checkout"},"items":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","pattern":"^price_","description":"priceId do item"},"quantity":{"type":"integer","minimum":1,"description":"Quantidade (default 1)"}},"required":["priceId"]},"description":"Lista de { priceId, quantity } (sobrescreve o item principal)"},"billingDay":{"type":"number","minimum":1,"maximum":31,"description":"Dia do mês das cobranças recorrentes (1 a 31)"},"prorataStartDate":{"type":"string","format":"date","description":"Início do cálculo de pró-rata (YYYY-MM-DD)"},"installments":{"type":"integer","minimum":1,"maximum":12,"description":"Parcelas fixas da sessão (1 a 12)"},"dueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento do boleto (YYYY-MM-DD, maior que hoje)"},"boletoDueDays":{"type":"integer","minimum":1,"description":"Dias até o vencimento (mín. 1; ignorado se dueDate informado)"},"expirationAfterDueDate":{"type":"integer","minimum":0,"maximum":60,"description":"Dias após o vencimento que o boleto aceita pagamento (0 a 60)"},"discounts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENTAGE","FIXED","percentage","fixed"],"description":"PERCENTAGE ou FIXED"},"value":{"type":"number","description":"Valor do desconto"},"paymentMethod":{"type":"string","enum":["pix","creditcard","boleto","pix_automatico"],"description":"Restringe a um método"},"fromCycle":{"type":"number","description":"Ciclo inicial"},"toCycle":{"type":"number","description":"Ciclo final"},"durationMonths":{"type":"number","description":"Duração em meses"}},"required":["type","value"]},"description":"Descontos aplicados à sessão"},"passFeesToCustomer":{"type":"boolean","description":"Repassa as taxas ao cliente (default false)"},"freeInstallments":{"type":"integer","minimum":0,"maximum":12,"description":"Parcelas sem juros (1 a 12, default 1)"},"maxInstallments":{"type":"number","description":"Limite máximo de parcelas exibido (1 a 12)"},"boletoInstructions":{"type":"object","properties":{"fine":{"type":"number","description":"Multa em % (0.1 a 100; fine + interest <= 60)"},"interest":{"type":"number","description":"Juros mensais em % (0.1 a 100)"},"discount":{"type":"object","properties":{"amount":{"type":"number","multipleOf":0.01,"description":"Valor do desconto"},"modality":{"type":"string","description":"fixed (R$) ou percent (%)"},"limitDate":{"type":"string","format":"date","description":"Data limite (antes de dueDate)"}},"description":"Desconto antecipado"}},"description":"Regras de multa/juros/desconto do boleto"},"orderBumps":{"type":"array","items":{"type":"object","properties":{"priceId":{"type":"string","description":"priceId do produto adicional"},"callToAction":{"type":"string","description":"Texto do botão"},"title":{"type":"string","description":"Título exibido"},"description":{"type":"string","description":"Descrição exibida"},"showImage":{"type":"boolean","description":"Exibir imagem"}},"required":["priceId"]},"description":"Produtos adicionais exibidos no checkout"},"primaryColor":{"type":"string","description":"Cor primária em hex"},"secondaryColor":{"type":"string","description":"Cor secundária em hex"},"fontColor":{"type":"string","description":"Cor do texto em hex"},"companyName":{"type":"string","description":"Nome da empresa exibido no checkout"},"successUrl":{"type":"string","description":"Redireciona após pagamento aprovado"},"failureUrl":{"type":"string","description":"Redireciona após pagamento recusado"},"termsOfServiceUrl":{"type":"string","description":"Termos de serviço exibidos no checkout para aceite do cliente"},"privacyPolicyUrl":{"type":"string","description":"Política de privacidade exibida no checkout para aceite do cliente"},"metadata":{"type":"object","properties":{"referencia":{"type":"string"}}}},"required":["priceId"]},"example":{"priceId":"price_abc123","allowedPaymentMethods":["pix","creditcard","boleto","pix_automatico"],"customer":{"name":"João Silva","email":"joao@email.com","documentNumber":"12345678901","phone":"51999999999","address":{"type":"BILLING","street":"Rua das Flores","number":"123","complement":"Apto 4","neighborhood":"Centro","city":"Porto Alegre","state":"RS","zipCode":"90010000","country":"BR","cityCode":"4314902"}},"items":[{"priceId":"price_abc123","quantity":1}],"billingDay":15,"prorataStartDate":"2026-06-11","installments":1,"dueDate":"2026-07-30","boletoDueDays":7,"expirationAfterDueDate":30,"discounts":[{"type":"PERCENTAGE","value":10,"paymentMethod":"pix","fromCycle":1,"toCycle":3,"durationMonths":3}],"passFeesToCustomer":false,"freeInstallments":1,"maxInstallments":12,"boletoInstructions":{"fine":2,"interest":1,"discount":{"amount":10,"modality":"fixed","limitDate":"2026-07-28"}},"orderBumps":[{"priceId":"price_bump123","callToAction":"Adicionar ao pedido","title":"Produto adicional","description":"Descrição do order bump","showImage":true}],"primaryColor":"#6366f1","secondaryColor":"#818cf8","fontColor":"#ffffff","companyName":"Minha Empresa","successUrl":"https://meusite.com/sucesso","failureUrl":"https://meusite.com/falha","termsOfServiceUrl":"https://meusite.com/termos-de-servico","privacyPolicyUrl":"https://meusite.com/politica-de-privacidade","metadata":{"referencia":"pedido-001"}}}}},"security":[{"oauth2":["checkouts/write"]}]}},"/v1/checkout-sessions/{id}":{"get":{"operationId":"get-buscar-sessao-de-pagamento","summary":"Buscar sessão de pagamento","tags":["Links de pagamento"],"parameters":[{"name":"id","in":"path","required":true,"description":"ID da sessão de checkout (ex: cs_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"priceId":{"type":"string"}}},"example":{"id":"cs_xxx","status":"PENDING","priceId":"price_xxx"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Sessão não encontrada","code":"SESSION_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Retorna os dados de uma sessão de checkout ativa, como produtos disponíveis e formas de pagamento.","security":[{"oauth2":["checkouts/read"]}]}},"/v1/wallet/pay/{chargeId}":{"post":{"operationId":"post-pagar-em-sandbox","summary":"Pagar em sandbox","tags":["Simular pagamentos"],"parameters":[{"name":"chargeId","in":"path","required":true,"description":"Identificador retornado no ato da geraçao da cobrança","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso"},"400":{"description":"`MISSING_CHARGE_ID` — chargeId não informado  \n`NOT_SANDBOX_ACCOUNT` — Rota disponível apenas para contas sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`CHARGE_NOT_FOUND` — Cobrança não encontrada  \n`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Confirma o pagamento de uma cobrança do **sandbox** sem dinheiro de verdade. A ValidaPay envia ao seu webhook o mesmo evento de PIX recebido que um pagamento real dispararia, então o seu fluxo de baixa é exercitado ponta a ponta.\n\n**Case de uso:**\n\n_Como desenvolvedor integrando a API, quero marcar uma cobrança do sandbox como paga, para testar meu webhook de confirmação sem transferir dinheiro._\n\nInforme no path o `chargeId` devolvido na criação da cobrança. A resposta é imediata e traz `status: PROCESSING` — a confirmação chega pelo webhook; consulte a cobrança depois para vê-la como `PAID`.\n\nDisponível **apenas em contas de sandbox**: em produção a chamada é recusada com `400 NOT_SANDBOX_ACCOUNT`. Cobrança já paga responde `200` com a mensagem \"Cobranca ja foi paga\" e cobrança inexistente, `404 CHARGE_NOT_FOUND`.\n\n**Cartão de crédito não passa por esta rota.** No sandbox o resultado da cobrança no cartão é decidido pelo número enviado:\n\n**Cartões de teste (sandbox):** em conta de sandbox nenhuma cobrança chega ao adquirente — o número do cartão é que define o resultado:\n\n- `4111111111111111` — pagamento aprovado\n- `4000000000000002` — recusado pela operadora (`card_declined`)\n- `4000000000000004` — saldo insuficiente (`insufficient_funds`)\n- `4000000000000006` — cartão expirado (`expired_card`)\n- `4000000000000008` — CVV inválido (`invalid_cvv`)\n- `4000000000000010` — suspeita de fraude (`fraud_suspected`)\n\nQualquer outro número de 16 dígitos é aprovado. CVV, validade e nome do titular podem ser quaisquer valores válidos. Em produção o número não muda nada: quem decide é o emissor do cartão.","security":[{"oauth2":["wallet/write"]}]}},"/v1/wallet/withdraw":{"post":{"operationId":"post-saque-subconta","summary":"Saque subconta · Saque master account","tags":["Saques"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"withdrawalId":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number"},"accountNumber":{"type":"string"}}},"example":{"withdrawalId":"wdr_1772883158760_tdhomd8xe","status":"PROCESSING","amount":1,"accountNumber":"258965356"}}}},"400":{"description":"Bloqueio por titularidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"A chave PIX nao pertence ao titular da conta","code":"OWNERSHIP_MISMATCH","details":null,"timestamp":"2026-03-17T04:01:57.811Z"}}}}},"401":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Subconta nao pertence a esta conta","code":"OWNERSHIP_MISMATCH","details":null,"timestamp":"2026-03-17T04:01:14.653Z"}}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Com esta funcionalidade você pode criar um saque em uma subconta associada à sua _master account._\n\n> ⚠️ **Atenção:** Só é possível fazer saques para contas de mesma titularidade\n\nCom esta funcionalidade você pode criar um saque da sua _conta ValidaPay._\n\n> ⚠️ **Atenção:** Só é possível fazer saques para contas de mesma titularidade","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","multipleOf":0.01,"description":"Valor do saque"},"pixKey":{"type":"string","description":"Chave Pix de destino"},"pixKeyType":{"type":"string","enum":["CPF","CNPJ","EMAIL","PHONE","EVP"],"description":"tipo de chave Pix"},"accountId":{"type":"string","description":"Número da subconta de destino"}},"required":["amount","pixKey","pixKeyType"]},"examples":{"saque-subconta":{"summary":"Saque subconta","value":{"amount":1,"pixKey":"12345678925","pixKeyType":"CPF","accountId":"258965356"}},"saque-master-account":{"summary":"Saque master account","value":{"amount":1,"pixKey":"12345678925","pixKeyType":"CPF"}}}}}},"security":[{"oauth2":["wallet/write"]}]}},"/v1/wallet/transactions":{"get":{"operationId":"get-extrato-subconta","summary":"Extrato subconta · Extrato conta master","tags":["Extratos"],"parameters":[{"name":"accountId","in":"query","required":true,"description":"- ID da subconta a consultar","schema":{"type":"string","example":"460851686"}},{"name":"type","in":"query","required":false,"description":"- CREDIT ou DEBIT","schema":{"type":"string","example":"CREDIT"}},{"name":"category","in":"query","required":false,"description":"- PAYMENT, PIX_IN, WITHDRAWAL, etc.","schema":{"type":"string","example":"PAYMENT"}},{"name":"dateFrom","in":"query","required":false,"description":"- Data início (ISO 8601)","schema":{"type":"string","example":"2026-03-01T00:00:00Z"}},{"name":"dateTo","in":"query","required":false,"description":"- Data fim (ISO 8601)","schema":{"type":"string","example":"2026-03-16T23:00:00Z"}},{"name":"limit","in":"query","required":false,"description":"- 1-100, default 50","schema":{"type":"string","example":"5"}},{"name":"nextPageToken","in":"query","required":false,"description":"- Token de paginação","schema":{"type":"string","example":"eyJTSyI6IjIwMjYtMDMtMTRUMjM6MjM6MzYuMDk2WiN0eG5fMTc3MzUzMDYxNjA5Nl8zOXdmbTk5aTQiLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string"},"transactions":{"type":"array","items":{"type":"object","properties":{"transactionId":{"type":"string"},"type":{"type":"string"},"category":{"type":"string"},"amount":{"type":"number"},"balanceAfter":{"type":"number"},"title":{"type":"string"},"paymentMethod":{"type":"string"},"chargeId":{},"subscriptionId":{},"endToEndId":{"type":"string"},"counterparty":{},"referenceId":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"nextPageToken":{"type":"string"},"hasMore":{"type":"boolean"}}},"example":{"accountId":"429134563","transactions":[{"transactionId":"txn_1773694940975_r10b6fyzm","type":"CREDIT","category":"PIX_IN","amount":2.56,"balanceAfter":901.6,"title":"PIX recebido de Empresa Exemplo LTDA","paymentMethod":"PIX","chargeId":null,"subscriptionId":null,"endToEndId":"E13935893202603162102IfDcitXf0zO","counterparty":{"name":"Empresa Exemplo LTDA","bank":"13935893","taxId":"37134852000458","account":"410900056"},"referenceId":"E139389320260316202IfDyytXf0zO","description":"PIX recebido direto","createdAt":"2026-03-16T21:02:20.975Z"},{"transactionId":"txn_1773718528326_449bqmhm7","type":"DEBIT","category":"WITHDRAWAL","amount":1,"balanceAfter":929.85,"title":"Saque PIX","paymentMethod":"PIX","chargeId":null,"subscriptionId":null,"endToEndId":"E13935893202563270335KF9O0GDVVIz","counterparty":null,"referenceId":"f7d1e875-7096-4fa8-992d-0c81a09f91c0","description":"Saque / transferência PIX","createdAt":"2026-03-17T03:35:28.326Z"}],"nextPageToken":"eyJTSyI6IjIwMjYtMDMtMTVUMjM6NTk6MzMuMDcxWiN0eG5fMTc3MzYxOTE3MzA3MV8zb3JpcjNjYnciLCJhY2NvdW50SWQiOiI0MjkxMzEyMTIifQ","hasMore":true}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Com esta funcionalidade você pode isualizar movimentações em uma subconta associada a sua _master account_\n\nCom esta funcionalidade você pode isualizar movimentações na sua conta","security":[{"oauth2":["wallet/read"]}]}},"/v1/wallet/refunds":{"post":{"operationId":"post-criar-devolucao-pix","summary":"Criar devolução PIX · Criar estorno de cartão","tags":["Devolução Pix"],"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"refundId":{"type":"string"},"status":{"type":"string"},"success":{"type":"boolean"},"amount":{"type":"number"},"reason":{"type":"string"},"chargeId":{"type":"string"},"providerChargeId":{"type":"string"},"paymentType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"example":{"refundId":"ref_1774531490865_bq4e8v12x","status":"CONFIRMED","success":true,"amount":100,"reason":"CUSTOMER_REQUEST","chargeId":"cha_1774530966959_frgj3ptax","providerChargeId":"prov_ch_9f8a7b6c","paymentType":"CREDIT_CARD","createdAt":"2026-03-26T13:24:52.106Z"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Subconta nao pertence a esta conta","code":"OWNERSHIP_MISMATCH","details":null,"timestamp":"2026-03-25T11:28:25.397Z"}}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Cria uma **devolução PIX** a partir do `endToEndId` da transação original. A devolução pode ser parcial ou total.\n\n> ⚠️ **Atenção:** o campo `reason` (motivo da devolução) é **obrigatório**.\n\nValores aceitos para `reason`:\n\n- `CUSTOMER_REQUEST` — solicitação do cliente\n- `FRAUD` — suspeita de fraude\n- `BANK_ERROR` — erro bancário\n- `PIX_CHANGE_ERROR` — erro na transação\n\nA devolução nasce em geral como `PROCESSING`. Guarde o `refundId` retornado e acompanhe a confirmação pela rota **Consultar status da devolução PIX** (`GET /v1/wallet/refunds`).\n\nCria um **estorno de cartão de crédito** a partir do `chargeId` da cobrança original. O estorno pode ser parcial ou total.\n\n> ℹ️ Para cartão, o estorno pode retornar `CONFIRMED` na hora, quando a confirmação vem imediatamente — nesse caso o polling não é necessário (`success` já vem `true`).\n\nSe vier `PROCESSING`, guarde o `refundId` e acompanhe pela rota **Consultar status do estorno** (`GET /v1/wallet/refunds`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endToEndId":{"type":"string","description":"EndToEndId da transação PIX original."},"amount":{"type":"number","multipleOf":0.01},"reason":{"type":"string"},"accountId":{"type":"string","description":"Número da subconta. Se omitido, opera na conta principal."},"chargeId":{"type":"string"}},"required":["amount"]},"examples":{"criar-devolucao-pix":{"summary":"Criar devolução PIX","value":{"accountId":"459013777","endToEndId":"E003603052026032511186a4f4cdf139","amount":1,"reason":"CUSTOMER_REQUEST","chargeId":"cha_1774437468463_4hj927ips"}},"criar-estorno-de-cartao":{"summary":"Criar estorno de cartão","value":{"accountId":"459013777","chargeId":"cha_1774530966959_frgj3ptax","amount":100,"reason":"CUSTOMER_REQUEST"}}}}}},"security":[{"oauth2":["wallet/write"]}]},"get":{"operationId":"get-consultar-status-da-devolucao-pix","summary":"Consultar status da devolução PIX · Consultar status do estorno","tags":["Devolução Pix"],"parameters":[{"name":"refundId","in":"query","required":false,"description":"- Detalhe/polling de um estorno específico","schema":{"type":"string","example":"ref_1774531490865_bq4e8v12x"}}],"responses":{"200":{"description":"Item único (por refundId)","content":{"application/json":{"schema":{"type":"object","properties":{"refundId":{"type":"string"},"accountId":{"type":"string"},"status":{"type":"string"},"success":{"type":"boolean"},"amount":{"type":"number"},"reason":{"type":"string"},"chargeId":{"type":"string"},"originalEndToEndId":{},"returnIdentification":{},"providerChargeId":{"type":"string"},"paymentType":{"type":"string"},"splitReversals":{"type":"array","items":{}},"error":{},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"example":{"refundId":"ref_1774531490865_bq4e8v12x","accountId":"429131212","status":"CONFIRMED","success":true,"amount":100,"reason":"CUSTOMER_REQUEST","chargeId":"cha_1774530966959_frgj3ptax","originalEndToEndId":null,"returnIdentification":null,"providerChargeId":"prov_ch_9f8a7b6c","paymentType":"CREDIT_CARD","splitReversals":[],"error":null,"createdAt":"2026-03-26T13:24:52.106Z","updatedAt":"2026-03-26T13:24:57.553Z"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"REFUND_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Refund não encontrado","code":"REFUND_NOT_FOUND","details":null,"timestamp":"2026-08-05T12:00:00.000Z"}}}}}},"description":"Consulta se uma **devolução PIX** foi confirmada.\n\nNão use o status da cobrança (`REFUNDED` / `PARTIALLY_REFUNDED`) para saber se o estorno foi confirmado — use o refund:\n\n- `status === \"CONFIRMED\"` (ou `success === true`): estorno confirmado\n- `status === \"PROCESSING\"`: ainda aguardando\n- `status === \"ERROR\"`: falhou (`error` pode vir preenchido)\n\nModos de uso:\n\n- Informe `refundId` (ou `returnIdentification`) para o detalhe/polling de uma devolução específica.\n- Informe `endToEndId` do PIX original para consultar as devoluções daquele pagamento.\n- MasterAccounts podem consultar uma subconta informando `accountId`.\n\nPrecedência: `refundId` > `returnIdentification` > `endToEndId` > `chargeId`.\n\n> ℹ️ Polling sugerido: 2–5s com timeout (60–120s).\n\nConsulta se um **estorno de cartão** foi confirmado.\n\nUse o refund (não o status da cobrança) para confirmar:\n\n- `status === \"CONFIRMED\"` (ou `success === true`): estorno confirmado\n- `status === \"PROCESSING\"`: ainda aguardando\n- `status === \"ERROR\"`: falhou (`error` pode vir preenchido)\n\nModos de uso:\n\n- Informe `refundId` para o detalhe/polling de um estorno específico.\n- Informe `chargeId` para consultar os estornos daquela cobrança de cartão.\n- MasterAccounts podem consultar uma subconta informando `accountId`.\n\n> ℹ️ No estorno de cartão a resposta traz `paymentType: \"CREDIT_CARD\"` e o `providerChargeId` da transação.","security":[{"oauth2":["wallet/read"]}]}},"/v1/customers":{"post":{"operationId":"post-criar-cliente","summary":"Criar Cliente","tags":["Clientes"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"type":"object","properties":{"customerId":{"type":"string"},"document":{"type":"string"},"name":{"type":"string"}}}}},"example":{"customer":{"customerId":"cus_xxx","document":"11144477735","name":"Alexandre Souza"}}}}},"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"type":"object","properties":{"customerId":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"document":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"accountId":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}},"example":{"customer":{"customerId":"cus_xxx","id":"cus_xxx","name":"Alexandre Souza","document":"11144477735","email":"alexandre@exemplo.com.br","phone":"5511987654321","accountId":"460851686","status":"ACTIVE","createdAt":"2026-08-28T12:00:00.000Z"}}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Já existe um cliente cadastrado com este documento","code":"CUSTOMER_ALREADY_EXISTS","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Cadastra um cliente na sua conta a partir do CPF/CNPJ, com endereço opcional.\n\nO documento é a chave do cliente dentro da conta e não pode ser alterado depois. Por padrão, se já existir um cliente com o mesmo documento, a API devolve 200 com o cadastro existente em vez de duplicar. Envie upsert: true para que a tentativa de recadastrar retorne erro 400 (CUSTOMER_ALREADY_EXISTS).\n\nQuando o endereço é informado, o código IBGE do município (cityCode) é resolvido automaticamente a partir do CEP — necessário para emissão de NFS-e.\n\nCase de uso:\n\n_Como plataforma, quero cadastrar meus clientes junto com o endereço de cobrança, para depois gerar assinaturas e cobranças sem redigitar os dados a cada venda._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Nome completo ou razão social"},"document":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14), apenas dígitos"},"phone":{"type":"string","description":"E.164 com DDI 55"},"email":{"type":"string","format":"email"},"upsert":{"type":"boolean","description":"true retorna erro 400 se o documento já existir (default false)"},"address":{"type":"object","properties":{"zipCode":{"type":"string","description":"8 dígitos, apenas números"},"street":{"type":"string"},"number":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"UF com 2 letras"},"complement":{"type":"string"}},"required":["zipCode","street","number","neighborhood","city","state"]}},"required":["name","document","phone"]},"example":{"name":"Alexandre Souza","document":"11144477735","phone":"5511987654321","email":"alexandre@exemplo.com.br","upsert":false,"address":{"zipCode":"01310100","street":"Avenida Paulista","number":"1000","complement":"Sala 5","neighborhood":"Bela Vista","city":"São Paulo","state":"SP"}}}}},"security":[{"oauth2":["customers/write"]}]},"get":{"operationId":"get-listar-clientes","summary":"Listar Clientes · Buscar Cliente por Documento","tags":["Clientes"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página (default 15) - optional","schema":{"type":"string","example":"15"}},{"name":"lastKey","in":"query","required":true,"description":"Cursor da próxima página, em base64, retornado em pagination.lastKey - optional","schema":{"type":"string"}},{"name":"search","in":"query","required":true,"description":"Busca parcial por nome, e-mail ou documento - optional","schema":{"type":"string"}},{"name":"document","in":"query","required":true,"description":"Filtro por CPF/CNPJ exato, apenas dígitos - optional","schema":{"type":"string"}},{"name":"status","in":"query","required":true,"description":"ACTIVE | INACTIVE | BLOCKED - optional","schema":{"type":"string"}},{"name":"startDate","in":"query","required":true,"description":"Data inicial de criação (ISO 8601) - optional","schema":{"type":"string"}},{"name":"endDate","in":"query","required":true,"description":"Data final de criação (ISO 8601) - optional","schema":{"type":"string"}},{"name":"lookupDocument","in":"query","required":false,"description":"CPF (11) ou CNPJ (14), apenas dígitos - required","schema":{"type":"string","example":"11144477735"}}],"responses":{"200":{"description":"(não encontrado)","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{},"address":{}}},"example":{"customer":null,"address":null}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Lista os clientes cadastrados na sua conta, com busca por texto e paginação por cursor.\n\nO parâmetro search faz busca parcial simultânea em nome, e-mail e documento — é o filtro indicado para uma tela de seleção de cliente, onde o usuário pode digitar qualquer um dos três. Já document faz correspondência exata e deve ser usado quando o CPF/CNPJ completo já é conhecido.\n\nA paginação é por cursor: quando houver mais páginas, pagination.lastKey vem preenchido; repita a chamada enviando esse valor em lastKey, mantendo os mesmos filtros. Quando lastKey vier null, não há mais páginas.\n\nCase de uso:\n\n_Como integrador, quero buscar um cliente já cadastrado por nome, e-mail ou CPF/CNPJ, para preencher automaticamente os dados na hora de criar uma nova cobrança._\n\nBusca direta de um único cliente pelo CPF/CNPJ exato, retornando junto o endereço padrão dele.\n\nDiferente de Listar Clientes, esta chamada não devolve lista nem paginação: retorna o objeto do cliente e o endereço em uma única resposta, pronto para preencher um formulário. Quando o documento não está cadastrado, a resposta é 200 com customer e address em null — não é erro.\n\nCase de uso:\n\n_Como checkout próprio, quero consultar o CPF digitado pelo comprador e, se ele já for cliente, preencher nome, e-mail, telefone e endereço automaticamente._","security":[{"oauth2":["customers/read"]}]}},"/v1/customers/{customerId}":{"get":{"operationId":"get-detalhar-cliente","summary":"Detalhar Cliente","tags":["Clientes"],"parameters":[{"name":"customerId","in":"path","required":true,"description":"Customerid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"document":{"type":"string"},"status":{"type":"string"}}},"addresses":{"type":"array","items":{"type":"object","properties":{"zipCode":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"isDefault":{"type":"boolean"}}}},"subscriptions":{"type":"array","items":{}}}},"example":{"customer":{"customerId":"cus_xxx","name":"Alexandre Souza","document":"11144477735","status":"ACTIVE"},"addresses":[{"zipCode":"01310100","street":"Avenida Paulista","number":"1000","city":"São Paulo","state":"SP","isDefault":true}],"subscriptions":[]}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Cliente não encontrado","code":"CUSTOMER_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Retorna os dados completos de um cliente, incluindo todos os endereços cadastrados e o histórico de assinaturas.\n\nCada assinatura vem acompanhada dos itens, dos ciclos de cobrança e das faturas e cobranças de cada ciclo. É a visão consolidada usada na tela de detalhe do cliente.\n\nCase de uso:\n\n_Como atendente, quero ver tudo que um cliente possui — assinaturas, ciclos e faturas — em uma única consulta, para responder a um contato de suporte._","security":[{"oauth2":["customers/read"]}]},"patch":{"operationId":"patch-atualizar-cliente","summary":"Atualizar Cliente","tags":["Clientes"],"parameters":[{"name":"customerId","in":"path","required":true,"description":"Customerid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}}}},"example":{"customer":{"customerId":"cus_xxx","name":"Alexandre Souza Silva","email":"novo@exemplo.com.br","phone":"5511987654321"}}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"O documento do cliente não pode ser alterado","code":"DOCUMENT_UPDATE_NOT_ALLOWED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Atualiza os dados de um cliente. Envie apenas os campos que deseja alterar.\n\nO documento não pode ser alterado: enviar um CPF/CNPJ diferente do atual retorna erro 400 (DOCUMENT_UPDATE_NOT_ALLOWED). Quando o endereço é enviado, ele substitui o endereço padrão do cliente.\n\nCase de uso:\n\n_Como plataforma, quero atualizar o e-mail e o telefone de um cliente que mudou de contato, sem recriar o cadastro._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"additionalEmails":{"type":"array","items":{"type":"string","format":"email"}},"phone":{"type":"string","description":"E.164 com DDI 55"},"address":{"type":"object","properties":{"zipCode":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"complement":{"type":"string"}},"required":["zipCode","street","number","neighborhood","city","state"],"description":"substitui o endereço padrão"}}},"example":{"name":"Alexandre Souza Silva","email":"novo@exemplo.com.br","additionalEmails":["financeiro@exemplo.com.br"],"phone":"5511987654321","address":{"zipCode":"01310100","street":"Avenida Paulista","number":"2000","complement":"Andar 3","neighborhood":"Bela Vista","city":"São Paulo","state":"SP"}}}}},"security":[{"oauth2":["customers/write"]}]},"delete":{"operationId":"delete-remover-cliente","summary":"Remover Cliente","tags":["Clientes"],"parameters":[{"name":"customerId","in":"path","required":true,"description":"Customerid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Cliente possui assinaturas vinculadas e não pode ser excluído","code":"CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Remove um cliente da sua conta.\n\nA exclusão é bloqueada quando o cliente possui assinaturas recorrentes vinculadas, retornando erro 400 (CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS). Cancele as assinaturas antes de excluir.\n\nCase de uso:\n\n_Como plataforma, quero remover um cadastro criado por engano, garantindo que clientes com assinaturas ativas não sejam apagados por acidente._","security":[{"oauth2":["customers/delete"]}]}},"/v1/subscriptions":{"get":{"operationId":"get-listar-assinaturas","summary":"Listar Assinaturas","tags":["Assinaturas"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página (default 15) - optional","schema":{"type":"string","example":"15"}},{"name":"lastKey","in":"query","required":true,"description":"Cursor de paginação em base64 retornado na resposta anterior - optional","schema":{"type":"string"}},{"name":"startDate","in":"query","required":true,"description":"Filtro por createdAt. ISO 8601 recomendado (ex: 2026-03-10T00:00:00.000Z). YYYY-MM-DD aceito - optional","schema":{"type":"string"}},{"name":"endDate","in":"query","required":true,"description":"Filtro por createdAt. ISO 8601 com fim do dia (ex: 2026-03-10T23:59:59.999Z). YYYY-MM-DD pode excluir registros do mesmo dia com horário - optional","schema":{"type":"string"}},{"name":"status","in":"query","required":true,"description":"Filtro por status (lista separada por vírgula): PENDING, AWAITING_PAYMENT, ACTIVE, TRIALING, PAST_DUE, PAUSED, CANCELED, INCOMPLETE - optional","schema":{"type":"string"}},{"name":"search","in":"query","required":true,"description":"Busca por nome ou documento do cliente - optional","schema":{"type":"string"}},{"name":"document","in":"query","required":true,"description":"Filtro por CPF ou CNPJ do cliente - optional","schema":{"type":"string"}},{"name":"paymentMethod","in":"query","required":true,"description":"Filtro por método: CREDIT_CARD, PIX, BOLETO ou PIX_AUTOMATICO. Alias aceito: paymentType - optional","schema":{"type":"string"}},{"name":"priceId","in":"query","required":true,"description":"Filtro por ID do preço - optional","schema":{"type":"string"}},{"name":"productId","in":"query","required":true,"description":"Filtro por ID do produto - optional","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"subscriptionId":{"type":"string"},"status":{"type":"string"},"interval":{"type":"string"},"billingDay":{"type":"number"},"currentCycleNumber":{"type":"number"},"currentCycleAmount":{"type":"number"},"nextCycleChargeDate":{"type":"string","format":"date"},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}}},"lastCharge":{"type":"object","properties":{"netAmount":{"type":"number"},"status":{"type":"string"}}}}}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"hasMore":{"type":"boolean"},"lastKey":{"type":"string"}}}}},"example":{"items":[{"subscriptionId":"sub_xxx","status":"ACTIVE","interval":"MONTHLY","billingDay":15,"currentCycleNumber":3,"currentCycleAmount":99.9,"nextCycleChargeDate":"2024-02-15","customer":{"customerId":"cus_xxx","name":"João Silva","email":"joao@email.com"},"lastCharge":{"netAmount":98.91,"status":"PAID"}}],"pagination":{"total":50,"hasMore":true,"lastKey":"eyJ..."}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Lista todas as assinaturas da conta com suporte a filtros por status, cliente, método de pagamento, produto e período.\n\nUtilize o campo `lastKey` retornado na resposta para navegar entre as páginas.\n\nStatus possíveis: `PENDING`, `AWAITING_PAYMENT`, `ACTIVE`, `TRIALING`, `PAST_DUE`, `PAUSED`, `CANCELED`, `INCOMPLETE`.\n\n> Assinaturas com `interval: ONE_TIME` são excluídas automaticamente do resultado.\n\nCase de uso:\n\n_Como SaaS, quero listar todas as assinaturas ativas dos meus clientes para exibir no meu painel administrativo._","security":[{"oauth2":["subscriptions/read"]}]}},"/v1/subscriptions/{subscriptionId}":{"get":{"operationId":"get-buscar-assinatura","summary":"Buscar Assinatura","tags":["Assinaturas"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (ex: sub_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string"},"status":{"type":"string"},"customer":{"type":"object","properties":{}},"items":{"type":"array","items":{}},"upgrades":{"type":"array","items":{}},"billingCycles":{"type":"array","items":{}},"coupon":{}}},"example":{"subscriptionId":"sub_xxx","status":"ACTIVE","customer":{},"items":[],"upgrades":[],"billingCycles":[],"coupon":null}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Assinatura não encontrada","code":"SUBSCRIPTION_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Retorna os detalhes completos de uma assinatura específica.\n\nA resposta inclui: `customer` (dados do cliente), `items` (itens da assinatura), `upgrades` (mudanças de plano pendentes), `billingCycles` (histórico de ciclos) e `coupon` (cupom aplicado, se houver).\n\nCase de uso:\n\n_Como SaaS, quero consultar o status e os itens de uma assinatura específica para exibir na área do cliente._","security":[{"oauth2":["subscriptions/read"]}]},"patch":{"operationId":"patch-atualizar-assinatura-item","summary":"Atualizar Assinatura (Item) · Cancelar Item","tags":["Assinaturas"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (ex: sub_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"type":{"type":"string"},"itemId":{"type":"string"}}},"example":{"success":true,"type":"ITEM_CANCELED","itemId":"item_xxx"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"old.itemId é obrigatório","code":"MISSING_ITEM_ID","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Item não encontrado","code":"ITEM_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Realiza **upgrade ou downgrade** de um item da assinatura. Envie `old.itemId` do item atual e `new.priceId` (e opcionalmente `new.quantity`) do novo plano.\n\n> Rota **canônica** para upgrade/downgrade: **Atualizar Item** (PUT). Este PATCH delega para a mesma lógica.\n\n- **Upgrade:** gera cobrança de pro rata imediatamente (cartão) ou de forma assíncrona via webhook (PIX/boleto). O item antigo só é substituído após confirmação do pagamento.\n- **Downgrade:** a mudança é agendada para o próximo ciclo de cobrança, sem cobrança imediata.\n\nPré-condições: assinatura `ACTIVE`, `PAST_DUE` ou `AWAITING_PAYMENT`; item com status `ACTIVE`.\n\nCase de uso:\n\n_Como SaaS, quero permitir que meu cliente faça upgrade do plano Básico para o Pro no meio do ciclo, cobrando apenas a diferença proporcional._\n\nRemove um **item** da assinatura sem cancelar a assinatura inteira.\n\nEnvie apenas `old.itemId` — **não informe** o campo `new`. A ausência de `new` indica cancelamento de item.\n\nCase de uso:\n\n_Como SaaS, quero remover um add-on da assinatura do cliente mantendo o plano principal ativo._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"old":{"type":"object","properties":{"itemId":{"type":"string"}},"required":["itemId"]},"new":{"type":"object","properties":{"priceId":{"type":"string","description":"ID do novo preço"},"quantity":{"type":"number","description":"Nova quantidade (default 1)"}},"required":["priceId"]}},"required":["old"]},"examples":{"atualizar-assinatura-item":{"summary":"Atualizar Assinatura (Item)","value":{"old":{"itemId":"item_xxx"},"new":{"priceId":"price_yyy","quantity":2}}},"cancelar-item":{"summary":"Cancelar Item","value":{"old":{"itemId":"item_xxx"}}}}}}},"security":[{"oauth2":["subscriptions/write"]}]},"delete":{"operationId":"delete-cancelar-assinatura","summary":"Cancelar Assinatura","tags":["Assinaturas"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (ex: sub_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"status":{"type":"string"},"canceledCycles":{"type":"number"}}},"example":{"success":true,"message":"Assinatura cancelada com sucesso","status":"CANCELED","canceledCycles":2}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Assinatura já está cancelada","code":"SUBSCRIPTION_ALREADY_CANCELED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Assinatura não encontrada","code":"SUBSCRIPTION_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Cancela uma assinatura ativa, interrompendo todas as cobranças futuras. **Rota recomendada** para cancelamento (preferir em relação ao PATCH com `action: \"cancel\"`).\n\nA assinatura é marcada como `CANCELED` imediatamente. Ciclos futuros pendentes (`PENDING`, `AWAITING_PAYMENT`) são cancelados.\n\nO campo `reason` é opcional e pode ser usado para registrar o motivo do cancelamento.\n\nCase de uso:\n\n_Como SaaS, quero cancelar a assinatura de um cliente que solicitou encerramento do serviço._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Motivo do cancelamento"}}},"example":{"reason":"Cliente solicitou"}}}},"security":[{"oauth2":["subscriptions/write"]}]}},"/v1/subscriptions/{subscriptionId}/items":{"post":{"operationId":"post-adicionar-item","summary":"Adicionar Item","tags":["Assinaturas"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (ex: sub_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"PIX","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"type":{"type":"string"},"paymentMethod":{"type":"string"},"chargeId":{"type":"string"},"payment":{"type":"object","properties":{"emvQrCode":{"type":"string"}}}}},"example":{"success":true,"type":"ADD_ITEM","paymentMethod":"PIX","chargeId":"cha_xxx","payment":{"emvQrCode":"..."}}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Assinatura não está ativa","code":"SUBSCRIPTION_NOT_ACTIVE","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Adiciona um novo produto ou serviço a uma assinatura já existente.\n\nInforme o `priceId` de um preço previamente cadastrado. Para assinaturas com cartão de crédito, a cobrança é processada imediatamente. Para PIX ou boleto, a resposta inclui `payment.transactionId` — a confirmação chega via **webhook**.\n\nPré-condições: assinatura `ACTIVE` ou `PAST_DUE`. Antes do 1º pagamento confirmado (`currentCycleNumber === 1`), add item retorna `400`.\n\n> `billOnNextCycle` adia a cobrança para o próximo ciclo (apenas boleto/PIX; incompatível com cartão ou `ONE_TIME`).\n\nCase de uso:\n\n_Como SaaS, quero adicionar um módulo extra (add-on) à assinatura de um cliente que já possui um plano base._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","description":"ID do preço do item"},"quantity":{"type":"number","description":"Quantidade (default 1, mínimo 1)"},"type":{"type":"string","description":"RECURRING ou ONE_TIME (default RECURRING)"},"billOnNextCycle":{"type":"boolean","description":"Adia cobrança para próximo ciclo (boleto/PIX apenas)"},"dueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD)"},"boletoInstructions":{"type":"object","properties":{"fine":{"type":"number"},"interest":{"type":"number"}},"description":"Para assinaturas com boleto"},"expirationAfterDueDate":{"type":"integer","minimum":0,"maximum":60,"description":"Dias após vencimento (0 a 60, default 30)"}},"required":["priceId"]},"example":{"priceId":"price_xxx","quantity":1,"type":"RECURRING","billOnNextCycle":false,"dueDate":"2026-04-06","boletoInstructions":{"fine":2,"interest":1},"expirationAfterDueDate":30}}}},"security":[{"oauth2":["subscriptions/write"]}]}},"/v1/subscriptions/{subscriptionId}/items/{itemId}":{"put":{"operationId":"put-atualizar-item","summary":"Atualizar Item","tags":["Assinaturas"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (ex: sub_xxx) - required","schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"description":"ID do item da assinatura (ex: item_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"downgrade","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"type":{"type":"string"},"effectiveAt":{"type":"string","format":"date"},"newAmount":{"type":"number"}}},"example":{"success":true,"type":"DOWNGRADE","effectiveAt":"2024-02-01","newAmount":59.9}}}},"400":{"description":"pagamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Cartão recusado por saldo insuficiente","code":"PAYMENT_DECLINED","details":{"declinedCode":"insufficient_funds"},"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Item não encontrado","code":"ITEM_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"**Rota canônica** para upgrade ou downgrade de plano. Altera o `priceId` ou `quantity` de um item específico.\n\nO `subscriptionId` e `itemId` vão na URL. Informe pelo menos `priceId` ou `quantity`.\n\n- **Upgrade** (`newTotal > currentTotal`): cobra pro-rata imediatamente (cartão) ou gera boleto/PIX assíncrono.\n- **Downgrade** (`newTotal <= currentTotal`): efetivado no próximo ciclo, sem cobrança imediata.\n\nPré-condições: assinatura `ACTIVE`, `PAST_DUE` ou `AWAITING_PAYMENT`; item `ACTIVE`.\n\n> Falha de pagamento retorna **400** com `PAYMENT_DECLINED` ou `PAYMENT_FAILED` (não 402).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","description":"Pelo menos priceId ou quantity é obrigatório"},"quantity":{"type":"number"},"dueDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Vencimento do boleto/PIX de pro-rata (YYYY-MM-DD)"},"boletoInstructions":{"type":"object","properties":{"fine":{"type":"number"},"interest":{"type":"number"}},"description":"Juros, multa e desconto do boleto"},"expirationAfterDueDate":{"type":"integer","minimum":0,"maximum":60,"description":"Dias após vencimento (0 a 60, default 30)"}}},"example":{"priceId":"price_yyy","quantity":2,"dueDate":"2026-04-06","boletoInstructions":{"fine":2,"interest":1},"expirationAfterDueDate":30}}}},"security":[{"oauth2":["subscriptions/write"]}]}},"/v1/subscriptions/{subscriptionId}/prorata":{"post":{"operationId":"post-calcular-pro-rata","summary":"Calcular Pro Rata","tags":["Assinaturas"],"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (ex: sub_xxx) - required","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string"},"currentAmount":{"type":"number"},"newAmount":{"type":"number"},"prorataAmount":{"type":"number"},"remainingDays":{"type":"number"},"cycleDays":{"type":"number"},"currentCredit":{"type":"number"},"nextCycleChargeDate":{"type":"string","format":"date"}}},"example":{"subscriptionId":"sub_xxx","currentAmount":99.9,"newAmount":199.9,"prorataAmount":45.48,"remainingDays":15,"cycleDays":31,"currentCredit":48.34,"nextCycleChargeDate":"2024-02-15"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"sub","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Assinatura não encontrada","code":"SUBSCRIPTION_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Calcula o valor de pro rata para uma troca de plano **sem efetuar cobrança**.\n\nÚtil para exibir ao cliente o valor exato da mudança antes de confirmar o upgrade. O cálculo considera os dias restantes do ciclo atual.\n\nEnvie `old` com o preço/quantidade atuais e `new` com o preço/quantidade desejados.\n\nCase de uso:\n\n_Como SaaS, quero mostrar na interface \"Você pagará R$ 45,48 hoje pela diferença proporcional\" antes do cliente confirmar o upgrade._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"old":{"type":"object","properties":{"priceId":{"type":"string","description":"Preço atual"},"quantity":{"type":"number"}},"required":["priceId"]},"new":{"type":"object","properties":{"priceId":{"type":"string","description":"Novo preço"},"quantity":{"type":"number"}},"required":["priceId"]}},"required":["old","new"]},"example":{"old":{"priceId":"price_xxx","quantity":1},"new":{"priceId":"price_yyy","quantity":1}}}}},"security":[{"oauth2":["subscriptions/read"]}]}},"/v1/invoices/notas":{"get":{"operationId":"get-listar-notas-fiscais","summary":"Listar Notas Fiscais","tags":["Notas Fiscais"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Itens por página (default 20) - optional","schema":{"type":"string","example":"20"}},{"name":"lastKey","in":"query","required":true,"description":"Cursor da próxima página, de pagination.lastKey - optional","schema":{"type":"string"}},{"name":"search","in":"query","required":true,"description":"Busca parcial por nome do tomador ou documento - optional","schema":{"type":"string"}},{"name":"taxId","in":"query","required":true,"description":"CPF/CNPJ exato do tomador, apenas dígitos - optional","schema":{"type":"string"}},{"name":"customerName","in":"query","required":true,"description":"Nome do tomador - optional","schema":{"type":"string"}},{"name":"status","in":"query","required":true,"description":"AUTHORIZED (ou ISSUED), PROCESSING, ERROR (ou FAILED), CANCELED ou REPLACED - optional","schema":{"type":"string"}},{"name":"startDate","in":"query","required":true,"description":"Data inicial da emissão, ISO 8601 - optional","schema":{"type":"string"}},{"name":"endDate","in":"query","required":true,"description":"Data final da emissão, ISO 8601 - optional","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"emissor":{"type":"object","properties":{"configId":{"type":"string"},"cnpj":{"type":"string"},"nome":{"type":"string"}}},"type":{"type":"string"},"invoiceId":{"type":"string"},"chargeId":{},"customerId":{},"customerName":{"type":"string"},"taxId":{"type":"string"},"amount":{"type":"number"},"emitidaEm":{"type":"string","format":"date-time"},"ref":{"type":"string"},"status":{"type":"string"},"feeStatus":{"type":"string"},"feeAmount":{"type":"number"},"nf":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"},"pdfUrl":{"type":"string"},"xmlPath":{"type":"string"},"xmlUrl":{"type":"string"},"verificationCode":{"type":"string"},"rpsNumber":{"type":"string"},"rpsSeries":{"type":"string"},"cnpj":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"errors":{}}}}}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"totalPages":{"type":"number"},"limit":{"type":"number"},"hasMore":{"type":"boolean"},"lastKey":{}}}}},"example":{"items":[{"emissor":{"configId":"unc_1788193720141_65g0zh12p","cnpj":"99988877000108","nome":"EMPRESA EXEMPLO LTDA"},"type":"NFSE","invoiceId":"nf_1788101026585_uqaspo7bn","chargeId":null,"customerId":null,"customerName":"Alexandre Souza","taxId":"11144477735","amount":150,"emitidaEm":"2026-08-30T14:43:49.719Z","ref":"2109541","status":"AUTHORIZED","feeStatus":"COMPLETED","feeAmount":0.37,"nf":{"id":"2109541","number":"7814","status":"AUTHORIZED","url":"https://…","pdfUrl":"https://…","xmlPath":"/arquivos/…-nfse.xml","xmlUrl":"https://…","verificationCode":"PGRW-2TFA","rpsNumber":"5053","rpsSeries":"1","cnpj":"99988877000108","issuedAt":"2026-08-30T14:43:49.719Z","errors":null}}],"pagination":{"total":1,"totalPages":1,"limit":20,"hasMore":false,"lastKey":null}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Conta não encontrada","code":"ACCOUNT_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Lista as notas fiscais da conta, da mais recente para a mais antiga.\n\nInclui todas as origens: notas geradas por cobranças e assinaturas e também as avulsas, emitidas por POST nesta mesma rota.\n\n### O identificador da nota\n\nO campo `invoiceId` é o identificador usado nas demais rotas — consultar, cancelar, reemitir, reenviar e emitir. Na nota avulsa ele é o `ref` que você informou na emissão; nas notas geradas por cobrança, é o identificador da própria cobrança.\n\nNão o confunda com o `ref` da resposta, que traz o identificador interno da nota e serve apenas para suporte.\n\n### Status\n\n- `PROCESSING` — enviada, a prefeitura ainda não respondeu\n- `ISSUED` ou `AUTHORIZED` — autorizada. Os dois valores são equivalentes: o primeiro vem da emissão síncrona, o segundo da confirmação assíncrona da prefeitura\n- `FAILED` ou `ERROR` — recusada. `nf.errors` traz as mensagens da prefeitura\n- `CANCELED` — cancelada\n- `REPLACED` — substituída por uma reemissão\n\nNo filtro `status` os pares são intercambiáveis: `AUTHORIZED` traz também as `ISSUED`, e `ERROR` traz também as `FAILED`.\n\n### Paginação\n\nPor cursor: envie em `lastKey` o valor devolvido em `pagination.lastKey`. Enquanto `pagination.hasMore` for `true`, ainda há páginas.\n\n`emissor` identifica de qual empresa a nota saiu, útil quando a conta tem mais de uma configuração fiscal. `feeAmount` e `feeStatus` descrevem a taxa de emissão cobrada pela ValidaPay, não um tributo da nota.\n\nCase de uso:\n\n_Como plataforma, quero conciliar as notas do mês e conferir quais foram autorizadas antes de fechar o faturamento._","security":[{"oauth2":["nota.fiscal/read"]}]},"post":{"operationId":"post-emitir-nota-fiscal","summary":"Emitir Nota Fiscal","tags":["Notas Fiscais"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"ref":{"type":"string"},"id":{"type":"string"},"nfStatus":{"type":"string"},"tipo":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"internalStatus":{"type":"string"}}},"example":{"success":true,"status":"PROCESSING","ref":"nf_1788101026585_uqaspo7bn","id":"nf_1788101026585_uqaspo7bn","nfStatus":"processando_autorizacao","tipo":"nacional","issuedAt":"2026-08-30T14:43:49.719Z","internalStatus":"PROCESSING"}}}},"400":{"description":"- configuração inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Configuração não encontrada ou desabilitada","code":"NOTA_CONFIG_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Emite uma nota fiscal de serviço avulsa, sem vínculo com cobrança ou assinatura.\n\nA emissão é imediata: o `invoiceTiming` da configuração fiscal vale apenas para as notas geradas a partir de cobranças, não para a avulsa.\n\nInforme em `configId` qual configuração fiscal usar — uma conta pode ter configurações de mais de uma empresa, e a nota sai no CNPJ da configuração escolhida. Liste as disponíveis em `GET /v1/invoices/notas/config`.\n\nO `ref` que você enviar passa a ser o identificador da nota nas demais rotas: consultar, cancelar, reemitir e reenviar. Omitido, a API gera um identificador próprio e o devolve na resposta.\n\nO campo `type` indica o modelo do documento fiscal. O único valor aceito hoje é `NFSE` (nota fiscal de serviço), que também é o assumido quando o campo é omitido — qualquer outro valor retorna 400 com o código `NOTA_TYPE_NOT_SUPPORTED`.\n\nOutros tipos de nota estarão disponíveis em breve. Envie `type` explicitamente desde já: quando cada modelo for liberado, nenhuma alteração no payload será necessária.\n\nO tomador não precisa estar cadastrado. Se o endereço não trouxer `cityCode`, o código IBGE do município é resolvido a partir do CEP — assim como logradouro e bairro, quando faltarem.\n\nA resposta volta com status `PROCESSING`: a prefeitura responde de forma assíncrona. Não há evento de webhook para nota fiscal — acompanhe o desfecho em `GET /v1/invoices/notas/{notaId}`, que passa a `AUTHORIZED` ou a `ERROR` com as mensagens da prefeitura.\n\nCase de uso:\n\n_Como prestador, quero emitir uma nota para um serviço cobrado fora da plataforma, informando apenas o tomador, o valor e a descrição._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configId":{"type":"string","description":"Configuração fiscal, de GET /v1/invoices/notas/config"},"amount":{"type":"number","multipleOf":0.01,"description":"Valor do serviço em reais"},"descricao":{"type":"string","description":"Discriminação do serviço na nota"},"customer":{"type":"object","properties":{"document":{"type":"string","pattern":"^\\d{11}$|^\\d{14}$","description":"CPF (11) ou CNPJ (14), apenas dígitos"},"name":{"type":"string","description":"Nome completo ou razão social do tomador"},"address":{"type":"object","properties":{"zipCode":{"type":"string","description":"8 dígitos, apenas números"},"street":{"type":"string"},"number":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"UF com 2 letras"},"complement":{"type":"string"},"cityCode":{"type":"string","description":"Código IBGE; resolvido pelo CEP quando ausente"}},"required":["zipCode","street","number","neighborhood","city","state"]},"email":{"type":"string","format":"email"},"phone":{"type":"string"}},"required":["document","name","address"]},"type":{"type":"string","description":"Modelo do documento fiscal; único valor aceito hoje, outros tipos em breve. Padrão: NFSE"},"ref":{"type":"string","description":"Vira o identificador da nota nas demais rotas; se omitida, a API gera uma"}},"required":["configId","amount","descricao","customer"]},"example":{"configId":"unc_1776888897617_ppwgo7oef","type":"NFSE","amount":150,"descricao":"Consultoria em tecnologia da informação","ref":"pedido-2026-0912","customer":{"document":"11144477735","name":"Alexandre Souza","email":"alexandre@exemplo.com.br","phone":"5511987654321","address":{"zipCode":"01310100","street":"Avenida Paulista","number":"1000","complement":"Sala 5","neighborhood":"Bela Vista","city":"São Paulo","state":"SP","cityCode":"3550308"}}}}}},"security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/summary":{"get":{"operationId":"get-resumo-de-notas-fiscais","summary":"Resumo de Notas Fiscais","tags":["Notas Fiscais"],"parameters":[{"name":"startDate","in":"query","required":true,"description":"Data inicial da emissão, ISO 8601 - optional","schema":{"type":"string"}},{"name":"endDate","in":"query","required":true,"description":"Data final da emissão, ISO 8601 - optional","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"authorizedCount":{"type":"number"},"authorizedAmount":{"type":"number"},"canceledCount":{"type":"number"},"canceledAmount":{"type":"number"},"errorCount":{"type":"number"},"errorAmount":{"type":"number"},"processingCount":{"type":"number"},"processingAmount":{"type":"number"},"replacedCount":{"type":"number"},"replacedAmount":{"type":"number"}}},"example":{"authorizedCount":128,"authorizedAmount":45320.75,"canceledCount":3,"canceledAmount":890,"errorCount":2,"errorAmount":450,"processingCount":1,"processingAmount":150,"replacedCount":2,"replacedAmount":300}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Totais de notas da conta por status, em quantidade e em valor.\n\nSem `startDate` e `endDate`, o resumo cobre todas as notas da conta.\n\nOs pares de status são somados juntos: `authorized` inclui as notas `ISSUED` e `AUTHORIZED`, e `error` inclui as `FAILED` e `ERROR`.\n\nCase de uso:\n\n_Como plataforma, quero mostrar no painel quantas notas foram autorizadas e quantas falharam no mês, sem paginar a listagem inteira._","security":[{"oauth2":["nota.fiscal/read"]}]}},"/v1/invoices/notas/{notaid}":{"get":{"operationId":"get-consultar-nota-fiscal","summary":"Consultar Nota Fiscal","tags":["Notas Fiscais"],"parameters":[{"name":"notaid","in":"path","required":true,"description":"Notaid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"emissor":{"type":"object","properties":{"configId":{"type":"string"},"cnpj":{"type":"string"},"nome":{"type":"string"}}},"type":{"type":"string"},"invoiceId":{"type":"string"},"chargeId":{},"customerId":{},"customerName":{"type":"string"},"taxId":{"type":"string"},"amount":{"type":"number"},"emitidaEm":{"type":"string","format":"date-time"},"ref":{"type":"string"},"status":{"type":"string"},"feeStatus":{},"feeAmount":{},"nf":{"type":"object","properties":{"id":{"type":"string"},"number":{},"status":{"type":"string"},"url":{},"pdfUrl":{},"xmlPath":{},"xmlUrl":{},"verificationCode":{},"rpsNumber":{},"rpsSeries":{},"cnpj":{"type":"string"},"issuedAt":{},"errors":{"type":"array","items":{"type":"object","properties":{"mensagem":{"type":"string"}}}}}}}},"example":{"emissor":{"configId":"unc_1788193720141_65g0zh12p","cnpj":"99988877000108","nome":"EMPRESA EXEMPLO LTDA"},"type":"NFSE","invoiceId":"nf_1788101026585_uqaspo7bn","chargeId":null,"customerId":null,"customerName":"Alexandre Souza","taxId":"11144477735","amount":150,"emitidaEm":"2026-08-30T14:43:49.719Z","ref":"2109541","status":"ERROR","feeStatus":null,"feeAmount":null,"nf":{"id":"2109541","number":null,"status":"ERROR","url":null,"pdfUrl":null,"xmlPath":null,"xmlUrl":null,"verificationCode":null,"rpsNumber":null,"rpsSeries":null,"cnpj":"99988877000108","issuedAt":null,"errors":[{"mensagem":"Código de tributação nacional do ISS inválido para o município"}]}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Nota fiscal não encontrada","code":"NOTA_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Retorna uma nota pelo `invoiceId` devolvido na listagem — que na nota avulsa é o `ref` informado na emissão, e na nota de cobrança é o identificador da cobrança.\n\nTraz os links do PDF e do XML e o código de verificação quando a nota já está autorizada. Quando a prefeitura recusou, `nf.errors` traz as mensagens do que precisa ser corrigido.\n\nNota inexistente, excluída ou de outra conta responde 404 com `NOTA_NOT_FOUND`.\n\nCase de uso:\n\n_Como plataforma, quero buscar o PDF de uma nota para anexar ao e-mail que envio ao meu cliente._","security":[{"oauth2":["nota.fiscal/read"]}]},"delete":{"operationId":"delete-cancelar-nota-fiscal","summary":"Cancelar Nota Fiscal","tags":["Notas Fiscais"],"parameters":[{"name":"notaid","in":"path","required":true,"description":"Notaid","schema":{"type":"string"}},{"name":"motivo","in":"query","required":false,"description":"Justificativa enviada à prefeitura - required","schema":{"type":"string","example":"Valor do servico informado incorretamente"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"invoiceId":{"type":"string"}}},"example":{"success":true,"invoiceId":"nf_1788101026585_uqaspo7bn"}}}},"400":{"description":"- não autorizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Nota fiscal não está autorizada para cancelamento","code":"NF_NOT_AUTHORIZED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Nota fiscal não encontrada","code":"NOTA_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Cancela na prefeitura uma nota fiscal já autorizada. O identificador é o `invoiceId` da listagem.\n\nO motivo vai na query string, e não no corpo: parte dos clientes HTTP descarta body em requisições DELETE.\n\nSó é possível cancelar notas da própria conta e que estejam autorizadas. O status é reconferido antes do cancelamento: nota em processamento ou já cancelada é recusada com `NF_NOT_AUTHORIZED`.\n\nO prazo de cancelamento é definido pela prefeitura do município emissor. Passada essa janela, o cancelamento é recusado com `NF_CANCEL_FAILED` e a correção passa a exigir substituição da nota.\n\nCase de uso:\n\n_Como prestador, quero cancelar uma nota emitida com valor errado, dentro do prazo permitido pelo município._","security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/{notaid}/emitir":{"post":{"operationId":"post-emitir-nota-de-uma-cobranca","summary":"Emitir Nota de uma Cobrança","tags":["Notas Fiscais"],"parameters":[{"name":"notaid","in":"path","required":true,"description":"Notaid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"invoiceId":{"type":"string"},"subscriptionId":{"type":"string"},"cycleNumber":{"type":"number"},"type":{"type":"string"},"status":{"type":"string"},"numero":{},"tipo":{"type":"string"}}},"example":{"success":true,"invoiceId":"inv_1788101026585_uqaspo7bn","subscriptionId":"sub_1788101026585_a1b2c3d4e","cycleNumber":3,"type":"NFSE","status":"PROCESSING","numero":null,"tipo":"nacional"}}}},"400":{"description":"- sem emissor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Informe o emissor (configId) para emitir a nota fiscal","code":"NF_CONFIG_REQUIRED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Cobrança não encontrada","code":"INVOICE_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Emite a nota de uma cobrança que já existe — a que nunca emitiu e também a que falhou. O identificador na URL é o da cobrança: `invoiceId` de uma fatura de assinatura ou `chargeId` de uma cobrança avulsa.\n\nDiferente da emissão avulsa, a nota nasce ligada à cobrança: herda cliente, valor e, quando existe, assinatura e ciclo.\n\n### De onde vem a configuração fiscal\n\nNa ordem: o `configId` do corpo, depois o da nota anterior, o `nfConfigId` da cobrança e o da assinatura. Não achando nenhum, a resposta é `NF_CONFIG_REQUIRED` e nada é emitido.\n\n### Quando a emissão é recusada\n\n- `INVOICE_NOT_FOUND` (404) — cobrança inexistente ou de outra conta\n- `INVOICE_STATUS_NOT_EMITTABLE` — só emite cobrança pendente, aguardando pagamento ou paga\n- `NOTA_ALREADY_ISSUED` — já existe nota autorizada, vinculada ou agendada para essa cobrança\n- `NOTA_PROCESSING` — há uma emissão em andamento aguardando o retorno da prefeitura\n- `NF_INCOMPLETE_DATA` — faltam dados do tomador; `details` lista exatamente o que falta\n- `NF_CONFIG_NOT_FOUND` — a configuração informada não existe ou está desabilitada\n\nPara conferir os dados antes sem emitir nada, use `POST /v1/invoices/notas/{notaId}/verificar-emissao`.\n\nCase de uso:\n\n_Como prestador, quero emitir a nota de uma cobrança que ficou sem nota, sem precisar refazer a cobrança._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configId":{"type":"string","description":"Configuração fiscal a usar; sem ela vale a da cobrança ou da assinatura"}}},"example":{"configId":"unc_1776888897617_ppwgo7oef"}}}},"security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/{notaid}/verificar-emissao":{"post":{"operationId":"post-verificar-dados-para-emissao","summary":"Verificar Dados para Emissão","tags":["Notas Fiscais"],"parameters":[{"name":"notaid","in":"path","required":true,"description":"Notaid","schema":{"type":"string"}}],"responses":{"200":{"description":"- com pendências","content":{"application/json":{"schema":{"type":"object","properties":{"invoiceId":{"type":"string"},"ready":{"type":"boolean"},"pendencias":{"type":"array","items":{"type":"string"}},"configId":{"type":"string"},"amount":{"type":"number"}}},"example":{"invoiceId":"inv_1788101026585_uqaspo7bn","ready":false,"pendencias":["CEP do cliente","Município do cliente (código IBGE)"],"configId":"unc_1788193720141_65g0zh12p","amount":150}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Confere se uma cobrança tem tudo o que a nota fiscal exige, sem emitir nada. O identificador na URL é o da cobrança, como em `POST /v1/invoices/notas/{notaId}/emitir`.\n\n`ready` diz se a emissão passaria agora; `pendencias` lista em português o que falta — CPF ou CNPJ, nome, valor, endereço, CEP, município (código IBGE), logradouro ou bairro do cliente.\n\n`configId` traz a configuração fiscal que seria usada, ou `null` quando nenhuma foi encontrada. Diferente da emissão, aqui a ausência de configuração não é erro.\n\nA conferência é uma rota própria em vez de um parâmetro na rota de emissão: um flag ignorado por engano emitiria a nota de verdade.\n\nCase de uso:\n\n_Como plataforma, quero avisar o usuário sobre o cadastro incompleto do cliente antes de tentar emitir a nota e receber a recusa._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configId":{"type":"string","description":"Configuração fiscal a conferir; sem ela vale a da cobrança ou da assinatura"}}},"example":{"configId":"unc_1776888897617_ppwgo7oef"}}}},"security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/{notaid}/reemitir":{"post":{"operationId":"post-reemitir-nota-fiscal","summary":"Reemitir Nota Fiscal","tags":["Notas Fiscais"],"parameters":[{"name":"notaid","in":"path","required":true,"description":"Notaid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"invoiceId":{"type":"string"},"subscriptionId":{},"cycleNumber":{},"type":{"type":"string"},"status":{"type":"string"},"numero":{},"tipo":{"type":"string"}}},"example":{"success":true,"invoiceId":"nf_1788101026585_uqaspo7bn","subscriptionId":null,"cycleNumber":null,"type":"NFSE","status":"PROCESSING","numero":null,"tipo":"nacional"}}}},"400":{"description":"- já autorizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Nota já autorizada — não pode ser reemitida","code":"NOTA_ALREADY_ISSUED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Gera uma nova nota para uma emissão que falhou na prefeitura. O identificador é o `invoiceId` da listagem.\n\nSó vale para notas que não foram autorizadas: uma nota já autorizada é recusada com `NOTA_ALREADY_ISSUED` — nesse caso o caminho é cancelar e emitir de novo.\n\nA nota anterior fica com status `REPLACED` e a nova assume o lugar dela. A configuração fiscal usada é a mesma da nota anterior.\n\nCorrija a causa da recusa antes de reemitir: a mensagem da prefeitura está em `nf.errors`, na consulta da nota.\n\nCase de uso:\n\n_Como prestador, quero reprocessar uma nota recusada por erro de cadastro, depois de corrigir a configuração fiscal._","security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/{notaid}/reenviar":{"post":{"operationId":"post-reenviar-nota-por-e-mail","summary":"Reenviar Nota por E-mail","tags":["Notas Fiscais"],"parameters":[{"name":"notaid","in":"path","required":true,"description":"Notaid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"emails":{"type":"array","items":{"type":"string","format":"email"}}}},"example":{"success":true,"emails":["financeiro@exemplo.com.br","contabilidade@exemplo.com.br"]}}}},"400":{"description":"- sem e-mail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Informe ao menos um e-mail","code":"EMAILS_REQUIRED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Reenvia por e-mail uma nota já autorizada. O identificador é o `invoiceId` da listagem.\n\nAceita até 10 destinatários por chamada — acima disso a resposta é `TOO_MANY_EMAILS`. Notas que ainda não foram autorizadas são recusadas com `NOTA_NOT_ISSUED`.\n\nA nota segue anexada em PDF e XML.\n\nCase de uso:\n\n_Como prestador, quero reenviar a nota para um segundo e-mail do cliente, sem precisar baixar e anexar o PDF manualmente._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","format":"email"},"description":"No máximo 10 destinatários"}},"required":["emails"]},"example":{"emails":["financeiro@exemplo.com.br","contabilidade@exemplo.com.br"]}}}},"security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/config":{"get":{"operationId":"get-listar-configuracoes-fiscais","summary":"Listar Configurações Fiscais","tags":["Notas Fiscais"],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"configs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"config_name":{"type":"string"},"enabled":{"type":"boolean"},"invoiceTiming":{"type":"string"},"codigo_tributacao_nacional_iss":{"type":"string"},"tributacao_iss":{"type":"number"},"tipo_retencao_iss":{"type":"number"},"serie_dps":{"type":"string"},"prestador":{"type":"object","properties":{"cnpj":{"type":"string"},"nome_fantasia":{"type":"string"},"inscricao_municipal":{"type":"string"},"codigo_municipio":{"type":"string"},"codigo_municipio_prestacao":{"type":"string"},"codigo_opcao_simples_nacional":{"type":"number"},"regime_especial_tributacao":{"type":"number"}}},"prefeitura":{"type":"object","properties":{"login":{"type":"string"},"has_senha":{"type":"boolean"},"serie_rps":{"type":"string"},"proximo_numero_rps":{"type":"number"}}},"certificate":{"type":"object","properties":{"has_certificate":{"type":"boolean"},"expiry_date":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"defaults":{"type":"object","properties":{"prestador":{"type":"object","properties":{"cnpj":{"type":"string"},"nome_fantasia":{"type":"string"},"email":{"type":"string","format":"email"},"telefone":{"type":"string"},"codigo_municipio":{"type":"string"},"codigo_municipio_prestacao":{"type":"string"},"endereco":{"type":"object","properties":{"logradouro":{"type":"string"},"numero":{"type":"string"},"bairro":{"type":"string"},"cep":{"type":"string"},"uf":{"type":"string"}}}}},"responsavel":{"type":"object","properties":{"nome":{"type":"string"},"cpf":{"type":"string"}}}}}}},"example":{"configs":[{"id":"unc_1788193720141_65g0zh12p","accountId":"460851686","config_name":"Matriz","enabled":true,"invoiceTiming":"IMMEDIATE","codigo_tributacao_nacional_iss":"010701","tributacao_iss":1,"tipo_retencao_iss":1,"serie_dps":"1","prestador":{"cnpj":"99988877000108","nome_fantasia":"EMPRESA EXEMPLO LTDA","inscricao_municipal":"1234567","codigo_municipio":"4205407","codigo_municipio_prestacao":"4205407","codigo_opcao_simples_nacional":1,"regime_especial_tributacao":0},"prefeitura":{"login":"usuario-do-portal","has_senha":true,"serie_rps":"1","proximo_numero_rps":145},"certificate":{"has_certificate":true,"expiry_date":"2026-11-18T11:01:15.000Z"},"createdAt":"2026-08-31T16:28:43.167Z","updatedAt":"2026-08-31T16:28:43.167Z"}],"defaults":{"prestador":{"cnpj":"99988877000108","nome_fantasia":"EMPRESA EXEMPLO LTDA","email":"fiscal@exemplo.com.br","telefone":"5548999999999","codigo_municipio":"4205407","codigo_municipio_prestacao":"4205407","endereco":{"logradouro":"RUA DAS PALMEIRAS","numero":"110","bairro":"CENTRO","cep":"88010000","uf":"SC"}},"responsavel":{"nome":"Maria Souza","cpf":"11144477735"}}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Lista as configurações fiscais da conta.\n\nUse o `id` de cada uma como `configId` ao emitir uma nota avulsa, e como `nfConfigId` em cobranças, produtos e assinaturas.\n\nA resposta traz também `defaults`: os valores que a API preencheria sozinha a partir do cadastro da conta — CNPJ, endereço, contato e código IBGE do município — úteis para montar a tela de cadastro já preenchida.\n\nSegredos nunca são devolvidos. De `prefeitura` vêm o `login`, `has_senha` e a numeração do RPS; do certificado, se existe e a validade.\n\nCase de uso:\n\n_Como plataforma, quero listar as empresas emissoras da conta para escolher por qual emitir cada nota._","security":[{"oauth2":["nota.fiscal/read"]}]},"post":{"operationId":"post-criar-configuracao-fiscal","summary":"Criar Configuração Fiscal","tags":["Notas Fiscais"],"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"config_name":{"type":"string"},"enabled":{"type":"boolean"},"invoiceTiming":{"type":"string"},"codigo_tributacao_nacional_iss":{"type":"string"},"tributacao_iss":{"type":"number"},"tipo_retencao_iss":{"type":"number"},"serie_dps":{"type":"string"},"descricao_servico":{"type":"string"},"prestador":{"type":"object","properties":{"cnpj":{"type":"string"},"nome_fantasia":{"type":"string"},"inscricao_municipal":{"type":"string"},"codigo_municipio":{"type":"string"},"codigo_municipio_prestacao":{"type":"string"},"codigo_opcao_simples_nacional":{"type":"number"},"regime_especial_tributacao":{"type":"number"}}},"prefeitura":{"type":"object","properties":{"login":{"type":"string"},"has_senha":{"type":"boolean"},"serie_rps":{"type":"string"},"proximo_numero_rps":{"type":"number"}}},"certificate":{"type":"object","properties":{"has_certificate":{"type":"boolean"},"expiry_date":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"example":{"id":"unc_1788193720141_65g0zh12p","accountId":"460851686","config_name":"Matriz","enabled":true,"invoiceTiming":"IMMEDIATE","codigo_tributacao_nacional_iss":"010701","tributacao_iss":1,"tipo_retencao_iss":1,"serie_dps":"1","descricao_servico":"Prestação de Serviços","prestador":{"cnpj":"99988877000108","nome_fantasia":"EMPRESA EXEMPLO LTDA","inscricao_municipal":"1234567","codigo_municipio":"4205407","codigo_municipio_prestacao":"4205407","codigo_opcao_simples_nacional":1,"regime_especial_tributacao":0},"prefeitura":{"login":"usuario-do-portal","has_senha":true,"serie_rps":"1","proximo_numero_rps":145},"certificate":{"has_certificate":true,"expiry_date":"2026-11-18T11:01:15.000Z"},"createdAt":"2026-08-31T16:28:43.167Z","updatedAt":"2026-08-31T16:28:43.167Z"}}}},"400":{"description":"- sincronização","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Mensagem devolvida pela prefeitura","code":"NF_CONFIG_SYNC_FAILED","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"- regime incompleto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"aliquota_pis é obrigatório para regime Não Optante","code":"INTERNAL_ERROR","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Cadastra a empresa emissora: CNPJ, regime tributário, certificado digital e os tributos que entram na nota.\n\nO `id` devolvido aqui é o `configId` da emissão avulsa e o `nfConfigId` de cobranças, produtos e assinaturas. Uma conta pode ter mais de uma configuração — o CNPJ do prestador define de qual empresa a nota sai.\n\nO que não for enviado é preenchido a partir do cadastro da conta: CNPJ, endereço, contato e código IBGE do município. Enviar explicitamente evita depender desses dados.\n\nA criação valida e registra a empresa emissora, incluindo o certificado. Se essa etapa falhar, nada é gravado e o certificado enviado é descartado — não sobra configuração pela metade.\n\nNão envie `id` no corpo: com ele a chamada vira atualização da configuração existente.\n\n### Municipal ou nacional: quem decide é o município\n\nO código IBGE em `prestador.codigo_municipio` determina por qual padrão a nota sai, e isso muda quais campos tributários são lidos:\n\n- **NFS-en nacional** — padrão nacional da NFS-e, adotado pela maior parte dos municípios. Usa `codigo_tributacao_nacional_iss`, `tributacao_iss`, `tipo_retencao_iss`, `serie_dps` e os campos de PIS/COFINS ou do Simples, conforme o regime.\n- **NFS-e municipal** — municípios com sistema próprio. Usa `item_lista_servico`, `aliquota_iss`, `iss_retido`, `natureza_operacao` e, quando o município exige, `codigo_cnae` e `codigo_tributario_municipio`.\n\nVocê não precisa escolher: a rota é resolvida na emissão, a partir do município do prestador. `tipo_nf` força um dos dois padrões e só faz sentido quando o município aceita ambos.\n\nNa dúvida sobre em qual padrão o seu município está, preencha os dois conjuntos — o que não se aplica é ignorado.\n\n### Credencial da prefeitura e numeração do RPS\n\nO certificado digital A1 basta na maior parte dos municípios. Os que têm sistema próprio podem exigir também uma credencial do portal, enviada em `prefeitura` — nem todos pedem `login`, e há municípios em que só a senha é necessária.\n\nConfira o portal do seu município antes de preencher. Em parte deles o que vai em `senha` é uma chave digital gerada no perfil do usuário, e não a senha de acesso ao portal — usar a senha errada só aparece como falha de autenticação na primeira emissão.\n\n### Numeração\n\nCada padrão tem a sua, e as duas continuam a sequência que a prefeitura já registrou para a empresa — em branco, a numeração começa do início.\n\n- **NFS-e municipal** — `prefeitura.serie_rps` e `prefeitura.proximo_numero_rps`.\n- **NFS-en nacional** — `serie_dps`, no primeiro nível do corpo. A série declarada no cadastro é a mesma que vai em cada emissão e precisa bater com a registrada na prefeitura; a sequência dos números é mantida pela ValidaPay.\n\n### Quando a nota é emitida\n\n`invoiceTiming` define o momento da emissão das notas geradas por cobrança:\n\n- `IMMEDIATE` — junto com a cobrança. É o padrão.\n- `AFTER_CONFIRMATION` — somente após a confirmação do pagamento.\n- `DAYS_AFTER_CONFIRMATION` — `daysAfterConfirmation` dias depois da confirmação (padrão 1).\n\nA emissão avulsa por `POST /v1/invoices/notas` sai sempre na hora, qualquer que seja o valor configurado.\n\n> ⚠️ **Atenção:** configurações criadas pelo painel trazem também `quando_emitir`, com os mesmos três valores. Ele é apenas o espelho gravado pela tela — quem define o agendamento é `invoiceTiming`.\n\n### Campos exigidos pelo regime\n\nO regime vem de `prestador.codigo_opcao_simples_nacional`:\n\n- **1, não optante** — exige `situacao_tributaria_pis_cofins`, `aliquota_pis` e `aliquota_cofins`.\n- **2 (MEI) e 3 (ME/EPP)** — exigem `percentual_total_tributos_simples_nacional`.\n\nFaltando um deles, a configuração não é gravada e a resposta traz a mensagem da validação com o código `INTERNAL_ERROR`.\n\nCase de uso:\n\n_Como plataforma, quero cadastrar a empresa emissora e o certificado digital por API, para habilitar a emissão de notas sem passar pelo painel._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codigo_tributacao_nacional_iss":{"type":"string","description":"NFS-en: código de tributação nacional do ISS, 6 dígitos"},"tributacao_iss":{"type":"number","description":"NFS-en: 1 tributável, 2 imunidade, 3 exportação, 4 não incidência"},"tipo_retencao_iss":{"type":"number","description":"NFS-en: 1 não retido, 2 retido pelo tomador, 3 pelo intermediário"},"situacao_tributaria_pis_cofins":{"type":"string","description":"se não optante pelo Simples - NFS-en"},"aliquota_pis":{"type":"number","description":"se não optante - Percentual aplicado sobre o valor do serviço"},"aliquota_cofins":{"type":"number","description":"se não optante - Percentual aplicado sobre o valor do serviço"},"percentual_total_tributos_simples_nacional":{"type":"number","description":"se optante pelo Simples (MEI ou ME/EPP)"},"prestador":{"type":"object","properties":{"cnpj":{"type":"string","description":"14 dígitos, apenas números"},"codigo_municipio":{"type":"string","description":"Código IBGE do município, 7 dígitos; define o padrão de emissão"},"codigo_opcao_simples_nacional":{"type":"number","description":"NÚMERO, não string. 1 não optante, 2 MEI, 3 ME/EPP"},"regime_especial_tributacao":{"type":"number","description":"0 nenhum"},"inscricao_municipal":{"type":"string"},"inscricao_estadual":{"type":"string"},"nome_fantasia":{"type":"string"},"email":{"type":"string","format":"email"},"telefone":{"type":"string"},"codigo_municipio_prestacao":{"type":"string","description":"Default igual a codigo_municipio"},"endereco":{"type":"object","properties":{"logradouro":{"type":"string"},"numero":{"type":"string"},"complemento":{"type":"string"},"bairro":{"type":"string"},"municipio":{"type":"string"},"cep":{"type":"string"},"uf":{"type":"string"}},"description":"Preenchido pelo cadastro da conta quando ausente"}},"required":["cnpj","codigo_municipio","codigo_opcao_simples_nacional","regime_especial_tributacao"]},"config_name":{"type":"string","description":"Nome para diferenciar as configurações da conta"},"enabled":{"type":"boolean","description":"Default true; configuração desabilitada não emite"},"razao_social":{"type":"string","description":"Razão social da empresa emissora; sem ela vale o nome_fantasia"},"invoiceTiming":{"type":"string","description":"Momento da emissão nas notas geradas por cobrança. Default IMMEDIATE","enum":["IMMEDIATE","AFTER_CONFIRMATION","DAYS_AFTER_CONFIRMATION"]},"daysAfterConfirmation":{"type":"number","description":"Dias após a confirmação, quando invoiceTiming for DAYS_AFTER_CONFIRMATION. Default 1","minimum":1},"tipo_nf":{"type":"string","description":"Força o padrão de emissão; por padrão quem decide é o município do prestador","enum":["municipal","nacional"]},"descricao_servico":{"type":"string","description":"Discriminação padrão do serviço, usada quando a cobrança não traz o nome do item"},"enviar_email_destinatario":{"type":"boolean","description":"Default true; a nota é enviada ao tomador por e-mail na autorização"},"serie_dps":{"type":"string","description":"NFS-en: série da DPS, declarada no cadastro e enviada em cada emissão. Default 1"},"aliquota_csll":{"type":"number","description":"Percentual; vira o valor de CSLL da nota"},"aliquota_irrf":{"type":"number","description":"Percentual; vira o valor de IRRF da nota"},"tipo_retencao_pis_cofins":{"type":"number","description":"0 não retido"},"percentual_total_tributos_federais":{"type":"number","description":"Percentual informado na nota"},"percentual_total_tributos_estaduais":{"type":"number","description":"Percentual informado na nota"},"percentual_total_tributos_municipais":{"type":"number","description":"Percentual informado na nota"},"regime_tributario_simples_nacional":{"type":"number","description":"1 federais e municipal pelo SN. Default 1"},"item_lista_servico":{"type":"string","description":"Obrigatório na NFS-e municipal: item da lista de serviços, formato NN.NN"},"aliquota_iss":{"type":"number","description":"Obrigatório na NFS-e municipal: alíquota do ISS em percentual"},"iss_retido":{"type":"boolean","description":"NFS-e municipal: ISS retido pelo tomador. Default false"},"natureza_operacao":{"type":"string","description":"NFS-e municipal. Default 1"},"codigo_cnae":{"type":"string","description":"NFS-e municipal; exigido por parte dos municípios"},"codigo_tributario_municipio":{"type":"string","description":"NFS-e municipal; exigido por parte dos municípios"},"prefeitura":{"type":"object","properties":{"login":{"type":"string","description":"Só nos municípios que pedem login"},"senha":{"type":"string","description":"Em parte dos municípios é a chave digital, não a senha de acesso"},"serie_rps":{"type":"string","description":"Série do RPS registrada na prefeitura"},"proximo_numero_rps":{"type":"number","description":"Número do próximo RPS a emitir","minimum":1}},"description":"Credencial do portal e numeração do RPS, na NFS-e municipal"},"responsavel":{"type":"object","properties":{"nome":{"type":"string"},"cpf":{"type":"string"}},"description":"Guardado no cadastro; não vai para a nota"},"certificate":{"type":"object","properties":{"pfx_base64":{"type":"string","description":"Certificado A1 em base64; anda junto com password"},"password":{"type":"string"}},"required":["pfx_base64","password"],"description":"Sem certificado a prefeitura normalmente recusa a empresa"}},"required":["codigo_tributacao_nacional_iss","tributacao_iss","tipo_retencao_iss","situacao_tributaria_pis_cofins","aliquota_pis","aliquota_cofins","percentual_total_tributos_simples_nacional","prestador"]},"example":{"config_name":"Matriz","enabled":true,"razao_social":"EMPRESA EXEMPLO LTDA","invoiceTiming":"IMMEDIATE","daysAfterConfirmation":1,"tipo_nf":"nacional","descricao_servico":"Prestação de Serviços","enviar_email_destinatario":true,"codigo_tributacao_nacional_iss":"010701","tributacao_iss":1,"tipo_retencao_iss":1,"serie_dps":"1","situacao_tributaria_pis_cofins":"01","aliquota_pis":0.65,"aliquota_cofins":3,"aliquota_csll":0,"aliquota_irrf":0,"tipo_retencao_pis_cofins":0,"percentual_total_tributos_federais":5.65,"percentual_total_tributos_estaduais":0,"percentual_total_tributos_municipais":2,"percentual_total_tributos_simples_nacional":6,"regime_tributario_simples_nacional":1,"item_lista_servico":"07.02","aliquota_iss":2,"iss_retido":false,"natureza_operacao":"1","codigo_cnae":"6201500","codigo_tributario_municipio":"620150001","prestador":{"cnpj":"99988877000108","inscricao_municipal":"1234567","inscricao_estadual":"","nome_fantasia":"EMPRESA EXEMPLO LTDA","email":"fiscal@exemplo.com.br","telefone":"5548999999999","codigo_municipio":"4205407","codigo_municipio_prestacao":"4205407","codigo_opcao_simples_nacional":1,"regime_especial_tributacao":0,"endereco":{"logradouro":"RUA DAS PALMEIRAS","numero":"110","complemento":"","bairro":"CENTRO","municipio":"Florianópolis","cep":"88010000","uf":"SC"}},"prefeitura":{"login":"usuario-do-portal","senha":"chave-ou-senha-do-portal","serie_rps":"1","proximo_numero_rps":1},"responsavel":{"nome":"Maria Souza","cpf":"11144477735"},"certificate":{"pfx_base64":"MIIQ…","password":"senha-do-certificado"}}}}},"security":[{"oauth2":["nota.fiscal/write"]}]}},"/v1/invoices/notas/config/{configid}":{"get":{"operationId":"get-consultar-configuracao-fiscal","summary":"Consultar Configuração Fiscal","tags":["Notas Fiscais"],"parameters":[{"name":"configid","in":"path","required":true,"description":"Configid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"config_name":{"type":"string"},"enabled":{"type":"boolean"},"invoiceTiming":{"type":"string"},"codigo_tributacao_nacional_iss":{"type":"string"},"tributacao_iss":{"type":"number"},"tipo_retencao_iss":{"type":"number"},"serie_dps":{"type":"string"},"descricao_servico":{"type":"string"},"prestador":{"type":"object","properties":{"cnpj":{"type":"string"},"nome_fantasia":{"type":"string"},"inscricao_municipal":{"type":"string"},"codigo_municipio":{"type":"string"},"codigo_municipio_prestacao":{"type":"string"},"codigo_opcao_simples_nacional":{"type":"number"},"regime_especial_tributacao":{"type":"number"}}},"prefeitura":{"type":"object","properties":{"login":{"type":"string"},"has_senha":{"type":"boolean"},"serie_rps":{"type":"string"},"proximo_numero_rps":{"type":"number"}}},"certificate":{"type":"object","properties":{"has_certificate":{"type":"boolean"},"expiry_date":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"example":{"id":"unc_1788193720141_65g0zh12p","accountId":"460851686","config_name":"Matriz","enabled":true,"invoiceTiming":"IMMEDIATE","codigo_tributacao_nacional_iss":"010701","tributacao_iss":1,"tipo_retencao_iss":1,"serie_dps":"1","descricao_servico":"Prestação de Serviços","prestador":{"cnpj":"99988877000108","nome_fantasia":"EMPRESA EXEMPLO LTDA","inscricao_municipal":"1234567","codigo_municipio":"4205407","codigo_municipio_prestacao":"4205407","codigo_opcao_simples_nacional":1,"regime_especial_tributacao":0},"prefeitura":{"login":"usuario-do-portal","has_senha":true,"serie_rps":"1","proximo_numero_rps":145},"certificate":{"has_certificate":true,"expiry_date":"2026-11-18T11:01:15.000Z"},"createdAt":"2026-08-31T16:28:43.167Z","updatedAt":"2026-08-31T16:28:43.167Z"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`ACCOUNT_NOT_FOUND` — Conta não encontrada para as credenciais informadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Retorna uma configuração fiscal pelo `id`.\n\nSegredos nunca são devolvidos: a senha do certificado e a senha da prefeitura ficam de fora. `certificate.expiry_date` traz o vencimento do certificado, e `prefeitura.has_senha` diz se há credencial gravada.\n\nConfiguração inexistente ou de outra conta responde `{}`, e não 404.\n\nCase de uso:\n\n_Como plataforma, quero conferir a validade do certificado de uma empresa antes que ela pare de emitir._","security":[{"oauth2":["nota.fiscal/read"]}]},"put":{"operationId":"put-atualizar-configuracao-fiscal","summary":"Atualizar Configuração Fiscal","tags":["Notas Fiscais"],"parameters":[{"name":"configid","in":"path","required":true,"description":"Configid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"config_name":{"type":"string"},"enabled":{"type":"boolean"},"invoiceTiming":{"type":"string"},"codigo_tributacao_nacional_iss":{"type":"string"},"tributacao_iss":{"type":"number"},"tipo_retencao_iss":{"type":"number"},"serie_dps":{"type":"string"},"descricao_servico":{"type":"string"},"prestador":{"type":"object","properties":{"cnpj":{"type":"string"},"nome_fantasia":{"type":"string"},"inscricao_municipal":{"type":"string"},"codigo_municipio":{"type":"string"},"codigo_municipio_prestacao":{"type":"string"},"codigo_opcao_simples_nacional":{"type":"number"},"regime_especial_tributacao":{"type":"number"}}},"prefeitura":{"type":"object","properties":{"login":{"type":"string"},"has_senha":{"type":"boolean"},"serie_rps":{"type":"string"},"proximo_numero_rps":{"type":"number"}}},"certificate":{"type":"object","properties":{"has_certificate":{"type":"boolean"},"expiry_date":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"example":{"id":"unc_1788193720141_65g0zh12p","accountId":"460851686","config_name":"Matriz","enabled":true,"invoiceTiming":"IMMEDIATE","codigo_tributacao_nacional_iss":"010701","tributacao_iss":1,"tipo_retencao_iss":1,"serie_dps":"1","descricao_servico":"Prestação de Serviços","prestador":{"cnpj":"99988877000108","nome_fantasia":"EMPRESA EXEMPLO LTDA","inscricao_municipal":"1234567","codigo_municipio":"4205407","codigo_municipio_prestacao":"4205407","codigo_opcao_simples_nacional":1,"regime_especial_tributacao":0},"prefeitura":{"login":"usuario-do-portal","has_senha":true,"serie_rps":"1","proximo_numero_rps":145},"certificate":{"has_certificate":true,"expiry_date":"2026-11-18T11:01:15.000Z"},"createdAt":"2026-08-31T16:28:43.167Z","updatedAt":"2026-08-31T16:28:43.167Z"}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Configuração não encontrada","code":"NOTA_CONFIG_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Atualiza uma configuração fiscal. Envie apenas os campos que mudam — os demais são preservados.\n\n> ⚠️ **Atenção:** o merge é por campo do primeiro nível, não por campo aninhado. Enviar `prestador` com dois campos substitui o objeto `prestador` inteiro, apagando o que não veio. O mesmo vale para `endereco` e `certificate`: monte o objeto completo antes de enviar.\n\n`prefeitura` é a exceção: os campos enviados são mesclados com os já gravados, então dá para alterar só a série do RPS sem reenviar a senha.\n\nEnviar `null` em um campo o remove da configuração.\n\n`certificate` com `pfx_base64` e `password` substitui o certificado e revalida a empresa emissora; o certificado anterior é apagado, a menos que outra configuração da conta use o mesmo arquivo.\n\nQualquer alteração revalida a empresa emissora. Se essa etapa falhar, nada é gravado.\n\nCase de uso:\n\n_Como plataforma, quero trocar o certificado digital antes do vencimento, sem recriar a configuração._","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"config_name":{"type":"string"},"enabled":{"type":"boolean","description":"false desliga a emissão sem apagar a configuração"},"invoiceTiming":{"type":"string","description":"Momento da emissão nas notas geradas por cobrança","enum":["IMMEDIATE","AFTER_CONFIRMATION","DAYS_AFTER_CONFIRMATION"]},"daysAfterConfirmation":{"type":"number","description":"Só com invoiceTiming DAYS_AFTER_CONFIRMATION","minimum":1},"descricao_servico":{"type":"string"},"codigo_tributacao_nacional_iss":{"type":"string"},"tributacao_iss":{"type":"number"},"tipo_retencao_iss":{"type":"number"},"aliquota_iss":{"type":"number","description":"NFS-e municipal"},"item_lista_servico":{"type":"string","description":"NFS-e municipal"},"serie_dps":{"type":"string","description":"NFS-en: série da DPS"},"prefeitura":{"type":"object","properties":{"login":{"type":"string"},"senha":{"type":"string","description":"Só quando a credencial muda"},"serie_rps":{"type":"string","description":"Série do RPS registrada na prefeitura"},"proximo_numero_rps":{"type":"number","description":"Número do próximo RPS a emitir","minimum":1}},"description":"Mesclado com o que já está gravado; envie só o que muda"},"certificate":{"type":"object","properties":{"pfx_base64":{"type":"string"},"password":{"type":"string"}},"required":["pfx_base64","password"],"description":"Só para substituir o certificado"}}},"example":{"config_name":"Matriz","enabled":true,"invoiceTiming":"AFTER_CONFIRMATION","daysAfterConfirmation":3,"descricao_servico":"Consultoria em tecnologia da informação","codigo_tributacao_nacional_iss":"010701","tributacao_iss":1,"tipo_retencao_iss":1,"aliquota_iss":2,"item_lista_servico":"07.02","serie_dps":"1","prefeitura":{"login":"usuario-do-portal","senha":"chave-ou-senha-do-portal","serie_rps":"1","proximo_numero_rps":145},"certificate":{"pfx_base64":"MIIQ…","password":"senha-do-certificado"}}}}},"security":[{"oauth2":["nota.fiscal/write"]}]},"delete":{"operationId":"delete-excluir-configuracao-fiscal","summary":"Excluir Configuração Fiscal","tags":["Notas Fiscais"],"parameters":[{"name":"configid","in":"path","required":true,"description":"Configid","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}},"401":{"description":"`UNAUTHORIZED` — Token ausente, expirado ou sem o scope necessário","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Configuração não encontrada","code":"NOTA_CONFIG_NOT_FOUND","details":null,"timestamp":"2026-07-14T21:39:36.322Z"}}}}}},"description":"Remove uma configuração fiscal da conta.\n\nA exclusão vale para a plataforma. As notas já emitidas por ela não são afetadas.\n\nCase de uso:\n\n_Como plataforma, quero remover a configuração de uma empresa que deixou de operar._","security":[{"oauth2":["nota.fiscal/write"]}]}}},"webhooks":{"subscription.created":{"post":{"operationId":"webhook-subscription-created","summary":"Assinatura criada, aguardando primeiro pagamento.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{"plan":{"type":"string"},"checkoutSessionId":{"type":"string"}}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"coupon":{"type":"object","properties":{"code":{"type":"string"}}}}},"example":{"event":"subscription.created","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"PENDING","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":1,"metadata":{"plan":"PREMIUM","checkoutSessionId":"pa_mstiv3jy_b012bc"},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"PENDING","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":null,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"coupon":{"code":"PRIMEIRO999"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.trial":{"post":{"operationId":"webhook-subscription-trial","summary":"Assinatura entrou em período de teste. Não carrega objeto `trial`: o prazo está em `items[].price.trialDays`.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{"type":"number"}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.trial","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"TRIALING","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":0,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"TRIALING","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":7},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":null,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.activated":{"post":{"operationId":"webhook-subscription-activated","summary":"Assinatura ativada após confirmação de pagamento.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.activated","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":1,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":1,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"pix"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.renewed":{"post":{"operationId":"webhook-subscription-renewed","summary":"Ciclo renovado e pago. Quando emitido pelo motor de cobrança, acrescenta os campos do próximo ciclo.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"nextCycleChargeDate":{"type":"string","format":"date-time"},"nextCycleAmount":{"type":"number"}}},"example":{"event":"subscription.renewed","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"nextCycleChargeDate":"2026-09-10T14:45:05.953Z","nextCycleAmount":89.9}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.upgraded":{"post":{"operationId":"webhook-subscription-upgraded","summary":"Plano da assinatura alterado para cima.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.upgraded","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.item_added":{"post":{"operationId":"webhook-subscription-item-added","summary":"Novo item adicionado à assinatura.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.item_added","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.item_removed":{"post":{"operationId":"webhook-subscription-item-removed","summary":"Item removido da assinatura.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.item_removed","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.downgrade_scheduled":{"post":{"operationId":"webhook-subscription-downgrade-scheduled","summary":"Downgrade agendado para o fim do ciclo.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.downgrade_scheduled","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.canceled":{"post":{"operationId":"webhook-subscription-canceled","summary":"Assinatura cancelada. O ciclo corrente continua no payload, com o status em que ficou.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"cancelReason":{"type":"string"}}},"example":{"event":"subscription.canceled","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"CANCELED","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":"2026-08-14T21:05:54.399Z","items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":1,"amount":199.9,"status":"CANCELED","chargeDate":"2026-08-14T20:58:39.833Z","paidAt":null,"paymentMethod":"pix_automatico"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"cancelReason":"Cancelamento solicitado pelo administrador."}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.expired":{"post":{"operationId":"webhook-subscription-expired","summary":"Assinatura expirada. O evento é assinável e o caminho de envio existe no backend; confirme com o time se algum fluxo já o dispara.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"subscription.expired","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"EXPIRED","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":null,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"subscription.cancel_scheduled":{"post":{"operationId":"webhook-subscription-cancel-scheduled","summary":"Cancelamento agendado; assinatura segue ativa até o fim do ciclo.","tags":["Webhooks · Assinaturas"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"cancelAtPeriodEnd":{"type":"boolean"},"cancelRequestedAt":{"type":"string","format":"date-time"},"effectiveAt":{"type":"string","format":"date-time"},"cancelReason":{"type":"string"}}},"example":{"event":"subscription.cancel_scheduled","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"cancelAtPeriodEnd":true,"cancelRequestedAt":"2026-08-03T18:25:09.025Z","effectiveAt":"2026-09-03T18:25:09.025Z","cancelReason":"Solicitado pelo cliente"}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"payment.success":{"post":{"operationId":"webhook-payment-success","summary":"Pagamento confirmado. O payload difere entre cobrança avulsa via Pix direto e cobrança vinculada a uma assinatura.","tags":["Webhooks · Pagamentos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"Cobrança avulsa (Pix direto)","type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"chargeId":{"type":"string"},"amount":{"type":"number"},"paymentMethod":{"type":"string"},"paymentId":{"type":"string"},"paidAt":{"type":"string","format":"date-time"},"metadata":{"type":"object","properties":{"orderId":{"type":"string"}}},"payer":{"type":"object","properties":{"name":{"type":"string"},"taxId":{"type":"string"},"bank":{"type":"string"},"account":{"type":"string"},"branch":{"type":"string"},"accountType":{"type":"string"}}}}},{"title":"Assinatura ou checkout (cobrança com subscriptionId)","type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"chargeId":{"type":"string"},"invoiceId":{"type":"string"}}}]},"examples":{"cobranca-avulsa-pix-direto":{"summary":"Cobrança avulsa (Pix direto)","value":{"event":"payment.success","timestamp":"2026-09-05T12:00:00.000Z","accountId":"4231833","chargeId":"cha_1771511282731_9p1wo3tql","amount":10.5,"paymentMethod":"PIX","paymentId":"E13935893202609051200s0290d93572","paidAt":"2026-09-05T12:00:00.000Z","metadata":{"orderId":"pedido-1001"},"payer":{"name":"João da Silva","taxId":"12345678901","bank":"13935893","account":"410900056","branch":"0001","accountType":"CACC"}}},"assinatura-ou-checkout-cobranca-com-subscriptionid":{"summary":"Assinatura ou checkout (cobrança com subscriptionId)","value":{"event":"payment.success","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"ACTIVE","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"chargeId":"cha_1788634613625_dd5fgel3q","invoiceId":"inv_1788634612997_b6qfdvb4z"}}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"payment.overdue":{"post":{"operationId":"webhook-payment-overdue","summary":"Ciclo vencido sem pagamento. A assinatura passa a `DEFAULT` quando estava `ACTIVE`, ou a `PAST_DUE` quando estava `PENDING` ou `TRIALING`.","tags":["Webhooks · Pagamentos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}},"example":{"event":"payment.overdue","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"DEFAULT","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"FAILED","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":null,"paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"charge.expired":{"post":{"operationId":"webhook-charge-expired","summary":"Cobrança expirou sem pagamento. Só ocorre a partir de PENDING, PROCESSING ou AWAITING_PAYMENT; o `status` no payload é o da COBRANÇA.","tags":["Webhooks · Pagamentos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"Cobrança avulsa","type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"chargeId":{"type":"string"},"invoiceId":{},"subscriptionId":{},"customerId":{},"amount":{"type":"number"},"paymentType":{"type":"string"},"status":{"type":"string"},"dueDate":{},"expiresAt":{"type":"string","format":"date-time"},"expiredAt":{"type":"string","format":"date-time"},"productName":{}}},{"title":"Cobrança de assinatura","type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{"type":"object","properties":{}},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{"type":"object","properties":{"cycleNumber":{"type":"number"},"amount":{"type":"number"},"status":{"type":"string"},"chargeDate":{"type":"string","format":"date-time"},"paidAt":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"}}},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"chargeId":{"type":"string"},"invoiceId":{"type":"string"},"amount":{"type":"number"},"paymentType":{"type":"string"},"dueDate":{"type":"string","format":"date"},"expiresAt":{"type":"string","format":"date-time"},"expiredAt":{"type":"string","format":"date-time"},"productName":{"type":"string"}}}]},"examples":{"cobranca-avulsa":{"summary":"Cobrança avulsa","value":{"event":"charge.expired","timestamp":"2026-08-21T00:05:12.031Z","accountId":"4231833","chargeId":"cha_1771511282731_9p1wo3tql","invoiceId":null,"subscriptionId":null,"customerId":null,"amount":10.5,"paymentType":"PIX","status":"EXPIRED","dueDate":null,"expiresAt":"2026-09-05T23:59:59.000Z","expiredAt":"2026-09-06T00:05:12.031Z","productName":null}},"cobranca-de-assinatura":{"summary":"Cobrança de assinatura","value":{"event":"charge.expired","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"EXPIRED","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":3,"metadata":{},"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":{"cycleNumber":3,"amount":89.9,"status":"PAID","chargeDate":"2026-08-10T14:45:05.953Z","paidAt":"2026-08-10T14:45:05.953Z","paymentMethod":"creditcard"},"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"chargeId":"cha_1788634613625_dd5fgel3q","invoiceId":"inv_1788634612997_b6qfdvb4z","amount":89.9,"paymentType":"PIX","dueDate":"2026-08-20","expiresAt":"2026-08-20T23:59:59.000Z","expiredAt":"2026-08-21T00:05:12.031Z","productName":"Belary Premium"}}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"payment.failed":{"post":{"operationId":"webhook-payment-failed","summary":"Tentativa de pagamento falhou. Schema próprio: não carrega a base de assinatura e usa `accountId`.","tags":["Webhooks · Pagamentos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"customerId":{},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"cellphone":{},"item":{},"metadata":{},"failed":{"type":"string"}}},"example":{"event":"payment.failed","timestamp":"2026-06-20T00:09:17.334Z","accountId":"4231833","customerId":null,"name":"João da Silva","email":"joao@example.com","taxId":"11144477735","cellphone":null,"item":null,"metadata":null,"failed":"Pagamento não autorizado"}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"charge.created":{"post":{"operationId":"webhook-charge-created","summary":"Cobrança gerada. Traz a base da assinatura mais os dados da cobrança — atenção: `status` aqui é o status da COBRANÇA.","tags":["Webhooks · Pagamentos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountNumber":{"type":"string"},"subscriptionId":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"interval":{"type":"string"},"currentCycleNumber":{"type":"number"},"metadata":{},"startDate":{"type":"string","format":"date-time"},"canceledAt":{},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"name":{"type":"string"},"description":{},"type":{"type":"string"},"amount":{"type":"number"},"quantity":{"type":"number"},"discount":{"type":"number"},"status":{"type":"string"},"price":{"type":"object","properties":{"priceId":{"type":"string"},"amount":{"type":"number"},"title":{"type":"string"},"recurrenceType":{"type":"string"},"trialDays":{}}},"product":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}}}}}},"currentCycle":{},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"chargeId":{"type":"string"},"invoiceId":{"type":"string"},"transactionId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"paymentType":{"type":"string"},"type":{"type":"string"},"pixCollectionType":{"type":"string"},"emvQrCode":{"type":"string"},"dueDate":{"type":"string","format":"date-time"}}},"example":{"event":"charge.created","timestamp":"2026-08-14T22:31:59.869Z","accountNumber":"4231833","subscriptionId":"sub_1786746719522_a8h3r7tix","customerId":"cus_1786746719497_9px4bs9dh","status":"PENDING","email":"lucas@example.com","taxId":"12354358903","interval":"MONTHLY","currentCycleNumber":1,"metadata":null,"startDate":"2026-08-14T22:31:59.522Z","canceledAt":null,"items":[{"itemId":"item_1786746719640_j4ekjyjgd","name":"Belary Premium","description":null,"type":"RECURRING","amount":89.9,"quantity":1,"discount":0,"status":"ACTIVE","price":{"priceId":"price_1786738209146_15vvse7x6","amount":89.9,"title":"Mensal","recurrenceType":"MONTHLY","trialDays":null},"product":{"productId":"prod_1786738209087_fhwxkyp6b","name":"Belary Premium","type":"RECURRING"}}],"currentCycle":null,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"chargeId":"cha_1788634613625_dd5fgel3q","invoiceId":"inv_1788634612997_b6qfdvb4z","transactionId":"3080767385","amount":10.5,"currency":"BRL","paymentType":"PIX","type":"ONE_TIME_ITEM","pixCollectionType":"COBV","emvQrCode":"00020101021226960014br.gov.bcb.pix…","dueDate":"2026-10-05T00:00:00Z"}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"refund.requested":{"post":{"operationId":"webhook-refund-requested","summary":"Devolução registrada e em processamento.","tags":["Webhooks · Devoluções"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"title":"Devolução de Pix","type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"refundId":{"type":"string"},"chargeId":{"type":"string"},"endToEndId":{"type":"string"},"amount":{"type":"number"},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"reason":{"type":"string"},"status":{"type":"string"}}},{"title":"Estorno de cartão","type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"refundId":{"type":"string"},"chargeId":{"type":"string"},"amount":{"type":"number"},"reason":{"type":"string"},"status":{"type":"string"},"paymentType":{"type":"string"},"providerChargeId":{"type":"string"},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}}}}]},"examples":{"devolucao-de-pix":{"summary":"Devolução de Pix","value":{"event":"refund.requested","timestamp":"2026-08-14T22:33:58.728Z","accountId":"4231833","refundId":"ref_1786746837248_gsoosg37y","chargeId":"cha_1786746721295_f7y0qtzpz","endToEndId":"E18236120202608142232s0290d93572","amount":9.99,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"reason":"CUSTOMER_REQUEST","status":"PROCESSING"}},"estorno-de-cartao":{"summary":"Estorno de cartão","value":{"event":"refund.requested","timestamp":"2026-08-14T22:33:58.728Z","accountId":"4231833","refundId":"ref_1786746837248_gsoosg37y","chargeId":"cha_1786746721295_f7y0qtzpz","amount":9.99,"reason":"CUSTOMER_REQUEST","status":"PROCESSING","paymentType":"CREDIT_CARD","providerChargeId":"ch_01JQ8R4M2K","customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"}}}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"refund.confirmed":{"post":{"operationId":"webhook-refund-confirmed","summary":"Valor devolvido ao pagador.","tags":["Webhooks · Devoluções"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"refundId":{"type":"string"},"chargeId":{"type":"string"},"endToEndId":{"type":"string"},"amount":{"type":"number"},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"returnIdentification":{"type":"string"},"status":{"type":"string"},"splitReversals":{"type":"array","items":{"type":"object","properties":{"accountNumber":{"type":"string"},"amount":{"type":"number"},"status":{"type":"string"},"debtId":{"type":"string"}}}}}},"example":{"event":"refund.confirmed","timestamp":"2026-08-14T22:33:58.728Z","accountId":"4231833","refundId":"ref_1786746837248_gsoosg37y","chargeId":"cha_1786746721295_f7y0qtzpz","endToEndId":"E18236120202608142232s0290d93572","amount":9.99,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"returnIdentification":"D13935893202608142233X967RIOG07L","status":"CONFIRMED","splitReversals":[{"accountNumber":"429131213","amount":2,"status":"REVERSED"},{"accountNumber":"429131214","amount":1,"status":"PENDING","debtId":"sdb_1786746837_x9k2"}]}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"refund.failed":{"post":{"operationId":"webhook-refund-failed","summary":"Devolução recusada ou falhou. O status enviado é `ERROR`.","tags":["Webhooks · Devoluções"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"refundId":{"type":"string"},"chargeId":{"type":"string"},"endToEndId":{"type":"string"},"amount":{"type":"number"},"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"taxId":{"type":"string"},"phone":{"type":"string"}}},"returnIdentification":{"type":"string"},"status":{"type":"string"},"error":{"type":"string"}}},"example":{"event":"refund.failed","timestamp":"2026-08-14T22:33:58.728Z","accountId":"4231833","refundId":"ref_1786746837248_gsoosg37y","chargeId":"cha_1786746721295_f7y0qtzpz","endToEndId":"E18236120202608142232s0290d93572","amount":9.99,"customer":{"customerId":"cus_1786746719497_9px4bs9dh","name":"Lucas Ferreira Valente","email":"lucas@example.com","taxId":"12354358903","phone":"4197424445"},"returnIdentification":"D13935893202608252206s2DvmooTPb2","status":"ERROR","error":"ERROR"}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"onboarding.create":{"post":{"operationId":"webhook-onboarding-create","summary":"Conta da subconta criada.","tags":["Webhooks · Onboarding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"data":{"type":"object","properties":{"formId":{"type":"string","format":"uuid"},"proposalId":{"type":"string","format":"uuid"},"documentNumber":{"type":"string"},"status":{"type":"string"},"account":{"type":"object","properties":{"number":{"type":"string"},"branch":{"type":"string"},"name":{"type":"string"}}}}}}},"example":{"event":"onboarding.create","timestamp":"2026-08-24T22:00:54.470Z","accountId":"4231833","data":{"formId":"03712fd1-bf57-403e-a278-76ca70b2ed1a","proposalId":"c8d1f2a5-871f-46f2-8f98-dd55641ac225","documentNumber":"12354372990","status":"CONFIRMED","account":{"number":"483918595","branch":"0001","name":"Guilherme Ferreira Valente"}}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"onboarding.backgroundcheck":{"post":{"operationId":"webhook-onboarding-backgroundcheck","summary":"Análise de background concluída.","tags":["Webhooks · Onboarding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"data":{"type":"object","properties":{"formId":{"type":"string","format":"uuid"},"proposalId":{"type":"string","format":"uuid"},"documentNumber":{"type":"string"},"proposalType":{"type":"string"},"status":{"type":"string"}}}}},"example":{"event":"onboarding.backgroundcheck","timestamp":"2026-08-24T22:00:54.470Z","accountId":"4231833","data":{"formId":"1fc0f2e7-5fe0-4716-a1a2-e3cb31b94035","proposalId":"8ff8f785-a81d-48a5-a7de-6717c4beb099","documentNumber":"67624185000186","proposalType":"PJ","status":"APPROVED"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"onboarding.documentscopy":{"post":{"operationId":"webhook-onboarding-documentscopy","summary":"Etapa de documentoscopia atualizada.","tags":["Webhooks · Onboarding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"data":{"type":"object","properties":{"formId":{"type":"string","format":"uuid"},"proposalId":{"type":"string","format":"uuid"},"documentNumber":{"type":"string"},"proposalType":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}}}}},"example":{"event":"onboarding.documentscopy","timestamp":"2026-08-24T22:00:54.470Z","accountId":"4231833","data":{"formId":"1fc0f2e7-5fe0-4716-a1a2-e3cb31b94035","proposalId":"8ff8f785-a81d-48a5-a7de-6717c4beb099","documentNumber":"67624185000186","proposalType":"PJ","status":"PENDING","url":"https://…/153ece225709906db8c3656b91536f22"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"onboarding.proposal":{"post":{"operationId":"webhook-onboarding-proposal","summary":"Status final da proposta.","tags":["Webhooks · Onboarding"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"data":{"type":"object","properties":{"formId":{"type":"string","format":"uuid"},"proposalId":{"type":"string","format":"uuid"},"documentNumber":{"type":"string"},"proposalType":{"type":"string"},"status":{"type":"string"}}}}},"example":{"event":"onboarding.proposal","timestamp":"2026-08-24T22:00:54.470Z","accountId":"4231833","data":{"formId":"1fc0f2e7-5fe0-4716-a1a2-e3cb31b94035","proposalId":"8ff8f785-a81d-48a5-a7de-6717c4beb099","documentNumber":"67624185000186","proposalType":"PJ","status":"APPROVED"}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"med.infraction.updated":{"post":{"operationId":"webhook-med-infraction-updated","summary":"Infração do MED atualizada.","tags":["Webhooks · MED"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"caseId":{"type":"string"},"infractionId":{"type":"string","format":"uuid"},"originalEndToEndId":{"type":"string"},"status":{"type":"string"},"analysisResult":{},"chargeId":{"type":"string"}}},"example":{"event":"med.infraction.updated","timestamp":"2026-07-03T18:25:09.025Z","accountId":"4231833","caseId":"med_1786746837248_gsoosg37y","infractionId":"3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f","originalEndToEndId":"E18236120202608142232s0290d93572","status":"ACKNOWLEDGED","analysisResult":null,"chargeId":"cha_1786746721295_f7y0qtzpz"}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"med.balance.blocked":{"post":{"operationId":"webhook-med-balance-blocked","summary":"Saldo bloqueado por ordem do MED.","tags":["Webhooks · MED"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"caseId":{"type":"string"},"blockId":{"type":"string","format":"uuid"},"infractionId":{"type":"string","format":"uuid"},"originalEndToEndId":{"type":"string"},"blockedAmount":{"type":"number"},"blockStatus":{"type":"string"},"balanceAfter":{"type":"number"},"blockedBalanceAfter":{"type":"number"}}},"example":{"event":"med.balance.blocked","timestamp":"2026-07-03T18:25:09.025Z","accountId":"4231833","caseId":"med_1786746837248_gsoosg37y","blockId":"b4b0c9de-2f18-4a55-9f31-7c0d9a1e2b34","infractionId":"3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f","originalEndToEndId":"E18236120202608142232s0290d93572","blockedAmount":150,"blockStatus":"BLOCKED","balanceAfter":320.55,"blockedBalanceAfter":150}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"med.balance.unblocked":{"post":{"operationId":"webhook-med-balance-unblocked","summary":"Saldo desbloqueado.","tags":["Webhooks · MED"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"caseId":{"type":"string"},"blockId":{"type":"string","format":"uuid"},"infractionId":{"type":"string","format":"uuid"},"originalEndToEndId":{"type":"string"},"unblockedAmount":{"type":"number"},"balanceAfter":{"type":"number"},"blockedBalanceAfter":{"type":"number"}}},"example":{"event":"med.balance.unblocked","timestamp":"2026-07-03T18:25:09.025Z","accountId":"4231833","caseId":"med_1786746837248_gsoosg37y","blockId":"b4b0c9de-2f18-4a55-9f31-7c0d9a1e2b34","infractionId":"3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f","originalEndToEndId":"E18236120202608142232s0290d93572","unblockedAmount":150,"balanceAfter":470.55,"blockedBalanceAfter":0}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"med.refund.opened":{"post":{"operationId":"webhook-med-refund-opened","summary":"Processo de devolução do MED aberto.","tags":["Webhooks · MED"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"caseId":{"type":"string"},"medRefundId":{"type":"string","format":"uuid"},"originalEndToEndId":{"type":"string"},"refundAmount":{"type":"number"}}},"example":{"event":"med.refund.opened","timestamp":"2026-07-03T18:25:09.025Z","accountId":"4231833","caseId":"med_1786746837248_gsoosg37y","medRefundId":"9a7f2c31-8d64-4b0e-a512-6c3d8e9f0a1b","originalEndToEndId":"E18236120202608142232s0290d93572","refundAmount":150}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}},"med.refund.closed":{"post":{"operationId":"webhook-med-refund-closed","summary":"Processo de devolução do MED encerrado.","tags":["Webhooks · MED"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"caseId":{"type":"string"},"medRefundId":{"type":"string","format":"uuid"},"originalEndToEndId":{"type":"string"},"refundAmount":{"type":"number"},"analysisResult":{"type":"string"},"returnIdentification":{"type":"string"},"chargeId":{"type":"string"},"balanceResult":{"type":"object","properties":{"balanceAfter":{"type":"number"},"blockedBalanceAfter":{"type":"number"}}}}},"example":{"event":"med.refund.closed","timestamp":"2026-07-03T18:25:09.025Z","accountId":"4231833","caseId":"med_1786746837248_gsoosg37y","medRefundId":"9a7f2c31-8d64-4b0e-a512-6c3d8e9f0a1b","originalEndToEndId":"E18236120202608142232s0290d93572","refundAmount":150,"analysisResult":"TOTALLY_ACCEPTED","returnIdentification":"D13935893202608142233X967RIOG07L","chargeId":"cha_1786746721295_f7y0qtzpz","balanceResult":{"balanceAfter":320.55,"blockedBalanceAfter":0}}}}},"responses":{"200":{"description":"Evento recebido. Responda 200 rapidamente e processe de forma assíncrona."}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2 client credentials. Solicite apenas os scopes necessários.","flows":{"clientCredentials":{"tokenUrl":"https://oauth2.validapay.com.br/auth/token","refreshUrl":"https://oauth2.validapay.com.br/auth/token","scopes":{"pix.cob/read":"Consultar cobranças Pix","pix.cob/write":"Criar cobranças Pix imediatas","proposals/write":"Enviar propostas de onboarding de subcontas","subaccounts/read":"Listar subcontas e suas cobranças","wallet/read":"Consultar saldo e extrato","products/write":"Criar e alterar produtos e preços","products/read":"Consultar produtos e preços","checkouts/write":"Criar links, sessões e cobranças de checkout","checkouts/read":"Consultar links e sessões de checkout","wallet/write":"Saques, devoluções e simulação de pagamento em sandbox","customers/write":"Criar e alterar clientes","customers/read":"Consultar clientes","customers/delete":"Remover clientes","subscriptions/read":"Consultar assinaturas","subscriptions/write":"Alterar assinaturas existentes","nota.fiscal/read":"Consultar notas fiscais e configurações","nota.fiscal/write":"Emitir, cancelar e reenviar notas fiscais"}}}}},"schemas":{"Error":{"type":"object","description":"Formato de erro com envelope, usado em cobranças, devoluções e carteira.","properties":{"error":{"type":"object","additionalProperties":true,"properties":{"message":{"type":"string","description":"Mensagem legível do erro"},"code":{"type":"string","description":"Código estável do erro, ex.: DUPLICATE_CHARGE"},"details":{"description":"Dados adicionais do erro"},"timestamp":{"type":"string","format":"date-time"}},"required":["message","code"]}},"required":["error"]},"SimpleError":{"type":"object","description":"Formato de erro plano, usado em produtos, checkouts e clientes.","additionalProperties":true,"properties":{"code":{"type":"string","description":"Código estável do erro"},"message":{"type":"string","description":"Mensagem legível do erro"}},"required":["code"]},"OAuthError":{"type":"object","description":"Erro no formato OAuth2 (RFC 6749): o campo error é uma string.","properties":{"error":{"type":"string"}},"required":["error"]},"CardDeclined":{"type":"object","description":"Recusa de cartão. O campo error é a razão da falha, em texto.","properties":{"success":{"type":"boolean"},"chargeId":{"type":"string"},"status":{"type":"string"},"error":{"type":"string","description":"failureReason retornado pelo adquirente"}},"required":["success"]}}}}