Depois de criar uma cobrança ou de receber um pedido, o sistema precisa acompanhar as mudanças da operação. O sistema pode perguntar ao fornecedor de tempos em tempos ou receber um aviso quando houver novidade, e cada forma falha em pontos diferentes.
Polling, o sistema pergunta
No polling, a aplicação consulta o fornecedor em intervalos regulares, como na consulta da situação de uma cobrança pendente ou na busca de pedidos novos. O contrato define a operação de consulta, os filtros e a forma de indicar a posição do último evento lido.
O intervalo entre as consultas define o atraso máximo esperado. Com uma consulta a cada cinco minutos, uma mudança pode levar até cinco minutos para ser percebida, sem que exista falha. A autenticação, os filtros, a paginação, a posição do último evento e o processamento local também interferem no resultado. Uma consulta bem-sucedida não prova que todos os eventos foram lidos e aplicados.
Webhook, o fornecedor avisa
No webhook, o fornecedor faz uma chamada HTTP para um endereço configurado pelo cliente quando um evento acontece, como a aprovação de uma cobrança. O endereço precisa estar acessível pela Internet, e o receptor valida a origem e o conteúdo, em geral por uma assinatura prevista no contrato.
A repetição dos avisos, a ordem de entrega e o prazo para responder variam por fornecedor. O receptor trata as duplicatas, quando elas são possíveis, e a resposta ao aviso não confirma que o pedido já foi atualizado no banco.
O computador da loja
O caixa 01 e o servidor da loja não costumam ficar acessíveis a partir da Internet, e por isso o polling, que usa só conexões de saída, aparece com frequência nos programas de loja. Essa preferência não é uma exigência de todo programa instalado em uma estação.
Um serviço na Internet também pode receber o webhook e repassar os dados à loja por outra interface, e a solução pode usar um servidor publicado ou um canal persistente. A arquitetura de cada integração define onde o aviso é recebido e como ele chega ao sistema da loja.
Receber, guardar e aplicar o aviso
Alguns contratos assinam os bytes originais do corpo do aviso. A interpretação do JSON e a reformatação do texto antes da verificação mudam esses bytes e fazem uma assinatura válida parecer inválida. Uma assinatura válida confirma a integridade e a origem, mas não impede, sozinha, a repetição de um aviso antigo, e por isso o identificador e a validade do evento também são conferidos.
A resposta HTTP do receptor ao aviso precisa ter um significado conhecido. Quando o receptor confirma o recebimento antes de guardar o evento e cai em seguida, o fornecedor considera a entrega concluída, e o trabalho local se perde. Algumas soluções guardam o evento ou o colocam em uma fila antes de responder e processam depois, e a etapa que a resposta confirma varia em cada instalação.
O horário não define a ordem dos eventos, porque os avisos podem se repetir ou chegar fora de ordem. O identificador do evento, o identificador do recurso e o tipo da alteração, junto com a versão ou a situação atual, evitam que um aviso antigo substitua um estado mais recente.
No polling, a posição recebida e a posição aplicada são diferentes. Quando um lote é aplicado só em parte, o avanço para o lote seguinte perde dados, e a repetição do lote inteiro sem proteção duplica os efeitos.
No suporte
No polling, convém conferir as consultas, o intervalo e o último evento tratado. No webhook, convém conferir o envio no fornecedor, a chegada ao receptor, a validação e o processamento local, sempre com o mesmo identificador para acompanhar a sequência.
Para guardar
- No polling, o sistema pergunta, e, no webhook, o fornecedor avisa.
- O intervalo do polling define o atraso máximo esperado.
- O webhook exige um endereço acessível, e por isso o polling é comum nos programas de loja.
- A resposta ao aviso não confirma a atualização do pedido.
- A posição recebida e a posição aplicada são acompanhadas separadamente.
Por que o polling é comum em um caixa sem endereço público?
Porque o caixa consulta o fornecedor com conexões de saída, sem precisar ficar acessível pela Internet. É uma vantagem dessa solução, e não uma exigência de todo programa instalado em uma estação.
O fornecedor registra o webhook como entregue, mas o pedido não aparece na loja. O que conferir?
O receptor correto do aviso, a validação, a resposta e a aplicação local dos dados. A palavra entregue descreve uma etapa segundo o fornecedor, e não necessariamente a atualização final do pedido.