Cobre BaseA cobrança do seu sistema, pela API
O software cria o cliente, a assinatura e o uso. A Cobre Base emite a fatura. Quando o pagamento entra ou falha, um webhook avisa o seu sistema.
API
Autenticação com Authorization: Bearer. Use cb_test_ no desenvolvimento e cb_live_ na cobrança real.
Valores são inteiros em centavos. R$ 10,00 vai como 1000. A moeda é BRL.
Todo POST leva o header Idempotency-Key. A chave vale 24 horas. Reusar a mesma chave com outro corpo devolve 409. Um replay devolve o header Idempotent-Replayed.
Número do cartão e CVV não passam por esta API. O cartão é tokenizado no provedor de pagamento.
O erro vem como error.type, code, message e param. Listagens usam limit (padrão 25, máximo 100) e page.
Produto, preço, cupom, lembrete e provedor de pagamento ficam no painel. A API cria o cliente, a assinatura e o uso, e lê a fatura.
- POST/v1/customersCria o cliente.
- POST/v1/subscriptionsLiga o cliente ao preço e à cobrança que se repete.
- POST/v1/meter-eventsRegistra o uso do período.
- GET/v1/invoicesConsulta a fatura, o valor e a situação.
- POST/v1/customer-portal/sessionsDevolve o link da área do cliente. O link expira.
Webhooks
A Cobre Base chama a URL que você cadastra quando a fatura é paga, quando o pagamento falha ou quando a situação muda.
O header é SaasPay-Signature, no formato t=timestamp,v1=hex. A assinatura é HMAC-SHA256 de timestamp e corpo, com o segredo whsec_.
O envelope traz id, type, created, livemode e o objeto. Em eventos *.updated, também vem previous_attributes. Responda 2xx. Se não responder, o envio tenta de novo até 5 vezes.
Faturas
- invoice.created
- invoice.paid
- invoice.payment_failed
- invoice.voided
Assinaturas
- subscription.created
- subscription.updated
- subscription.canceled
Pagamentos
- payment.paid
- payment.failed
- payment.refunded
Uso
- usage.recorded
Chaves
Cada organização tem chave de teste e chave de cobrança real. O objeto da API traz livemode: false com cb_test_, true com cb_live_.
cb_test_
Desenvolvimento. A cobrança não é real. Prefira esta chave enquanto integra.
cb_live_
Cobrança real. Só use quando o fluxo de teste já criou cliente, assinatura e fatura.
As chaves são criadas no painel, depois que a conta existe. A página pública não pede login para explicar o contrato.
Sandbox
O ambiente de teste é separado da cobrança real. Cliente, fatura e webhook de teste não misturam com o que foi cobrado de verdade.
Sem a chave do provedor de pagamento, a API usa um sandbox interno: o PIX é fictício e o pagamento permanece pendente. Com a chave de teste, você percorre o mesmo contrato da cobrança real.
MCP no Cursor
Quem integra outro sistema não precisa sair do editor para lembrar o contrato. O servidor MCP do Cobre Base responde o guia, busca a operação em /v1 e lista os eventos de webhook.
Sem chave, fica só a documentação. Com cb_test_, o agente chama a API de verdade, só em /v1. Com cb_live_, a chamada real é só leitura, a menos que a escrita em produção seja liberada.
A chave não entra em log nem em mensagem de erro.
Crie a chave de teste e chame a API
A conta abre o painel. Lá você gera a chave cb_test_ e cadastra a URL do webhook.