Integrador ASSINA — API de documentos

Onde fica: Integrador ASSINA › Loja de Plugins › API para o seu sistema · API em /api/webservice/

O ASSINA recebe um documento em PDF, gera os links de assinatura para os signatários e avisa quando todos assinaram. A API permite que um ERP ou outro sistema envie o documento, acompanhe o andamento e baixe o PDF assinado — sem ninguém abrir o painel do ASSINA.

Antes de começar

• A chave de API é da empresa e é vista (e regenerada) pelo administrador da empresa no ASSINA. Regenerar invalida a chave anterior na hora. Também é possível ter chaves dedicadas por integração, para trocar uma sem afetar as outras.
• Para receber o aviso de documento concluído, cadastre no ASSINA o endereço de aviso (webhook) e o segredo. Sem segredo, o ASSINA não envia o aviso (a assinatura é obrigatória).

Autenticação

Cabeçalho X-API-Key em toda chamada. A chave identifica a empresa: ela só alcança os documentos da própria empresa. Chave ausente ou inválida: 401.

Recursos

Documentos

Método e rota	Para quê
POST /documentos	Cria o documento e devolve os links. Limite: 30 chamadas por minuto.
GET /documentos/{documento_id}	Estado do documento — para o ERP consultar de tempos em tempos (120 por minuto).
GET /documentos/{documento_id}/assinado	Baixa o PDF assinado. 404 enquanto nem todos assinaram (20 por minuto).
POST /documentos/{documento_id}/recriar	Refaz o PDF de um documento que veio do ISP, com o contrato atual, mantendo os mesmos links.

POST /documentos — campos:

• titulo (obrigatório) e tipo (livre, por exemplo contrato);
• o PDF, em base64: arquivo_base64 (um arquivo) ou arquivos (vários, cada um com titulo e arquivo_base64). Com vários, o cliente assina uma vez e cada peça ganha a sua folha de assinatura; entrega_modo escolhe unico (padrão) ou separado;
• signatarios: lista com nome (obrigatório), cpf, email, telefone e papel (por exemplo Cliente, Testemunha). Ao menos um é obrigatório; o CPF informado é validado;
• opcionais: assinante_responsavel_id e assinante_testemunha_id, para carimbar com o par de assinantes da empresa. Se o certificado de quem carimba estiver vencido, o documento não é criado.

Resposta: documento_id, titulo e links — um por signatário, com nome, papel, token, url e expira_em. Entregue ao cliente a url.

GET /documentos/{id} — resposta: status (rascunho, aguardando, assinado ou cancelado), concluido (verdadeiro quando o PDF assinado está pronto), assinado_em e a lista de signatarios, cada um com status, estado do envio, quando visualizou, quando viu o PDF e quando assinou.

Para quem integra com ERPs e com o OMNI

Método e rota	Para quê
GET /empresa	De quem é a chave: id, nome e cnpj. Serve de teste de conexão e para o OMNI saber a quem a chave pertence.
GET /assinaturas-pendentes	Documentos aguardando assinatura de um cliente, por cpf (preferencial) ou telefone. Somente leitura. Traz o link pronto, o papel e a origem.
POST /ixc/os/{os_id}/link	Dado o id de uma O.S. do IXC, devolve o link de assinatura — criando o documento na hora, se ainda não foi importado. Repetir devolve o mesmo link.
POST /omni/vincular	O OMNI grava aqui o seu endereço e a sua chave, para o ASSINA poder disparar o link por WhatsApp. Corpo: omni_base_url, omni_api_key, integration_row_id, modo (texto ou template).

Webhook de saída — documento concluído

Quando todos assinam, o ASSINA faz POST no endereço de aviso da empresa:

{"evento": "documento.concluido", "documento_id": "00000000-0000-0000-0000-000000000001",
 "titulo": "Contrato de exemplo", "tipo": "contrato", "origem": "api", "status": "assinado",
 "concluido": true, "assinado_em": "2026-10-20T14:30:00+00:00", "hash": "…",
 "signatarios": [{"nome": "Cliente Exemplo", "papel": "Cliente", "status": "assinado",
                  "visualizado_em": "…", "pdf_visto_em": "…", "assinado_em": "…"}]}

• Assinatura: X-Assina-Signature: sha256=<hex>, HMAC-SHA256 do corpo exato com o segredo da empresa. Veja como conferir em Webhooks com HMAC.
• Tentativas: até 3, com espera crescente (imediata, 5 s e 20 s). Resposta 4xx (exceto 408 e 429) encerra as tentativas.
• Se todas falharem, o ERP ainda pode consultar por GET /documentos/{id}. Cada documento guarda o histórico de entregas e pode ser reenviado pelo painel.

O ASSINA também recebe avisos do OMNI sobre o envio do link por WhatsApp (enviado, entregue, lido, falhou) em POST /omni/webhook, validando a assinatura X-Integrador-Omni-Signature quando há segredo configurado.

Exemplos

Criar um documento com um signatário

curl -s -X POST https://assina.exemplo.com.br/api/webservice/documentos \
  -H "X-API-Key: chave-de-exemplo" \
  -H "Content-Type: application/json" \
  -d '{"titulo": "Contrato de exemplo", "tipo": "contrato",
       "arquivo_base64": "JVBERi0xLjQK…",
       "signatarios": [{"nome": "Cliente Exemplo", "cpf": "11122233396",
                        "email": "cliente@exemplo.com.br", "telefone": "5545999990000",
                        "papel": "Cliente"}]}'

{"documento_id": "00000000-0000-0000-0000-000000000001", "titulo": "Contrato de exemplo",
 "links": [{"nome": "Cliente Exemplo", "papel": "Cliente", "token": "exemplo-token",
            "url": "https://assina.exemplo.com.br/assinar/exemplo-token",
            "expira_em": "2026-11-20T14:00:00+00:00"}]}

Acompanhar e baixar

curl -s https://assina.exemplo.com.br/api/webservice/documentos/00000000-0000-0000-0000-000000000001 \
  -H "X-API-Key: chave-de-exemplo"

curl -s -o contrato-assinado.pdf \
  https://assina.exemplo.com.br/api/webservice/documentos/00000000-0000-0000-0000-000000000001/assinado \
  -H "X-API-Key: chave-de-exemplo"

Como o ASSINA conversa com o ISP e o IXC

O ASSINA também busca as O.S. de assinatura no ERP, de minuto em minuto: no Integrador ISP pela API de assinatura (escopo assinatura, veja Integrador ISP) e no IXC pelo cadastro de O.S. O ISP, por sua vez, avisa o ASSINA para refazer um PDF (/documentos/{id}/recriar).

Erros comuns

Código	Quando
400	Sem arquivo_base64/arquivos, PDF ilegível, nenhum signatário ou CPF inválido.
401	X-API-Key ausente ou inválida.
404	Documento de outra empresa ou inexistente; PDF assinado ainda não pronto.
409	Em /recriar: documento já assinado, assinatura em andamento ou origem inválida (motivo informa).
429	Limite de chamadas por minuto excedido.
503	Falha ao guardar o PDF no armazenamento; nada é criado.

Leia também

• Integrações — visão geral
• Integrador ISP
• Integrador OMNI