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).

Fontes canônicas

• Referência técnica completa (endpoints, parâmetros, schemas, requests, responses): /reference (Scalar, gerado do OpenAPI)
• 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.
• Base URL: https://receivables-api.zemocapital.com
• 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

1. Autenticar — troque suas credenciais M2M por um JWT (ver Autenticação).
2. (Opcional) Descobrir produtos — GET /v1/products lista os product_id válidos, com faixas de taxa/prazo/valor.
3. Simular — POST /v1/simulate calcula valor líquido, taxas e descontos sem criar nada. Use para mostrar valores ao cedente.
4. 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.
5. Acompanhar — GET /v1/operations/{id} e GET /v1/titles/{id} para status e saldo devedor.
6. Reagir a eventos — registre webhooks para operation.paid, title.paid, etc.

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_live_...",
    client_secret="sk_live_...",
    environment="production",
)

# 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="12345678000199",
        net_face_value=10000.00,
        requested_advance_value=10000.00,
        due_date="2026-08-15",
    )],
    fees=zemo.Fees(monthly_rate_pct=3.5),
)
print(sim.opr_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.zemocapital.com/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"zk_live_...","client_secret":"sk_live_..."}' | jq -r .access_token)

# 2. Simular
curl -X POST "https://receivables-api.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":"12345678000199","net_face_value":10000,"requested_advance_value":10000,"due_date":"2026-08-15"}],"fees":{"monthly_rate_pct":3.5}}'

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).

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.paid, title.paid, operation.cancelled, etc.). Toda entrega é assinada com HMAC-SHA256 no header X-Zemo-Signature — valide a assinatura antes de processar. Detalhes em Webhooks.

SDKs

• 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.

Links canônicos

• Referência técnica completa (/reference)
• OpenAPI (/openapi.json)
• Códigos de erro