# 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`](./openapi.json); o passo a passo da primeira integração, em [`integration.md`](./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-Key` com 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. Chaves `cp_live_` (ou `cp_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](./integration.md#4-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) e `offset`. `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. |
| `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](./integration.md#3-criar-a-primeira-transação) |
| `POST /v1/boleto` | `boleto:write` | Cria um boleto com vencimento, multa, juros e um Pix do mesmo valor junto. [Guia](boleto.md) |
| `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](./integration.md#cartão-de-crédito-pela-api) |
| `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](operations.md#estornos-e-vencimento) |
| `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](operations.md#estornos-e-vencimento) |
| `POST /v1/checkouts` | escrita de cada forma oferecida | Cria um link em que quem paga escolhe Pix, boleto ou cartão. [Guia](./integration.md#checkout-quem-paga-escolhe-pix-boleto-ou-cartão) |
| `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](./operations.md#json-de-criação-e-corpo-preparado-para-envio) |
| `POST /v1/transactions/{id}/refresh` | `transactions:read` + escrita do método | Consulta o provedor e atualiza o estado. [Guia](./operations.md#como-o-refresh-se-comporta) |
| `POST /v1/transactions/{id}/simulate` | `transactions:read` + escrita do método | Só com chave de teste: simula pagamento (`paid`) ou expiração (`expired`). [Guia](./integration.md#teste-antes-de-cobrar) |

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.

## 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](subscriptions.md).

## 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](./integration.md#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](./integration.md#cadastrar-subtenant-e-converter-a-subconta) |
| `GET /v1/subtenants` | `subtenants:read` | Lista os filhos diretos; com `include_descendants=true`, toda a árvore abaixo. [Guia](./integration.md#listar-subtenants) |
| `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](./integration.md#gerar-uma-chave-de-api-para-um-subtenant) |

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

- `transaction.created`: a cobrança foi registrada;
- `transaction.updated`: o status mudou, com `previous_status`.

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_url` de uma cobrança recebe os eventos dela.

A assinatura, as retentativas e o corpo de cada evento estão em [Receber eventos por webhook](./integration.md#receber-eventos-por-webhook).

## Contrato, SDK e saúde

- `GET /health`: o serviço está respondendo. Não exige chave.
- [`openapi.json`](./openapi.json): o contrato OpenAPI 3.1 de todas as operações acima.
- [`llms.txt`](./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](./integration.md#8-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. |
| 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](https://app.calebepay.com.br) ou no app Calebe Pay com um usuário que tenha a permissão.