Catalisa.Building Blocks

API do E-Signature

24 endpoints em 5 recursos. A permissão de cada rota é a que o código exige — conferida linha a linha, não copiada do nome.

Ver a referência detalhada, com corpo de requisição e catálogo de erros →

34 endpoints

Página de assinatura hospedada

/e-signature14
  • GET/e-signature/sign/:codeA página: termo em PDF (pdf.js da mesma origem, sem iframe), nome e CPF mascarados, "li e concordo", código por e-mail, assinatura desenhada ou digitada. Estados finais: assinado, recusado, expirado, cancelado, inválido
  • GET/e-signature/sign/:code/stateEstado pela ótica do link, sem dado pessoal — e sem "conferido": a conferência só vale para quem a fez
  • GET/e-signature/sign/:code/document.pdfO PDF do envelope, do storage do bloco (o original vai para lá na criação)
  • POST/e-signature/sign/:code/otpEnvia o código de 6 dígitos ao e-mail do signatário. Espera de 60 s entre envios, validade de 10 min, **10 envios na vida do link**. O envio é reivindicado no banco (atualização condicional): pedidos paralelos não furam a espera nem o teto
  • POST/e-signature/sign/:code/verify{ otp } → { signToken, expiresAt }. Cada conferência gasta uma tentativa reivindicada no banco antes de comparar: 5 erros seguidos travam por 15 min e **15 tentativas na vida do link** travam o link (LINK_LOCKED) até a casa reemitir. O signToken (30 min, uso único, do signatário que conferiu) é o que libera assinar ou recusar
  • POST/e-signature/sign/:code/sign{ accepted: true, method: 'drawn' \'typed', image: 'data:image/png;base64,...' } (até 1 MB de corpo, 512 KB de PNG). Exige o signToken do /verify, que é consumido (uso único; volta a valer se o motor não aplicou por motivo passageiro). Quem aplica é o SignatureApplier do motor (sela o PDF, move o envelope a PARTIALLY_SIGNED/COMPLETED e publica esignature.signer.signed); a página grava ao lado a própria evidência (aceite, fator, hash da imagem e do documento)
  • POST/e-signature/sign/:code/decline{ reason, signToken } (3 a 500 caracteres, mesmo token do /verify). Sob o mesmo lock do applier (esignature:signing:<requestId>): recusar e assinar nunca correm juntos; signatário em SIGNING não recusa. Signatário e envelope vão a DECLINED
  • POST/e-signature/api/v1/esignature/provider-configsCria configuração e cifra as credenciais. Responde 201ESIGNATURE_ADMIN
  • GET/e-signature/api/v1/esignature/provider-configsLista as configurações da organizaçãoESIGNATURE_READ
  • GET/e-signature/api/v1/esignature/provider-configs/:idBusca uma configuração (sem as credenciais)ESIGNATURE_READ
  • PATCH/e-signature/api/v1/esignature/provider-configs/:idAtualiza nome, credenciais, ajustes ou estadoESIGNATURE_ADMIN
  • DELETE/e-signature/api/v1/esignature/provider-configs/:idExclusão lógica. Responde 204ESIGNATURE_ADMIN
  • POST/e-signature/api/v1/esignature/provider-configs/:id/testTesta a conexão com o provedorESIGNATURE_ADMIN
  • POST/e-signature/api/v1/esignature/provider-configs/:id/set-defaultMarca como padrão e desmarca as demaisESIGNATURE_ADMIN

Solicitações de assinatura

/e-signature/api/v1/esignature/requests12
  • POST/e-signature/api/v1/esignature/requestsCria a solicitação a partir de um arquivo. Responde 201ESIGNATURE_CREATE
  • POST/e-signature/api/v1/esignature/requests/from-templateCria a partir de um template **do provedor**. Responde 201ESIGNATURE_CREATE
  • GET/e-signature/api/v1/esignature/requestsLista solicitações, paginadoESIGNATURE_READ
  • GET/e-signature/api/v1/esignature/requests/:idBusca a solicitação com os signatáriosESIGNATURE_READ
  • POST/e-signature/api/v1/esignature/requests/:id/cancelCancela a solicitaçãoESIGNATURE_CREATE
  • POST/e-signature/api/v1/esignature/requests/:id/resendReenvia a todos ou a um signatárioESIGNATURE_CREATE
  • GET/e-signature/api/v1/esignature/requests/:id/evidence**Lê** a evidência já gravada, sem recapturar e sem chamar o provedor. meta.evidence e meta.capturedAt vêm null enquanto nada foi capturado. A evidência devolvida (aqui e no POST) não traz token de link de terceiro: o ZapSign grava só documentTokenRef/signers[].tokenRef (SHA-256 truncado), e tokens de evidência antiga são retirados da respostaESIGNATURE_READ
  • POST/e-signature/api/v1/esignature/requests/:id/evidenceCaptura (ou recaptura) a evidência de um envelope COMPLETED: hash do documento assinado, nível legal, material do provedor. Provedor com getEvidence fornece; sem ele, o bloco baixa o PDF assinado e calcula o SHA-256. Publica esignature.request.evidence_captured; também roda sozinha quando o webhook conclui o envelope. A recaptura preserva signedFileId e certificateFileId (lidos dos documentos do envelope; um id conhecido nunca vira null)ESIGNATURE_CREATE
  • POST/e-signature/api/v1/esignature/requests/:id/refreshReconsulta o provedor e concilia a cópia local: estado, conclusão, URL, validade e cada signatário (por id externo, depois por e-mail). meta.changed e meta.signersUpdated dizem o que mudou; publica esignature.request.completed quando a conciliação concluiESIGNATURE_CREATE
  • GET/e-signature/api/v1/esignature/requests/:id/downloadURL do documento assinado. Exige COMPLETEDESIGNATURE_READ
  • GET/e-signature/api/v1/esignature/requests/:id/certificateURL assinada do **certificado de conclusão** arquivado no file-storage (certificateFileId). Exige COMPLETED (400 antes disso); 404 se não há certificado arquivado. Só a cópia arquivada — não consulta o provedorESIGNATURE_READ
  • DELETE/e-signature/api/v1/esignature/requests/:idExclusão lógica. Responde 204ESIGNATURE_DELETE

Webhook do provedor

/e-signature/api/v1/esignature/webhooks1
  • POST/e-signature/api/v1/esignature/webhooks/:configIdRecebe evento do provedor. Resolve a configuração pelo id (ativa, não excluída) e escopa tudo pela organização **dela**; corpo lido como bytes e entregue ao provedor para verificar a assinatura**Pública** — sem JWT. Ver §14 e §15

Conferir assinatura de arquivo

/e-signature/api/v1/esignature6
  • POST/e-signature/api/v1/esignature/verificationsConfere um arquivo. **Multipart**: file (o PDF/P7S/XML assinado), detachedFile (o conteúdo, se a assinatura for destacada), businessId — corpo total até 1 MB. **JSON**: { "fileId", "detachedFileId"?, "businessId"? } com arquivos já no file-storage da organização, até ESIGNATURE_VERIFICATION_MAX_BYTES. Responde 201 com meta.reused e meta.auditRecordedESIGNATURE_CREATE
  • GET/e-signature/api/v1/esignature/verificationsLista, filtros filter[fileHash], filter[businessId], filter[status]ESIGNATURE_READ
  • GET/e-signature/api/v1/esignature/verifications/:idUma conferênciaESIGNATURE_READ
  • GET/e-signature/api/v1/esignature/verifications/proof?fileHash=**Prova pela trilha**: o arquivo com este SHA-256 foi conferido, quando, com que resultado; confere o digest do relatório e a linha localESIGNATURE_READ
  • GET/e-signature/api/v1/esignature/verification-settingsConfiguração efetiva; source: DEFAULT = padrão da casa, não alteradoESIGNATURE_READ
  • PUT/e-signature/api/v1/esignature/verification-settings{ "thirdPartyEnabled"?, "fileRetentionDays"? } (1–365). Publica esignature.verification-settings.changedESIGNATURE_ADMIN

Saúde

/e-signature/health1
  • GET/e-signature/healthSonda de disponibilidade. Pública, não contabilizada nas 16 rotas