Callbacks do S-Sign

Publicado por QA em

You are here:
< Back

Pré-requisito obrigatório de rede

Atenção: o IP público de saída utilizado para envio dos callbacks é 54.232.135.99/32.

Para que o callback funcione corretamente, o cliente deve solicitar a liberação/allowlist do IP 54.232.135.99/32 em seu firewall, WAF, proxy reverso, API Gateway ou qualquer outro mecanismo de controle de acesso aplicado ao endpoint receptor.

Sem essa liberação, a aplicação do cliente pode bloquear as requisições enviadas pelo S-Sign, mesmo que a URL de callback esteja cadastrada corretamente.

Checklist de infraestrutura:

  • Solicitar a liberação do IP 54.232.135.99/32;
  • Liberar requisições de entrada originadas desse IP;
  • Permitir o método HTTP POST;
  • Permitir o header Content-Type: application/json;
  • Garantir que a URL esteja acessível externamente;
  • Manter certificado TLS/HTTPS válido, quando a URL utilizar HTTPS;
  • Verificar se WAF, proxy, VPN ou regras de geolocalização não bloqueiam a origem;
  • Disponibilizar logs de acesso para diagnóstico.

Quando o S-Sign envia callbacks

O S-Sign envia callback somente quando todas as condições abaixo são atendidas:

  1. O envelope foi criado como envelope de integração/externo;
  2. O envelope possui um tenant válido;
  3. Existe uma configuração de integração ativa associada ao envelope;
  4. A configuração possui uma URL de callback preenchida;
  5. O fluxo do envelope alcança um dos eventos suportados.

Envelopes criados exclusivamente pelo portal, sem a identificação de origem externa e sem configuração de integração associada, não disparam esses callbacks.

Configuração da URL

A URL de callback é cadastrada na configuração de integração do tenant. Ela deve ser uma URL absoluta válida, por exemplo:

https://integracao.cliente.com.br/api/ssign/callback

A URL pode conter caminho, porta e parâmetros de query, desde que esteja acessível pelo serviço de callback.

Contrato da requisição

O callback é enviado por HTTP POST com conteúdo JSON.

Headers
Content-Type: application/json
Payload
{
  "EnvelopeId": 12345,
  "Action": "COMPLETED"
}
Campos
Campo Tipo Obrigatório Descrição
EnvelopeId inteiro Sim Identificador do envelope no S-Sign.
Action texto Sim Evento ocorrido no envelope.

Os nomes observados no envio efetivo utilizam EnvelopeId e Action. Recomenda-se que o desserializador do sistema receptor aceite os campos sem depender de diferenciação entre letras maiúsculas e minúsculas.

Resposta esperada do sistema receptor

O endpoint do cliente deve responder rapidamente com um código HTTP de sucesso 2xx, preferencialmente:

HTTP/1.1 200 OK

Exemplo de resposta:

{
  "received": true
}

O conteúdo da resposta não é usado como comando para alterar o envelope. O importante é que a requisição seja aceita e processada de maneira idempotente.

Recomendações:

  • Responder 200 OK, 201 Created, 202 Accepted ou 204 No Content somente após aceitar o evento;
  • Não executar processamento demorado antes de responder; quando possível, registrar o evento e encaminhá-lo para uma fila interna;
  • Não usar redirecionamentos 301 ou 302 como resposta normal;
  • Tratar qualquer repetição do mesmo evento sem duplicar efeitos;
  • Registrar EnvelopeId, Action, data/hora, IP de origem e resultado do processamento;
  • Não depender da ordem absoluta de chegada dos eventos sem validar o estado atual do envelope.

Resumo dos retornos de callback

Action Significado Natureza
ONFILLING Envelope entrou em preenchimento Intermediário
FILLED Todos os responsáveis concluíram o preenchimento Intermediário
ONAPPROVAL Envelope entrou em aprovação Intermediário
APPROVED Todos os autorizadores aprovaram Intermediário
PENDING Envelope está aguardando assinaturas Intermediário
COMPLETED Envelope foi concluído Final
REJECTED Um signatário recusou a assinatura Final/impeditivo
REPROVED Um autorizador reprovou o envelope Final/impeditivo
EXPIRED Envelope expirou Final
DELETED Envelope foi excluído Final

Detalhamento de cada callback

ONFILLING — Em preenchimento

O que significa

Indica que o envelope entrou na etapa de preenchimento e está aguardando a atuação de um ou mais participantes do tipo Responsável.

Enquanto existir responsável aguardando o preenchimento, o envelope permanece nessa etapa.

O que fazer para acontecer
  1. Criar um envelope pela integração.
  2. Associar uma configuração de integração com URL de callback.
  3. Adicionar pelo menos um participante do tipo Responsável.
  4. Definir campos que devem ser preenchidos pelo responsável, quando aplicável.
  5. Enviar/iniciar o envelope.

O callback também pode ser emitido quando um envelope editado ou anteriormente expirado é reavaliado e ainda possui responsável aguardando preenchimento.

Exemplo
{
  "EnvelopeId": 12345,
  "Action": "ONFILLING"
}
Próximos retornos possíveis

Normalmente FILLED, mas o envelope também pode posteriormente ser excluído ou expirar.

FILLED — Preenchimento concluído

O que significa

Indica que todos os participantes responsáveis concluíram suas atividades de preenchimento.

Esse retorno não significa que o envelope foi concluído. Após o preenchimento:

  • se ainda houver autorizadores aguardando, o envelope segue para aprovação;
  • se não houver autorizadores pendentes, o envelope segue para assinaturas.
O que fazer para acontecer
  1. Criar e enviar um envelope com um ou mais responsáveis.
  2. Fazer todos os responsáveis acessarem o envelope.
  3. Preencher os campos obrigatórios.
  4. Confirmar/finalizar o preenchimento de cada responsável.

O evento somente ocorre quando não restar responsável com status aguardando.

Exemplo
{
  "EnvelopeId": 12345,
  "Action": "FILLED"
}
Estado esperado após o evento
  • ONAPPROVAL, quando houver autorizador pendente; ou
  • PENDING, quando o envelope estiver pronto para assinatura.

ONAPPROVAL — Em aprovação

O que significa

Indica que o envelope está aguardando a decisão de um ou mais participantes do tipo Autorizador.

O envelope ainda não está liberado para conclusão das assinaturas enquanto houver autorizadores pendentes.

O que fazer para acontecer
  1. Criar um envelope pela integração.
  2. Adicionar pelo menos um autorizador.
  3. Enviar/iniciar o envelope.
  4. Caso existam responsáveis, concluir primeiro todos os preenchimentos.

O callback também pode ocorrer após edição ou reativação de um envelope quando ainda existir autorizador aguardando.

Exemplo
{
  "EnvelopeId": 12345,
  "Action": "ONAPPROVAL"
}
Próximos retornos possíveis
  • APPROVED, se todos aprovarem;
  • REPROVED, se um autorizador reprovar;
  • EXPIRED ou DELETED, conforme ação/prazo do envelope.

APPROVED — Aprovação concluída

O que significa

Indica que a etapa de autorização foi concluída com sucesso. Todos os autorizadores necessários aprovaram o envelope e não existe autorizador aguardando ou com reprovação.

Após esse evento, o envelope é colocado em situação pendente para continuar o fluxo de assinatura.

O que fazer para acontecer
  1. Criar e enviar um envelope que possua autorizador.
  2. Caso existam responsáveis, concluir o preenchimento.
  3. Fazer cada autorizador acessar o envelope.
  4. Selecionar a opção de aprovação.
  5. Concluir a aprovação de todos os autorizadores pendentes.
Exemplo
{
  "EnvelopeId": 12345,
  "Action": "APPROVED"
}
Observação

APPROVED não é sinônimo de COMPLETED. O envelope foi aprovado, mas ainda pode depender de assinaturas.

PENDING — Pendente de assinatura

O que significa

Indica que o envelope está ativo e aguardando a atuação dos signatários/testemunhas liberados para assinatura.

É o estado operacional normal antes da conclusão, quando não há preenchimentos nem aprovações pendentes.

O que fazer para acontecer

Existem alguns caminhos:

Criação direta para assinatura

  1. Criar um envelope pela integração.
  2. Adicionar signatários/testemunhas, sem responsável ou autorizador pendente.
  3. Enviar/iniciar o envelope.

Após aprovação

  1. Criar envelope com autorizadores.
  2. Obter aprovação de todos.
  3. O fluxo segue para pendência de assinatura.

Após preenchimento sem aprovação

  1. Criar envelope com responsável e sem autorizador.
  2. Concluir todos os preenchimentos.
  3. O fluxo segue para pendência de assinatura.

Após edição/reativação

Um envelope reavaliado pode voltar a PENDING quando não possui responsável ou autorizador aguardando.

Exemplo
{
  "EnvelopeId": 12345,
  "Action": "PENDING"
}
Observação

Na função de teste da URL de callback, o S-Sign usa EnvelopeId: 1 e Action: PENDING. Esse evento de teste não deve ser tratado como envelope real sem validação adicional.

COMPLETED — Concluído

O que significa

Indica que o fluxo do envelope foi concluído com sucesso. Todas as ações obrigatórias dos participantes foram atendidas e o envelope alcançou o estado final de conclusão.

Após a conclusão, o S-Sign também executa outros processos, como geração/armazenamento do relatório de assinatura, notificações e tratamento de recursos temporários. Esses processos podem ser assíncronos ou ocorrer após o disparo do callback.

O que fazer para acontecer
  1. Criar e enviar um envelope válido.
  2. Concluir os preenchimentos, se houver responsáveis.
  3. Aprovar o envelope, se houver autorizadores.
  4. Realizar todas as assinaturas obrigatórias.
  5. Em fluxo ordenado, respeitar a sequência dos participantes.
  6. Não recusar, reprovar, excluir ou deixar o envelope expirar.
Exemplo
{
  "EnvelopeId": 12345,
  "Action": "COMPLETED"
}
Cuidados da integração
  • O callback confirma a conclusão lógica do envelope.
  • Caso a integração precise baixar documentos/relatórios, recomenda-se implementar retentativa controlada, pois artefatos posteriores podem estar em processamento.
  • O consumidor deve ser idempotente para não baixar ou registrar o mesmo envelope mais de uma vez.

REJECTED — Assinatura recusada

O que significa

Indica que um participante recusou a assinatura do envelope.

A recusa de assinatura é diferente da reprovação feita por um autorizador. O S-Sign possui motivos de recusa padronizados, incluindo informação incorreta, pessoa não responsável, documentos ausentes, retorno à negociação e outros.

O que fazer para acontecer
  1. Criar e enviar um envelope com pelo menos um signatário.
  2. Fazer o signatário acessar o fluxo de assinatura.
  3. Selecionar a opção de recusar/rejeitar o documento.
  4. Informar o motivo solicitado.
  5. Confirmar a recusa.
Exemplo
{
  "EnvelopeId": 12345,
  "Action": "REJECTED"
}
Observação

Uma edição posterior pode permitir que o envelope volte ao fluxo, conforme suas regras e composição. Portanto, o sistema consumidor não deve assumir que nunca haverá um evento posterior para o mesmo EnvelopeId.

REPROVED — Reprovado

O que significa

Indica que um participante do tipo Autorizador reprovou o envelope durante a etapa de aprovação.

REPROVED está relacionado à decisão do autorizador; REJECTED está relacionado à recusa de assinatura por um signatário.

O que fazer para acontecer
  1. Criar e enviar um envelope que possua autorizador.
  2. Concluir preenchimentos anteriores, quando existirem.
  3. Fazer o autorizador acessar o envelope.
  4. Selecionar a opção de reprovação.
  5. Confirmar a decisão.
Exemplo
{
  "EnvelopeId": 12345,
  "Action": "REPROVED"
}

EXPIRED — Expirado

O que significa

Indica que o prazo do envelope terminou antes da conclusão do fluxo.

A expiração é processada pelo S-Sign de forma assíncrona. Por isso, o callback pode não ser recebido exatamente no primeiro segundo após a data limite.

O que fazer para acontecer
  1. Criar um envelope pela integração.
  2. Definir uma data de expiração.
  3. Enviar o envelope.
  4. Manter alguma ação obrigatória pendente.
  5. Aguardar a data expirar e o processo de expiração executar.
Exemplo
{
  "EnvelopeId": 12345,
  "Action": "EXPIRED"
}
Observação

Alterações posteriores na data de expiração podem recolocar o envelope em preenchimento, aprovação ou pendência, conforme os participantes restantes. O consumidor deve aceitar novas transições para o mesmo envelope.

DELETED — Excluído

O que significa

Indica que o envelope foi excluído no S-Sign. A exclusão funcional é tratada como estado do envelope e pode envolver exclusão lógica dos registros/arquivos relacionados.

O que fazer para acontecer
  1. Criar um envelope pela integração.
  2. Garantir que seu estado permita exclusão.
  3. Excluir o envelope pelo portal ou endpoint de integração aplicável.
  4. Aguardar o processamento do fluxo de exclusão.
Exemplo
{
  "EnvelopeId": 12345,
  "Action": "DELETED"
}
Cuidados da integração

O receptor deve definir se o evento causará cancelamento, ocultação ou exclusão lógica do registro local. Evite exclusão física automática sem política de auditoria e retenção.

Sequências comuns

Envelope somente com signatários
PENDING → COMPLETED

Possíveis finais alternativos:

PENDING → REJECTED
PENDING → EXPIRED
PENDING → DELETED
Envelope com responsáveis e signatários
ONFILLING → FILLED → PENDING → COMPLETED
Envelope com autorizadores e signatários
ONAPPROVAL → APPROVED → PENDING → COMPLETED

Alternativa de reprovação:

ONAPPROVAL → REPROVED
Envelope com responsáveis, autorizadores e signatários
ONFILLING → FILLED → ONAPPROVAL → APPROVED → PENDING → COMPLETED

Essas sequências representam o fluxo esperado, mas edições, reativações, expiração e processamento assíncrono podem produzir novas transições para o mesmo envelope.

Falhas, reprocessamento e idempotência

Quando o envio inicial falha, o S-Sign registra um callback pendente para reprocessamento. O registro pode assumir os estados internos:

Estado interno Significado
PENDING Callback aguardando nova tentativa.
SUCCESS Callback reenviado com sucesso.
EXPIRED Evento pendente deixou de ser aplicável porque o envelope expirou.
CANCELED Evento pendente foi cancelado porque o envelope mudou de estado.

Regras relevantes:

  • não é criado outro pendente idêntico para o mesmo envelope, tenant e evento enquanto já existir um equivalente;
  • quando surge um evento diferente, callbacks pendentes anteriores do envelope podem ser cancelados;
  • antes do reenvio, o S-Sign verifica se o estado do envelope ainda corresponde ao evento;
  • tentativas e mensagens de erro são registradas;
  • o timeout padrão observado no código é de 30 segundos, sujeito à configuração do ambiente;
  • a janela/duração de reprocessamento é configurável por ambiente.
Obrigação de idempotência

O sistema receptor deve considerar que o mesmo par EnvelopeId + Action pode ser entregue mais de uma vez. Uma chave idempotente recomendada é:

EnvelopeId + Action

Se o domínio do cliente permitir que a mesma ação ocorra novamente após uma edição/reativação, acrescente versão do estado ou data de recebimento e consulte o estado atual antes de ignorar o evento.

Exemplo de implementação do receptor

Pseudocódigo:

receber POST
validar JSON
validar EnvelopeId > 0
validar Action na lista suportada
registrar evento recebido
verificar idempotência
encaminhar processamento para fila interna
responder HTTP 200 rapidamente

Lista permitida de ações:

ONFILLING
FILLED
ONAPPROVAL
APPROVED
PENDING
COMPLETED
REJECTED
REPROVED
EXPIRED
DELETED

Embora exista a constante interna ERROR, ela é usada como fallback técnico para ação não mapeada e não representa um retorno funcional normal documentado para o cliente.

Última atualização em setembro 01, 2026
Categorias: