# FullCash — Guia de Integração (Contas a Pagar e Arquivos)

> Guia para desenvolvedores (e para IAs geradoras de código) entenderem como
> integrar um sistema externo ao **Contas a Pagar do FullCash**.
>
> A API é o **espelho do papel cliente**: você pode **ver** o que um cliente vê e
> **criar** o que um cliente cria — nada além. O fluxo (validar, devolver,
> rejeitar) é do operador FullCash e **não** existe na API. O passo do cliente —
> **reenviar para análise** uma conta em Pendência — existe — veja
> [Fases de um lançamento](#fases-de-um-lancamento).

## Base URL

```
https://api.fullcashbpo.com    endereço da API
/api/v1                        prefixo de todos os endpoints
/docs                          Swagger UI (testar no navegador)
/openapi.json                  contrato OpenAPI
/agente                        base completa para IAs geradoras de código
```

## Autenticação

Toda chamada em `/api/v1/*` exige a chave no header:

```
Authorization: Bearer fc_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

- As chaves são **emitidas pela equipe FullCash** (o cliente não cria chave).
- Cada chave enxerga **uma ou mais empresas liberadas** — nunca outra empresa,
  nunca outro módulo.
- Guardamos só o hash da chave. Se perder, geramos outra.
- Toda chave tem um **usuário de integração** próprio (`integration_user_id`): um usuário
  técnico, **sem login**, com o nome que a FullCash definir (ex.: "Extranet Cliente X"). Ele
  assina o que a chave cria. Você não cria nem gerencia usuários pela API.

Headers usados na integração:

| Header | Direção | Para quê |
|---|---|---|
| `Authorization` | você → API | `Bearer fc_live_...` em toda chamada |
| `X-FullCash-Company` | você → API | empresa-alvo quando a chave tem várias |
| `Idempotency-Key` | você → API | no `POST /contas-pagar`, evita duplicar |
| `x-request-id` | API → você | id da requisição (mande para o suporte) |
| `Retry-After` | API → você | quantos segundos esperar depois de um `429` |
| `X-FullCash-Event` / `X-FullCash-Delivery` / `X-FullCash-Signature` | FullCash → seu webhook | nome do evento, id da entrega e assinatura |

### Escolhendo a empresa

Se a chave acessa **uma** empresa, ela é implícita. Se acessa **mais de uma**,
informe a empresa-alvo em cada request, por uma destas vias (nesta ordem):

1. Header `X-FullCash-Company: <company_id>`
2. Campo `company_id` no corpo (POST)
3. Query `?company_id=<company_id>`

Empresa fora do conjunto liberado → `403 empresa_nao_liberada`.

**Rotas de um lançamento** (`/contas-pagar/{id}`, `/mensagens`, `/anexos`) **não precisam**
da empresa: a API acha sozinha a dona do lançamento entre as empresas da chave. Se você
informar, ela é respeitada (empresa errada → `404`). Não chute empresa por empresa.

### Homologação

Não existe ambiente separado: a homologação é feita na **mesma API**, com uma chave
de teste que só enxerga **empresas de teste** (sem lançamento real nem operador real
envolvido). Teste o fluxo completo nela — criar, anexar, conversar no chat e receber os
webhooks — e só então passe a usar a chave das empresas reais. Os IDs (contas,
fornecedores, centros…) de uma empresa **não valem** em outra: os da homologação
respondem `404`/`422` com a chave de produção.

## Escopos

A chave carrega escopos; sem o escopo, a resposta é `403 forbidden_scope`.

| Escopo | Libera |
|---|---|
| `contas_pagar:read` | listar/consultar lançamentos |
| `contas_pagar:write` | criar lançamento |
| `cadastros:read` | fornecedores, plano de contas, centros, contas bancárias, usuários, tipos de documento, regras de upload |
| `chat:read` / `chat:write` | ler / escrever no chat da conta |
| `anexos:read` / `anexos:write` | listar / enviar anexos (anexo numa mensagem exige `chat:write` e `anexos:write`) |
| `arquivos:read` | ler e baixar os arquivos de **todos os módulos** (anexos, chat e pastas da equipe) |

## Endpoints

### Meta
- `GET /api/v1/me` — empresas liberadas, escopos e rate limit da chave.

### Lançamentos
- `GET /api/v1/contas-pagar` — lista, da `data` mais recente para a mais antiga. Filtros:
  `busca` (parte do título ou do código, ex.: `CP2026`), `status_documento`, `fornecedor_id`,
  `data_de`, `data_ate`, `valor_min`, `valor_max`, `page`, `size`.
- `POST /api/v1/contas-pagar` — cria (ver corpo abaixo). **Idempotente** com header
  `Idempotency-Key`.
- `GET /api/v1/contas-pagar/{id}` — consulta um lançamento.
- `POST /api/v1/contas-pagar/{id}/reenviar-analise` — **responde a Pendência**: a conta
  volta de `pendencias` para `em_analise` (o botão "Reenviar para análise" da tela).
  Corpo opcional: `mensagem` (a resposta, vai pro chat antes do aviso; precisa de
  `chat:write`) e `autor_externo` **ou** `user_id` (quem reenviou). O chat ganha o aviso
  "🔄 Conta Reenviada para Análise", a equipe é notificada e sai `conta.mudou_fase`.
  Responde `200 { conta, mensagem }`. Conta em outra fase → `409 conta_fora_de_pendencia`
  (`details.status_documento`; `em_analise` = já foi reenviada, não repita). Escopo
  `contas_pagar:write`. **Só escrever no chat não tira a conta da Pendência.**
- `POST /api/v1/contas-pagar/analisar-documento` — **leitura por IA** de NF/boleto
  (`multipart/form-data`, campo `file`; PDF ou imagem JPEG/PNG/WebP; opcional
  `tipo_transacao` = `saida` (padrão) ou `entrada`). Devolve os campos extraídos (valor,
  datas, nº do documento, meio de pagamento, parcelamento…) e as sugestões já resolvidas:
  `fornecedor.fornecedor_id` (quando o CNPJ/CPF casa com o cadastro) e
  `plano_conta_sugerido.plano_conta_id`. **Não cria nada** — use o retorno para montar o
  `POST /contas-pagar` (e confira antes de enviar). Escopo `contas_pagar:write`.
  Erros: `422 documento_ilegivel`, `502 ia_indisponivel` / `ia_falhou`.

### Cadastros de apoio (para mandar IDs válidos)
- `GET /api/v1/cadastros/fornecedores?termo=` — da empresa + gerais.
- `GET /api/v1/cadastros/plano-contas?termo=` — só folhas (`nivel=conta`).
- `GET /api/v1/cadastros/centros-custo` — só os vinculados à empresa.
- `GET /api/v1/cadastros/contas-bancarias` — só as da empresa.
- `GET /api/v1/cadastros/usuarios` — usuários ativos da empresa (sem e-mail). Só é
  necessário se você for usar `user_id` no chat; para o caso comum, use `autor_externo`.
- `GET /api/v1/cadastros/tipos-documento` — listas fechadas de **tipo de documento** e
  **meio de pagamento** aceitas no lançamento (mesmas da tela do FullCash).
- `GET /api/v1/cadastros/upload-regras` — tamanho máximo (hoje 10 MB) e formatos/MIME
  aceitos nos anexos da conta e do chat. Consulte antes de enviar arquivo.

### Chat da conta
- `GET /api/v1/contas-pagar/{id}/mensagens`
- `POST /api/v1/contas-pagar/{id}/mensagens` — corpo `{ "message": "...", "autor_externo": { "nome": "..." } }`.
  Conta **finalizada** (`status_documento` = `validado`, rótulo "Finalizado") é **somente
  consulta**, igual na tela: mensagem nova → `409 conta_finalizada` (a FullCash reabre se precisar).

  **Quem é o autor.** Toda chave tem um **usuário de integração** próprio (sem login, nome
  definido pela FullCash, ex.: "Extranet Cliente X") que assina o que chega pela API. Pra dizer
  quem escreveu de verdade:

  | Caso | O que mandar | Aparece no FullCash como |
  |---|---|---|
  | **Recomendado** — qualquer pessoa do seu sistema | `autor_externo` (só `nome` é obrigatório) | "Murillo Guimarães · via Extranet Cliente X" |
  | Opcional — a pessoa tem conta no FullCash e você quer que conte como dela | `user_id` (de `GET /cadastros/usuarios`, vinculado à empresa) | "Murillo Guimarães", igual a uma mensagem da tela |
  | Nenhum dos dois | — | "Extranet Cliente X" |

```json
{ "message": "Pode seguir com o pagamento",
  "autor_externo": { "nome": "Murillo Guimarães", "email": "murillo@cliente.com", "id": "id-no-seu-sistema" } }
```

  Não precisa criar nem mapear usuário pra usar o `autor_externo`. `user_id` e
  `autor_externo` juntos → `422`; `user_id` que não é da empresa → `422`. O `GET /mensagens`
  devolve `autor_externo` em cada mensagem (ou `null`), da mais antiga para a mais nova.
  Mensagens com `message_type` diferente de `user` são avisos automáticos do FullCash (ex.:
  mudança de fase) — mostre como aviso, não como conversa.
  Chave antiga sem usuário de integração e sem `user_id` → `422` (peça pra FullCash configurar).
- `POST /api/v1/contas-pagar/{id}/mensagens/{msgId}/anexos` — anexa um arquivo a uma
  mensagem do chat (`multipart/form-data`, campo `file`). É **o caminho para mandar
  arquivo depois que a conta já foi criada**. Escopos `chat:write` + `anexos:write`.
  **Só na mensagem que a sua chave acabou de mandar, até 2 minutos depois dela.** Mensagem
  antiga, escrita pelo operador na tela ou de outra chave → `409 anexo_fora_da_janela`
  (`details.motivo`: `janela_expirada` ou `mensagem_de_outra_origem`): mande uma mensagem
  nova com o arquivo. Conta finalizada (`status_documento` = `validado`) →
  `409 conta_finalizada`. Fluxo: `POST /mensagens` → pega o `id` → anexa logo em seguida.

### Anexos
- `GET /api/v1/contas-pagar/{id}/anexos` — devolve URLs assinadas temporárias.
- **Visualizar sem baixar (`preview_url`)** — todo anexo de imagem (JPG, PNG, WebP, GIF) ou
  PDF, aqui e nos anexos de `GET /mensagens`, traz um `preview_url`: link **fixo**, válido por
  **30 dias** e enquanto a chave estiver ativa. Use direto em `<img src>` / `<iframe src>`
  (não leva `Authorization`) — o arquivo não precisa trafegar pela sua integração nem ser
  guardado de novo do seu lado. Revogou a chave → todos os links dela param. Outros tipos vêm
  com `preview_url: null` (use o `url`, 1 h).
- `GET /api/v1/anexos/{id}/ver?t=<token>` — é a rota do `preview_url` (venha sempre pelo link
  pronto; não monte o token `t`). Respostas: `302` para o arquivo · `404` sem dizer o motivo
  (token inválido, chave revogada ou anexo de outra empresa) · `410 link_expirado` (passou dos
  30 dias — busque um link novo no `GET /mensagens` ou `GET /anexos`).
- `POST /api/v1/contas-pagar/{id}/anexos` — `multipart/form-data`, campo `file`.
  **Só na criação:** até **2 minutos** depois de criada a conta. Passou disso →
  `409 anexo_apos_lancamento`; envie o arquivo pelo chat (escreva a mensagem e anexe em
  `/mensagens/{msgId}/anexos`). Exige que a chave tenha **usuário de integração**
  configurado (senão `422`).

Fluxo recomendado para criar com documento: `POST /contas-pagar` → logo em seguida
`POST /contas-pagar/{id}/anexos` com a NF/boleto.

### Arquivos (todos os módulos, só leitura e download)
Os anexos e os arquivos enviados nos chats de **todos os módulos** (Fechamento de Caixa,
Cofre, Contas a Pagar, Agendamento, Conciliação, Solicitações) e as pastas criadas pela
equipe, no mesmo modelo do módulo de Arquivos do FullCash: **as pastas param no ano**
(Módulo → Ano) e, dentro do ano, vem a **lista com filtros**. Escopo `arquivos:read`.

- `GET /api/v1/arquivos/pastas` — sem parâmetros: os módulos; com `modulo`: os anos. Cada item
  traz `filtro`; o do ano (`{ modulo, ano }`) vai direto na lista e nas facetas.
- `GET /api/v1/arquivos` — lista paginada (`page`, `size` até 200). Filtros combináveis:
  `modulo` + `ano` (+ `mes`, ou `dia` = `AAAA-MM-DD`), `registro_tipo` + `registro_id`,
  `pasta_id` (+ `incluir_subpastas=true`), `origem` (`arquivos` = anexo, `chat` = enviado numa
  mensagem), `enviado_por` (id de quem enviou), `busca` (parte do nome do arquivo) e período
  `desde`/`ate`. Ordem: `ordem` = `enviado_em` (padrão, mais recentes primeiro), `data` (data do
  registro — use para separar por mês/dia como a tela), `nome`, `tamanho`, `registro` ou `por`;
  `desc=false` inverte. Traz `total` e `total_bytes` do filtro inteiro. **Sem link de download.**
- `GET /api/v1/arquivos/facetas?modulo=&ano=` (ou `?pasta_id=`) — as opções dos filtros com
  contagem: meses, registros, quem enviou e origens. Monte os seus filtros a partir dela.
- `GET /api/v1/arquivos/{id}` — um arquivo, com `url` assinada válida por 1 hora.
- `POST /api/v1/arquivos/zip` — **baixa vários de uma vez** num `.zip`. Corpo JSON com os mesmos
  filtros da lista, ou `chaves` (as linhas marcadas, `"<id>|<registro.id>|<origem>"`), e `nome`.
  Dentro do `.zip` vem **uma pasta só**, com o `nome` pedido, e todos os arquivos direto nela (nome
  repetido ganha " (2)"); pasta da equipe mantém as subpastas da equipe. Limite: **500 arquivos ou 1 GB** — passou, `413 limite_zip` com a contagem
  em `details`. `"somente_conferir": true` devolve só `{ arquivos, bytes }`.
- `GET /api/v1/arquivos/pastas-equipe?parent_id=` — pastas criadas pela equipe; os arquivos
  de uma pasta saem em `GET /api/v1/arquivos?pasta_id={id}`.

**Pela API, Arquivos é só ler e baixar**: não dá para criar, renomear ou apagar pasta, nem
enviar ou apagar arquivo — isso é feito pela equipe dentro do FullCash.

**Vários registros no mesmo dia** (ex.: dois fechamentos em 30/09, cada um com anexo e
arquivo de chat): cada linha da lista traz o seu `registro` e a `origem`, então nada se
mistura. Para o dia inteiro: `GET /api/v1/arquivos?modulo=fechamento-caixa&dia=2026-09-30` e
agrupe por `registro.id`.

Regras: só aparecem os módulos ligados na empresa; itens de **uso interno** nunca aparecem;
os chats de grupo da empresa ficam de fora. A data é a do **registro** (dia do fechamento,
vencimento…), não a do envio. Um anexo do **lote** de agendamento aparece em cada item do lote
(`do_lote: true`) — por isso o `.zip` dos selecionados usa a linha (`chaves`), não só o id.

Compatibilidade: os níveis antigos de `/pastas` (`ano` → meses, `mes` → dias, `dia` →
registros) continuam respondendo como antes.

```bash
# 1) módulos e os anos de um módulo
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/pastas"
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/pastas?modulo=contas-pagar"
# 2) dentro do ano: opções dos filtros e a lista de outubro, pela data do registro
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/facetas?modulo=contas-pagar&ano=2026"
curl -H "Authorization: Bearer $FC_KEY" \
  "$BASE/api/v1/arquivos?modulo=contas-pagar&ano=2026&mes=10&ordem=data"
# 3) um arquivo (link de 1 h) ou o mês inteiro num .zip
curl -H "Authorization: Bearer $FC_KEY" "$BASE/api/v1/arquivos/<arquivo_id>"
curl -X POST -H "Authorization: Bearer $FC_KEY" -H "Content-Type: application/json" \
  -d '{"modulo":"contas-pagar","ano":2026,"mes":10,"nome":"CP outubro"}' \
  -o cp-outubro.zip "$BASE/api/v1/arquivos/zip"
```

## Criar um lançamento

```bash
curl -X POST https://api.fullcashbpo.com/api/v1/contas-pagar \
  -H "Authorization: Bearer fc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c-uma-chave-unica-por-lancamento" \
  -d '{
    "tipo_transacao": "saida",
    "status": "a_pagar",
    "valor": 1250.90,
    "data": "2026-09-10",
    "titulo": "NF 12345 — Fornecedor X",
    "fornecedor_id": "UUID_DO_FORNECEDOR",
    "plano_conta_id": "UUID_DE_UMA_FOLHA_DO_PLANO",
    "centro_custo_id": "UUID_DE_CENTRO_DA_EMPRESA",
    "parcelas": [
      { "numero": 1, "total": 2, "vencimento": "2026-10-05", "valor": 625.45 },
      { "numero": 2, "total": 2, "vencimento": "2026-11-05", "valor": 625.45 }
    ]
  }'
```

### Campos

Obrigatórios: `titulo`, `valor` (> 0) e `data` (YYYY-MM-DD). Todo o resto é opcional.

| Campo | O que é |
|---|---|
| `tipo_transacao` | `saida` (padrão), `entrada` ou `transferencia` |
| `status` | situação financeira: `a_pagar`, `paga`, `a_receber`, `recebida` (não é a fase) |
| `descricao` | texto livre (ex.: dados de fornecedor ainda não cadastrado) |
| `fornecedor_id`, `plano_conta_id`, `centro_custo_id` | IDs dos cadastros de apoio |
| `conta_bancaria_id` | conta da empresa (saída/entrada) |
| `conta_origem_id` / `conta_destino_id` | só em `transferencia`: as duas obrigatórias e diferentes |
| `numero_documento` | nº da NF/boleto |
| `competencia` | `YYYY-MM` ou `MM/YYYY` |
| `data_emissao` | data de emissão do documento |
| `data_liquidacao` | data do pagamento; só vale com `status` paga/recebida (sem ela, usa `data`) |
| `tipo_documento`, `meio_pagamento` | um valor das listas de `GET /cadastros/tipos-documento` |
| `historico` | histórico do lançamento |
| `codigo_barras` | linha digitável do boleto |
| `parcelas` | lista de `{ numero, total, vencimento, valor }`: `numero` (1…N), `total` (N), `vencimento` (YYYY-MM-DD), `valor`. Vazio = parcela única. A API **não confere** a soma: mande a soma igual a `valor` |
| `tem_rateio`, `rateio_tipos` | marca o rateio e as dimensões (`centro_custo`, `plano_conta`) |
| `company_id` | empresa-alvo (alternativa ao header) |

Resposta `201`: `{ "conta": { ... } }` com `status_documento: "em_analise"`, `created_via: "api"`
e o `codigo` de rastreio (ex.: `CP20260007`). O valor oficial de cada informação é o campo do
lançamento (`valor`, `data`…); `dados_avancados` é só a leitura feita pela IA.

### Regras de validação (segurança)

Todas checadas contra a **empresa-alvo**. Falha → `422` com o campo em `details`:

| Campo | Regra |
|---|---|
| `fornecedor_id` | existe e é da empresa **ou** geral |
| `plano_conta_id` | existe, ativo e é **folha** (`nivel=conta`) |
| `centro_custo_id` | **vinculado à empresa-alvo** |
| `conta_bancaria_id`, `conta_origem_id`, `conta_destino_id` | pertencem à empresa-alvo |
| transferência | exige origem e destino, diferentes entre si |
| formato | tipos e obrigatórios do corpo (os problemas vêm em `details`) |

### Fornecedor ainda não cadastrado

`fornecedor_id` é **opcional** e a API não cadastra fornecedor. Se o fornecedor
não aparece em `/cadastros/fornecedores`, crie o lançamento **sem** `fornecedor_id`
e informe nome e CPF/CNPJ na `descricao`. O operador cadastra e vincula na análise.

## Fases de um lançamento

O campo `status_documento` diz em que fase do fluxo o lançamento está. Todo
lançamento criado pela API nasce em `em_analise`; as demais transições são feitas
pelo operador FullCash — menos a volta da Pendência (`pendencias` → `em_analise`), que é
do cliente: `POST /api/v1/contas-pagar/{id}/reenviar-analise`.

> ⚠️ **Use sempre a chave, nunca o rótulo da tela.** Por razão histórica, duas
> chaves têm rótulo trocado: `finalizado` aparece como **Validado** e `validado`
> aparece como **Finalizado**.

| Chave (`status_documento`) | Rótulo na tela | Significado |
|---|---|---|
| `em_analise` | Em Análise | Recebido; o operador está conferindo. Toda conta nasce aqui. |
| `pendencias` | Pendências | Falta informação ou há inconsistência; voltou para o cliente responder (pelo chat). |
| `finalizado` | Validado | Conferido e aprovado pelo operador; aguarda o envio ao ERP. |
| `validado` | Finalizado | Lançado no ERP. Fim do fluxo. |
| `rejeitado` | Rejeitado | Recusado (inconsistência, prazo ou decisão de uma das partes). |

Caminho normal: `em_analise` → `finalizado` → `validado`.

Transições possíveis:

- `em_analise` → `finalizado` (operador validou)
- `em_analise` ou `finalizado` → `pendencias` (operador devolveu ao cliente)
- `pendencias` → `em_analise` (cliente reenviou — pela tela ou pelo `POST /api/v1/contas-pagar/{id}/reenviar-analise` — ou o operador retomou)
- `finalizado` → `validado` (saiu num lote e foi lançado no ERP)
- qualquer fase → `rejeitado`
- `finalizado`, `validado` ou `rejeitado` → `em_analise` (reabertura pela equipe FullCash)

Toda mudança de fase emite o webhook `conta.mudou_fase` com `de` e `para`.

**Respondendo uma Pendência (fluxo):**
1. chega `conta.mudou_fase` com `para: "pendencias"`;
2. leia o chat (`GET /api/v1/contas-pagar/{id}/mensagens`) pra ver o que falta;
3. resolva e chame `POST /api/v1/contas-pagar/{id}/reenviar-analise` com a resposta em
   `mensagem` (arquivo? anexe na mensagem devolvida, em até 2 min);
4. chega `conta.mudou_fase` com `de: "pendencias"`, `para: "em_analise"`.

**Situação de pagamento é outro campo.** Não existe fase "agendado" ou "pago":
isso está em `status` (`a_pagar` | `paga` | `a_receber` | `recebida`), independente
da fase. Mudança em `status` emite `conta.atualizada` (não `mudou_fase`); consulte
`GET /api/v1/contas-pagar/{id}` para ler o valor atual.

**Correção de um lançamento já criado.** A API não altera lançamentos. Peça a
correção pelo chat da conta (`POST /api/v1/contas-pagar/{id}/mensagens`); o
operador ajusta enquanto a conta está em `em_analise` ou `pendencias`.

## Erros

Formato único:

```json
{
  "error": { "code": "validation_error", "message": "...", "details": [] },
  "request_id": "uuid"
}
```

| HTTP | code | quando |
|---|---|---|
| 400 | `bad_request` / `empresa_obrigatoria` | request malformado / falta escolher empresa |
| 401 | `invalid_key` | chave ausente, errada, revogada ou expirada |
| 403 | `forbidden_scope` / `empresa_nao_liberada` | sem escopo / empresa fora da chave |
| 404 | `not_found` | não existe ou não é de uma empresa da chave (não vaza existência) |
| 409 | `idempotency_conflict` | mesma Idempotency-Key com corpo diferente |
| 409 | `idempotency_in_progress` | a 1ª requisição com essa chave ainda está criando; tente de novo em instantes |
| 409 | `anexo_apos_lancamento` | anexo na conta depois da janela de 2 min — envie pelo chat |
| 409 | `conta_fora_de_pendencia` | reenviar para análise uma conta que não está em Pendência (`em_analise` = já foi reenviada) |
| 409 | `anexo_fora_da_janela` | anexo no chat em mensagem que não é da sua chave ou com mais de 2 min — mande mensagem nova com o arquivo |
| 409 | `conta_finalizada` | mensagem ou anexo no chat com a conta finalizada (somente consulta) — peça para a FullCash reabrir |
| 410 | `link_expirado` | `preview_url` vencido (30 dias) — pegue um novo no `GET` |
| 413 | `limite_zip` | `.zip` passaria de 500 arquivos ou 1 GB |
| 413 | `corpo_grande` | requisição grande demais: upload acima de 11 MB (arquivo até 10 MB) ou JSON acima de 1 MB |
| 422 | `validation_error` | regra de negócio (fornecedor/plano/centro inválido, arquivo fora das regras de upload, chave sem usuário de integração) |
| 422 | `documento_ilegivel` | a IA não conseguiu ler o documento |
| 429 | `rate_limited` | teto por minuto (respeite `Retry-After`) |
| 500 | `internal` | erro inesperado do nosso lado — repita com espera e mande o `request_id` ao suporte |
| 502 | `ia_indisponivel` / `ia_falhou` | serviço de leitura por IA fora ou com erro; tente de novo |
| 503 | `db_unavailable` | API sem conexão com o banco — repita com espera |
| outro | `http_error` | erro HTTP genérico do servidor (raro); trate pelo status |

Guarde o `request_id`: ele casa com o log de auditoria do FullCash.

## Idempotência

No `POST`, envie `Idempotency-Key` única por lançamento. Reenvio com a mesma
chave devolve a **mesma** resposta (não duplica). Mesma chave com corpo diferente
→ `409 idempotency_conflict`.

- **Validade:** a chave **não expira**. Fica registrada de forma permanente,
  separada por chave de API. Use um identificador estável do seu lado (ex.: o id
  do chamado ou do documento no seu sistema).
- **Criação que falhou** (ex.: `422`) libera a chave: dá para reenviar, corrigido,
  com a mesma `Idempotency-Key`.
- **Duas requisições simultâneas** com a mesma chave: só uma cria; a outra recebe
  `409 idempotency_in_progress` e deve tentar de novo em instantes.

## Webhooks

Quando ativados, o FullCash faz `POST` na URL cadastrada quando algo muda.

**Cadastro.** É feito pela equipe FullCash, por chave de API. Informe a URL
(HTTPS) e os eventos desejados; devolvemos o segredo (`whsec_...`) usado na
assinatura. O segredo é mostrado uma vez só — guarde-o com segurança.

Eventos e o que vem em `data`:

| Evento | Quando | `data` |
|---|---|---|
| `conta.criada` | lançamento criado (API ou tela) | `conta_id`, `codigo`, `titulo`, `valor`, `status_documento`, `created_via` |
| `conta.mudou_fase` | `status_documento` mudou (qualquer transição) | `conta_id`, `de`, `para` |
| `conta.atualizada` | outro campo mudou, sem troca de fase | `conta_id`, `status_documento` |
| `conta.mensagem.nova` | nova mensagem no chat da conta | `conta_id`, `message_id` |
| `conta.anexo.novo` | novo anexo **do lançamento** (não do chat) | `conta_id`, `anexo_id` |

- Os eventos disparam **independente da origem**: valem tanto para o que entra pela
  API quanto para o que o operador faz na tela do FullCash (emissão por trigger de banco).
  O que você mesmo criou também gera evento: use o `conta_id`/`message_id` pra ignorar.
- Arquivo enviado numa mensagem do chat chega em `conta.mensagem.nova` (e aparece em
  `anexos` no `GET /mensagens`), não em `conta.anexo.novo`.
- O evento traz só o essencial; para o estado completo, consulte `GET /api/v1/contas-pagar/{id}`.
- Todo evento traz **`company_id`** e **`company_sigla`** no topo do corpo: a loja dona do
  lançamento, pra você saber de quem é sem consultar nada.
- Headers: `X-FullCash-Event` (nome do evento), `X-FullCash-Delivery` (id da entrega)
  e `X-FullCash-Signature` (`sha256=` + HMAC do corpo cru com o segredo). Valide a assinatura
  sempre, antes de fazer o parse do JSON.
- Idempotência: cada evento tem `id`; deduplique pelo `id`.
- Confirmação: responda **HTTP 2xx**. Qualquer outra resposta (ou falha de rede)
  gera nova tentativa: até **5 tentativas** no total, com esperas de 1, 5, 30 e
  120 minutos. Depois disso a entrega é marcada como falha — sem loop.

Corpo do evento (exemplo):

```json
{ "id": "uuid-do-evento", "event": "conta.mudou_fase", "created_at": "2026-09-18T12:00:00Z", "company_id": "uuid-da-empresa", "company_sigla": "14A1", "data": { "conta_id": "uuid", "de": "em_analise", "para": "finalizado" } }
```

Exemplo de verificação (Node):

```js
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(signatureHeader)
  return a.length === b.length && timingSafeEqual(a, b)
}
```

## Limites e boas práticas

- **Rate limit** por chave (padrão 100/min). Trate `429` com `Retry-After`.
- **Quando repetir uma chamada que falhou:**

  | Resposta | Repetir? |
  |---|---|
  | `4xx` (`400`, `401`, `403`, `404`, `409`, `410`, `413`, `422`) | **Não.** O pedido está errado e vai falhar igual. Corrija o dado (veja `error.message`) ou registre o erro e siga. `410` = pegue um link novo. |
  | `429` | Sim, depois do `Retry-After`. |
  | `5xx` ou falha de rede | Sim, com espera crescente (ex.: 1, 5, 30 min) e **teto** de tentativas (ex.: 5). Depois disso, marque como falha e avise alguém. |

  Mande `Idempotency-Key` nos `POST` pra repetir sem risco de duplicar.
- **Use o webhook, não fique consultando.** O FullCash avisa em segundos quando um
  lançamento é criado, muda de fase ou recebe mensagem. Consultar a lista a cada poucos
  segundos não traz nada a mais e gasta seu rate limit. Se quiser uma rede de segurança,
  uma conferência a cada **15–30 min** (filtrando por data) é suficiente.
- **Paginação**: `page`/`size` (padrão 50; máx 200, ou 1000 em fornecedores e plano de
  contas); use `total` para paginar.
- **Sempre** resolva `fornecedor_id`/`plano_conta_id`/`centro_custo_id` pelos
  endpoints de cadastros antes de criar — não invente IDs.
