Primeiros passos com a API v2

A API da ForSign permite que o seu sistema envie documentos para assinatura sem ninguém abrir o app: você sobe o PDF, cria a operação, acompanha por webhook e baixa o arquivo assinado. Para começar, você precisa da chave de API da empresa e da documentação em docs.forsign.digital.

Antes de começar

• Tenha um plano comercial. Na conta em período de teste, o Painel do desenvolvedor fica bloqueado.
• Tenha um usuário com permissão de integração. Sem ela, o menu Desenvolvedor não aparece.
• Pegue a chave em Desenvolvedor, aba Configurações, campo Chave atual. O passo a passo está em Onde pegar a chave de API.

Como autenticar

Envie a chave no cabeçalho X-Api-Key em toda chamada:

curl -H "X-Api-Key: SUA_CHAVE" https://api.forsign.digital/api/v2/...

A chave não expira. Ela vale até alguém clicar em alterar a chave no Painel do desenvolvedor. Guarde a chave no servidor, nunca no navegador ou no aplicativo do usuário final.

O fluxo básico

1. Suba o PDF. POST /api/v2/document/upload. A resposta traz o id do documento.
2. Crie a operação. POST /api/v1/operation, com o id do documento, os participantes, o tipo de assinatura de cada um e o canal de envio. A v2 não tem endpoint para criar operação: a criação só existe na v1. O resto do fluxo usa a v2.
3. Espere os eventos. Cadastre um webhook do tipo Documento Pronto para Download. Veja Configurar um webhook.
4. Baixe o resultado. GET /api/v2/operations/{id}/files/download/authenticated devolve um ZIP com os PDFs assinados e o dossiê.

Se precisar, a API também conclui (POST /api/v2/operation/{id}/complete) e cancela (POST /api/v2/operation/{id}/cancel) uma operação, e lista, aprova, recusa e baixa anexos.

v1 e v2

As duas versões convivem. A maioria dos endpoints novos está em /api/v2/. A criação de operação só existe na v1, em /api/v1/operation. Confira a versão na página de cada endpoint da documentação.

Na v2, o prefixo muda conforme o endpoint, e os dois estão certos. Concluir, cancelar e listar operações ficam em /api/v2/operation/..., no singular. Baixar arquivos e ver detalhes de uma operação ficam em /api/v2/operations/{id}/..., no plural. Copie o caminho exato da documentação.

O formato das respostas

Toda resposta vem no mesmo envelope:

{ "success": true, "statusCode": 200, "data": { }, "messages": [] }

• As mensagens saem no idioma do cabeçalho Content-Language: pt-br (padrão), en ou es.
• Erro de validação volta com código 400 e o detalhe de cada campo.
• Falta de crédito ou plano vencido volta com código 402. Nesse caso nada é gravado.

O que aparece no app

A operação criada pela API aparece em Minhas operações como qualquer outra, e o feed da operação mostra a API como autora. Na aba Monitoramento do Painel do desenvolvedor você vê o total de requisições, os erros e os tempos de resposta.

Créditos

A chamada à API não custa nada. A operação criada por ela consome os mesmos créditos de uma operação criada na tela: documento, SMS, WhatsApp, certificado e antifraude. Veja O que consome crédito.

Perguntas comuns

Existe um ambiente separado para testar? Não há ambiente público. A ForSign pode transformar uma conta em ambiente de testes, a pedido. Veja Ambiente de testes: como pedir e o que muda.

Tenho que escrever as chamadas HTTP na mão? Não precisa. Há bibliotecas prontas para C# e PHP. Veja SDKs oficiais.

Posso consultar a operação em vez de usar webhook? Pode, mas o webhook avisa na hora certa e evita consultas repetidas. Para baixar o PDF final, espere o evento Documento Pronto para Download.