API externa

Onde fica: Endereço /api/webservice (use a chave de Loja de Plugins › API para o seu sistema)Desde a v1.3.0

Resumo do que a API externa permite: criar documento, consultar status, baixar o PDF assinado e receber o aviso de conclusão. Esta página descreve o que existe; o endereço exato aparece no campo Endpoint da ficha do plugin.

Antes de começar

Observação

Toda chamada leva o cabeçalho X-API-Key com a chave da empresa. Cada chave só enxerga os documentos da própria empresa.

Pegue a chave em API para o seu sistema.

O que existe

• POST /api/webservice/documentos: cria o documento e devolve os links. Envia-se o título, o tipo, o PDF em base64 (arquivo_base64) ou uma lista de peças (arquivos, até 10), a forma de entrega (entrega_modo: unico ou separado) e a lista de signatarios (nome, CPF, e-mail, telefone e papel). Opcionalmente, o responsável e a testemunha da empresa (assinante_responsavel_id, assinante_testemunha_id).
• GET /api/webservice/documentos/{id}: status do documento e de cada signatário (envio, abertura, PDF visto, assinatura). concluido fica verdadeiro quando o PDF assinado está pronto.
• GET /api/webservice/documentos/{id}/assinado: baixa o PDF assinado. Devolve 404 enquanto não concluir.
• POST /api/webservice/documentos/{id}/recriar: usado pelo Integrador ISP para refazer o PDF mantendo os links.
• POST /api/webservice/ixc/os/{os_id}/link: devolve o link de assinatura de uma O.S. do IXC, criando o documento se preciso.
• GET /api/webservice/empresa: de quem é a chave (só identidade, sem dados de cliente).
• GET /api/webservice/assinaturas-pendentes: documentos aguardando um cliente, buscando por cpf ou telefone.

Webhook de saída

Quando o documento conclui, o ASSINA envia um POST em JSON para a URL cadastrada, com evento igual a documento.concluido, o documento_id, título, tipo, origem, assinado_em, o código hash e a lista de signatários. O cabeçalho X-Assina-Signature traz sha256= seguido do HMAC-SHA256 do corpo. Há até 3 tentativas, e recusa 4xx (exceto 408 e 429) não é repetida.

Regras que a API aplica

Atenção

Há limite de chamadas por minuto: 30 criações, 120 consultas de status e 20 downloads, por rota. Certificado vencido de quem carimba pela empresa recusa a criação (409), igual ao painel. CPF inválido e PDF ilegível recusam com 400.

• Documento criado por API mostra via API na lista.
• Sem indicar responsável e testemunha, o documento usa o par padrão da empresa.

O que acontece depois

O documento aparece em Todos os documentos e segue o fluxo normal de assinatura, links e auditoria.

Perguntas frequentes

Como sei se o cliente assinou? Consulte o status ou receba o webhook.

O PDF vai em base64? Sim, no campo arquivo_base64 de cada peça.

Leia também

• API para o seu sistema
• Integrador ISP
• Todos os documentos