API

Guia para integradores. A narrativa completa e as tabelas de escopos estão em API_PLATFORM.md. Para uma visão de contrato parcial, use a referência OpenAPI (subset). O JSON OpenAPI do site é curado manualmente e pode não listar todos os endpoints ou detalhes do runtime; em divergência, prevalece o comportamento da API implantada.

Autenticação

Authorization: Bearer sk_test_… ou sk_live_…. Sessão JWT do app também é aceita em rotas de sign (tenant derivado do token).

Cada API key tem scopes (ex.: envelopes:read, envelopes:write, export:read, webhooks:read, webhooks:write). Sem escopo adequado → 403 com INSUFFICIENT_SCOPE.

API keys

Crie e revogue chaves no portal (Sign → API Keys) ou via GET/POST /api/sign/api-keys. O valor sk_* só aparece na criação — armazene em cofre seguro.

Abrir API keys no portal →

Idempotência

Envie o header Idempotency-Key: <uuid> em POSTs que alteram estado (criação de envelope, resend, cancel, criação de webhook, etc.). Repetições com a mesma chave retornam a mesma resposta armazenada.

Endpoints principais

  • POST /api/sign/envelopes — criar envelope
  • GET /api/sign/envelopes — listar (filtros de status, data, signatário)
  • GET /api/sign/envelopes/:id — detalhe
  • POST /api/sign/envelopes/:id/send — enviar convites
  • POST /api/sign/envelopes/:id/resend — reenviar pendentes (ver API_PLATFORM.md)
  • POST /api/sign/envelopes/:id/cancel — cancelar (se aplicável; ver API_PLATFORM.md)
  • GET /api/sign/envelopes/:id/export — exportar proof pack (ZIP), scope export:read
  • GET /api/sign/usage — uso do mês / limites
  • GET /api/sign/api-keys — listar API keys
  • POST /api/sign/api-keys — criar API key
  • GET /api/sign/webhooks — listar webhooks
  • POST /api/sign/webhooks — criar webhook

Ver subset OpenAPI interativo →

Ambientes test / live

O prefixo sk_test_* vs sk_live_* define o ambiente. Mesmas rotas; quotas e risco operacional separados.

Exemplo: criar envelope

curl
curl -X POST "https://<host>/api/sign/envelopes" \
  -H "Authorization: Bearer sk_test_XXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"title":"Contrato","signers":[{"name":"João","phone":"5511999999999"}]}'

Erros comuns

  • 401 — token ausente ou inválido.
  • 403 + INSUFFICIENT_SCOPE — escopo da API key não cobre a rota.
  • 429 + RATE_LIMITED — limite por janela; respeite Retry-After quando enviado.
  • 402 / entitlements — quota ou plano quando aplicável ao produto.

Ligações úteis

API_PLATFORM.md (referência completa) →

Próximos passos