# CasePay API

> Plataforma de cobrancas PIX via Conta PIX.

## PIX manual

Endpoint: `POST /api/v1/manual-pix`.

Escopo selecionável: `manual-pix`. Ele não é concedido automaticamente.

`pixKey` aceita somente chaves DICT válidas: CPF, CNPJ, telefone, e-mail ou EVP. Chave CNPJ: 14 caracteres, numérica ou alfanumérica (modelo novo, como 12ABC34501DE35), com ou sem máscara; a API guarda sem máscara e em maiúsculas. `receiverName` tem máximo 25 e `city` tem máximo 15. `transactionId` é alfanumérico, tem máximo 25 e, quando omitido, usa `***`. `amount` é opcional, deve ser positivo, ter no máximo 2 casas decimais e ser menor ou igual a 9.999.999.999,99. No Sicoob, `customerName` tem máximo 200.

### code_only
Request:

```json
{"mode":"code_only","pixKey":"financeiro@empresa.com.br","receiverName":"Empresa Ltda","city":"Sao Paulo"}
```

Response 200:

```json
{"mode":"code_only","pix_code":"000201..."}
```

### qr_only
Request:

```json
{"mode":"qr_only","pixKey":"financeiro@empresa.com.br","receiverName":"Empresa Ltda","city":"Sao Paulo"}
```

Response 200:

```json
{"mode":"qr_only","qr_code_data_url":"data:image/png;base64,..."}
```

### both
Request:

```json
{"mode":"both","pixKey":"financeiro@empresa.com.br","receiverName":"Empresa Ltda","city":"Sao Paulo","amount":149.9}
```

Response 200:

```json
{"mode":"both","pix_code":"000201...","qr_code_data_url":"data:image/png;base64,..."}
```

### link
```http
Idempotency-Key: pedido-1001-manual
```

Request:

```json
{"mode":"link","pixKey":"financeiro@empresa.com.br","receiverName":"Empresa Ltda","city":"Sao Paulo","domain":"canonical"}
```

Response 201:

```json
{"mode":"link","id":"550e8400-e29b-41d4-a716-446655440000","pay_url":"https://meu.casepay.com.br/pay/550e8400-e29b-41d4-a716-446655440000","canonical_pay_url":"https://meu.casepay.com.br/pay/550e8400-e29b-41d4-a716-446655440000","receipt_received":false}
```

Somente o modo link exige Idempotency-Key; os demais modos são stateless. `link` retorna 201; os demais modos retornam 200. `domain` só existe em `link` e aceita canonical, casepay_subdomain ou custom. O padrão é `canonical`; não aceita hostname arbitrário.

O PIX manual fica sem confirmação bancária: não há status pago nem conciliação. Um comprovante não confirma o pagamento. No link, o webhook `manual_pix/receipt_received` avisa quando o pagador envia um comprovante e `manual_pix/receipt_removed`, quando a equipe o remove; eles tratam do comprovante, não do pagamento.

Upload opcional: `POST /api/pay/[id]/receipt`, multipart `receipt`, PNG, JPEG ou PDF até 4 MiB. Sem `Content-Length`: 411; acima do limite: 413; MIME ou magic bytes incompatíveis: 415.

A resposta pública contém somente `receipt_received`. O público não pode visualizar nem baixar. A equipe usa GET e DELETE autenticados em `/api/workspaces/[wsId]/manual-pix/[id]/receipt`.

### Erros do PIX manual

| Status | Quando acontece |
|--------|-----------------|
| 400 | Validação ou Idempotency-Key inválido |
| 401 | API key ou sessão ausente/inválida |
| 403 | Escopo, workspace, acesso ou feature indisponível |
| 404 | Recurso ou link não encontrado |
| 409 | Idempotência ou comprovante em conflito |
| 411 | Content-Length ausente |
| 413 | Tamanho acima do limite |
| 415 | MIME ou magic bytes incompatíveis |
| 422 | Domínio não configurado ou não verificado |
| 429 | Rate limit |
| 500 | Configuração, banco ou Storage indisponível |

## Docs

- [Central da documentação](/docs): escolha o fluxo e comece a integração
- [Autenticação](/docs/autenticacao): API keys, escopos e idempotência
- [PIX manual](/docs/pix-manual): código, QR Code ou link sem confirmação bancária
- [PIX Instantâneo](/docs/pix-instantaneo): cobrança com status e conciliação
- [Webhooks](/docs/webhooks): eventos, assinatura e reconciliação
- [Referência da API](/docs/referencia): índice das operações públicas
- [Swagger UI](/docs/swagger): referência OpenAPI navegável
- [OpenAPI JSON](/api/docs/openapi): contrato OpenAPI 3.1
- [Guia de Integracao](/api/docs/md): PIX Instantaneo
- [Referencia da API](/api/docs/referencia/md): Endpoints da API v1

## API v1 Overview

Base URL: https://meu.casepay.com.br/api/v1
Auth: Bearer token via header Authorization
Nao envie x-api-user-id, x-api-key-id ou x-api-workspace-id manualmente; a API key define o contexto e o proxy injeta esses headers internamente.

## Horários

Todo horário das respostas da API v1 e dos webhooks vem em ISO 8601 no horário de Brasília (UTC−03:00), por exemplo `2026-09-30T21:15:00-03:00`. É o mesmo instante de antes: quem lê com um parser ISO não precisa mudar nada. Datas sem hora (`AAAA-MM-DD`, como `start_date` e `scheduled_date`) são o dia em Brasília e não mudam.

Nas entradas, data e hora sem fuso (`2026-12-31T23:59:00`) valem no horário de Brasília; com `Z` ou `-03:00`, valem aquele instante. Uma data sem hora (`AAAA-MM-DD`) é o dia em Brasília. A repetição de uma `Idempotency-Key` devolve o mesmo corpo da primeira resposta, também com os horários em Brasília.

Nos webhooks, os horários do corpo também saem em `-03:00`. A assinatura é calculada sobre o corpo exatamente como é enviado; `X-Webhook-Timestamp` e o `t=` da assinatura continuam em segundos Unix, sem fuso, e o `eventId` não muda. Os cabeçalhos HTTP seguem o padrão do protocolo: `Date` é sempre em GMT e `Retry-After` vem em segundos.

## CPF e CNPJ

O CPF tem 11 números. O CNPJ tem 14 caracteres e pode ser numérico (modelo antigo, como `11222333000181`) ou alfanumérico (modelo novo da Receita Federal, como `12ABC34501DE35`): as 12 primeiras posições aceitam números e letras (A a Z) e os dois últimos caracteres são sempre números.

Envie com ou sem máscara (`12.ABC.345/01DE-35`), em maiúsculas ou minúsculas. A API confere os dígitos verificadores, guarda o documento sem máscara e em maiúsculas e devolve assim (`12ABC34501DE35`). Campos de CPF continuam só numéricos.

## Endpoints API v1

- POST /api/v1/payments - Criar cobranca PIX Instantaneo e retornar pay_url /pay

## Webhooks

Configure a URL do webhook no painel (menu Webhooks). Cada aviso é um POST JSON com `event`, `eventId` e `paymentRequestId`, assinado com `X-Webhook-Signature-V2` quando houver segredo configurado.

| Evento | Origem | Quando |
|--------|--------|--------|
| payment_intent/completed | PIX pela conta Sicoob | Cobrança paga, confirmada pelo banco (provider: sicoob). |
| payment_request/updated | PIX pela conta Sicoob | Cobrança expirada (EXPIRED), cancelada (CANCELED) ou com erro (ERROR). |
| manual_pix/receipt_received | PIX manual (link com comprovante) | O pagador enviou um comprovante. Não confirma o pagamento. |
| manual_pix/receipt_removed | PIX manual (link com comprovante) | A equipe removeu o comprovante e reabriu o envio. |

`paymentRequestId` é o identificador devolvido na criação: `payment_id` do PIX pela conta Sicoob, `id` do link de PIX manual e `payment_request_id` do Open Finance.

`provider` indica a origem do aviso: `sicoob`, `manual` ou `pluggy` (Open Finance). Campos novos podem ser acrescentados; ignore os que não conhecer.

Valores em `amount` são centavos inteiros (`14990` representa R$ 149,90).

Horários seguem ISO 8601 no horário de Brasília (UTC−03:00), por exemplo `2026-09-30T11:32:00.000-03:00`. É o mesmo instante de antes: quem lê com um parser ISO não precisa mudar nada. Datas sem hora (`AAAA-MM-DD`, como `date` no PIX Automático) são o dia em Brasília.

A assinatura é calculada sobre o corpo exatamente como é enviado, já com os horários em `-03:00`: valide sobre o corpo bruto, sem reescrevê-lo. `X-Webhook-Timestamp` e o `t=` da assinatura continuam em segundos Unix, sem fuso, e o `eventId` não muda.

No PIX pela conta Sicoob, `payment_request/updated` usa `status` `EXPIRED`, `CANCELED` ou `ERROR`; `GET /api/payments/{payment_id}/status` mostra `expired`, `canceled` ou `failed`. Uma cobrança paga depois de expirar gera os dois avisos, e o pagamento vale. Falha ao criar a cobrança volta na resposta da criação e não gera aviso. Devolução não gera aviso.

No PIX manual, os avisos tratam do comprovante, não do pagamento: o PIX manual continua sem confirmação bancária. Confira o crédito no extrato antes de liberar o pedido.

Os avisos saem em até alguns minutos e podem chegar repetidos ou fora de ordem: use `eventId` para processar cada um uma vez e consulte o status quando precisar do estado atual.

```json
{
  "event": "payment_intent/completed",
  "eventId": "5c3f2a1e-8d4b-5f6a-9e7c-2b1d0a9f8e7d",
  "paymentRequestId": "550e8400-e29b-41d4-a716-446655440098",
  "provider": "sicoob",
  "status": "completed",
  "amount": 14990,
  "paidAt": "2026-09-30T11:32:00.000-03:00",
  "endToEndId": "E75608532202609301432Ab12Cd34Ef5"
}
```

```json
{
  "event": "manual_pix/receipt_received",
  "eventId": "7d2e4f60-9a1b-5c3d-9e8f-0a1b2c3d4e5f",
  "paymentRequestId": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "manual",
  "amount": 2500,
  "receiptReceivedAt": "2026-09-30T11:40:00.000-03:00"
}
```

## Erros

- 400: Dados invalidos
- 401: API key invalida ou ausente
- 403: chave sem workspace, escopo ausente ou recurso nao habilitado no workspace
- 404: Recurso nao encontrado
- 409: operacao em andamento ou estado ambiguo
- 422: Operacao invalida para o status atual
- 429: Rate limit excedido
- 502: Erro no provedor