Primeiro envelope em 5 minutos

Este guia cria e envia um envelope pela API v4 usando o Sandbox, ambiente indicado para desenvolvimento e homologação. O contrato é o mesmo em Produção; ao entrar em operação, troque somente a URL base e a chave.

Antes de começar

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

Chave: ss_test_..., gerada 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.

5. Registre o PDF

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.

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, altere a URL base para https://api.sign.supersign.com.br e substitua a chave por uma credencial ss_live_.... Mantenha as mesmas rotas, corpos e regras de tratamento das respostas.

Antes de começar#

1. Valide a chave#

2. Crie o rascunho#

3. Configure o envelope#

4. Defina os participantes#

5. Registre o PDF#

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#