Atualmente, o suporte a chaves de idempotência é parcial. Algumas mutações internas de nova tentativa — por exemplo, os fluxos de nova tentativa de faturação de encomendas e de faturação de reembolsos — já aceitam uma chave de idempotência e utilizam-na para eliminar chamadas duplicadas ao processador de pagamentos a jusante. Ainda não existe um argumento idempotencyKey padronizado em todas as mutações de criação disponibilizadas aos clientes no Zonos Graph; essa funcionalidade está prevista no roteiro. Até ser lançada, utilize os padrões abaixo para garantir que as mutações podem ser repetidas em segurança.
Algumas mutações são naturalmente idempotentes, porque fazem upsert através de um identificador estável fornecido por si. Quando as invoca com os mesmos dados de entrada, o resultado é o mesmo — não existe risco de criar duplicados.
As mutações que recebem um identificador único fornecido pelo comerciante (por exemplo, o externalId de uma encomenda) devolvem o registo existente numa chamada repetida, em vez de criarem um novo.
As operações só de leitura (queries) podem ser sempre repetidas em segurança.
Sempre que possa associar o seu próprio identificador estável ao recurso que está a criar, opte por essa abordagem.
Para mutações que criam recursos sem uma chave fornecida pelo comerciante, trate-as, do seu lado, como no máximo uma vez (at-most-once):
Guarde o pedido antes de o enviar. Escreva uma linha na sua própria base de dados (estado pending) antes da chamada de rede.
Envie a mutação. Em caso de sucesso, registe o id do recurso devolvido na sua linha pendente (estado committed).
Em caso de erro de rede, não repita às cegas. Consulte o Zonos Graph para determinar se o recurso foi criado (por exemplo, listando os recursos criados nos últimos minutos para a sua conta, ou consultando um recurso relacionado que consiga correlacionar). Repita apenas se conseguir confirmar que o recurso não existe.
Utilize uma restrição de unicidade na sua própria base de dados sobre a chave de negócio que representa o pedido, para que uma nova tentativa duplicada da sua própria aplicação não possa submeter o pedido duas vezes.
Ao consumir webhooks da Zonos, conceba os seus handlers para serem idempotentes — o mesmo evento pode ser entregue mais do que uma vez. Elimine duplicados através do id do evento. Consulte Webhooks para saber qual é o campo do id do evento.
A plataforma subjacente já executa fluxos com chaves de idempotência em produção para novas tentativas de faturação: a chave delimita cada tentativa e evita chamadas duplicadas ao processador de pagamentos. Estamos a trabalhar para disponibilizar o mesmo padrão como um argumento opcional idempotencyKey nas mutações de criação disponibilizadas aos clientes. Quando for fornecido, o Graph devolverá a resposta original a qualquer chamada subsequente com a mesma chave, dentro de um período de retenção. Esta página será atualizada quando a funcionalidade estiver disponível para todos.
Se a falta de chaves de idempotência padronizadas nas mutações disponibilizadas aos clientes estiver a bloquear a sua integração, contacte o suporte.
Idempotência
Estado
Atualmente, o suporte a chaves de idempotência é parcial. Algumas mutações internas de nova tentativa — por exemplo, os fluxos de nova tentativa de faturação de encomendas e de faturação de reembolsos — já aceitam uma chave de idempotência e utilizam-na para eliminar chamadas duplicadas ao processador de pagamentos a jusante. Ainda não existe um argumento
idempotencyKeypadronizado em todas as mutações de criação disponibilizadas aos clientes no Zonos Graph; essa funcionalidade está prevista no roteiro. Até ser lançada, utilize os padrões abaixo para garantir que as mutações podem ser repetidas em segurança.Mutações seguras por predefinição
Algumas mutações são naturalmente idempotentes, porque fazem upsert através de um identificador estável fornecido por si. Quando as invoca com os mesmos dados de entrada, o resultado é o mesmo — não existe risco de criar duplicados.
externalIdde uma encomenda) devolvem o registo existente numa chamada repetida, em vez de criarem um novo.Sempre que possa associar o seu próprio identificador estável ao recurso que está a criar, opte por essa abordagem.
Padrões para mutações que não são naturalmente idempotentes
Para mutações que criam recursos sem uma chave fornecida pelo comerciante, trate-as, do seu lado, como no máximo uma vez (at-most-once):
pending) antes da chamada de rede.committed).A entrega de webhooks é do tipo «pelo menos uma vez»
Ao consumir webhooks da Zonos, conceba os seus handlers para serem idempotentes — o mesmo evento pode ser entregue mais do que uma vez. Elimine duplicados através do id do evento. Consulte Webhooks para saber qual é o campo do id do evento.
O rumo da plataforma
A plataforma subjacente já executa fluxos com chaves de idempotência em produção para novas tentativas de faturação: a chave delimita cada tentativa e evita chamadas duplicadas ao processador de pagamentos. Estamos a trabalhar para disponibilizar o mesmo padrão como um argumento opcional
idempotencyKeynas mutações de criação disponibilizadas aos clientes. Quando for fornecido, o Graph devolverá a resposta original a qualquer chamada subsequente com a mesma chave, dentro de um período de retenção. Esta página será atualizada quando a funcionalidade estiver disponível para todos.Se a falta de chaves de idempotência padronizadas nas mutações disponibilizadas aos clientes estiver a bloquear a sua integração, contacte o suporte.
Esta página foi útil?