Integration Overview

Página única de orientação para desenvolvedores e agentes de IA integrarem a API V2 de Antecipação de Recebíveis da Zemo Capital. Aqui você encontra o panorama, as entidades, o fluxo completo e os links canônicos — sem schemas ou parâmetros detalhados (esses vivem apenas na Referência Técnica e no openapi.json).

Vai integrar com IA (inteligência artificial)?

Use esta documentação otimizada para LLMs → — um índice único, na ordem de leitura certa (panorama → autenticação → especificação v1.3.0 → webhooks/HMAC → erros → golden path), pronto para colar no contexto do seu agente. Também disponível em /.well-known/llms.txt.

Fontes canônicas

Referência técnica completa (endpoints, parâmetros, schemas, requests, responses): /reference (Scalar, gerado do OpenAPI)
Caminho executável (6 curls, de credencial a webhook verificado): /golden-path
Especificação OpenAPI (fonte da verdade): /openapi.json
SDK Python: pip install zemo — exemplos de código por endpoint embutidos na /reference (x-codeSamples)

Visão geral da plataforma

A API permite que originadores (parceiros) antecipem recebíveis (NF-e, duplicatas, contratos) de seus cedentes, com liquidação via PIX. Características:

Multi-tenant: tudo é filtrado pelo originator_id do token (zero-trust).
Respostas JSON: valores monetários em BRL com 2 casas decimais (string). IDs em UUIDv7. Cada valor monetário vem sob dois nomes — o canônico (*_future_value / *_present_value) e o deprecado — sempre com o mesmo número; veja Valores do Recebível.
Base URL de homologação: https://receivables-api-sandbox.zemocapital.com (use Produção apenas no go-live)
Versão atual: v1 (prefixo de rota).

Entidades principais

Entidade	Descrição	Relação
Originator	O parceiro autenticado (tenant). Você.	Dono de tudo abaixo.
Assignor (cedente)	Dono do recebível que quer antecipar.	Pertence ao originator.
Payer (sacado)	Devedor do recebível (quem paga no vencimento).	Referenciado pelos recebíveis.
Stock item (estoque)	Recebível pré-cadastrado aguardando antecipação.	Vira `title` quando antecipado.
Operation (operação)	A antecipação efetiva de um ou mais recebíveis.	Gera `titles`.
Title (título)	Recebível individual dentro de uma operação, com saldo devedor rastreado.	Pertence a uma operation.

Aprofunde em Conceitos → Lifecycle (máquinas de estado de estoque e operação).

Fluxo completo de integração

Autenticar — troque suas credenciais de API por um JWT (ver Autenticação).
(Opcional) Descobrir produtos — GET /v1/products lista os product_id válidos, com faixas de taxa/prazo/valor.
Simular — POST /v1/simulate calcula valor líquido, taxas e descontos sem criar nada. Use para mostrar valores ao cedente.
Criar a antecipação — dois caminhos:
- Direta: POST /v1/operations/direct (envia cedente + recebíveis + banco numa chamada).
- Via estoque: POST /v1/stock para cadastrar, depois POST /v1/stock/request-anticipation.
Assinatura do contrato — ao ser aprovada, a operação dispara o contrato sozinha e os signatários são notificados por e-mail. Você não precisa fazer nada. Se quiser apresentar o link de assinatura na sua própria interface (modo embedded), veja Assinatura embedded.
Acompanhar — GET /v1/operations/{id} e GET /v1/titles/{id} para status e saldo devedor.
Reagir a eventos — registre webhooks para operation.approved, operation.contract_signed, title.paid, etc. (lista canônica de eventos em Webhooks).

Os detalhes de taxas (hierarquia, PMP, limites) estão em Conceitos → Taxas. O saldo devedor está em Conceitos → Saldos.

Quickstart (mínimo)

Exemplo ilustrativo do caminho mais curto — autenticar → simular (read-only, não cria nada). Parâmetros completos, schemas e responses vivem na Referência Técnica e no openapi.json.

import zemo

# 1. Autenticar (Client Credentials → JWT RS256; o SDK faz o auto-refresh)
zemo.user = zemo.Originator(
    client_id="zk_sbx_...",  # prefixo de Sandbox (zk_test_* legado segue valido)
    client_secret="sk_test_...",
    environment="https://receivables-api-sandbox.zemocapital.com",
)

# 2. Simular antecipação (não cria nada — use para mostrar valores ao cedente)
sim = zemo.Simulation.create(
    receivables=[zemo.Receivable(
        external_id="NF-001",
        payer_name="Cliente XPTO SA",
        payer_document="98765432000198",
        net_future_value=10000.00,
        requested_net_future_value=10000.00,
        due_date="2026-08-15",
    )],
    fees=zemo.Fees(monthly_rate_pct=3.5),
)
print(sim.opr_net_present_liquid_value)  # valor líquido da antecipação

# 1. Trocar credenciais por um JWT de curta duração
TOKEN=$(curl -s -X POST "https://receivables-api-sandbox.zemocapital.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"zk_test_...","client_secret":"sk_test_..."}' | jq -r .access_token)

# 2. Simular
curl -X POST "https://receivables-api-sandbox.zemocapital.com/v1/simulate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"receivables":[{"external_id":"NF-001","payer_name":"Cliente XPTO SA","payer_document":"98765432000198","net_future_value":10000,"requested_net_future_value":10000,"due_date":"2026-08-15"}],"fees":{"monthly_rate_pct":3.5}}'

Nomes dos valores: net_future_value e requested_net_future_value são os nomes canônicos; os antigos (net_face_value, requested_advance_value) seguem aceitos em toda a série 1.x — e são removidos na 2.0 — e as respostas trazem os dois. De-para completo em Valores do Recebível.

Para criar a antecipação de fato, troque o passo 2 por POST /v1/operations/direct (ou o fluxo via estoque). Veja o fluxo completo acima e os exemplos de SDK por endpoint na Referência Técnica.

Autenticação

Fluxo Client Credentials: troque X-Client-Id/X-Client-Secret por um JWT RS256 de curta duração via POST /v1/auth/token. O SDK faz isso automaticamente (auto-refresh). Tokens carregam scopes granulares (stock:read, operation:create, etc.) — 403 scope_insufficient se faltar (veja a tabela de scopes). Detalhes em Autenticação.

Idempotência

Toda rota financeira (POST/PUT/PATCH/DELETE) deve enviar o header Idempotency-Key (UUID, TTL 24h, escopo por originator_id + key). Mesma chave + mesmo body = resposta cacheada; mesma chave + body diferente = 409. Detalhes em Idempotência.

Paginação

Endpoints de listagem (GET /v1/stock, /operations, /titles, /products, etc.) usam limit (1–200, default 50) e offset. A resposta inclui total (contagem antes da paginação) para você iterar. O SDK Python pagina automaticamente via query() (generator) ou page() (manual).

# Primeira página; avance offset pelo número de items recebidos até alcançar total.
curl "https://receivables-api-sandbox.zemocapital.com/v1/operations?limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"
# {"items": [...], "total": 137}

# query() percorre todas as páginas; page() permite controlar uma página específica.
for operation in zemo.Operation.query(limit=50):
    print(operation.id)

items, total = zemo.Operation.page(limit=50, offset=100)

Rate limits

Limite default de 120 requisições/minuto por client_id (sliding window). Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining; em 429, o header Retry-After indica os segundos até o reset. Detalhes em Rate Limits.

Webhooks

Registre URLs HTTPS para receber eventos (operation.created, operation.approved, title.paid, etc. — a lista canônica vive em Webhooks). Toda entrega é assinada com HMAC-SHA256 no header X-Zemo-Signature — valide a assinatura antes de processar.

SDKs

Node.js/TypeScript: npm install @zemocapital/sdk — auth, idempotência, paginação (for await), tipos camelCase gerados do OpenAPI e verificação de webhooks. Quickstart completo e exemplos por endpoint na Referência Técnica.
Python: pip install zemo — cobre auth, idempotência, paginação e verificação de webhooks. Exemplos de código (SDK) por endpoint na Referência Técnica.

Visão geral da plataforma​

Entidades principais​

Fluxo completo de integração​

Quickstart (mínimo)​

Autenticação​

Idempotência​

Paginação​

Rate limits​

Webhooks​

SDKs​

Links canônicos​