Introdução

A ForSign expõe uma API REST pra automatizar todo o ciclo de uma assinatura eletrônica — do upload do PDF ao download dos documentos finalizados. Antes de escrever a primeira linha de código, vale entender o conceito central e o vocabulário da plataforma.

A "Operação" — o conceito central

Quase tudo na ForSign gira em torno de uma operação. Pense nela como o contêiner que junta tudo o que precisa acontecer pra um conjunto de documentos ser assinado: os PDFs, quem assina, em que ordem, que formulários preenchem, que anexos enviam, e como tudo se encerra.

Cada operação tem um identificador único — o ID da operação (o campo id retornado na criação) — que você usa pra rastrear, cancelar, finalizar ou baixar os documentos depois. É um número sequencial por conta. Toda ação posterior à criação é "uma operação sobre uma operação".

Glossário

Termos que aparecem em vários endpoints e que vale a pena fixar:

Limites e quotas

Coisas que vale saber antes de planejar a integração:

Formato das respostas

Toda resposta bem-sucedida usa o mesmo envelope:

{
  "success": true,
  "statusCode": 200,
  "data": { /* o resultado do endpoint */ },
  "messages": [{ "value": "Mensagem amigável e localizada" }]
}

• success — true em caso de sucesso.
• statusCode — o código HTTP, repetido no corpo.
• data — o resultado do endpoint (objeto, lista ou null).
• messages[] — mensagens amigáveis (no campo value), localizadas pelo header Content-Language (pt-br por padrão).

Convenção de erros

Os status codes mais comuns:

Erros de validação (400)

Erros de validação trazem os detalhes por campo em detail[]:

{
  "statusCode": 400,
  "description": "O arquivo não foi enviado",
  "detail": [
    { "code": "NotEmptyValidator", "target": "File", "message": "Arquivo é obrigatório" }
  ]
}

• description — mensagem amigável (a primeira falha), localizada.
• detail[] — cada item tem target (o campo), message e code.

Demais erros

Os outros erros (403, 404, 500, e 401 quando há corpo) usam o envelope padrão com success: false:

{
  "success": false,
  "statusCode": 404,
  "messages": [{ "value": "Operação não encontrada" }]
}

Versões da API

Endpoints novos vivem em /api/v2/, alguns legados em /api/v1/. A versão correta está sempre indicada na URL de cada endpoint nesta documentação — sempre confira antes de copiar o exemplo.

Ambiente de testes

Próximos passos