A API pública foi projetada para que integrações possam repetir requisições com segurança sem criar envelopes, participantes ou operações duplicadas.Idempotency-Key#
Todas as requisições POST em /v4/api/* exigem o header Idempotency-Key.ter entre 8 e 255 caracteres;
usar somente caracteres ASCII imprimíveis;
identificar uma única intenção de negócio;
ser reutilizada somente com o mesmo método, rota e corpo.
Uma boa chave combina o identificador estável do seu sistema com a operação, sem incluir dados pessoais. Exemplo: erp-184-criar-envelope.Os quatro POST que não exigem a chave#
A regra vale para todo POST de /v4/api/*, menos estes quatro. Eles não aparecem com Idempotency-Key obrigatória no contrato e a chave, se enviada, é ignorada:POST | Por que não exige |
|---|
/v4/api/envelopes/{envelopeId}/documents/{documentId}/anchors:find | É leitura (procura texto no PDF); não cria nada |
/v4/api/templates/{templateId}/documents/{documentId}/anchors:find | Mesma operação, no modelo |
/v4/api/webhooks/{webhookId}/secret/rotate | Devolve o segredo novo uma única vez e nunca o guarda para replay; repetir gera outro segredo |
/v4/api/webhooks/{webhookId}/test | Cada chamada precisa enviar um evento de teste de novo, sem replay de 24 horas |
O que acontece em cada cenário#
| Situação | Resposta | O que fazer |
|---|
| Primeira requisição válida | A operação é executada e a resposta bem-sucedida é guardada por 24 horas | Armazene a chave junto ao identificador da operação no seu sistema |
| Mesma chave e mesmo conteúdo | A resposta original é devolvida com Idempotency-Replayed: true | Trate como sucesso; não crie outra operação |
| Mesma chave ainda em processamento | 409 IDEMPOTENCY_KEY_IN_USE | Aguarde e repita com a mesma chave |
| Mesma chave com conteúdo diferente | 422 IDEMPOTENCY_KEY_REUSE | Corrija a integração; use uma nova chave apenas para uma nova intenção |
| Serviço de idempotência indisponível | 503 IDEMPOTENCY_UNAVAILABLE | Não troque a chave; aplique retry com backoff |
| A primeira tentativa falha | A reserva é liberada | Corrija a causa e repita com a mesma chave |
Repetir POST /v4/api/webhooks/ já concluído | 409 IDEMPOTENCY_SECRET_NOT_REPLAYABLE com o id do endpoint (o segredo de assinatura nunca é guardado para replay) | Não crie outro endpoint; gire o segredo em POST /v4/api/webhooks/{webhookId}/secret/rotate |
Somente respostas bem-sucedidas são armazenadas para replay. Nunca gere uma chave nova apenas porque ocorreu timeout: a primeira requisição pode ter sido concluída.
Exemplo#
A resposta de erro usa o objeto error. O campo code deve orientar a lógica da integração; message serve para diagnóstico humano.{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Envelope not found"
}
}
Erros de validação podem trazer uma lista de campos inválidos. Não dependa do texto exato da mensagem para tomar decisões automáticas.Códigos HTTP mais comuns#
| HTTP | Significado | Ação recomendada |
|---|
400 | Corpo, parâmetro ou header inválido | Corrija a requisição; não repita sem alteração |
401 | Chave ausente, inválida ou revogada | Confira o header Authorization e a credencial |
403 | A conta ou a credencial não pode executar a ação | Confira permissões, plano e vínculo do recurso com a conta |
404 | Recurso não encontrado ou não visível para a conta | Confira o ID e evite revelar existência de recursos de outra conta |
409 | Operação concorrente ou estado incompatível | Leia o código do erro; aguarde antes de repetir quando aplicável |
422 | Semântica inválida, incluindo reutilização incorreta da chave | Corrija os dados ou a chave conforme o código |
429 | Limite de requisições excedido | Respeite Retry-After e aplique backoff com jitter |
503 | Proteção crítica temporariamente indisponível | Repita de forma segura com a mesma Idempotency-Key |
Códigos do ambiente de testes (sandbox)#
| Código | HTTP | Quando | O que fazer |
|---|
SANDBOX_TRIAL_READ_ONLY | 403 | O teste grátis da sandbox acabou há menos de 30 dias; a chave de teste só lê (*:read). details.readOnlyUntil traz o fim da janela. | Operações de escrita voltam com um plano que inclua o ambiente de testes; leitura segue normal. Não repita a chamada. |
SANDBOX_TRIAL_EXPIRED | 403 | Teste grátis e janela de leitura encerrados. Nada é apagado. | Assine um plano com sandbox; a conta de teste e as chaves religam no próximo acesso. |
SANDBOX_TRIAL_ALREADY_USED | 409 | Outra conta do mesmo CNPJ ou do mesmo dono já usou o teste grátis. details.accountId identifica a conta. | Use a conta que já tem o teste ou peça ao comercial a liberação desta conta. |
Esses códigos só existem no host de teste (api.sandbox.supersign.com.br). Em produção uma chave ss_test_ recebe 401 com o código de ambiente errado.Política de retry#
Repita automaticamente apenas falhas transitórias: 429, 502, 503, 504 e erros de rede.
Use backoff exponencial com jitter.
Respeite o header Retry-After quando presente.
Mantenha a mesma Idempotency-Key em todas as tentativas da mesma operação.
Não repita automaticamente 400, 401, 403, 404 ou 422 sem corrigir a causa.
Suporte#
Ao abrir um chamado, informe o horário com fuso, método, rota, status HTTP, error.code e o identificador do recurso. Nunca envie a API Key completa. Modificado em 2026-11-15 14:09:47