API e webhooks: ligar a votação ao sistema que a entidade já usa

A secretaria exporta a lista de associados do sistema de gestão, limpa à mão, cola na votação. Depois da apuração, faz o caminho de volta: baixa o resultado, digita no cadastro quem participou, arquiva o PDF numa pasta. Duas transcrições manuais por assembleia, cada uma com sua chance de erro, e nenhuma das duas aparecendo em lugar nenhum quando alguém pergunta de onde veio aquele número. Entidade que faz assembleia com frequência não precisa conviver com isso. A API REST e os webhooks do Votari, disponíveis no plano Pro, ligam a votação ao sistema que a entidade já usa.

Dois caminhos, duas funções

A API é você perguntando ao Votari. O webhook é o Votari avisando você. Confundir os dois é a causa mais comum de integração que fica consultando o servidor de minuto em minuto sem necessidade.

Pela API o seu sistema cria a votação, publica, encerra, lê o resultado, baixa a ata e consulta a lista de votantes. Pelo webhook o Votari manda um aviso no momento em que algo acontece, para o endereço que você cadastrar. Uma integração bem feita usa os dois: o webhook dispara o processo, a API busca o detalhe.

O que a API faz

A chave de API sai em painel, integrações. Os endereços ficam sob /api/v1/polls e cobrem o ciclo inteiro de uma votação:

• Listar e consultar. Uma chamada devolve as votações da conta, outra devolve uma votação específica com a configuração dela.
• Criar e alterar. O seu sistema monta a votação com as perguntas, as opções e a lista de aptos que ele já conhece, e ajusta depois se a pauta mudar.
• Publicar e encerrar. São duas ações separadas, de propósito. Publicar abre a urna. Encerrar fecha e congela.
• Resultado, ata e votantes. Depois do encerramento, o resultado vem estruturado, a ata vem em PDF e a lista de quem participou vem separada do conteúdo dos votos.

Essa última separação é a que mais importa em votação secreta. A lista de votantes responde quem participou, o resultado responde o que foi decidido, e não existe chamada que ligue uma coisa à outra, porque o vínculo não é guardado. A arquitetura disso está no texto sobre voto secreto e voto aberto.

O que o webhook avisa

São quatro eventos. poll.published quando a votação abre, vote.cast a cada voto registrado, poll.closed no encerramento e ata.ready quando a ata fica disponível.

O que você faz com cada um depende do seu processo. Uma cooperativa pode usar o vote.cast para acompanhar adesão num painel próprio durante a AGO, sem ninguém recarregando tela. Um sindicato pode usar o ata.ready para arquivar o documento automaticamente no repositório da entidade, no segundo em que ele existe. Um conselho profissional pode usar o poll.closed para disparar a comunicação oficial aos inscritos.

O vote.cast merece um cuidado. Ele diz que um voto entrou, e numa votação secreta ele não pode dizer de quem nem em quem, porque essa informação não existe no banco. Se o seu painel precisa de nome, a votação tem que ser de voto aberto, e isso é decisão de rito, não de integração.

Como saber que o aviso veio do Votari

Um endereço que aceita webhook é um endereço aberto na internet. Qualquer pessoa que descubra a URL pode mandar um corpo inventado dizendo que a votação encerrou com determinado resultado. Se o seu sistema confia no que chega, acabou de ganhar uma porta.

Cada entrega chega com três cabeçalhos: X-Votari-Event com o nome do evento, X-Votari-Delivery com o identificador daquela entrega e X-Votari-Signature com a assinatura. A assinatura é o HMAC-SHA256 do corpo cru da requisição, calculado com o segredo que só você e o Votari conhecem, no formato sha256= seguido do hash.

A verificação do seu lado tem três regras que não são opcionais. Calcule o HMAC sobre o corpo cru, antes de qualquer conversão de JSON, porque reserializar muda bytes e invalida a assinatura. Compare as assinaturas com função de tempo constante, não com igualdade comum. E rejeite o que não casar, em silêncio, sem explicar ao remetente o que estava errado.

Guarde o X-Votari-Delivery. Ele é o que permite ao seu sistema reconhecer uma entrega repetida e não processar duas vezes o mesmo encerramento.

Reentrega: o que acontece quando o seu servidor cai

Integração que só funciona com tudo no ar não é integração. Quando a sua ponta não responde, o Votari tenta de novo numa escada que começa em um minuto e vai alargando: cinco minutos, trinta minutos, duas horas, seis horas e um dia. Depois disso ele desiste daquela entrega.

Duas consequências para o seu desenho. A primeira é que o seu endereço precisa ser idempotente, porque a mesma entrega pode chegar mais de uma vez quando a resposta se perde no caminho de volta. A segunda é que a escada compra tempo, não resolve manutenção longa: se a sua janela de indisponibilidade passa de um dia, puxe o estado pela API quando voltar, em vez de esperar o aviso que já expirou.

Responda rápido e processe depois. Receber, validar a assinatura, gravar numa fila sua e devolver sucesso leva milissegundos. Receber e tentar gerar relatório na mesma requisição transforma cada voto numa aposta contra o seu próprio tempo de resposta.

Por onde começar

• Uma votação de teste primeiro. Crie pela API, publique, vote você mesmo, encerre. Veja os quatro eventos chegarem antes de ligar nada em produção.
• Valide a assinatura desde a primeira linha de código. Deixar a verificação para depois é o atalho que fica permanente.
• Decida quem é a fonte da verdade da lista de aptos. Se é o seu sistema, considere também a validação do votante por API, que consulta a aptidão no momento do voto em vez de depender de uma lista exportada antes.
• Trate a chave de API como senha. Ela cria e encerra votação. Fora do código, fora do repositório, rotacionada quando alguém da equipe sai.

A assembleia que não precisa de digitação

O ganho da integração não é velocidade. É tirar o ponto em que uma pessoa cansada copia número de uma tela para outra, que é onde o erro entra e onde ele fica difícil de explicar depois. Veja o que o plano Pro inclui em preços, ou crie sua conta e monte uma votação de teste hoje, para a próxima assembleia de verdade já nascer conectada.