Primeiro envelope em 5 minutos

Este guia cria e envia um envelope pela API v4 no Sandbox. Depois da homologação, apenas a URL base e a chave mudam.

Antes de começar

Base URL: https://api.sandbox.supersign.com.br

Chave: ss_test_..., gerada na área de Sandbox em Configurações → Desenvolvedor

A chave deve permanecer no backend ou em um gerenciador de segredos.

Cada operação POST exige uma Idempotency-Key de 8 a 255 caracteres ASCII imprimíveis.

O PDF não é enviado em Base64 para a API. Primeiro você registra o documento; depois envia o binário diretamente para a URL assinada retornada.

1. Valide a chave

A resposta identifica o ambiente, a conta, a integração e o usuário responsável:

{
  "accountId": "conta_123",
  "environment": "sandbox",
  "integration": {
    "id": "integracao_123",
    "name": "ERP"
  },
  "responsibleUser": {
    "id": "usuario_123",
    "name": "Maria Silva",
    "email": "maria@example.com"
  }
}

2. Crie o rascunho

Observe a barra final em /envelopes/: ela faz parte da rota atual.

{
  "envelopeId": "550e8400-e29b-41d4-a716-446655440000"
}

3. Configure o envelope

4. Defina os participantes

Gere um UUID v4 para cada participante e reutilize o mesmo ID nas chamadas seguintes.

Para que o participante receba a página de assinatura e os e-mails em outro idioma, envie o campo opcional locale no objeto dele (em signatories, approvers ou observers): pt-BR (português), en (inglês) ou es (espanhol). Sem o campo, o participante recebe tudo em pt-BR. O mesmo campo existe em POST /v4/api/envelopes/send-now (inclusive em carbonCopies) e nos participantes de modelo. Exemplo de signatário em inglês:

{
  "id": "7a9e6679-7425-40de-944b-e07fc1f90ae7",
  "order": 1,
  "deliveryMethod": "EMAIL",
  "locale": "en",
  "name": "John Smith",
  "email": "john@example.com",
  "qualification": "Contratante",
  "type": "INDIVIDUAL"
}

O locale pode ser definido ao criar ou sincronizar os participantes. Para trocar depois o idioma da página de assinatura e dos e-mails de um participante (pt-BR, en ou es), envie o campo opcional locale em PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId}. Sem o campo, o idioma atual não muda; a troca vale para os próximos e-mails e mensagens.

5. Baixe o PDF de exemplo e registre-o

Não tem um PDF à mão? A SuperSign® oferece um documento de exemplo de 1 página, com a marca d’água "EXEMPLO, SEM VALOR". O download é público (não exige chave) e tem limite de 20 requisições por minuto por IP:

O arquivo tem 2171 bytes; confira o valor no seu download. Em produção o envelope criado com esse PDF consome a cota normalmente, então use a sandbox para testar.

Agora registre o documento. Informe o nome, o tipo e o tamanho exato do arquivo em bytes.

A resposta contém o ID do documento, a URL de upload e os campos assinados:

[
  {
    "documentId": "2f1c5d8d-97dd-40a8-aefe-1eec9d17e301",
    "uploadUrl": "https://storage.googleapis.com/...",
    "uploadFields": {
      "key": "...",
      "Content-Type": "application/pdf",
      "x-goog-algorithm": "...",
      "x-goog-credential": "...",
      "x-goog-date": "...",
      "policy": "...",
      "x-goog-signature": "..."
    }
  }
]

6. Envie o binário para a URL assinada

Faça um multipart/form-data diretamente para uploadUrl, incluindo todos os pares de uploadFields sem alterá-los e o arquivo no campo file. A autorização da SuperSign não é enviada nessa chamada.

Exemplo em Node.js 20 ou superior:

A política assinada expira em 15 minutos e exige exatamente o tamanho e o tipo declarados.

7. Posicione os campos

As páginas começam em 1. Posição e tamanho usam pontos de PDF, com origem no canto superior esquerdo.

Descubra o tamanho das páginas antes de posicionar. Uma página A4 em pé mede 595 × 842 pontos, mas um PDF pode ter página deitada, girada ou recortada. GET /v4/api/envelopes/{envelopeId}/documents/{documentId}/pages devolve width e height de cada página já como ela aparece na tela (rotação aplicada); mantenha x + width e y + height do campo dentro desses limites. Se o documento ainda estiver em processamento, a resposta é 409 PAGE_GEOMETRY_UNAVAILABLE: aguarde e tente de novo.

O PUT substitui a coleção completa. Um campo omitido é removido; "fields": [] remove todos.

8. Envie o envelope

Se o PDF ainda estiver sendo processado, a API pode responder 409 ENVELOPE_DOCUMENTS_NOT_READY. Aguarde e repita o mesmo envio com a mesma Idempotency-Key.

9. Consulte o estado

Para automações de conclusão, prefira webhooks em vez de consultas repetidas.

Passar para Produção

Depois de homologar o fluxo, troque a base URL por https://api.sign.supersign.com.br e a chave por uma credencial ss_live_.... Rotas, corpos e tratamento de respostas permanecem iguais.

Antes de começar#

1. Valide a chave#

2. Crie o rascunho#

3. Configure o envelope#

4. Defina os participantes#

5. Baixe o PDF de exemplo e registre-o#

6. Envie o binário para a URL assinada#

7. Posicione os campos#

8. Envie o envelope#

9. Consulte o estado#

Passar para Produção#