Vamos começar definindo callbacks (também conhecidos como webhooks). Há duas maneiras de dois aplicativos se comunicarem para compartilhar informações: pesquisas e retornos de chamada. A votação é como fazer uma viagem e perguntar ao motorista “já chegamos?” a cada 5 minutos. Chamadas de retorno são como adormecer e o motorista acordar quando você finalmente chegar lá.
Callbacks são mensagens automatizadas enviadas de aplicativos para notificar que algo aconteceu. Eles têm uma carga útil (ou corpo) e são enviados para um URL exclusivo.
A API HelloSign envia callbacks para o ciclo de vida de uma solicitação de assinatura. Em vez de chamar a API para verificar o status de uma solicitação, você pode ouvir esses retornos de chamada para construir um fluxo confiável em seu aplicativo.
Vejamos o exemplo de criação de uma solicitação de assinatura simples. Depois de chamar o endpoint “ signature_request / create_embedded ” , você receberá uma resposta da API com um status (“200” se foi bem-sucedido. Caso contrário, aprenda nossas mensagens de erro) e um JSON contendo informações pertinentes à chamada que você fez. Esta resposta é útil porque fornece informações básicas sobre a solicitação, permite que você saiba que nosso servidor a recebeu com sucesso e que não houve problemas com os parâmetros que você passou.
Aqui está o que está acontecendo nos bastidores:
Se, por exemplo, houve um problema durante o processamento do documento porque o documento carregado tem uma tag de texto malformada, isso é sinalizado como um erro e nossa API irá notificá-lo de que isso aconteceu por meio de um evento de retorno de chamada. Não seria bom para você saber que houve um problema com seu arquivo imediatamente, em vez de ter que descobrir da maneira mais difícil?
É por isso que é uma prática recomendada aguardar o retorno de chamada “signature_request_sent” (que só dispara quando o processamento do documento é concluído) antes de tentar abrir um URL de assinatura no iFrame. No caso do erro que usamos como exemplo, um callback “file_error”será enviado. É assim que um exemplo do evento de retorno de chamada “file_error” se parecerá no Painel de API:
Outro exemplo de quando você pode se beneficiar dos retornos de chamada é fazer o download do documento final (assinado). O retorno de chamada “signature_request_all_signed” será acionado somente depois que todos os signatários concluírem o documento e ele estiver pronto para download. Nesse caso, uma prática recomendada é aguardar o evento de retorno de chamada “signature_request_all_signed”e, em seguida, acionar o download do documento . Isso garante que você obterá a cópia final do documento com todas as assinaturas e o status “concluído” na trilha de auditoria.
Respondendo a callbacks
A API HelloSign enviará callbacks para qualquer URL que você indicar. Você pode definir o retorno de chamada da conta usando a chamada de API da conta ou manualmente na página de configurações.
Seu endpoint precisará retornar um código HTTP 200 e um corpo de resposta contendo o seguinte texto: “Hello API Event Received”. Caso contrário, o retorno de chamada será considerado uma falha e será tentado novamente mais tarde. Consulte o artigo “Eventos e retornos de chamada” para obter mais informações sobre isso. Para ilustrar o fluxo de trabalho:
Solicite uma trial do Dropbox e conte sempre com o apoio da equipe Figo Sofware!
