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
- Endereço:
https://api.calebepay.com.br, o mesmo para teste e produção. - Autenticação: header
X-API-Keycom a chave do seu tenant, sempre a partir do seu servidor. A chave decide o tenant e o modo. - Modo de teste: chaves
cp_test_criam e leem só cobranças de teste, que nunca chegam ao provedor de pagamento. Chavescp_live_(oucp_key_, nas antigas) são de produção. - Valores: inteiros em centavos de real (
1250é R$ 12,50). - Criação idempotente: toda criação de cobrança, checkout, assinatura, autorização, subtenant ou chave exige o header
Idempotency-Key. Repetir a mesma chave com o mesmo corpo devolve o registro original; com outro corpo,409 idempotency_conflict. Veja Idempotência e resultado incerto. - Respostas: um objeto vem em
{ "data": { ... } }, uma lista em{ "data": [...], "meta": { "limit", "offset", "count" } }e um erro em{ "error": { "code", "message", "request_id" } }. - Paginação:
limit(padrão 50, máximo 100) eoffset.meta.counté o tamanho da página, não o total. - Limite: 120 requisições por minuto por chave; acima disso,
429 rate_limit_exceeded. - Rastreio: toda resposta traz
X-Request-ID. Informe esse valor ao falar com o suporte.
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. |
ticket:write |
Cobrar com Ticket (vale-refeição e alimentação). Atualizar e estornar cobranças Ticket. Checkout que oferece Ticket. |
pluxee:write |
Cobrar com Pluxee (vale-refeição e alimentação). Atualizar e estornar cobranças Pluxee. Checkout que oferece Pluxee. |
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. |
fees:read |
Consultar tarifas totais e condições de parcelamento. |
subtenants:fees:read |
Consultar os adicionais próprios dos subtenants. |
subtenants:fees:write |
Cadastrar, alterar e excluir vigências futuras desses adicionais. Só produção. |
account:read |
Consultar resumo financeiro, repasses, extrato, dados bancários e transferências. Só produção. |
account:transfers:write |
Solicitar transferências do saldo e consultar sua confirmação no provedor. Só produção. |
account:bank:write |
Trocar a conta bancária de repasse. Só produção, e só quem gerencia a empresa emite. |
invoices:read |
Consultar notas fiscais, o emitente e a configuração fiscal. |
invoices:write |
Emitir e cancelar notas fiscais. Chave de teste só em homologação. |
invoices:issuer:write |
Cadastrar o emitente, enviar o certificado digital e configurar a emissão. |
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/ticket |
ticket:write |
Cobra no cartão Ticket (vale-refeição e alimentação), à vista, com captura imediata. Guia |
POST /v1/pluxee |
pluxee:write |
Cobra no cartão Pluxee (vale-refeição e alimentação), à vista, 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 |
GET /v1/transactions/{id}/chargeback |
transactions:read |
Mostra a contestação de uma cobrança no cartão: caso, motivo e prazo da defesa. Guia |
POST /v1/transactions/{id}/simulate |
transactions:read + escrita do método |
Só com chave de teste: simula pagamento (paid), expiração (expired) ou, no cartão, recusa (failed) e contestação (disputed, depois chargeback ou paid). Guia |
Toda criação de cobrança e de checkout aceita, opcionalmente:
callback_url, um endereço https que recebe os eventos daquela cobrança;cost_center_id, para classificar a cobrança num centro de custo.
Pix, boleto, Boleto Pix e cartão aceitam também split_rule_id, para dividir o valor da cobrança com os participantes de uma regra de split. Veja Split por regra.
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; com method, troca a forma de pagamento dos próximos ciclos entre cartão, Pix e boleto. |
GET /v1/subscriptions/{id}/cycles |
transactions:read |
Lista os ciclos e a cobrança de cada um. |
PUT /v1/subscriptions/{id}/credit-card |
credit_card:write |
Troca o cartão salvo, com nova autorização do pagador; numa assinatura de Pix ou boleto, passa os próximos ciclos para o cartão. Nada é cobrado na troca. |
POST /v1/subscriptions/{id}/cycles/{cycle}/retry |
escrita do método | Cobra de novo um ciclo com débito recusado: no cartão salvo ou, com method, por Pix ou boleto só naquele ciclo. Exige Idempotency-Key. |
POST /v1/subscriptions/{id}/cycles/advance |
escrita do método | Só no modo de teste: emite agora o próximo ciclo, com o vencimento e o valor do calendário, sem esperar a data. |
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.
Split por regra
Uma regra de split divide o valor de uma cobrança entre a sua empresa e outras empresas com cadastro no Calebe. As regras e os participantes são cadastrados no portal, em Empresa › Split de pagamento; a API usa a regra pronta.
| Operação | Escopo | O que faz |
|---|---|---|
GET /v1/split-rules |
transactions:read |
Lista as regras da empresa da chave, com as partes de cada participante. |
Para dividir uma cobrança, envie split_rule_id na criação de Pix, boleto, Boleto Pix ou cartão. Quando a cobrança é paga, a parte de cada participante vai direto para a conta dele, e o que sobra fica com a sua empresa.
- A parte é um percentual do valor da cobrança ou um valor fixo. A regra diz se a sua empresa paga a tarifa inteira (
fee_mode: "issuer") ou se cada participante paga na proporção da parte dele ("shared"). - A cobrança devolve a divisão em
split.rule: o nome da regra,participants_amounte o valor de cada participante.split.merchant_amountjá vem sem essas partes. - A divisão é fixada na criação: mudar a regra depois não altera cobrança já emitida.
- Recusas
422:invalid_split_rule,split_participant_unavailable,split_participant_not_ready,split_part_too_small,split_exceeds_amountesplit_rule_not_supported(vales, Pix Automático, assinaturas e checkout não aceitam regra). - O estorno de uma cobrança real dividida por regra ainda não é feito pela API (
422 refund_split_unsupported): fale com o suporte.
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 |
Tarifas, parcelamento e conta
As operações abaixo exigem chave padrão com os novos escopos selecionados explicitamente. Chaves antigas não ganham permissões. Chaves de perfil developer e chaves atribuídas a usuários com visibilidade financeira restrita não acessam essas operações. Veja o contrato e os exemplos.
| Operação | Escopo | O que faz |
|---|---|---|
GET /v1/subtenants/{id} |
subtenants:read |
Consulta o cadastro básico de um descendente e a situação da conta de recebimento dele (subaccount_status). |
GET /v1/subtenants/{id}/fees |
subtenants:fees:read |
Lista os adicionais próprios do descendente, com paginação. |
POST /v1/subtenants/{id}/fees |
subtenants:fees:write |
Cadastra uma vigência de taxa: adicional (soma com a sua taxa) ou, com mode: "fixed", taxa fixa (o descendente paga só esse valor). Com percentual, aceita min_amount e max_amount: o mínimo e o máximo da taxa por cobrança. |
PATCH /v1/subtenants/{id}/fees/{feeId} |
subtenants:fees:write |
Substitui o valor fixo e, opcionalmente, o percentual e o modo. |
DELETE /v1/subtenants/{id}/fees/{feeId} |
subtenants:fees:write |
Exclui somente uma vigência futura. |
GET /v1/fees |
fees:read |
Consulta totais por método e frequência de repasse. |
GET /v1/credit-card/installments |
fees:read |
Consulta condições remotas e tarifas locais por parcelas. |
GET /v1/account |
account:read |
Consulta valores recebidos, previstos e cancelados no período. |
GET /v1/account/payouts |
account:read |
Lista repasses bancários. |
GET /v1/account/payouts/{date} |
account:read |
Consulta o extrato do repasse de uma data. |
GET /v1/account/bank |
account:read |
Consulta a conta bancária de repasse. |
PUT /v1/account/bank |
account:bank:write |
Troca a conta bancária de repasse. Guia |
GET /v1/account/transfers |
account:read |
Lista transferências de produção. |
GET /v1/account/transfers/{transferID} |
account:read |
Consulta uma transferência salva. |
POST /v1/account/transfers |
account:transfers:write |
Solicita transferência com Idempotency-Key. |
POST /v1/account/transfers/{transferID}/refresh |
account:transfers:write |
Consulta a confirmação, sem reenviar a transferência. |
Em /v1/fees, /v1/credit-card/installments e /v1/account e suas subrotas, tenant_id na query seleciona uma empresa da sua árvore; omitido, usa a empresa da chave. A consulta local de tarifas aceita teste. Alterar tarifas ou consultar o provedor exige produção; uma chave de teste nunca lê a conta real nem movimenta dinheiro. Consultas financeiras não comprovam saldo disponível ou prazo de liquidação.
Notas fiscais
Tudo o que o painel faz com notas fiscais de serviço (NFS-e), a integração faz por chave de API: cadastrar o emitente, enviar o certificado digital, ligar a emissão, emitir, acompanhar, baixar e cancelar. A empresa é sempre a da chave.
| Operação | Escopo | O que faz | |
|---|---|---|---|
GET /v1/fiscal/issuer |
invoices:read |
Mostra o emitente e o que falta para emitir (ready, detail). |
|
PUT /v1/fiscal/issuer |
invoices:issuer:write |
Cadastra ou atualiza a empresa emitente e o perfil fiscal. | |
PUT /v1/fiscal/issuer/certificate |
invoices:issuer:write |
Envia o certificado A1 (.pfx em base64) e a senha. |
|
GET /v1/fiscal/settings |
invoices:read |
Consulta se a emissão está ligada e o gatilho automático. | |
GET /v1/fiscal/terms |
invoices:read |
Devolve o termo de adesão à emissão e se a empresa já aceitou. | |
PUT /v1/fiscal/settings |
invoices:issuer:write |
Liga a emissão e escolhe o gatilho: manual, na criação da cobrança ou no pagamento. Ligar pede o aceite do termo de adesão. | |
POST /v1/invoices |
invoices:write |
Emite uma nota, de uma cobrança (transaction_id) ou avulsa. |
|
GET /v1/invoices |
invoices:read |
Lista as notas, com status e q. |
|
GET /v1/invoices/{id} |
invoices:read |
Consulta uma nota. | |
POST /v1/invoices/{id}/refresh |
invoices:read |
Consulta agora a situação na prefeitura, sem reenviar. | |
POST /v1/invoices/{id}/cancel |
invoices:write |
Cancela uma nota autorizada (reason, 15 a 255 caracteres). |
|
| `GET /v1/invoices/{id}/document?format=pdf\ | xml` | invoices:read |
Baixa o PDF ou o XML. |
Retenções do tomador vão em withholdings, no POST /v1/invoices, e são opcionais: iss_withheld (o tomador retém o ISS inteiro da nota) e irrf, inss, pis, cofins e csll, em centavos. A soma dos federais precisa ficar abaixo do valor do serviço. A nota devolve o que foi pedido em withholdings e o valor líquido em net_amount. As alíquotas são responsabilidade da empresa: confirme com a contabilidade.
{ "customer": { "name": "Cliente Ltda", "document": "11.444.777/0001-61", "zip_code": "01001-000", "street": "Praça da Sé", "number": "1", "district": "Sé", "city": "São Paulo", "state": "SP" },
"description": "Consultoria em tecnologia", "amount": 100000,
"withholdings": { "irrf": 1500, "pis": 650, "cofins": 3000, "csll": 1000 } }
A ordem para começar a emitir:
PUT /v1/fiscal/issuercom o CNPJ, a razão social, a inscrição municipal, o regime tributário, o endereço e o serviço (código de serviço do município e alíquota de ISS), a série de RPS e o ambiente. Comece por"environment": "homologation".PUT /v1/fiscal/issuer/certificatecom o certificado A1 do mesmo CNPJ. É ele que comprova a titularidade e libera a emissão. O arquivo e a senha não são gravados pelo Calebe Pay e não aparecem no registro de chamadas.GET /v1/fiscal/termspara ler o termo de adesão à emissão: ele explica a responsabilidade fiscal e contábil da empresa e a tarifa por nota emitida (fee_cents). A tarifa de cada nota autorizada depois do aceite entra na próxima cobrança da empresa e é descontada quando ela é paga: a cobrança mostra quanto levou eminvoice_fee_amount, fora deretained_amount, e o termo mostra quantas notas ainda aguardam a tarifa empending_fee_countepending_fee_amount.PUT /v1/fiscal/settingscom"enabled": true, oauto_triggere o aceite do termo:"terms": { "version": "…", "hash": "…", "accepted": true }, com a versão e o hash lidos no passo anterior. Sem o aceite a resposta é422 invoice_terms_required. O aceite fica registrado e vale para a versão: religar a emissão depois não pede de novo.POST /v1/invoices. A nota volta emprocessinge a prefeitura autoriza em seguida; consulte porGET /v1/invoices/{id}.
curl -X PUT https://api.calebepay.com.br/v1/fiscal/issuer \
-H "X-API-Key: $CALEBE_API_KEY" -H "Content-Type: application/json" \
-d '{
"document": "11.222.333/0001-81", "legal_name": "Loja Integrada Ltda", "municipal_registration": "12345678",
"tax_regime": "lucro_presumido", "email": "fiscal@loja.com.br",
"address": { "street_type": "Avenida", "street": "Paulista", "number": "1000", "district": "Bela Vista",
"city": "São Paulo", "city_code": "3550308", "state": "SP", "zip_code": "01310-100" },
"service": { "code": "02660", "iss_rate": 2.9 },
"rps_series": "NF", "environment": "homologation"
}'
O que vale saber:
- Os dados fiscais são da empresa. Código de serviço, alíquota, regime e série de RPS vão como você enviar; o Calebe Pay confere o formato, não o enquadramento. Confirme com a contabilidade.
- Homologação e produção. Em homologação a prefeitura valida a nota sem valor fiscal; em alguns municípios (São Paulo) ela só valida o RPS e a nota volta com
homologation_only: true, sem número, PDF, XML ou cancelamento. Para emitir de verdade, reenvie o cadastro com"environment": "production"erps_next_number. Produção não volta para homologação. - Série de RPS. Se a empresa já emite por outro sistema ou pelo site da prefeitura, use uma série diferente da de lá.
- Chave de teste. Lê tudo, cadastra e emite em homologação. Com o emitente em produção, criar ou cancelar nota exige chave de produção (
403 live_key_required). - Um emitente por empresa, um dono por CNPJ. Outro CNPJ na mesma empresa retorna
409 issuer_already_registered; um CNPJ já comprovado por outra conta retorna409 issuer_owned_by_another_account. - Também pelo painel. O mesmo cadastro está em Dados da empresa → Dados cadastrais → Emitente fiscal.
- Cadastro mantido pelo suporte. Se a empresa foi ligada a um emitente pelo suporte, estas rotas de cadastro respondem
409 issuer_managed_by_platform; emitir e consultar funcionam normalmente.
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), updated_since (data e hora RFC 3339 com fuso: só o que mudou de status desde então), 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 ou quando uma assinatura emite um ciclo:
transaction.created: a cobrança foi registrada;transaction.updated: o status mudou, comprevious_status.subscription.cycle_created: uma assinatura emitiu um ciclo, com o link do pagador.
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:
- os endpoints cadastrados no painel recebem todos os eventos da conta no modo deles;
- o
callback_urlde uma cobrança recebe os eventos dela.
A assinatura, as retentativas e o corpo de cada evento estão em Receber eventos por webhook.
Contrato, SDK e saúde
GET /health: o serviço está respondendo. Não exige chave.openapi.json: o contrato OpenAPI 3.1 de todas as operações acima.llms.txt: as regras da integração resumidas para agentes de IA.- SDK TypeScript
@calebe-pay/sdk: um método para cada operação, com validação local antes da rede. Veja SDK TypeScript.
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. |
| Editar dados da empresa e enviar documentos | Exige sessão administrativa. Cadastro básico e consultas financeiras possuem rotas públicas específicas acima. |
| Provedores, regras de roteamento, cadastro de subcontas e tarifas dos níveis superiores | Administração da plataforma. A API pública gerencia somente o adicional dos descendentes. |
Para essas operações, entre no painel ou no app Calebe Pay com um usuário que tenha a permissão.