Entendendo o funcionamento do Callback

3 07/10/2025

O processamento de Callbacks é uma etapa essencial para garantir a continuidade e integridade dos fluxos de assinatura no SmartShare.

Essa funcionalidade permite que o sistema receba e trate automaticamente os retornos enviados pelos provedores de assinatura (S-SIGN e Certisign), atualizando o andamento das atividades conforme cada evento recebido.

Visão geral do Callback

O SmartSigner foi aprimorado para aumentar a resiliência no processamento de callbacks enviados pelos provedores S-SIGN e Certisign.

Agora, o recebimento e o processamento de callbacks foram desacoplados em duas camadas:

API de Callback

  1. (WebAPI REST):
    • Responsável por receber os callbacks e salvar os dados em arquivos JSON no diretório configurado.
  2. Serviço de Processamento de Callbacks:
    • Responsável por ler periodicamente os arquivos JSON, processar as informações (atualizar status do documento no banco de dados) e remover ou mover os arquivos conforme o resultado.

API de Callback

Após instalada a API de Callback do SmarSigner no servidor, terá o nome callbackAPI e as seguintes características, conforme o provedor de assinatura:

  • S-SIGN:
    URL: https://dominio/callbackAPI/api/callback?provider=ssign

    Método: POST

    Body: a callbackAPI espera receber as propriedades envelopeId e action do S-SIGN para o registro correto do Callback.

  • CERTISIGN

    URL: https://dominio/callbackAPI/api/callback?provider=certisign
    Método: POST

    Body: a callbackAPI espera receber as propriedades documentId e action da Certisign para o registro correto do Callback.

Ao receber a requisição de Callback originada do provedor de assinatura, uma pasta no formato aaaa-mm-dd será criada no diretório configurado, com o arquivo JSON contendo os dados do Callback:

Observação: O nome do arquivo JSON sempre seguirá o padrão: envelopeId_GUID.json para S-SIGN ou documentId_GUID.json para Certisign (para evitar duplicidades).

O conteúdo do arquivo JSON salvo pela API de Callback segue o seguinte padrão:

Onde:

  • timestamp: registro da data e hora em que o callback foi recebido e registrado.
  • originalPayload: corpo da requisição de callback enviado pelo provedor de assinatura.
  • envelopeId: código do envelope no S-SIGN
  • action: ação aplicada no documento, podendo ser:
    • S-SIGN: COMPLETED, PENDING, EXPIRED, DELETED
    • Certisign: FLOW (equivalente ao COMPLETED)
  • provider:
    • 0 – Certisign
    • 1 – S-SIGN
  • documentId: código do documento na Certisign.

Serviço de Processamento de Callbacks

O Serviço de Processamento de Callbacks é a segunda camada do processo de callback responsável por ler periodicamente os arquivos JSON gerados pela callbackAPI no diretório configurado, que contêm as informações de retorno (callbacks) dos provedores de assinatura S-SIGN e Certisign. A partir desses arquivos, o serviço interpreta o status (action) de cada envelope/documento, atualiza o registro de liberação do anexo no banco de dados, envia o documento assinado ao SmartShare e realiza o avanço automático do fluxo.

Para saber como configurar o Serviço de Processamento de Callbacks com a integração S-SIGN, acesse: Configurando o SmartSigner para integração com o S-SIGN


Para saber como configurar o Serviço de Processamento de Callbacks com a integração S-SIGN, acesse: Configurando o SmartSigner para integração com a Certisign