# FullCash — API de Contas a Pagar · Base de conhecimento para agentes de IA

> Documento legível por máquina e **completo**: toda rota, escopo, campo, erro e evento
> da API está aqui (um teste automático da API falha se faltar algo). Se você é um agente
> de IA (Codex, Claude, Gemini, etc.) gerando código de integração, use este texto como
> fonte da verdade. Contrato formal (OpenAPI) em `/openapi.json`; UI em `/docs`;
> guia para pessoas em `/integracao`.

## Modelo mental (leia primeiro)

A API é o **espelho do papel cliente** do FullCash: você consegue **ver** o que um
cliente vê e **criar** o que um cliente cria — nada além. As transições de fase do
BPO (finalizar, validar, rejeitar, devolver com pendência) são do **operador** e **não
existem** na API. A única que é do cliente — **reenviar para análise** uma conta em
Pendência — existe: `POST /contas-pagar/{id}/reenviar-analise`. Um lançamento criado pela API entra com `status_documento = em_analise` e
segue o fluxo do operador do lado do FullCash (ver **Fases de um lançamento**).

Cada **chave** de API pertence a um cliente e enxerga **uma ou mais empresas
liberadas** — nunca outra empresa, nunca outro módulo (fora a leitura de arquivos,
com `arquivos:read`).

Toda chave tem um **usuário de integração** próprio (`integration_user_id`): um usuário
técnico, **sem login**, com o nome definido pela FullCash (ex.: "Extranet Cliente X"). Ele
assina o que a chave cria (lançamentos, anexos, mensagens). Você **não** cria nem gerencia
usuários pela API.

## Base e autenticação

- **Base URL**: `https://api.fullcashbpo.com`
- **Prefixo** de todos os endpoints: `/api/v1`
- **Header obrigatório**: `Authorization: Bearer fc_live_...`
  As chaves são **emitidas pela equipe FullCash** (o cliente não cria chave). Guardamos só o hash;
  perdeu, a FullCash gera outra.
- **Content-Type**: `application/json` (exceto uploads: `multipart/form-data`).
- Toda resposta traz o header `x-request-id` (o mesmo `request_id` do corpo de erro).
- Única rota sem `Authorization`: o link de visualização de anexo
  `GET /anexos/{id}/ver?t=` (ver **Visualizar anexo**).

Headers que a API lê ou devolve:

| 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 duplicata |
| `x-request-id` | API → você | id da requisição para suporte |
| `Retry-After` | API → você | segundos de espera após `429` |
| `X-FullCash-Event` / `X-FullCash-Delivery` / `X-FullCash-Signature` | FullCash → seu webhook | evento, id da entrega e assinatura HMAC |

### Escolhendo a empresa (multi-empresa)

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

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`. Faltando escolher
quando a chave tem várias → `400 empresa_obrigatoria` (`details.empresas_liberadas` lista as liberadas).

Exceção: rotas de **um lançamento** (`/contas-pagar/{id}`, `/contas-pagar/{id}/mensagens`,
`/contas-pagar/{id}/mensagens/{msgId}/anexos`, `/contas-pagar/{id}/anexos`) acham a empresa
sozinhas entre as da chave — não precisa mandar. Se mandar, ela é respeitada (empresa errada →
`404`). E todo webhook já traz `company_id`/`company_sigla`. Não chute empresa por empresa.

### Homologação

Não existe ambiente separado: homologação é na **mesma API**, com uma chave de teste que só
enxerga **empresas de teste**. Teste o fluxo inteiro nela (criar, anexar, chat, webhooks) e só
então use a chave das empresas reais. IDs de uma empresa **não valem** em outra (`404`/`422`).

## 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; analisar documento por IA |
| `cadastros:read` | fornecedores, plano de contas, centros de custo, 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 em mensagem exige `chat:write` **e** `anexos:write`) |
| `arquivos:read` | ler e baixar arquivos de TODOS os módulos (só leitura) |

`GET /me` funciona com qualquer escopo. O link de visualização (`/anexos/{id}/ver`) vale
enquanto a chave que o gerou tiver `anexos:read` ou `chat:read`.

## Fluxo recomendado de integração (ponta a ponta)

1. **`GET /me`** — descubra as empresas liberadas, os escopos e o rate limit.
2. **(opcional, IA)** **`POST /contas-pagar/analisar-documento`** — mande a NF/boleto;
   recebe os campos extraídos + **fornecedor já casado com o cadastro** (`fornecedor_id`)
   e **plano de contas sugerido**.
3. **Resolva/valide os IDs** pelos endpoints `/cadastros/*` (fornecedor, plano de
   contas, centro de custo, conta bancária). **Nunca invente IDs.**
4. **`POST /contas-pagar`** com header `Idempotency-Key` — cria o lançamento.
5. **Logo após criar** (até **2 min**), suba o(s) documento(s) do lançamento em
   **`POST /contas-pagar/{id}/anexos`**. Passada a janela, é `409` (vá pro chat).
6. **Depois disso**, qualquer arquivo ou observação vai pelo **chat**:
   `POST /contas-pagar/{id}/mensagens` com `autor_externo: { nome }` (quem escreveu do seu
   lado) e, se tiver arquivo, `POST /contas-pagar/{id}/mensagens/{msgId}/anexos`.
7. Receba as mudanças por **webhook** (fase, mensagem nova, anexo novo) em vez de consultar
   a lista o tempo todo.
8. Conta voltou com **Pendência** (`conta.mudou_fase` com `para: "pendencias"`)? Leia o chat,
   resolva e responda com **`POST /contas-pagar/{id}/reenviar-analise`** (dá pra mandar a
   resposta junto, em `mensagem`). Só escrever no chat **não** tira a conta da Pendência.
9. Para mostrar um anexo na sua tela, use o **`preview_url`** dele (não baixe e reenvie).

## Referência de endpoints

Método · caminho (relativo a `/api/v1`) · escopo:

```
GET  /me                                         (qualquer)
POST /contas-pagar/analisar-documento            contas_pagar:write   (multipart: file, tipo_transacao)
GET  /contas-pagar                               contas_pagar:read    (lista paginada com filtros)
POST /contas-pagar                               contas_pagar:write   (cria; header Idempotency-Key)
GET  /contas-pagar/{id}                          contas_pagar:read
POST /contas-pagar/{id}/reenviar-analise         contas_pagar:write   (Pendência → Em análise; + chat:write se mandar `mensagem`)
GET  /cadastros/fornecedores?termo=              cadastros:read       (da empresa + gerais)
GET  /cadastros/plano-contas?termo=              cadastros:read       (só folhas: nivel=conta)
GET  /cadastros/centros-custo                    cadastros:read       (só os da empresa)
GET  /cadastros/contas-bancarias                 cadastros:read       (só as da empresa)
GET  /cadastros/tipos-documento                  cadastros:read       (listas fechadas de tipo de documento e meio de pagamento)
GET  /cadastros/upload-regras                    cadastros:read       (extensões e tamanho máx dos anexos)
GET  /cadastros/usuarios                         cadastros:read       (usuários da empresa — só se for usar user_id no chat)
GET  /contas-pagar/{id}/mensagens                chat:read
POST /contas-pagar/{id}/mensagens                chat:write           (body: message + autor_externo OU user_id)
POST /contas-pagar/{id}/mensagens/{msgId}/anexos chat:write + anexos:write (multipart: file)
GET  /contas-pagar/{id}/anexos                   anexos:read
POST /contas-pagar/{id}/anexos                   anexos:write         (multipart: file — só até 2 min após criar)
GET  /anexos/{id}/ver?t=<token>                  (sem Authorization)  (link de visualização: 302 para o arquivo)
GET  /arquivos/pastas?modulo=                    arquivos:read        (módulos e anos; as pastas param no ano)
GET  /arquivos?modulo=&ano=&mes=                 arquivos:read        (lista paginada com filtros — sem URL)
GET  /arquivos/facetas?modulo=&ano=              arquivos:read        (opções dos filtros com contagem)
POST /arquivos/zip                               arquivos:read        (vários arquivos num .zip; 500 arquivos / 1 GB)
GET  /arquivos/{id}                              arquivos:read        (url assinada, 1 h)
GET  /arquivos/pastas-equipe?parent_id=          arquivos:read        (pastas manuais; arquivos via /arquivos?pasta_id=)
```

### GET /me

Sem escopo específico. Retorna a identidade da chave, os escopos e as empresas.

```json
{
  "key": { "id": "uuid-da-chave", "name": "Integração ERP do Cliente X", "scopes": ["contas_pagar:read", "contas_pagar:write", "cadastros:read"], "rate_limit_per_min": 100 },
  "companies": [ { "id": "uuid", "name": "Empresa X", "sigla": "EMPX" } ]
}
```

Se `companies` tem mais de 1 item, você **precisa** mandar a empresa-alvo nas chamadas que
não são de um lançamento específico.

### POST /contas-pagar/analisar-documento — leitura por IA (escopo `contas_pagar:write`)

Envie o documento (NF-e, NFS-e, boleto, guia, fatura, comprovante) e a API lê por
IA, devolvendo os campos + sugestões **já resolvidas** contra o cadastro da empresa.
**Não cria nada** — é só leitura, para você montar o `POST /contas-pagar`.

Request: `multipart/form-data`
- `file` — PDF ou imagem (JPEG/PNG/WebP). Obrigatório. Outro tipo → `422 validation_error`.
- `tipo_transacao` — `saida` (padrão) ou `entrada`.
- Empresa: como nas rotas de lista (`X-FullCash-Company` se a chave tiver várias).

```bash
curl -X POST https://api.fullcashbpo.com/api/v1/contas-pagar/analisar-documento \
  -H "Authorization: Bearer fc_live_..." \
  -H "X-FullCash-Company: <company_id>" \
  -F "file=@boleto.pdf;type=application/pdf" \
  -F "tipo_transacao=saida"
```

Resposta `200`:

```json
{
  "analise": {
    "poor_quality": false,
    "tipo_documento": "Boleto",
    "tipo_transacao": "saida",
    "valor": "1250.90",
    "data_emissao": "2026-09-01",
    "data_vencimento": "2026-10-05",
    "data_liquidacao": null,
    "competencia": "2026-09",
    "numero_documento": "12345",
    "meio_pagamento": "Boleto",
    "titulo": "Pagamento - Boleto - Fornecedor X",
    "historico": "Serviço de manutenção predial",
    "parcelamento": { "parcelado": false, "parcela": null, "total": null },
    "fornecedor": {
      "nome_extraido": "FORNECEDOR X LTDA",
      "documento": "12.345.678/0001-99",
      "fornecedor_id": "uuid-se-já-existir-no-cadastro-ou-null"
    },
    "plano_conta_sugerido": { "codigo": "3.1.02", "nome": "Manutenção Predial", "plano_conta_id": "uuid-ou-null" },
    "centro_custo_sugerido": null
  }
}
```

Observações:
- `valor` vem como **texto** (`"1250.90"`); converta para número antes do `POST /contas-pagar`.
- `poor_quality: true` = a imagem/PDF está ruim; os campos podem estar incompletos — confira.
- `data_vencimento` da análise vai no campo `data` (ou nas `parcelas`) do lançamento.
- `fornecedor.fornecedor_id` vem preenchido quando o CPF/CNPJ extraído casa com um
  fornecedor da empresa (ou geral); use-o direto. Se `null`, resolva por
  `/cadastros/fornecedores` ou trate como fornecedor novo.
- `plano_conta_sugerido` é **sugestão** — confirme antes de usar.
- `data_liquidacao` extraída **não** prova pagamento: só mande `status: paga` se o seu sistema confirmar.
- Erros: `400 bad_request` (sem `file`), `422 documento_ilegivel` (não deu pra ler),
  `502 ia_indisponivel` / `ia_falhou` (pode tentar de novo mais tarde).

### GET /contas-pagar — listar (escopo `contas_pagar:read`)

Query (todos opcionais):

| Parâmetro | O que faz |
|---|---|
| `page` / `size` | paginação (`size` padrão 50, máx 200) |
| `busca` | parte do `titulo` ou do `codigo` (ex.: `CP2026`) |
| `status_documento` | fase exata (`em_analise`, `pendencias`, `finalizado`, `validado`, `rejeitado`) |
| `fornecedor_id` | só desse fornecedor |
| `data_de` / `data_ate` | período pelo campo `data` (YYYY-MM-DD, inclusivo) |
| `valor_min` / `valor_max` | faixa de valor |
| `company_id` | empresa-alvo (ou header `X-FullCash-Company`) |

Ordem: `data` mais recente primeiro.

```json
{ "data": [ { "id": "uuid", "codigo": "CP20260007", "titulo": "...", "valor": 1250.90, "status_documento": "em_analise", "data": "2026-09-10" } ], "page": 1, "size": 50, "total": 128 }
```

Cada item de `data` é um **lançamento completo** (mesmos campos de `GET /contas-pagar/{id}`).

### POST /contas-pagar — criar (escopo `contas_pagar:write`)

Envie `Idempotency-Key` única por lançamento (ex.: o id do documento no seu ERP).

Corpo (JSON):

| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
| `titulo` | texto | sim | não vazio |
| `valor` | número | sim | > 0 |
| `data` | `YYYY-MM-DD` | sim | data do lançamento / vencimento |
| `tipo_transacao` | `saida` \| `entrada` \| `transferencia` | não | padrão `saida` |
| `status` | `a_pagar` \| `paga` \| `a_receber` \| `recebida` | não | situação financeira (não é fase) |
| `descricao` | texto | não | livre (use para dados de fornecedor não cadastrado) |
| `fornecedor_id` | uuid | não | da empresa **ou** geral (ignorado em transferência) |
| `plano_conta_id` | uuid | não | ativo e **folha** (`nivel=conta`) |
| `centro_custo_id` | uuid | não | vinculado à empresa-alvo |
| `conta_bancaria_id` | uuid | não | da empresa-alvo (saída/entrada) |
| `conta_origem_id` / `conta_destino_id` | uuid | só em `transferencia` | ambas obrigatórias, diferentes, da empresa |
| `numero_documento` | texto | não | nº da NF/boleto |
| `competencia` | `YYYY-MM` ou `MM/YYYY` | não | gravada como `MM/YYYY` |
| `data_emissao` | `YYYY-MM-DD` | não | |
| `data_liquidacao` | `YYYY-MM-DD` | não | só vale com `status` `paga`/`recebida` (senão é ignorada); sem ela, usa `data` |
| `tipo_documento` | texto | não | um valor de `GET /cadastros/tipos-documento` |
| `meio_pagamento` | texto | não | um valor de `GET /cadastros/tipos-documento` |
| `historico` | texto | não | |
| `codigo_barras` | texto | não | linha digitável do boleto |
| `parcelas` | `[{ numero, total, vencimento, valor }]` | não | vazio = parcela única; a API **não confere** a soma — mande a soma igual a `valor` |
| `tem_rateio` | booleano | não | marca o lançamento como rateado |
| `rateio_tipos` | `["centro_custo"` \| `"plano_conta"]` | não | dimensões do rateio quando `tem_rateio = true` |
| `company_id` | uuid | não | empresa-alvo (alternativa ao header) |

Cada item de `parcelas`: `numero` (1…N), `total` (N), `vencimento` (YYYY-MM-DD) e `valor` (> 0).

```bash
curl -X POST https://api.fullcashbpo.com/api/v1/contas-pagar \
  -H "Authorization: Bearer fc_live_..." \
  -H "X-FullCash-Company: <company_id>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-doc-12345" \
  -d '{
    "tipo_transacao": "saida",
    "status": "a_pagar",
    "valor": 1250.90,
    "data": "2026-10-05",
    "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 }
    ]
  }'
```

Regras de validação (todas contra a empresa-alvo; falha → `422 validation_error` 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` | pertence à empresa-alvo |
| transferência | exige origem e destino, e as duas diferentes |
| corpo | tipos e obrigatórios do schema (erro de formato também é `422`, com os problemas em `details`) |

Resposta `201`: `{ "conta": { ... } }` — o lançamento criado, com `status_documento: "em_analise"`,
`created_via: "api"` e o `codigo` de rastreio.

**Fornecedor ainda não cadastrado:** `fornecedor_id` é opcional e a API não cadastra
fornecedor. Se não achar em `/cadastros/fornecedores`, crie **sem** `fornecedor_id`
e ponha nome + CPF/CNPJ na `descricao`; o operador cadastra e vincula na análise.

### GET /contas-pagar/{id} — consultar (escopo `contas_pagar:read`)

`{ "conta": { ... } }`. Se o lançamento não é de uma empresa da chave → `404 not_found`
(não vaza existência).

Campos do lançamento (`conta`):

| Campo | O que é |
|---|---|
| `id`, `company_id`, `codigo` | identificação (`codigo` = rastreio, ex.: `CP20260007`) |
| `titulo`, `descricao`, `historico` | textos |
| `tipo_transacao`, `valor`, `data`, `vencimento` | básicos |
| `status` | situação financeira (`a_pagar`, `paga`, `a_receber`, `recebida`) |
| `status_documento` | **fase** no fluxo do BPO (ver **Fases**) |
| `status_titulo` | `Aberto` / `Liquidado` (texto do título) |
| `fornecedor_id`, `plano_conta_id`, `centro_custo_id`, `conta_bancaria_id` | referências |
| `numero_documento`, `tipo_documento`, `meio_pagamento` | documento |
| `competencia`, `data_emissao`, `data_liquidacao` | datas |
| `parcela` | `1` ou `1/N` |
| `uso_interno` | marcado pela equipe (não vem nos arquivos) |
| `dados_avancados` | campos avançados/originais (inclui o que a leitura por IA extraiu) — **referência**, não é o valor oficial |
| `dados_avancados_origem` | o mesmo, da conta de origem (transferências) |
| `dados_editados` | correções feitas pelo operador na finalização |
| `created_via` | `api` ou `app` (tela) |
| `created_at`, `updated_at` | carimbos de data |

O valor oficial de cada informação é a **coluna** (`valor`, `data`, `fornecedor_id`…), nunca o
`dados_avancados`.

### POST /contas-pagar/{id}/reenviar-analise — responder a Pendência (escopo `contas_pagar:write`)

É o botão **"Reenviar para análise"** da tela do cliente. Use quando a conta voltou com
**Pendência** (`status_documento = pendencias`) e vocês já resolveram: a conta volta para
`em_analise` e a equipe FullCash é avisada.

Corpo **opcional** (JSON):

```json
{
  "mensagem": "Segue o boleto corrigido, pode seguir.",
  "autor_externo": { "nome": "Murillo Guimarães", "id": "u-77" }
}
```

- `mensagem` (opcional) — a resposta à pendência. Vai pro chat **antes** do aviso de reenvio
  e exige também o escopo `chat:write`. Quer mandar arquivo junto? Use o `id` da mensagem
  devolvida em `POST /contas-pagar/{id}/mensagens/{msgId}/anexos` em até 2 min.
- `autor_externo` **ou** `user_id` (opcionais, mesmas regras do chat) — quem reenviou. Sem
  eles, assina o usuário de integração da chave. Os dois juntos → `422`.
- Sem corpo nenhum também vale (só reenvia).

O que acontece:
1. a `mensagem` (se veio) entra no chat;
2. a conta vai de `pendencias` para `em_analise`;
3. o chat ganha o aviso automático "🔄 **Conta Reenviada para Análise** — _Por Fulano · via
   <integração>_" (o mesmo da tela);
4. a equipe é notificada e sai o webhook `conta.mudou_fase` (`de: "pendencias"`,
   `para: "em_analise"`), além de `conta.mensagem.nova` para cada mensagem.

Resposta `200`:

```json
{ "conta": { "id": "uuid", "status_documento": "em_analise", "...": "..." },
  "mensagem": { "id": "uuid", "message": "Segue o boleto corrigido, pode seguir.", "anexos": [] } }
```

(`mensagem` é `null` quando não mandou.)

Erros: conta em outra fase → **`409 conta_fora_de_pendencia`** com `details.status_documento`
(se for `em_analise`, ela **já foi reenviada** — trate como feito, não repita). Conta de
outra empresa → `404`. Sem `contas_pagar:write` (ou `mensagem` sem `chat:write`) → `403`.
Duas chamadas ao mesmo tempo: só uma reenvia, a outra leva `409` (se ela trazia `mensagem`,
a mensagem fica no chat).

**Escrever no chat não reenvia.** `POST /mensagens` sozinho deixa a conta em Pendência —
nem toda resposta resolve ("vou verificar e te aviso"). Reenviar é sempre explícito.

### Cadastros de apoio (escopo `cadastros:read`)

Use-os para **resolver IDs válidos** antes de criar. Nunca invente IDs. Todos aceitam
`company_id` (ou o header) para escolher a empresa.

| Rota | Resposta | Observações |
|---|---|---|
| `GET /cadastros/fornecedores?termo=&page=&size=` | `{ data: [{ id, nome, documento, company_id, plano_conta_padrao_id }], page, size, total }` | da empresa + **gerais** (`company_id: null`); `termo` busca por nome ou CPF/CNPJ; `size` até 1000 |
| `GET /cadastros/plano-contas?termo=&page=&size=` | `{ data: [{ id, nome, nivel, codigo_externo }], page, size, total }` | só folhas ativas (`nivel=conta`); `size` até 1000 |
| `GET /cadastros/centros-custo` | `{ data: [{ id, nome, codigo_externo, principal }] }` | só os vinculados à empresa |
| `GET /cadastros/contas-bancarias` | `{ data: [{ id, name, principal, padrao }] }` | só as da empresa |
| `GET /cadastros/tipos-documento` | `{ tipos_documento: [...], meios_pagamento: [...] }` | listas fechadas, iguais às da tela |
| `GET /cadastros/upload-regras` | `{ max_size_bytes, max_size_mb, extensoes: [...], mimes: [...] }` | hoje 10 MB; PDF, imagens, XML, CSV, TXT, planilhas, Word, ZIP, PFX |
| `GET /cadastros/usuarios` | `{ data: [{ id, name, role, is_company_manager }] }` | usuários ativos vinculados à empresa (sem e-mail); só serve para o `user_id` do chat |

`plano_conta_padrao_id` do fornecedor é o plano que a equipe costuma usar para ele — bom
palpite para `plano_conta_id`.

### Chat da conta (escopo `chat:*`)

- `GET /contas-pagar/{id}/mensagens` (`chat:read`) — todas as mensagens, da mais antiga para a mais nova:

```json
{ "data": [ {
  "id": "uuid", "message": "Pode seguir com o pagamento", "message_type": "user",
  "user_id": "uuid-de-quem-assinou", "user_name": "Extranet Cliente X",
  "autor_externo": { "nome": "Murillo Guimarães", "email": "murillo@cliente.com", "id": "id-no-seu-sistema" },
  "created_at": "2026-11-05T12:00:00Z",
  "anexos": [ { "id": "uuid", "file_name": "nf.pdf", "file_type": "application/pdf", "file_size": 120345,
                "url": "https://...(1 h)", "preview_url": "https://api.fullcashbpo.com/api/v1/anexos/uuid/ver?t=..." } ]
} ] }
```

  `autor_externo` é `null` quando a mensagem foi escrita na tela do FullCash ou sem autor externo.
  `message_type`: `user` = escrita por alguém (tela ou API); `system` e os demais
  (`sistema_migracao`, `uso_interno_marco`) = avisos automáticos do FullCash (ex.: mudança de
  fase) — mostre como aviso, não como conversa. `user_name` é o nome de quem assinou (pessoa ou
  usuário de integração); para exibir, prefira `autor_externo.nome · via user_name` quando houver.

- `POST /contas-pagar/{id}/mensagens` (`chat:write`) — body
  `{ "message": "...", "autor_externo": { "nome": "...", "email": "...", "id": "..." } }`
  → `201 { "mensagem": { ... } }` (mesmo formato do GET). `message` é obrigatório.
  Conta **finalizada** (`status_documento` = `validado`, rótulo "Finalizado") é **somente
  consulta**, igual na tela: mensagem nova → `409 conta_finalizada`. Precisou falar? A equipe
  FullCash reabre a conta. (Ler o chat continua liberado.)
- `POST /contas-pagar/{id}/mensagens/{msgId}/anexos` (`chat:write` + `anexos:write`) —
  `multipart/form-data`, campo `file` → `201 { "anexo": { ... } }`. Anexa um arquivo **a uma
  mensagem** do chat (escreva a mensagem primeiro e use o `id` dela). Mensagem que não é dessa
  conta → `404`. Tipo e tamanho seguem `GET /cadastros/upload-regras` (fora → `422`).
  **Só na mensagem que a sua chave mandou e até 2 min depois dela** — mensagem antiga, escrita
  na tela (operador) ou mandada por outra chave → `409 anexo_fora_da_janela` (`details.motivo`:
  `janela_expirada` ou `mensagem_de_outra_origem`); mande uma mensagem nova com o arquivo. Vale
  também para mensagem com `user_id`. Conta finalizada (`status_documento` = `validado`) →
  `409 conta_finalizada`.

**Identificação do autor (importante):** o que chega pela API é assinado pelo **usuário de
integração** da chave (`integration_user_id`, sem login). Para dizer quem escreveu de verdade:

| Caso | O que mandar | Aparece no FullCash como |
|---|---|---|
| **Padrão** — qualquer pessoa do seu sistema | `autor_externo: { nome, email?, id? }` (só `nome` é obrigatório; `nome` até 120, `email` válido até 200, `id` até 120) | "Murillo Guimarães · via Extranet Cliente X" |
| Opcional — a pessoa tem conta no FullCash vinculada à empresa e deve contar como dela | `user_id` (de `GET /cadastros/usuarios`) | "Murillo Guimarães", igual a uma mensagem da tela |
| Nenhum dos dois | — | "Extranet Cliente X" |

- Não crie nem mapeie usuário para usar o `autor_externo`. Campo extra dentro dele → `422`.
- `user_id` **e** `autor_externo` juntos → `422`. `user_id` que não é da empresa → `422`.
- Chave antiga sem usuário de integração e sem `user_id` → `422` (peça à FullCash para configurar).
- O `autor_externo` só é gravado pela API; mensagem escrita na tela nunca tem esse campo.

### Anexos da conta (escopo `anexos:*`)

- `GET /contas-pagar/{id}/anexos` (`anexos:read`) — os documentos do lançamento:
  `{ "data": [ { id, file_name, file_type, file_size, url, preview_url } ] }`.
  `url` = link assinado de download, válido por **1 h**.
- `POST /contas-pagar/{id}/anexos` (`anexos:write`) — `multipart/form-data`, campo `file`
  → `201 { "anexo": { ... } }`. **Só na janela de criação** (ver **Regra de anexo**). Exige
  usuário de integração na chave (senão `422`). Sem `file` → `400`; tipo/tamanho fora de
  `GET /cadastros/upload-regras` → `422`.

### Visualizar anexo — `preview_url` e `GET /anexos/{id}/ver`

Todo anexo de **imagem (JPG, PNG, WebP, GIF) ou PDF** — da conta ou do chat — traz um
`preview_url`: link **fixo** do domínio da API, válido por **30 dias** e enquanto a chave
estiver ativa. Outros tipos vêm com `preview_url: null` (use o `url`, 1 h).

- Formato: `https://api.fullcashbpo.com/api/v1/anexos/{id}/ver?t=<token>`. O token (`t`) é assinado
  e amarrado ao anexo e à chave — não monte nem altere.
- **Não leva `Authorization`**: use direto em `<img src>` / `<iframe src>` / link. Não baixe o
  arquivo para guardar de novo do seu lado.
- Respostas: `302` para um link curto do arquivo (5 min, servido por CDN) · `404 not_found`
  (token inválido, chave revogada/vencida/sem escopo, anexo de outra empresa — a resposta não
  diz qual) · `410 link_expirado` (passou dos 30 dias: pegue um novo no `GET /mensagens` ou
  `GET /anexos`).
- Revogou a chave → todos os links dela param na hora.
- A resposta vem com `Cache-Control: no-store` e `Referrer-Policy: no-referrer`; não indexe o link.

### Arquivos de todos os módulos (escopo `arquivos:read`)

- Mesmo modelo do módulo de Arquivos do FullCash: **as pastas param no ano**. `GET /arquivos/pastas`
  dá os módulos e, com `modulo`, os anos; o `filtro` do ano (`{ modulo, ano }`) vai direto em
  `GET /arquivos` e `GET /arquivos/facetas` — não monte a hierarquia na mão. Cada pasta traz
  `chave`, `rotulo`, `qtd_arquivos`, `total_bytes`, `ultimo_envio` e `filtro`.
- `GET /arquivos` — lista paginada (`page`, `size` até 200) com `{ data, page, size, total, total_bytes }`.
  Filtros combináveis: `modulo` + `ano` (+ `mes`, que exige `ano`, ou `dia` = `AAAA-MM-DD`),
  `registro_tipo` + `registro_id`, `pasta_id` (+ `incluir_subpastas` = `true` para descer nas subpastas), `origem`
  (`arquivos` = anexo, `chat` = enviado numa mensagem), `enviado_por` (id de quem enviou),
  `busca` (parte do nome do arquivo), período `desde`/`ate` e `company_id`.
  Ordem: `ordem` = `enviado_em` (padrão, mais recentes primeiro), `data` (data do registro —
  para separar por mês/dia como a tela), `nome`, `tamanho`, `registro` ou `por`; `desc` = `false` inverte.
- Cada arquivo: `{ id, file_name, file_type, file_size, origem, do_lote, enviado_em, enviado_por,
  enviado_por_id, modulo, data_referencia, registro: { tipo, id, titulo } }`. A lista **não** traz URL.
- `GET /arquivos/facetas?modulo=&ano=` (ou `?pasta_id=`) — opções dos filtros com contagem:
  `{ mes[], registro[], pessoa[], origem[] }`, cada item `{ chave, rotulo, qtd }`.
- `GET /arquivos/{id}` — o arquivo com `url` (download, **1 h**) e `url_expira_em`. Peça de novo se expirar.
- `POST /arquivos/zip` — vários arquivos num `.zip` (`application/zip`). Corpo JSON com os mesmos
  filtros da lista, ou `chaves` com as linhas marcadas (`"<id>|<registro.id>|<origem>"` — é a
  LINHA: anexo do lote repete por item), e `nome` (nome da pasta dentro do zip). Dentro do zip:
  uma pasta com o `nome` e os arquivos direto nela (nome repetido ganha " (2)"; pasta da equipe
  mantém as subpastas). Limite 500 arquivos ou 1 GB (`413 limite_zip`, contagem em `details`);
  `somente_conferir` = `true` devolve só `{ arquivos, bytes }` (confira antes de baixar). Nada encontrado → `404`.
- `GET /arquivos/pastas-equipe?parent_id=` — pastas criadas pela equipe (`parent_id` = pasta pai; sem ele, as da raiz):
  `{ data: [{ id, nome, parent_id, criada_em, qtd_arquivos, qtd_subpastas, total_bytes }] }`;
  os arquivos de uma pasta saem em `GET /arquivos?pasta_id={id}`.
- `modulo` aceita: `fechamento-caixa`, `cofre-diario`, `contas-pagar`, `agendamento-bancario`,
  `conciliacao-bancaria`, `solicitacoes-gerais` (e `pasta-manual` só em `GET /arquivos`).
- `registro_tipo`: `cash_closing`, `daily_safe`, `conta_pagar`, `bank_scheduling_item`, `solicitation`, `arquivo_pasta`.
- Nunca aparecem: itens de uso interno, chats de grupo da empresa, módulos desligados na empresa.
- `data_referencia` é a data do registro (dia do fechamento, vencimento…), não do envio.
  `do_lote: true` = anexo do lote de agendamento, repetido em cada item.
- Vários registros no mesmo dia: cada linha traz o seu `registro` e a `origem`; para o dia
  inteiro, `GET /arquivos?modulo=fechamento-caixa&dia=2026-09-30` e agrupe por `registro.id`.
- Compatibilidade: os níveis antigos de `/arquivos/pastas` (`ano` → meses, `mes` → dias,
  `dia` → registros) ainda respondem; pular nível (ex.: `mes` sem `ano`) → `422`.

## Regra de anexo (importante)

**Anexo na conta só na janela de criação.** O `POST /contas-pagar/{id}/anexos` só
funciona **até 2 minutos após a conta ser criada** (e com a conta em `em_analise` ou
`pendencias`). Passada a janela, retorna **`409 anexo_apos_lancamento`**.

Por quê: o documento do lançamento é definido **na criação**. Anexar numa conta **já
existente** (horas depois) abriria risco de **adulteração** (trocar a NF/boleto depois
da análise). A janela curta cobre o caso real — criar a conta e, logo em seguida,
subir 1 ou mais documentos.

Fluxo na prática:
1. `POST /contas-pagar` (cria a conta, entra em `em_analise`).
2. Dentro de **2 min**: `POST /contas-pagar/{id}/anexos` para cada documento do lançamento.
3. **Depois disso**, qualquer arquivo novo vai como **anexo de mensagem no chat**
   (`POST /contas-pagar/{id}/mensagens` e depois `POST /contas-pagar/{id}/mensagens/{msgId}/anexos`)
   — que tem autor, data e é rastreável.

**No chat vale a mesma janela.** O arquivo só entra na mensagem que **a sua chave** acabou de
mandar, **até 2 minutos** depois dela. Não dá pra pendurar arquivo numa mensagem antiga, numa
mensagem escrita pelo operador na tela ou numa mensagem de outra chave — senão um boleto novo
pareceria ter chegado lá atrás. Fora disso → **`409 anexo_fora_da_janela`**: não repita, mande
uma **mensagem nova** com o arquivo. Com a conta **finalizada** (`status_documento` =
`validado`) nenhum anexo entra → **`409 conta_finalizada`** (a equipe FullCash precisa reabrir).

## Fases de um lançamento

`status_documento` é a fase no fluxo do BPO. Todo lançamento nasce em `em_analise`;
as demais transições são do operador (não existem na API) — menos **`pendencias` →
`em_analise`**, que o cliente faz com `POST /contas-pagar/{id}/reenviar-analise`.

**ATENÇÃO — use a chave, nunca o rótulo da tela.** Duas chaves têm rótulo trocado
por razão histórica: `finalizado` aparece como "Validado" e `validado` aparece
como "Finalizado". Mapeie sempre pela chave.

| Chave (`status_documento`) | Rótulo na tela | Significado |
|---|---|---|
| `em_analise` | Em Análise | Recebido; operador conferindo. Toda conta nasce aqui. |
| `pendencias` | Pendências | Falta informação; voltou para o cliente responder (chat). |
| `finalizado` | Validado | Aprovado pelo operador; aguarda envio ao ERP. |
| `validado` | Finalizado | Lançado no ERP. Fim do fluxo. |
| `rejeitado` | Rejeitado | Recusado. |

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

Transições possíveis (cada uma emite `conta.mudou_fase` com `de`/`para`):

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

**Pagamento não é fase.** Não existe fase "agendado"/"pago": a situação financeira
é o campo `status` (`a_pagar` | `paga` | `a_receber` | `recebida`), independente de
`status_documento`. Mudança em `status` emite `conta.atualizada`, não `mudou_fase`.

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

## Idempotência

No `POST /contas-pagar`, 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`.

- A chave **não expira** (registro permanente, separado por chave de API). Use um
  id estável do seu lado (ex.: id do chamado/documento).
- Criação que falhou (ex.: `422`) **libera** a chave: reenvie corrigido com a mesma.
- Duas requisições simultâneas com a mesma chave: só uma cria; a outra recebe
  `409 idempotency_in_progress` — tente de novo em instantes.
- Os outros `POST` (mensagem, anexo) não usam `Idempotency-Key`: não repita às cegas
  depois de um `201`.

## Paginação

`page` (começa em 1) / `size` (padrão 50; máx 200 em `/contas-pagar` e `/arquivos`, 1000
em `/cadastros/fornecedores` e `/cadastros/plano-contas`). Use o campo `total` da resposta
para paginar até o fim.

## Rate limiting

Por chave (padrão 100 req/min; o valor da sua chave vem em `GET /me` →
`rate_limit_per_min`). Ao receber `429 rate_limited`, respeite o header `Retry-After`
(segundos; também em `details.retry_after`) e faça backoff.

## Erros — envelope único

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

Guarde o `request_id`: ele casa com o log de auditoria do FullCash. `message` é legível
para pessoas; decida pelo `code`.

| HTTP | code | quando |
|---|---|---|
| 400 | `bad_request` | request malformado (JSON inválido, `file` faltando no multipart) |
| 400 | `empresa_obrigatoria` | a chave tem várias empresas e nenhuma foi escolhida (`details.empresas_liberadas`) |
| 401 | `invalid_key` | chave ausente, errada, revogada ou expirada |
| 403 | `forbidden_scope` | a chave não tem o escopo da rota |
| 403 | `empresa_nao_liberada` | empresa informada fora da chave |
| 404 | `not_found` | recurso 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` | 1ª requisição com a chave ainda criando; tente de novo |
| 409 | `anexo_apos_lancamento` | anexo na conta fora da janela de criação (2 min) — use o chat |
| 409 | `conta_fora_de_pendencia` | reenviar para análise uma conta que não está em `pendencias` (`details.status_documento`; `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 (`details.motivo`) — mande mensagem nova com o arquivo |
| 409 | `conta_finalizada` | mensagem ou anexo no chat com a conta finalizada (`validado`) — somente consulta; peça para 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 (contagem em `details`) |
| 413 | `corpo_grande` | requisição grande demais: upload acima de 11 MB (o arquivo vai até 10 MB) ou JSON acima de 1 MB — cortada antes de ler (`details.limite_bytes`) |
| 422 | `validation_error` | formato do corpo/parâmetros ou regra de negócio (fornecedor/plano/centro/conta inválido, transferência sem contas, arquivo fora das regras, `user_id` + `autor_externo`, chave sem usuário de integração) — detalhes em `details` |
| 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 lado do FullCash — repita com espera e mande o `request_id` ao suporte |
| 502 | `ia_indisponivel` / `ia_falhou` | serviço de leitura por IA indisponível/falhou |
| 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 |

## Webhooks

Quando ativados (por chave), o FullCash faz `POST` na URL cadastrada quando algo muda.
O cadastro (URL HTTPS + eventos) é feito pela **equipe FullCash**, que devolve o
segredo `whsec_...` uma única vez.

| 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 para o que entra pela API **e**
  para o que o operador faz na tela do FullCash (emissão por trigger de banco). A sua própria
  mensagem/conta também gera evento — use o `id`/`message_id` para ignorar o que você mesmo criou.
- Arquivo enviado numa mensagem do chat **não** gera `conta.anexo.novo`: ele chega em
  `conta.mensagem.nova` e aparece em `anexos` no `GET /contas-pagar/{id}/mensagens`.
- Todo evento traz **`company_id`** e **`company_sigla`** no topo: a empresa (loja) dona do lançamento.
- O evento é enxuto; para o estado completo, `GET /contas-pagar/{id}` (ou `/mensagens`).
- **Headers**: `X-FullCash-Event` (nome do evento), `X-FullCash-Delivery` (id da entrega) e
  `X-FullCash-Signature: sha256=HMAC(secret, corpoCru)`. **Valide sempre**, sobre o corpo cru
  (antes de fazer parse do JSON).
- **Idempotência**: cada evento tem um `id` no corpo; **deduplique** por ele.
- **Confirmação**: responda **2xx** rápido (processe depois). Qualquer outra resposta ou falha
  de rede gera nova tentativa após 1, 5, 30 e 120 min — **5 tentativas** no total; depois a
  entrega é marcada como falha — sem loop.
- A ordem de chegada não é garantida: use `created_at` e, na dúvida, consulte o estado atual.

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" } }
```

Verificação da assinatura (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)
}
```

## Fora de escopo (NÃO existe na API)

- Transições de fase do operador (validar, devolver com pendência, rejeitar, reabrir) — são do
  operador no FullCash. A do cliente (reenviar para análise) existe: `POST /contas-pagar/{id}/reenviar-analise`.
- Editar ou apagar um lançamento já criado — correção é pedida pelo chat.
- Editar ou apagar mensagem/anexo.
- Cadastrar fornecedor, plano de contas, centro de custo ou conta bancária — crie o lançamento
  sem `fornecedor_id` e informe os dados na `descricao`.
- Criar usuários, chaves ou empresas. Quem escreve sem conta no FullCash vai em `autor_externo`.
- Mexer em outros módulos (em outros módulos só existe a LEITURA de arquivos, `arquivos:read`).
- Em Arquivos, qualquer escrita: criar, renomear ou apagar pasta; enviar ou apagar arquivo.
- Webhook de arquivo novo fora do Contas a Pagar.

## Regras para o código que você (agente) gerar

1. `GET /me` primeiro; se houver mais de uma empresa, mande `X-FullCash-Company` nas rotas
   de lista/criação (as rotas de um lançamento acham a empresa sozinhas).
2. Resolva `fornecedor_id` / `plano_conta_id` / `centro_custo_id` / `conta_bancaria_id` pelos
   `/cadastros/*` antes de criar. Nunca invente IDs.
3. `Idempotency-Key` estável por lançamento (ex.: id do documento no ERP).
4. **Nunca repita `4xx`** (400/401/403/404/409/410/413/422): o pedido está errado e falha igual —
   registre e siga (`410` = pegue um link novo). `429`: espere o `Retry-After`.
   `5xx`/rede: repita com espera crescente e **teto** (ex.: 5 tentativas).
5. Pagine usando `total`.
6. Anexo do documento só logo após criar (2 min); arquivo novo depois vai pelo chat, numa
   mensagem nova, anexado em até 2 min (`409 anexo_fora_da_janela` = mande outra mensagem).
7. Autor do chat sem conta no FullCash → `autor_externo: { nome, email?, id? }`; não crie
   nem mapeie usuário. `user_id` só para quem tem conta e deve aparecer como ele mesmo.
8. Para mostrar anexo, use o `preview_url` (imagem/PDF) direto no `<img>`/`<iframe>`; não
   baixe e reenvie o arquivo.
9. Reaja aos **webhooks** em vez de consultar a lista a cada poucos segundos; se quiser
   rede de segurança, uma conferência a cada 15–30 min basta.
10. Verifique webhooks com HMAC sobre o corpo cru, responda 2xx rápido e deduplique pelo `id`.
11. Mapeie fases por `status_documento` (chave), nunca pelo rótulo — `finalizado`
    é "Validado" e `validado` é "Finalizado". Situação de pagamento é `status`, não fase.
12. Valor oficial = colunas do lançamento; `dados_avancados` é só a leitura da IA.
13. Guarde o `request_id` de cada resposta para suporte.
14. Pendência resolvida → `POST /contas-pagar/{id}/reenviar-analise` (com a resposta em
    `mensagem`). Só escrever no chat não tira a conta da Pendência. `409 conta_fora_de_pendencia`
    com `em_analise` = já reenviada; não repita.

---

Contrato formal e testável: `/openapi.json` · Swagger UI: `/docs` · Guia para pessoas: `/integracao`.
