B
bumcashdocs

Referência

Endpoints da API Bumcash

Índice navegável dos endpoints, agrupados pela trilha que os utiliza. Para a especificação técnica completa (schemas Zod, exemplos de payload e ferramentas de teste), use a OpenAPI oficial.

Recorrência

recorrência

Notificação de pagamento de faturas. Trilha exclusiva para `companyType = recurrency` ou `hybrid`.

  • POST/v1/recurring/bill-paymentperm: recurring:bill_payment (+ customers:activate se activate)

    Notifica o pagamento de uma fatura e credita BMC ao cliente. Aceita bloco `activate` para ativar o cliente na primeira fatura.

Varejo PDV

varejo

Cashback proporcional em vendas em fiat. Trilha para `companyType = retail` ou `hybrid`.

  • POST/v1/payments/pos-cashbackperm: payments:create (+ customers:activate se activate)

    Credita cashback BMC numa venda no PDV. Aceita bloco `activate` para ativar o cliente na primeira compra.

  • POST/v1/paymentsperm: payments:create

    Pagamento com saldo BMC do cliente (consumo de moeda).

  • GET/v1/payments/:idperm: transactions:list

    Detalhe de um pagamento específico.

  • GET/v1/paymentsperm: transactions:list

    Listagem paginada de pagamentos do seu escopo.

Clientes

cross-cutting

Pré-cadastro e consulta. Cross-cutting — usado por ambas as trilhas.

  • POST/v1/customers/registerperm: customers:register

    Pré-cadastra cliente em status `pending` antes da primeira fatura/compra (não dispara validação oficial).

Conciliação

cross-cutting

Extratos, ganhos, transações. Cross-cutting — todos os tiers Merchant + Partner.

  • GET/v1/statementsperm: statements:read

    Extratos de faturamento por período. Filtrável por local.

  • GET/v1/statements/:idperm: statements:read

    Detalhe de um extrato com line items para conciliação.

  • GET/v1/earningsperm: earnings:read

    Saldo acumulado como ativador da rede no período.

Webhooks

cross-cutting

Notificações de eventos em tempo real, assinadas com HMAC-SHA256.

  • GET/v1/webhooks/event-types

    Lista canônica dos eventos disponíveis para subscrição.

Partner (integradores)

partner-only

Reservado a chaves Partner (`ptr_`). Lojistas diretos NÃO usam estas rotas — são as trilhas dedicadas (recorrência/varejo) que creditam BMC aos lojistas.

  • POST/v1/credits/mintperm: credits:mint

    Emite BMC ao cliente em nome de um lojista. Identifique o lojista por `cnpj` ou `location_id`.

  • POST/v1/credits/burnperm: credits:burn

    Resgata BMC do cliente em nome de um lojista.

  • POST/v1/credits/batch-mintperm: credits:mint

    Emissão em lote — útil para sincronização de bases.