Calebe Pay Documentação da API Tudo o que dá para fazer pela API
Baixar MD
GUIA DE INTEGRAÇÃO

Tudo o que dá para fazer pela API

Este guia é o mapa da API pública da Calebe Pay. Ele lista cada operação disponível, o escopo que a chave precisa ter e onde está o detalhe. No fim, mostra o que só existe no painel. O contrato completo, campo a campo, está em openapi.json; o passo a passo da primeira integração, em integration.md.

Como toda chamada funciona

Escopos da chave

Uma chave só faz o que os escopos dela permitem. Sem o escopo, a API responde 403 insufficient_scope.

Escopo O que libera
pix:write Criar Pix. Atualizar e simular cobranças Pix. Autorizações e débitos de Pix Automático. Assinaturas por Pix ou Pix Automático. Checkout que oferece Pix.
boleto:write Criar boleto. Atualizar e simular boletos. Assinaturas por boleto. Checkout que oferece boleto.
credit_card:write Cobrar no cartão de crédito. Atualizar e simular cobranças de cartão. Assinaturas no cartão. Checkout que oferece cartão.
transactions:read Consultar e listar transações, checkouts, assinaturas, ciclos, autorizações de Pix Automático e centros de custo. Ler o JSON de criação.
cost_centers:write Criar, renomear, desativar e reativar centros de custo do tenant da chave.
subtenants:write Cadastrar um subtenant e converter a subconta dele. Só chave de produção.
subtenants:read Listar os subtenants.
subtenants:keys:write Emitir uma chave de API para um subtenant.

Atualizar, simular, estornar ou alterar o vencimento de uma cobrança pede transactions:read e o escopo de escrita do método dela.

Quem cria a chave no painel só consegue marcar os escopos que poderia exercer no próprio painel. Por exemplo, sem permissão para emitir cobranças, não há escopo de escrita; os de subtenants pedem a permissão de cadastrar subtenants.

Chave restrita: quem emite uma chave sem poder verificar e simular cobranças no painel, como o perfil Desenvolvedor, gera uma chave com access_profile: "developer". Ela cria e consulta cobranças e checkouts, usa assinaturas e Pix Automático e consulta centros de custo. Ela não atualiza nem simula transações, não altera centros de custo e não mexe em subtenants, mesmo que os escopos pareçam permitir. O perfil da chave é decidido pelo servidor e não muda depois.

Cobranças

Operação Escopo O que faz
POST /v1/pix pix:write Cria um Pix com QR Code e copia e cola, válido de 1 minuto a 24 horas. Guia
POST /v1/boleto boleto:write Cria um boleto com vencimento, multa, juros e um Pix do mesmo valor junto. Guia
POST /v1/credit-card credit_card:write Cobra no cartão, por token ou dados do cartão, em 1 a 12 parcelas, com captura imediata. Guia
POST /v1/transactions/{id}/refund transactions:read + escrita do método Solicita estorno integral de cobrança paga. Boleto pago pelo boleto exige conta bancária do pagador. Acompanhe refund.status e o estado refunded. Guia
PATCH /v1/transactions/{id}/boleto transactions:read + boleto:write Altera o vencimento do boleto em aberto com due_date e Idempotency-Key, sem emitir outra cobrança ou mudar a assinatura. Guia
POST /v1/checkouts escrita de cada forma oferecida Cria um link em que quem paga escolhe Pix, boleto ou cartão. Guia
GET /v1/checkouts transactions:read Lista os checkouts do modo da chave.
GET /v1/checkouts/{id} transactions:read Consulta um checkout: open, processing, completed, failed ou expired.
GET /v1/transactions transactions:read Lista as transações, com os filtros da tabela abaixo.
GET /v1/transactions/{id} transactions:read Consulta o estado salvo de uma transação, sem falar com o provedor.
GET /v1/transactions/{id}/request transactions:read Mostra o JSON de criação e o corpo preparado para o provedor. Guia
POST /v1/transactions/{id}/refresh transactions:read + escrita do método Consulta o provedor e atualiza o estado. Guia
POST /v1/transactions/{id}/simulate transactions:read + escrita do método Só com chave de teste: simula pagamento (paid) ou expiração (expired). Guia

Toda criação de cobrança e de checkout aceita, opcionalmente:

Assinaturas e Pix Automático

Operação Escopo O que faz
POST /v1/subscriptions escrita do método Cria uma assinatura por boleto, Pix, Pix Automático ou cartão; a Calebe Pay emite cada ciclo.
GET /v1/subscriptions transactions:read Lista as assinaturas.
GET /v1/subscriptions/{id} transactions:read Consulta uma assinatura e o próximo ciclo.
PATCH /v1/subscriptions/{id} escrita do método Pausa, retoma ou cancela.
GET /v1/subscriptions/{id}/cycles transactions:read Lista os ciclos e a cobrança de cada um.
POST /v1/pix-automatic/authorizations pix:write Pede ao pagador a autorização de débito no aplicativo do banco.
GET /v1/pix-automatic/authorizations transactions:read Lista as autorizações.
GET /v1/pix-automatic/authorizations/{id} transactions:read Consulta uma autorização.
POST /v1/pix-automatic/authorizations/{id}/refresh pix:write Confere com o provedor se o pagador aprovou ou revogou.
POST /v1/pix-automatic/authorizations/{id}/simulate pix:write Só com chave de teste: simula a resposta do pagador.
DELETE /v1/pix-automatic/authorizations/{id} pix:write Revoga a autorização.
POST /v1/pix-automatic/charges pix:write Agenda um débito avulso numa autorização aprovada, sem assinatura.

Os campos, os estados e o teste estão no guia de assinaturas e Pix Automático.

Centros de custo

Operação Escopo O que faz
GET /v1/cost-centers transactions:read Lista os centros, ativos e inativos.
GET /v1/cost-centers/{id} transactions:read Consulta um centro da sua árvore.
POST /v1/cost-centers cost_centers:write Cria um centro no tenant da chave.
PATCH /v1/cost-centers/{id} cost_centers:write Renomeia, desativa ("active": false) ou reativa.

O cadastro é o mesmo em teste e produção. Veja Centros de custo.

Subtenants

Operação Escopo O que faz
POST /v1/subtenants subtenants:write Cadastra uma empresa filha e tenta converter a subconta dela. Guia
GET /v1/subtenants subtenants:read Lista os filhos diretos; com include_descendants=true, toda a árvore abaixo. Guia
POST /v1/subtenants/{id}/api-keys subtenants:keys:write Emite uma chave para o subtenant, com escopos que a sua chave também tem. Guia

Filtros das listagens

Listagem Filtros
GET /v1/transactions status, method (pix, boleto ou credit_card), reference, cost_center_id (ou unassigned para as sem centro), tenant_id, include_descendants, limit, offset
GET /v1/checkouts reference, include_descendants, limit, offset
GET /v1/subscriptions status, tenant_id, include_descendants, limit, offset
GET /v1/subscriptions/{id}/cycles limit, offset
GET /v1/pix-automatic/authorizations tenant_id, include_descendants, limit, offset
GET /v1/cost-centers active, tenant_id, include_descendants
GET /v1/subtenants status (active ou suspended), include_descendants, limit, offset

Por padrão, cada listagem traz só o tenant da chave. include_descendants=true inclui os tenants abaixo dele, nunca os de cima nem os de outra árvore. tenant_id escolhe um tenant dentro dessa árvore. As listas de cobranças, checkouts, assinaturas e autorizações trazem só o modo da chave.

Eventos (webhooks)

A Calebe Pay avisa o seu sistema quando uma cobrança muda:

Os eventos chegam assinados e valem para Pix, boleto, cartão, checkouts, ciclos de assinatura e débitos de Pix Automático. Há duas formas de receber, e elas se somam:

A assinatura, as retentativas e o corpo de cada evento estão em Receber eventos por webhook.

Contrato, SDK e saúde

O que só existe no painel

Algumas operações ficam fora da API pública de propósito, porque administram acesso à conta, configuração financeira ou destinos dos avisos. Essas operações exigem uma sessão com as permissões correspondentes.

No painel ou no app Por quê
Cancelar ou capturar uma cobrança Não há endpoint público dessas operações. Estornos integrais são solicitados pela API ou pelo detalhe da cobrança no painel.
Cadastrar endpoints de webhook, ver o segredo de assinatura e reenviar entregas Mudar o destino dos eventos desviaria todos os avisos da conta.
Criar e revogar as chaves de API da própria conta A chave não cria outra chave para si mesma; só emite chaves para subtenants, com escopos que já tem.
Enviar a cobrança ao cliente por e-mail ou WhatsApp O aviso sai do painel ou do app, a partir de uma cobrança já criada.
Agenda de clientes cadastrados Fica no painel e no app para preencher cobranças.
Usuários, perfis, permissões e verificação em duas etapas Quem acessa a conta é decidido por uma pessoa com sessão.
Dados da empresa, documentos, saldo e repasses da conta Ficam com quem administra a conta.
Tarifas, provedores, regras de roteamento e subcontas São configurados pela Calebe Pay.

Para essas operações, entre no painel ou no app Calebe Pay com um usuário que tenha a permissão.