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.
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:

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.

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.

json
{ "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:

  1. PUT /v1/fiscal/issuer com 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".
  2. PUT /v1/fiscal/issuer/certificate com 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.
  3. GET /v1/fiscal/terms para 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 em invoice_fee_amount, fora de retained_amount, e o termo mostra quantas notas ainda aguardam a tarifa em pending_fee_count e pending_fee_amount.
  4. PUT /v1/fiscal/settings com "enabled": true, o auto_trigger e 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.
  5. POST /v1/invoices. A nota volta em processing e a prefeitura autoriza em seguida; consulte por GET /v1/invoices/{id}.
bash
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:

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:

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.
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.