Ambientes

Base URLs

Ambiente	Base URL	Credencial
Produção	https://receivables-api.zemocapital.com	zk_live_*
Sandbox (homologação)	https://receivables-api-sandbox.zemocapital.com	zk_sbx_* (ou zk_test_*, legado)

O ambiente é indicado pelo prefixo da credencial: zk_live_* (Produção) e zk_sbx_* (Sandbox). O prefixo zk_test_* também identifica Sandbox e continua válido nas credenciais já emitidas. O SDK Node infere a base URL pelo prefixo. No SDK Python, informe environment="production" para Produção ou passe a URL completa do Sandbox (environment="https://receivables-api-sandbox.zemocapital.com").

O Sandbox está ativo como ambiente de homologação de clientes: mesma API e mesmas regras, sem transações reais. Use somente credenciais de Sandbox (zk_sbx_* ou zk_test_*) nesse ambiente e troque para zk_live_* apenas no go-live (veja o checklist).

Emissão de credenciais

O self-service ainda não tem seletor de ambiente e emite somente credenciais de Produção (zk_live_*/sk_live_*). Para obter credenciais zk_sbx_*/sk_test_* de Sandbox (ou zk_test_*, prefixo legado), solicite o provisionamento à equipe Zemo.

Teste interativo do portal ("Testar no navegador")

A ferramenta interativa em /reference envia requisições diretamente para a API, sem proxy de terceiros. Antes de testar, selecione o servidor Sandbox e use exclusivamente credenciais de Sandbox (zk_sbx_* ou zk_test_*). Execute a operação POST /v1/auth/token com o corpo JSON e informe o access_token retornado como Bearer; não use o formulário OAuth genérico do botão Authorize. Nunca envie credenciais zk_live_* em testes de homologação.

Identificação de ambiente

Toda resposta inclui o header X-Zemo-Env (prod, sandbox, dev). Em todo ambiente exceto Produção, a resposta também inclui o header X-Zemo-Banner, com o nome do ambiente em maiúsculas (ex.: X-Zemo-Banner: SANDBOX).

Especificação OpenAPI (fonte canônica para ferramentas)

Para Postman, Insomnia, geradores de SDK e agentes de IA, use o spec estático — sempre acessível e estável:

https://docs.zemocapital.com/openapi.json

• Referência técnica interativa (humanos): /reference (Scalar) — parâmetros, schemas e exemplos.
• O endpoint live /v1/openapi.json também existe, mas o caminho recomendado para ferramentas é o spec estático acima.

Postman Collection

Importe a collection para testar os endpoints rapidamente:

• Download: postman_collection.json (gerada automaticamente do OpenAPI)

Variáveis a configurar:

Variável	Valor
base_url	https://receivables-api-sandbox.zemocapital.com
client_id	Sua credencial zk_sbx_* (ou zk_test_*)
auth_token	JWT retornado por POST /v1/auth/token

Preencha client_id na collection e crie zemo_client_secret no Postman Vault; o secret não é salvo na collection. Execute primeiro a request de troca de credenciais por JWT (POST /v1/auth/token), na pasta Auth. O script limpa qualquer token anterior e grava o novo access_token em auth_token; as demais requests enviam Authorization: Bearer {{auth_token}}.

Cada request financeira mantém sua própria variável idempotency_*. Ela é gerada no primeiro envio e preservada nos retries. Limpe essa variável quando quiser iniciar uma nova operação ou antes de reenviar um payload corrigido após uma resposta 4xx; mantenha-a intacta ao repetir exatamente a mesma tentativa após timeout ou erro 5xx.

SDK Python

pip install zemo

import zemo

zemo.user = zemo.Originator(
    client_id="zk_test_...",
    client_secret="sk_test_...",
    environment="https://receivables-api-sandbox.zemocapital.com",
)

Veja o Quickstart para um exemplo completo (autenticar → simular).

SDK Node.js/TypeScript

npm install @zemocapital/sdk

import { Zemo } from "@zemocapital/sdk";

const zemo = new Zemo({
  clientId: "zk_sbx_...",       // zk_sbx_*/zk_test_* → sandbox | zk_live_* → produção
  clientSecret: "sk_test_...",
});

Veja o quickstart completo do SDK Node (registrar → simular → antecipar → conciliar).

Limitações por ambiente

Feature	Produção	Sandbox
Liquidação PIX	Real (Starkbank)	Simulada (Starkbank Sandbox — sem dinheiro real)
ZapSign (contratos)	Real	Simulada (ZapSign Sandbox)
Rate limiting	120 rpm	120 rpm
SSL/TLS	Obrigatório	Obrigatório