# Zemo Capital — API V2 (Antecipação de Recebíveis)

> API multi-tenant para originadores anteciparem recebíveis (NF-e, duplicatas, contratos) de seus cedentes, com liquidação via PIX. Autenticação de API via Client Credentials (OAuth2) → JWT RS256. Base URL de Produção: https://receivables-api.zemocapital.com; Sandbox: https://receivables-api-sandbox.zemocapital.com (prefixo /v1 nos dois).

Leia nesta ordem: panorama → autenticação → especificação → webhooks → erros → caminho executável.

## 1. Panorama

- [Para IAs & LLMs](https://docs.zemocapital.com/para-llms): **o system-prompt sugerido** — TL;DR machine-first em um bloco copiável (base URL, auth em 2 linhas, os 3 endpoints do golden path, vocabulário canônico), 6 regras de ouro (auth, idempotência, vocabulário, dinheiro, erros por `code`, webhooks), golden path executável e anti-padrões. Este `llms.txt` é o índice; aquela página é o que se cola no contexto do agente.
- [Integration Overview](https://docs.zemocapital.com/integration-overview): visão geral, entidades (originator, assignor, payer, stock item, operation, title), fluxo completo de integração, idempotência, paginação e SDKs — sem duplicar schemas.
- [Ambientes](https://docs.zemocapital.com/reference/environments): base URLs de Produção e Sandbox; o prefixo da credencial (`zk_live_*` / `zk_test_*`) determina o ambiente.
- [Lifecycle (estoque e operação)](https://docs.zemocapital.com/concepts/lifecycle): máquinas de estado; onde ler o estado (`lifecycle_status` vs. alias legado `status`).
- [Valores do Recebível (NFV)](https://docs.zemocapital.com/concepts/values), [Taxas, PMP e Limites](https://docs.zemocapital.com/concepts/fees), [Saldo Devedor dos Títulos](https://docs.zemocapital.com/concepts/balances).

## 2. Autenticação e controle de acesso

- [Autenticação](https://docs.zemocapital.com/auth/overview): fluxo Client Credentials — `POST /v1/auth/token` troca `client_id` + `client_secret` por JWT RS256 com TTL de 15 minutos. É o fluxo oficial servidor-a-servidor; `POST /v1/auth/login` (e-mail/senha) é para sessões de usuário, não para autenticação de API.
- [Scopes](https://docs.zemocapital.com/reference/scopes): lista canônica de escopos por endpoint (`operation:create`, `stock:write`, `webhook:write`, `contract:read`, `contract:send`, …). Escopo insuficiente devolve `403 scope_insufficient`. As duas rotas de contrato têm escopos **distintos**: `GET /v1/operations/{id}/contract/signers` exige `contract:read` (o caso típico — o disparo é automático na aprovação e a integração só acompanha) e `POST /v1/operations/{id}/contract/send-for-signature` exige `contract:send` (opt-in de borda: re-disparo após `CONTRACT_ERROR`, operações importadas do fluxo antigo, sobrescrever o modo `embedded`, disparar sem esperar a varredura). Nenhum dos dois vem junto de `operation:create`: credenciais antigas precisam receber o que usarem.
- [Idempotência](https://docs.zemocapital.com/auth/idempotency): header `Idempotency-Key` (16 a 80 caracteres), obrigatório nas rotas financeiras e honrado em todo método mutante sob `/v1`. Reenvio com a mesma chave e o mesmo corpo devolve a resposta guardada da primeira execução, com o header `Idempotency-Replayed: true`.
- [Rate Limits](https://docs.zemocapital.com/reference/rate-limits): dois limites simultâneos (por IP e por token); o `429` traz `Retry-After` e `detail.scope` dizendo qual bucket negou.

## 3. Especificação (fonte da verdade)

- [OpenAPI Spec](https://docs.zemocapital.com/openapi.json): especificação OpenAPI da release **v1.3.0** — fonte da verdade para endpoints, parâmetros, schemas, códigos de erro por operação e exemplos de request/response.
- **Contrato congelado**: a superfície pública de v1.1.0 está congelada e continua sendo o **piso de compatibilidade** verificado por gate automático a cada mudança (inclusive nas v1.2.0 e v1.3.0); só entra sem versão nova o que é **aditivo** (endpoint novo, campo opcional novo, valor de enum novo, código de erro novo) — remover ou apertar qualquer coisa exige nova versão na URL. Regras completas em [Versionamento](https://docs.zemocapital.com/reference/versioning).
- [API Reference (Scalar)](https://docs.zemocapital.com/reference): a mesma especificação renderizada, com exemplos de código por endpoint (`x-codeSamples`) para Python e Node.
- [Collection Postman](https://docs.zemocapital.com/postman_collection.json): gerada da especificação, para importar direto no Postman/Insomnia.
- [Assinatura embedded](https://docs.zemocapital.com/reference/assinatura-embedded): a operação **dispara o contrato sozinha** ao ser aprovada e o provedor notifica os signatários por e-mail — não é preciso chamar nada. O modo *embedded* (`embedded_signature: true` no create) suprime essa notificação e devolve a `sign_url` de cada signatário em `GET /v1/operations/{id}/contract/signers`, para o integrador apresentar o link na própria interface. `sign_url` é **credencial** (quem a tem assina): nunca logar, nunca persistir em claro; no replay de idempotência ela volta `null` de propósito.
- [Operação direta e antecipação parcial](https://docs.zemocapital.com/reference/operations-direct): `POST /v1/operations/direct` — cedente, recebíveis e dados bancários numa única chamada; é a **única** rota que faz antecipação parcial do NFV (o fluxo de estoque antecipa sempre 100% dos itens selecionados).

## 4. Webhooks e verificação HMAC

- [Webhooks — visão geral](https://docs.zemocapital.com/webhooks/overview) e [gerenciamento](https://docs.zemocapital.com/webhooks/managing): registre em `POST /v1/webhooks`; o `hmac_secret` é devolvido **apenas** na resposta de criação.
- [Eventos](https://docs.zemocapital.com/webhooks/events): catálogo canônico (`operation.approved`, `operation.paid`, `title.paid`, `stock.item_registered`, …) e o envelope comum (`event_type`, `event_id`, `occurred_at`, `data`).
- [Segurança de Webhooks](https://docs.zemocapital.com/webhooks/security): o header `X-Zemo-Signature` é o HMAC-SHA256 do **body cru** (hexadecimal), com o `hmac_secret` como chave — verifique sobre os bytes recebidos, nunca sobre o JSON re-serializado. Deduplique por `event_id` e responda 2xx em menos de 10 s. Exemplos em Python e Node.

## 5. Catálogo de erros

- [Códigos de Erro](https://docs.zemocapital.com/reference/error-codes): catálogo completo por status. `detail` assume três formas — objeto com `code: validation_error` e `errors[]` (falha de schema), objeto com `code` + `message` (regra de negócio) ou string com o código. Códigos de regra podem trazer um sufixo `: <detalhe>` variável: classifique por **prefixo** até o `:`, nunca por igualdade da string inteira.
- A lista de códigos possíveis **por operação** vive na própria especificação, na frase "Codigos possiveis nesta operacao" da descrição de cada resposta de erro.

## 6. Caminho executável

- [Integração em 6 curls](https://docs.zemocapital.com/golden-path): golden path completo e copiável — autenticar → simular (`POST /v1/simulate`) → criar (`POST /v1/operations/direct` com `Idempotency-Key`) → consultar → registrar webhook → conferir entregas, mais a verificação HMAC do receive em Python e Node.
- [Getting Started](https://docs.zemocapital.com/getting-started): o mesmo destino pelo fluxo de **estoque** — cadastrar em `POST /v1/stock`, simular e solicitar a antecipação.
- [SDK Node.js/TypeScript (@zemo/sdk)](https://docs.zemocapital.com/sdk/node): `npm install @zemo/sdk` — quickstart completo (registrar → simular → antecipar → conciliar).
- [SDK Python](https://pypi.org/project/zemo/): `pip install zemo`.
- [Checklist de go-live](https://docs.zemocapital.com/reference/go-live-checklist) e [Changelog](https://docs.zemocapital.com/reference/changelog).