Autenticação e ambientes

Todas as chamadas são autenticadas por uma chave de API da sua licença, enviada no cabeçalho Authorization.

POST /api/v1/documents HTTP/1.1
Host: api.signxp.com.br
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Ambientes

O prefixo da chave indica o ambiente:

Em produção o convite por e-mail depende de duas coisas: o signatário ter email e o envio não pedir delivery: "none". Nos dois ambientes o signing_url de cada signatário vem na consulta de status, então você sempre tem como entregar o link por conta própria.

Use a chave de teste durante toda a integração. O fluxo é idêntico ao de produção — inclusive a selagem do PDF e os callbacks.

Consultando a sua licença

Uma chave sabe responder sobre si mesma. Use este endpoint no arranque do seu sistema — ou numa tela de diagnóstico — para conferir qual ambiente a chave abre, quanto da quota já foi gasto e quais recursos a licença inclui, sem depender do portal nem do suporte:

GET /api/v1/license

{
  "client": { "reference": "acme", "name": "Acme Indústria Ltda." },
  "key": { "name": "servidor de produção", "environment": "live", "masked": "sk_live_••••3f2a" },
  "license": {
    "plan": "Profissional",
    "status": "active",
    "usable": true,
    "block_reason": null,
    "starts_at": "2026-01-01",
    "expires_at": "2026-12-31",
    "rate_limit_per_minute": 60,
    "features": {
      "ai_validation": true,
      "evidence_capture": true,
      "initials_and_order": true,
      "public_verification": true
    }
  },
  "usage": {
    "period": "2026-07",
    "documents_used": 139,
    "documents_limit": 500,
    "documents_remaining": 361
  }
}

usable é a pergunta que importa antes de enviar: quando ele é false, block_reason traz em português por que os envios estão bloqueados (licença fora de vigência, suspensa, cliente inativo). features diz o que a licença libera — é o que evita descobrir por um 422 que a rúbrica não está contratada. Veja erros e limites.

A consulta não consome quota e continua respondendo mesmo quando os envios estão bloqueados — é justamente aí que ela é útil.

Gerenciando as chaves

Em Chaves de API, no portal da sua conta, você pode:

• emitir novas chaves (por exemplo, uma por servidor);
• revogar uma chave imediatamente;
• agendar a expiração em 24h ou 72h, para rotacionar sem derrubar a integração.

A chave em claro aparece uma única vez, no momento da emissão. Guarde-a em um cofre de segredos; nós armazenamos apenas o hash.

Nunca coloque a chave em código do lado do cliente (navegador ou app). Ela dá acesso a todos os documentos da sua licença.

Rotação recomendada

1. Emita a nova chave.
2. Agende a expiração da antiga para 24h ou 72h.
3. Publique o seu sistema usando a nova chave.
4. Confirme, em Registros, que nenhuma chamada usa mais a chave antiga.

Erros de autenticação

Um 402 não interrompe as assinaturas já em andamento: os links continuam válidos e a consulta de status segue funcionando. Apenas o envio de novos documentos é bloqueado.