Getting Started

Faca sua primeira antecipacao em 4 passos.

Ja tem uma integracao rodando? Os nomes dos valores ganharam par

Cada valor monetario tem hoje um nome canonico e um deprecado, com o mesmo numero. Este guia usa o canonico:

Canonico (usado aqui)	Deprecado (segue aceito)
`gross_future_value` + `gross_future_value_deductions`	`gross_face_value`
`net_future_value`	`net_face_value`
`requested_net_future_value`	`requested_advance_value`
`opr_net_present_liquid_value`	`opr_liquid_value`
`opr_present_value_discount`	`opr_discounted_value`

Os deprecados continuam aceitos e devolvidos em toda a serie 1.x e serao removidos na 2.0 (politica). Se voce esta so seguindo o guia, ignore esta caixa; se esta migrando, o de-para completo (e as duas pegadinhas) esta em Valores do Recebivel.

Use o Sandbox neste guia

Os comandos abaixo usam o ambiente de homologacao e credenciais de Sandbox — zk_sbx_* (ou zk_test_*, prefixo legado) — sem transacoes reais. O self-service ainda emite apenas credenciais de Producao; solicite o par de Sandbox a equipe Zemo antes de comecar. Use zk_live_* somente no go-live.

1. Autentique-se

Troque suas credenciais de API por um JWT de curta duração (fluxo Client Credentials — OAuth2):

CLIENT_ID="zk_test_..."
read -rsp "Client secret de Sandbox: " CLIENT_SECRET; echo
export CLIENT_ID CLIENT_SECRET

TOKEN=$(jq -n '{client_id: env.CLIENT_ID, client_secret: env.CLIENT_SECRET}' \
  | curl -sS -X POST "https://receivables-api-sandbox.zemocapital.com/v1/auth/token" \
      -H "Content-Type: application/json" --data-binary @- \
  | jq -r .access_token)
unset CLIENT_SECRET

O token exchange via POST /v1/auth/token é o fluxo oficial para integração servidor a servidor; o SDK faz isso automaticamente. O endpoint POST /v1/auth/login (e-mail/senha) é para sessões de usuário, não para autenticação de API. Detalhes em Autenticação.

2. Registre o recebivel

Primeiro, cadastre um sacado e um cedente de teste. O dedup por documento torna estes comandos seguros para repetir no mesmo Sandbox:

PAYER_ID=$(curl -sS -X POST "https://receivables-api-sandbox.zemocapital.com/v1/payers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cnpj":"98765432000198","legal_name":"Sacado Sandbox SA"}' | jq -r .id)

ASSIGNOR_ID=$(curl -sS -X POST "https://receivables-api-sandbox.zemocapital.com/v1/assignors" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"document":"12345678000195","legal_name":"Cedente Sandbox SA","type":"J"}' | jq -r .id)

Agora cadastre o recebivel (NF-e, duplicata, contrato) no estoque. O vencimento é calculado como 70 dias a partir da execução para manter os valores da simulação reproduzíveis:

DUE_DATE=$(python3 -c 'from datetime import date, timedelta; print(date.today() + timedelta(days=70))')
EXTERNAL_ID="NF-SANDBOX-$(date +%s)"

curl -X POST "https://receivables-api-sandbox.zemocapital.com/v1/stock" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @- <<JSON
  {
    "assignor_id": "$ASSIGNOR_ID",
    "payer_id": "$PAYER_ID",
    "external_id": "$EXTERNAL_ID",
    "backing_type": "NFE",
    "gross_future_value": "10000.00",
    "gross_future_value_deductions": "0.00",
    "net_future_value": "10000.00",
    "due_date": "$DUE_DATE",
    "pre_authorized": true
  }
JSON

Resposta (201) — quatro campos, so isso:

{
  "id": "01970dc9-...",
  "external_id": "NF-SANDBOX-...",
  "status": "IN_STOCK",
  "created_at": "<timestamp>"
}

Guarde o id retornado — voce vai usar nos proximos passos. Para reler o item inteiro (inclusive o pre_authorized), use GET /v1/stock/{item_id}.

gross_future_value e o valor de face bruto do lastro; net_future_value e o NFV (Net Future Value) — o valor de face futuro liquido dos descontos ja aplicados a ele. Aqui os dois sao iguais porque o exemplo nao tem descontos, e por isso gross_future_value_deductions vai 0. Declarar as deducoes e obrigatorio sempre que voce usa gross_future_value: sem elas, 422 DEDUCTIONS_REQUIRED_WITH_GROSS. Quando bruto e NFV diferem, o desagio deste fluxo incide sobre o NFV e a diferenca e informacao gerencial: o valor pago nunca supera o lastro. Bruto e NFV precisam ser > 0. Veja Valores do Recebivel (NFV).

3. Simule a antecipacao

Antes de solicitar, simule para ver o valor liquido sem criar nada:

curl -X POST "https://receivables-api-sandbox.zemocapital.com/v1/stock/simulate-anticipation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stock_item_ids": ["01970dc9-..."],
    "requested_net_future_value": 10000.00,
    "fees": {
      "monthly_rate_pct": 3.5,
      "floating_days": 2
    }
  }'

Resposta (nada e criado):

{
  "status": "SIMULATED",
  "opr_gross_future_value": "10000.00",
  "opr_net_future_value": "10000.00",
  "opr_present_value_discount": "840.00",
  "opr_net_present_liquid_value": "9160.00",
  "average_days_in_advance": 70,
  "floating_days": 2,
  "receivables": [
    {
      "stock_item_id": "01970dc9-...",
      "external_id": "NF-SANDBOX-...",
      "gross_future_value": "10000.00",
      "net_future_value": "10000.00",
      "requested_net_future_value": "10000.00",
      "due_date": "<70 dias a partir da execucao>",
      "days_advanced": 72,
      "present_value_discount": "840.00",
      "net_present_liquid_value": "9160.00",
      "monthly_rate_pct": "3.5",
      "fee_source": "operation"
    }
  ]
}

O exemplo mostra os nomes canonicos; a resposta REAL traz os dois

Cada valor acima chega tambem sob o nome deprecado, com o mesmo numero: opr_net_present_liquid_value vem acompanhado de opr_liquid_value, present_value_discount de discount_brl, net_present_liquid_value de liquid_value, e assim por diante. Foram omitidos aqui so para o exemplo caber — nenhum campo saiu do contrato.

Taxas opcionais

Se voce nao informar fees, o sistema aplica automaticamente a hierarquia de taxas configurada pelo Backoffice para o seu originador.

O fluxo de estoque antecipa sempre 100% dos itens

A simulacao e a solicitacao consideram sempre 100% dos itens listados em stock_item_ids, com desagio sobre o net_future_value (Net Future Value) de cada um. Por isso requested_net_future_value e obrigatorio e validado: tem que ser exatamente igual a soma dos net_future_value dos itens selecionados; qualquer outro valor e recusado com 422 STOCK_REQUESTED_VALUE_MISMATCH. Nao existe campo de percentual nestas duas rotas, justamente porque aqui e sempre 100%.

Enviar um valor menor nao produz antecipacao parcial — produz erro. Antecipacao parcial do Net Future Value, com o restante voltando ao estoque, so existe em POST /v1/operations/direct. Para fixar o liquido a receber, use fees.total_liquid_value_brl. Veja Valores do Recebivel (NFV).

4. Solicite a antecipacao

Se os valores estao ok, solicite a antecipacao:

curl -X POST "https://receivables-api-sandbox.zemocapital.com/v1/stock/request-anticipation" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "stock_item_ids": ["01970dc9-..."],
    "requested_net_future_value": 10000.00,
    "bank": {
      "use_document_pix": true
    },
    "fees": {
      "monthly_rate_pct": 3.5,
      "floating_days": 2
    }
  }'

Resposta:

{
  "id": "01970dc6-...",
  "display_number": "OP-A1B2C3D4-E5F6G7H8",
  "lifecycle_status": "WAITING_APPROVAL",
  "opr_gross_future_value": "10000.00",
  "opr_net_future_value": "10000.00",
  "opr_present_value_discount": "840.00",
  "opr_net_present_liquid_value": "9160.00",
  "other_debt_discounts": "0.00",
  "opr_net_liquid_value": "9160.00"
}

opr_net_present_liquid_value e opr_net_liquid_value sao campos diferentes

opr_net_present_liquid_value (9160.00) e o PIX ao cedente — e por ele que se concilia. opr_net_liquid_value e uma projecao informativa (opr_net_present_liquid_value menos other_debt_discounts), nao e persistida e nao entra no vocabulario canonico: continua com esse nome, sem par. Aqui os dois coincidem porque other_debt_discounts e 0.00. Detalhe em Valores do Recebivel.

A operacao foi criada. A partir daqui:

Se precisa de aprovacao (WAITING_APPROVAL): o Backoffice aprova e o contrato e enviado automaticamente para assinatura
Se auto-aprovada (APPROVED_DIRECT): o contrato e enviado automaticamente, sem esperar aprovacao
Em ambos os casos os signatarios recebem o link por e-mail, sem nenhuma chamada sua. O despacho nao e instantaneo: leva ate ~2 minutos apos a aprovacao (mais o tempo do provedor). Se voce for consultar o contrato nessa janela, trate 404/409 como "ainda nao" e re-tente com backoff
Para apresentar o link na sua propria interface em vez do e-mail, veja Assinatura embedded
Apos contrato assinado: pagamento PIX ao cedente, acompanhe via GET /v1/titles

Qual campo de estado ler

Este endpoint devolve lifecycle_status — o campo autoritativo, o mesmo que aparece em GET /v1/operations/{id}. POST /v1/operations/direct devolve, em vez dele, o alias legado status. Se o seu cliente atende os dois fluxos, leia com precedencia lifecycle_status ?? status. Nos webhooks a regra e outra: so operation.created e operation.approved trazem lifecycle_status — nos demais eventos, busque o estado com GET /v1/operations/{id}. Regra completa em Lifecycle.

Fluxo alternativo: operacao direta

Se preferir enviar todos os dados em uma unica chamada (sem registrar no estoque antes), use POST /v1/operations/direct. Veja Referencia Tecnica.

1. Autentique-se​

2. Registre o recebivel​

3. Simule a antecipacao​

4. Solicite a antecipacao​

1. Autentique-se

2. Registre o recebivel

3. Simule a antecipacao

4. Solicite a antecipacao