{"openapi":"3.1.0","info":{"title":"API Bumcash","description":"# API Bumcash\n\nPlataforma B2B2C de fidelidade e moeda digital. Use esta API para creditar moeda Bumcash (BMC) ao cliente, registrar cashback de vendas no PDV, notificar pagamentos de contas recorrentes, e consultar seus extratos e ganhos na rede.\n\n> 📘 **Comece pela documentação para integradores:** [docs.bumcash.com.br](https://docs.bumcash.com.br) tem trilhas guiadas por modelo de negócio (recorrência, varejo PDV, híbrido), receitas copy-paste e a referência completa dos códigos de erro. Esta página é a referência técnica dos endpoints; os guias de integração vivem lá.\n\nA API atende **dois perfis**: empresas que estão na rede como **lojistas** (chaves `mch_`) e **integradores certificados** que operam para múltiplos lojistas (chaves `ptr_`).\n\n## Autenticação\n\nTodos os endpoints (exceto `POST /v1/register/*`) requerem uma chave Bearer no header `Authorization`:\n\n```\nAuthorization: Bearer bmc_live_mch_xxxxxxxxxxxx\n```\n\n### Tipos de Chave\n\n| Prefixo | Ambiente | Tipo |\n|---------|----------|------|\n| `bmc_live_ptr_` | Produção | Partner — integrador multi-lojista |\n| `bmc_test_ptr_` | Sandbox | Partner — ambiente de testes |\n| `bmc_live_mch_` | Produção | Merchant — lojista direto |\n| `bmc_test_mch_` | Sandbox | Merchant — ambiente de testes |\n\nDetalhes sobre escopos, permissões padrão por tier (recurrency/hybrid vs retail vs partner) e como solicitar habilitação: [docs.bumcash.com.br](https://docs.bumcash.com.br).\n\n## Valores Monetários\n\nA moeda interna é o **Bumcash (BMC)** com paridade fixa **1 BMC = R$ 1,00**. Todos os valores no payload usam **centavos inteiros** (R$ 1,00 = `100`, R$ 15,50 = `1550`). Nunca use float.\n\n## Idempotência\n\nToda operação de escrita aceita `idempotency_key` no body. Mesma chave + mesmo payload retorna o mesmo registro por 90 dias; mesma chave + payload diferente retorna `409 idempotency_conflict`. Detalhes e exceções em [docs.bumcash.com.br](https://docs.bumcash.com.br).\n\n## Paginação\n\nListagens usam cursor:\n\n```json\n{ \"data\": [...], \"has_more\": true, \"cursor\": \"cur_xxxxxxxxxxxx\" }\n```\n\nPasse `cursor` na query string para a próxima página.\n\n## Erros\n\nEnvelope padrão:\n\n```json\n{\n  \"error\": {\n    \"code\": \"customer_pending\",\n    \"message\": \"Mensagem em pt-BR, segura para logar.\"\n  },\n  \"request_id\": \"req_xxxxxxxxxxxx\"\n}\n```\n\n`error.code` é estável e parte do contrato — programe contra ele, não contra a mensagem. Lista completa de códigos com causa e ação recomendada: [docs.bumcash.com.br/errors](https://docs.bumcash.com.br/errors).\n\n## Sandbox\n\nSandbox é por **prefixo de chave**, não por host. Use `bmc_test_*` contra a mesma URL de produção (`https://api-v2.bumcash.com.br/v1`) e a Bumcash isola o tráfego automaticamente. Fixtures pré-cadastrados (CPFs e CNPJs de teste) e dicas de integração: [docs.bumcash.com.br](https://docs.bumcash.com.br).\n\n## Webhooks\n\nA lista canônica de eventos está em `GET /v1/webhooks/event-types`. Verificação HMAC-SHA256, política de retentativas, eventos por escopo (Partner vs Merchant) e exemplos de payload: [docs.bumcash.com.br](https://docs.bumcash.com.br).\n\n## Limites\n\nProdução: 100 req/min. Sandbox: 1.000 req/min. Header `Retry-After` em respostas 429.\n","version":"2026-03-01","contact":{"name":"Suporte API Bumcash","email":"api@bumcash.com","url":"https://docs.bumcash.com"},"license":{"name":"Proprietário"}},"externalDocs":{"description":"Documentação completa e guias","url":"https://docs.bumcash.com"},"servers":[{"url":"https://api-v2.bumcash.com.br/v1","description":"Produção (sandbox compartilha o mesmo host — use chaves bmc_test_*)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Chave de API Partner ou Merchant (formatos: bmc_live_ptr_..., bmc_live_mch_..., ou os equivalentes bmc_test_* para sandbox)."}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Créditos","description":"Operações de moeda Bumcash (BMC): emissão (mint) e resgate (burn). 1 BMC = R$ 1,00, expresso no payload como **centavos inteiros** (R$ 1,00 = 100). O saldo atualizado do cliente é retornado nas respostas de mint/burn."},{"name":"Statements","description":"Extratos de faturamento por período. Merchants e partners consultam apenas os extratos dos seus próprios locais (valor total devido por período e status do pagamento)."},{"name":"Earnings","description":"Saldo acumulado pelo merchant/partner no período — total ganho na rede Bumcash. Útil para conciliação contábil contra a sua base."},{"name":"Webhooks","description":"Gerenciamento e entrega de webhooks. Receba notificações em tempo real de eventos de créditos e clientes."}],"paths":{"/credits/mint":{"post":{"operationId":"postCreditsMint","tags":["Credits"],"summary":"Emitir BMC","description":"Cria saldo de Bumcash (BMC) na carteira de um cliente. Cria automaticamente o cliente caso ainda não exista. O valor final creditado pode ser maior do que o solicitado devido ao multiplicador de fidelidade do nível do cliente.","responses":{"201":{"description":"BMC emitido com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID da transação (ex: `txn_a1b2c3d4`)"},"type":{"type":"string","const":"MINT"},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Valor final creditado, em centavos, após aplicação do multiplicador do nível de fidelidade (ex: 1545)."},"amount_before_multiplier":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Valor base antes do multiplicador, em centavos (ex: 1500)"},"earn_multiplier":{"type":"number","exclusiveMinimum":0,"description":"Multiplicador aplicado (ex: 1.03)"},"customer_phone":{"type":"string","description":"Telefone do cliente em formato E.164"},"location_id":{"type":"string","description":"Local onde o BMC foi emitido"},"location_name":{"type":"string","description":"Nome do local"},"new_balance":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Saldo atualizado do cliente, em centavos (ex: 5045)"},"tier":{"type":"object","properties":{"name":{"type":"string","description":"Nome do nível atual (ex: `Ouro`)"},"consecutive_payments":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Quantidade de pagamentos consecutivos"},"multiplier":{"type":"number","exclusiveMinimum":0,"description":"Multiplicador do nível (ex: 1.03)"}},"required":["name","consecutive_payments","multiplier"],"description":"Nível de fidelidade do cliente após esta transação"},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","type","amount","amount_before_multiplier","earn_multiplier","customer_phone","location_id","location_name","new_balance","tier","created_at"]}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_phone":{"description":"Telefone do cliente em formato E.164 (ex: `+5511999990001`). Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":10},"customer_cpf":{"description":"CPF do cliente (11 dígitos, somente números). Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":11,"maxLength":11},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Valor base de BMC a emitir, em centavos inteiros. 1 BMC = R$ 1,00 = 100 centavos no payload (ex: 1500 = R$ 15,00)."},"location_id":{"description":"ID canônico do local Bumcash. Opcional se `cnpj` for fornecido.","type":"string"},"cnpj":{"description":"CNPJ de 14 dígitos do local. Aceita com pontuação (`12.345.678/0001-90` ou `12345678000190`). É resolvido para um `location_id` dentro do escopo da sua organização. Formato preferido para integradores Partner.","type":"string"},"reason":{"description":"Motivo da emissão (ex: `fidelidade_3%`).","type":"string"},"tag":{"description":"Tag para matching de regra de emissão (ex: `indicacao`).","type":"string"},"reference":{"description":"Referência do integrador para esta operação","type":"object","properties":{"external_id":{"description":"ID de referência externa do integrador","type":"string"},"description":{"description":"Descrição livre da operação","type":"string"}}},"idempotency_key":{"description":"Chave única para retentativa idempotente. Também aceita via header `X-Idempotency-Key`.","type":"string"}},"required":["amount"]}}}}}},"/credits/burn":{"post":{"operationId":"postCreditsBurn","tags":["Credits"],"summary":"Resgatar BMC","description":"Resgata (debita) BMC da carteira de um cliente. Usado quando o cliente troca seu saldo por um desconto, produto ou outra recompensa. Retorna o erro `insufficient_balance` se o cliente não tiver saldo suficiente.","responses":{"201":{"description":"BMC resgatado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID da transação (ex: `txn_a1b2c3d4`)"},"type":{"type":"string","const":"BURN"},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"BMC resgatado, em centavos (ex: 500)"},"customer_phone":{"type":"string","description":"Telefone do cliente em formato E.164"},"new_balance":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Saldo atualizado do cliente, em centavos (ex: 4545)"},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","type","amount","customer_phone","new_balance","created_at"]}}}},"400":{"description":"Requisição inválida ou saldo insuficiente","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_phone":{"description":"Telefone do cliente em formato E.164. Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":10},"customer_cpf":{"description":"CPF do cliente (11 dígitos). Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":11,"maxLength":11},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"BMC a resgatar, em centavos inteiros. 1 BMC = R$ 1,00 = 100 centavos (ex: 500 = R$ 5,00)."},"location_id":{"description":"ID canônico do local Bumcash onde ocorre o resgate. Opcional se `cnpj` for fornecido, ou se a sua organização tiver um único local ativo.","type":"string"},"cnpj":{"description":"CNPJ de 14 dígitos do local. Aceita com pontuação. **Obrigatório para integradores Partner** — resolvido para um `location_id` dentro do seu escopo. Chaves Merchant com apenas um local ativo podem omitir ambos os campos.","type":"string"},"reason":{"description":"Motivo do resgate","type":"string"},"reference":{"description":"Referência do integrador para esta operação","type":"object","properties":{"external_id":{"description":"ID de referência externa do integrador","type":"string"},"description":{"description":"Descrição livre da operação","type":"string"}}},"idempotency_key":{"description":"Chave única para retentativa idempotente. Também aceita via header `X-Idempotency-Key`.","type":"string"}},"required":["amount"]}}}}}},"/customers/register":{"post":{"operationId":"postCustomersRegister","tags":["Customers"],"summary":"Pré-cadastrar cliente","description":"Cria o vínculo cliente↔loja no momento da assinatura do serviço, **sem disparar a validação oficial do CPF** (etapa cara, fica para o primeiro uso). O cliente fica em status `pending` até a primeira fatura/pagamento com bloco `activate`, que efetiva a ativação e leva o cliente para `active`. A unicidade autoritativa é por `(sua organização, CPF)`: o mesmo CPF na mesma organização sempre retorna o mesmo cliente, independentemente da `idempotency_key`. Se o CPF já estiver registrado por outra organização, o cliente é retornado mas os campos de atribuição (`registered_by_location_id`, `external_reference_id`, `registered_at`) vêm como `null` para evitar vazamento de atribuição entre lojas.","responses":{"200":{"description":"Cliente já estava pré-cadastrado — retorno idempotente","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID interno Bumcash do cliente"},"cpf":{"type":"string"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["pending","active","blocked"]},"registered_by_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Location que pré-cadastrou o cliente. `null` se o cliente já existia e foi cadastrado por outra organização."},"external_reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ID externo definido por você. `null` se o cliente já existia ou pertence a outra organização."},"registered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp ISO 8601 do pré-cadastro original"}},"required":["id","cpf","phone","status","registered_by_location_id","external_reference_id","registered_at"]}}}},"201":{"description":"Cliente pré-cadastrado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID interno Bumcash do cliente"},"cpf":{"type":"string"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["pending","active","blocked"]},"registered_by_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Location que pré-cadastrou o cliente. `null` se o cliente já existia e foi cadastrado por outra organização."},"external_reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ID externo definido por você. `null` se o cliente já existia ou pertence a outra organização."},"registered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Timestamp ISO 8601 do pré-cadastro original"}},"required":["id","cpf","phone","status","registered_by_location_id","external_reference_id","registered_at"]}}}},"400":{"description":"CPF inválido ou local não está ativo","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"403":{"description":"Chave sem permissão `customers:register` ou local fora do escopo da chave","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"404":{"description":"Local não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"409":{"description":"`external_reference_id` já está em uso na sua organização para um cliente diferente","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location_id":{"type":"string","description":"ID do local da sua organização que está pré-cadastrando o cliente"},"customer_cpf":{"type":"string","minLength":11,"maxLength":11,"description":"CPF do cliente (11 dígitos, sem pontuação)"},"customer_phone":{"description":"Telefone do cliente em formato E.164 (opcional). Se enviado, é gravado para uso futuro em notificações e ativação.","type":"string"},"external_reference_id":{"description":"ID interno do cliente no seu ERP/CRM. Único dentro da sua organização — não pode ser reutilizado para clientes diferentes.","type":"string"},"idempotency_key":{"description":"Opcional. Útil para retentativas seguras de rede. A unicidade autoritativa é por (sua organização, CPF) — mesmo CPF na mesma organização sempre retorna o mesmo cliente, independentemente da idempotency_key.","type":"string"}},"required":["location_id","customer_cpf"]}}}}}},"/payments":{"post":{"operationId":"postPayments","tags":["Payments"],"summary":"Processar pagamento com moeda","description":"Processa um pagamento com moeda BMC na loja. O cliente paga parte da venda em BMC até o limite configurado em `coin_acceptance_rate` e o restante é coletado em dinheiro fora do sistema Bumcash.","responses":{"201":{"description":"Pagamento processado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID do pagamento"},"location_id":{"type":"string"},"total_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor total da venda em centavos"},"coin_acceptance_rate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Percentual da venda aceito em BMC pelo lojista (0-100)"},"coin_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"BMC debitado da carteira do cliente, em centavos"},"cash_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Restante que o cliente ainda deve pagar em dinheiro (fora do sistema Bumcash), em centavos"},"status":{"type":"string","enum":["pending","completed","failed","reversed"]},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","location_id","total_amount","coin_acceptance_rate","coin_amount","cash_amount","status","created_at"]}}}},"400":{"description":"Requisição inválida ou saldo insuficiente","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_phone":{"description":"Telefone do cliente (E.164). Informe `customer_phone` OU `customer_cpf`.","type":"string"},"customer_cpf":{"description":"CPF do cliente (11 dígitos). Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":11,"maxLength":11},"location_id":{"type":"string","description":"ID do local"},"total_amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Valor total da venda em centavos"},"operator_id":{"description":"ID do operador (opcional, para POS físico)","type":"string"},"idempotency_key":{"type":"string","description":"Chave única para evitar duplicatas"}},"required":["location_id","total_amount","idempotency_key"]}}}}},"get":{"operationId":"getPayments","tags":["Payments"],"summary":"Listar pagamentos","description":"Retorna uma lista paginada de pagamentos com moeda BMC. Filtrável por local e status.","responses":{"200":{"description":"Lista paginada de pagamentos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do pagamento"},"location_id":{"type":"string"},"total_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor total da venda em centavos"},"coin_acceptance_rate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Percentual da venda aceito em BMC pelo lojista (0-100)"},"coin_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"BMC debitado da carteira do cliente, em centavos"},"cash_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Restante que o cliente ainda deve pagar em dinheiro (fora do sistema Bumcash), em centavos"},"status":{"type":"string","enum":["pending","completed","failed","reversed"]},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","location_id","total_amount","coin_acceptance_rate","coin_amount","cash_amount","status","created_at"]}},"has_more":{"type":"boolean"},"cursor":{"type":"string"}},"required":["data","has_more"]}}}}},"parameters":[{"in":"query","name":"location_id","schema":{"type":"string"},"description":"Filtrar por ID do local"},{"in":"query","name":"status","schema":{"type":"string","enum":["pending","completed","failed","reversed"]},"description":"Filtrar por status"},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Cursor de paginação"},{"in":"query","name":"limit","schema":{"type":"number","minimum":1,"maximum":100},"description":"Quantidade de resultados (1-100)"}]}},"/payments/pos-cashback":{"post":{"operationId":"postPaymentsPosCashback","tags":["Payments"],"summary":"Creditar cashback de compra em PDV","description":"Credita ao cliente a porcentagem configurada em `coin_acceptance_rate` do valor pago em fiat. Disponível para locais do tipo `retail` e `hybrid` — locais `recurrency` usam `POST /recurring/bill-payment`. Se o cliente puder ainda não estar na rede, envie `activate: { cpf, phone? }` no mesmo payload — o cadastro é processado antes do crédito.","responses":{"201":{"description":"Cashback creditado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID do lançamento contábil (ledger)"},"type":{"type":"string","const":"POS_CASHBACK"},"customer_id":{"type":"string"},"cashback_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor de cashback creditado, em centavos"},"total_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor da compra em fiat, em centavos"},"coin_acceptance_rate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Percentual de cashback configurado no merchant (0-100)"},"new_balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Saldo atualizado da carteira do cliente, em centavos"},"location_id":{"type":"string"},"location_name":{"type":"string"},"created_at":{"type":"string","description":"Timestamp ISO 8601"},"customer_activation":{"type":"string","enum":["activated","already_active"],"description":"`activated` — esta chamada efetivou a inclusão na rede (via payload `activate`). `already_active` — o cliente já estava na rede. Enum para permitir extensibilidade futura sem quebrar contratos."}},"required":["id","type","customer_id","cashback_amount","total_amount","coin_acceptance_rate","new_balance","location_id","location_name","created_at","customer_activation"]}}}},"400":{"description":"Requisição inválida (tipo de loja, parâmetros, ou `activate` rejeitado)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"404":{"description":"Cliente não encontrado e `activate` não informado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_phone":{"description":"Telefone do cliente (E.164). Informe `customer_phone` OU `customer_cpf`.","type":"string"},"customer_cpf":{"description":"CPF do cliente (11 dígitos). Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":11,"maxLength":11},"location_id":{"type":"string","description":"ID do local do merchant"},"total_amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Valor total da compra em fiat, em centavos"},"operator_id":{"description":"ID do operador (opcional, para POS físico)","type":"string"},"idempotency_key":{"type":"string","description":"Chave única para evitar duplicatas"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"activate":{"description":"Payload de inclusão na rede no primeiro uso. Envie sempre que o cliente puder ainda não estar na rede — o cadastro é processado antes do crédito de cashback. Se o cadastro não puder ser concluído, a chamada falha e nada é creditado. Já presente na rede? O payload é ignorado e o crédito segue normalmente.","type":"object","properties":{"cpf":{"type":"string","minLength":11,"maxLength":11,"description":"CPF do cliente (11 dígitos)"},"phone":{"description":"Telefone do cliente (E.164, opcional)","type":"string"}},"required":["cpf"]}},"required":["location_id","total_amount","idempotency_key"]}}}}}},"/payments/{id}":{"get":{"operationId":"getPaymentsById","tags":["Payments"],"summary":"Detalhar pagamento","description":"Retorna os detalhes completos de um pagamento com moeda BMC pelo ID.","responses":{"200":{"description":"Detalhes do pagamento","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID do pagamento"},"location_id":{"type":"string"},"total_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor total da venda em centavos"},"coin_acceptance_rate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Percentual da venda aceito em BMC pelo lojista (0-100)"},"coin_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"BMC debitado da carteira do cliente, em centavos"},"cash_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Restante que o cliente ainda deve pagar em dinheiro (fora do sistema Bumcash), em centavos"},"status":{"type":"string","enum":["pending","completed","failed","reversed"]},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","location_id","total_amount","coin_acceptance_rate","coin_amount","cash_amount","status","created_at"]}}}},"404":{"description":"Pagamento não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/recurring/bill-payment":{"post":{"operationId":"postRecurringBillPayment","tags":["Recurring"],"summary":"Notificar pagamento de conta","description":"Notifica um pagamento de conta efetuado em uma empresa de recorrência (telecom, academia, convênio etc.) para creditar BMC na carteira do cliente. O local notificador precisa ser de tipo `recurrency` ou `hybrid`. O valor creditado segue a taxa de conversão configurada para o local (`recurrency_conversion_rate`, default `100`). Em locais com taxa = 100 (padrão), R$ 1,00 pago gera R$ 1,00 em BMC. Locais com taxa < 100 operam em modo manual definido fora desta API e não devem usar este endpoint — coordene com o time Bumcash antes de integrar.","responses":{"201":{"description":"Pagamento notificado e BMC creditado ao cliente","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"location_id":{"type":"string"},"customer_id":{"type":"string"},"bill_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"coins_minted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"customer_activation":{"type":"string","enum":["activated","already_active"],"description":"`activated` — esta chamada efetivou a ativação. `already_active` — cliente já estava ativo."},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","location_id","customer_id","bill_amount","coins_minted","customer_activation","created_at"]}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location_id":{"type":"string","description":"ID do local notificador (deve ser uma empresa de recorrência ou híbrida)"},"customer_phone":{"description":"Telefone do cliente (E.164). Informe `customer_phone` OU `customer_cpf`.","type":"string"},"customer_cpf":{"description":"CPF do cliente (11 dígitos). Informe `customer_phone` OU `customer_cpf`.","type":"string","minLength":11,"maxLength":11},"bill_amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Valor da conta paga, em centavos"},"reference_external_id":{"description":"Referência externa da conta na sua base","type":"string"},"idempotency_key":{"type":"string","description":"Chave única para evitar duplicatas"},"activate":{"description":"Payload de ativação na primeira fatura. Envie quando o cliente puder ainda não estar ativo (`pending` ou inexistente) — a ativação acontece antes do crédito de BMC. Idempotente: cliente já ativo? O bloco é tratado como no-op e o BMC é creditado normalmente. Requer a permissão `customers:activate` adicional ao `recurring:bill_payment`.","type":"object","properties":{"cpf":{"type":"string","minLength":11,"maxLength":11,"description":"CPF do cliente (11 dígitos)"},"phone":{"description":"Telefone do cliente (E.164, opcional)","type":"string"}},"required":["cpf"]}},"required":["location_id","bill_amount","idempotency_key"]}}}}}},"/statements":{"get":{"operationId":"getStatements","tags":["Statements"],"summary":"Listar extratos","description":"Retorna os extratos de faturamento visíveis para a chave utilizada. Chaves Merchant veem os extratos dos locais que pertencem à sua organização; chaves Partner veem os extratos dos locais que integram. Suporta filtros por período e status.","responses":{"200":{"description":"Lista de extratos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"location_id":{"type":"string"},"period_start":{"type":"string","description":"Início do período (ISO 8601)"},"period_end":{"type":"string","description":"Fim do período (ISO 8601)"},"total_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor total devido no período, em centavos de BRL (1 BMC = 100 centavos)."},"transaction_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Quantidade de transações cobertas neste extrato."},"status":{"type":"string","enum":["draft","issued","paid","overdue","cancelled"]},"invoice_number":{"type":"string"},"issued_at":{"type":"string"},"due_at":{"type":"string"},"paid_at":{"type":"string"},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","location_id","period_start","period_end","total_amount","transaction_count","status","created_at"]}},"has_more":{"type":"boolean"},"cursor":{"type":"string"}},"required":["data","has_more"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["draft","issued","paid","overdue","cancelled"]}},{"in":"query","name":"period_start","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"description":"ISO 8601 — filter statements whose period starts on or after"},{"in":"query","name":"period_end","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"description":"ISO 8601 — filter statements whose period ends on or before"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}},{"in":"query","name":"cursor","schema":{"type":"string"}}]}},"/statements/{id}":{"get":{"operationId":"getStatementsById","tags":["Statements"],"summary":"Detalhar extrato","description":"Retorna um extrato específico com os line items que o compõem, úteis para conciliação. As mesmas regras de escopo da listagem se aplicam: Merchant e Partner só leem extratos dos seus próprios locais.","responses":{"200":{"description":"Detalhe do extrato","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"location_id":{"type":"string"},"period_start":{"type":"string","description":"Início do período (ISO 8601)"},"period_end":{"type":"string","description":"Fim do período (ISO 8601)"},"total_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor total devido no período, em centavos de BRL (1 BMC = 100 centavos)."},"transaction_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Quantidade de transações cobertas neste extrato."},"status":{"type":"string","enum":["draft","issued","paid","overdue","cancelled"]},"invoice_number":{"type":"string"},"issued_at":{"type":"string"},"due_at":{"type":"string"},"paid_at":{"type":"string"},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","location_id","period_start","period_end","total_amount","transaction_count","status","created_at"]}}}},"403":{"description":"Acesso negado — a chave não pode ler este extrato","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"404":{"description":"Extrato não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/earnings":{"get":{"operationId":"getEarnings","tags":["Earnings"],"summary":"Consultar saldo acumulado","description":"Retorna o saldo acumulado pela sua organização na rede Bumcash dentro do período informado. Inclui um resumo com o total geral e até 500 linhas de eventos que contribuíram, com contexto de local. Útil para conciliação contábil contra a sua base.","responses":{"200":{"description":"Resumo + linhas do saldo acumulado","content":{"application/json":{"schema":{"type":"object","properties":{"period_start":{"type":"string"},"period_end":{"type":"string"},"summary":{"type":"object","properties":{"grand_total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total acumulado no período, em centavos de BRL"},"contributing_events":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Quantidade de eventos (transações) que contribuíram para o total"}},"required":["grand_total","contributing_events"]},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identificador opaco da linha (use para cross-reference com o detalhe do pagamento)"},"coin_payment_id":{"type":"string"},"location_id":{"type":"string"},"location_name":{"type":"string"},"created_at":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Valor acumulado nesta linha, em centavos de BRL"}},"required":["id","coin_payment_id","location_id","location_name","created_at","amount"]}},"has_more_lines":{"type":"boolean"}},"required":["period_start","period_end","summary","lines","has_more_lines"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"403":{"description":"Acesso negado — escopo da chave não pode ler earnings","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"in":"query","name":"period_start","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"required":true,"description":"Início do período (ISO 8601, inclusivo)"},{"in":"query","name":"period_end","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"required":true,"description":"Fim do período (ISO 8601, exclusivo)"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":500},"description":"Quantidade máxima de linhas retornadas (1-500, default 100)"}]}},"/webhooks":{"post":{"operationId":"postWebhooks","tags":["Webhooks"],"summary":"Criar endpoint de webhook","description":"Registra um novo endpoint HTTPS para receber notificações de eventos. As entregas são assinadas com HMAC-SHA256 e o `secret` de assinatura é retornado apenas uma vez, no momento da criação — guarde-o em local seguro.","responses":{"201":{"description":"Endpoint de webhook criado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID do endpoint de webhook"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","url","events","created_at"]}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL HTTPS para receber as entregas (HTTPS obrigatório em produção)"},"events":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Tipos de evento aos quais inscrever-se (ex: `['credit.minted', 'credit.burned']`)"},"description":{"description":"Descrição livre do endpoint","type":"string"}},"required":["url","events"]}}}}},"get":{"operationId":"getWebhooks","tags":["Webhooks"],"summary":"Listar endpoints de webhook","description":"Retorna todos os endpoints de webhook registrados para a organização da chave utilizada.","responses":{"200":{"description":"Lista de endpoints de webhook","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID do endpoint de webhook"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"created_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","url","events","created_at"]}}},"required":["data"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhooksById","tags":["Webhooks"],"summary":"Remover endpoint de webhook","description":"Remove um endpoint de webhook. A partir desse momento, nenhum novo evento será entregue para essa URL.","responses":{"200":{"description":"Endpoint removido","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}},"required":["deleted","id"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"404":{"description":"Endpoint não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true,"description":"ID do endpoint de webhook"}]}},"/webhooks/{endpointId}/attempts":{"get":{"operationId":"getWebhooksByEndpointIdAttempts","tags":["Webhooks"],"summary":"Listar tentativas de entrega","description":"Retorna o histórico de tentativas de entrega de um endpoint de webhook específico. Útil para investigar falhas de entrega.","responses":{"200":{"description":"Histórico de tentativas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"endpoint_id":{"type":"string"},"status":{"type":"string","enum":["success","failed","pending"]},"response_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attempted_at":{"type":"string","description":"Timestamp ISO 8601"}},"required":["id","event_id","endpoint_id","status","attempted_at"]}}},"required":["data"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"in":"path","name":"endpointId","schema":{"type":"string"},"required":true,"description":"ID do endpoint de webhook"},{"in":"query","name":"limit","schema":{"type":"number","minimum":1,"maximum":100},"description":"Quantidade de resultados (1-100)"}]}},"/webhooks/events/{eventId}/replay":{"post":{"operationId":"postWebhooksEventsByEventIdReplay","tags":["Webhooks"],"summary":"Reentregar evento","description":"Reentrega um evento específico para todos os endpoints inscritos. Útil para recuperar-se de indisponibilidades temporárias no seu servidor.","responses":{"200":{"description":"Evento reentregue","content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string"},"replayed":{"type":"boolean"}},"required":["event_id","replayed"]}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}},"404":{"description":"Evento não encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código de erro estável (ex: `customer_pending`, `insufficient_permissions`). Use este campo para tratamento programático — `error.message` é informativa e pode mudar."},"message":{"type":"string","description":"Mensagem em pt-BR, segura para logar."},"hint":{"description":"Sugestão acionável quando o erro tem causa conhecida (ex: \"verbo da trilha varejo, recorrência usa /recurring/bill-payment\"). Presente em respostas `insufficient_permissions` e em alguns outros códigos curados.","type":"string"},"docs":{"description":"URL para a documentação relevante quando aplicável (ex: `https://docs.bumcash.com.br/recurrency/quickstart#passo-2`).","type":"string"}},"required":["code","message"]},"request_id":{"description":"Identificador único da requisição (para suporte)","type":"string"}},"required":["error"]}}}}},"parameters":[{"in":"path","name":"eventId","schema":{"type":"string"},"required":true,"description":"ID do evento de webhook"}]}},"/webhooks/event-types":{"get":{"operationId":"getWebhooksEventTypes","tags":["Webhooks"],"summary":"Listar tipos de evento disponíveis","description":"Retorna todos os tipos de evento aos quais um endpoint de webhook pode se inscrever.","responses":{"200":{"description":"Lista de tipos de evento","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identificador do tipo de evento"},"description":{"description":"Descrição do tipo de evento","type":"string"}},"required":["type"]}}},"required":["data"]}}}}}}}}}