Status 

O suporte a chaves de idempotência é parcial atualmente. Mutações internas de nova tentativa selecionadas — por exemplo, os fluxos de nova tentativa de cobrança de pedido e de nova tentativa de cobrança de reembolso — já aceitam uma chave de idempotência e a utilizam para deduplicar as chamadas subsequentes ao processador de pagamento. Ainda não existe um argumento idempotencyKey padronizado em todas as mutações de criação voltadas ao cliente no Graph da Zonos; isso está no roteiro. Até que seja lançado, use os padrões abaixo para manter as mutações seguras para repetir.

Mutações seguras por padrão 

Algumas mutações são naturalmente idempotentes porque fazem upsert por um identificador estável fornecido por você. Ao chamá-las com a mesma entrada, o resultado é o mesmo — não há risco de criar duplicatas.

• Mutações que recebem um identificador único fornecido pelo comerciante (por exemplo, um externalId de pedido) retornarão o registro existente em uma chamada repetida, em vez de criar um novo.
• Operações somente leitura (queries) são sempre seguras para repetir.

Quando você conseguir anexar seu próprio identificador estável ao recurso que está criando, prefira esse caminho.

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 como no máximo uma vez do seu lado:

1. Persista a solicitação antes de enviá-la. Grave uma linha no seu próprio banco de dados (status pending) antes da chamada de rede.
2. Envie a mutação. Em caso de sucesso, registre o id do recurso retornado na sua linha pendente (status committed).
3. Em caso de erro de rede, não tente novamente às cegas. Consulte o Graph da Zonos para determinar se o recurso foi criado (por exemplo, listando recursos criados nos últimos minutos para sua conta, ou consultando um recurso relacionado que você possa correlacionar). Tente novamente somente se conseguir confirmar que o recurso não está presente.
4. Use uma restrição exclusiva no seu próprio banco de dados sobre a chave de negócio que representa a solicitação, para que uma nova tentativa duplicada vinda da sua própria aplicação não possa enviar o pedido duas vezes.

A entrega de webhooks é do tipo "pelo menos uma vez" 

Ao consumir os webhooks da Zonos, projete seus manipuladores para serem idempotentes — o mesmo evento pode ser entregue mais de uma vez. Deduplique pelo id do evento. Consulte Webhooks para o campo de id do evento.

Para onde a plataforma está caminhando 

A plataforma subjacente já executa fluxos de chaves de idempotência em produção para novas tentativas de cobrança: a chave delimita uma tentativa de repetição e evita chamadas duplicadas ao processador de pagamento. Estamos trabalhando para expor o mesmo padrão como um argumento opcional idempotencyKey nas mutações de criação voltadas ao cliente. Quando fornecido, o Graph retornará a resposta original para qualquer chamada subsequente com a mesma chave dentro de uma janela de retenção. Esta página será atualizada quando o recurso estiver disponível de forma geral.

Se chaves de idempotência padronizadas em mutações voltadas ao cliente estiverem bloqueando sua integração, entre em contato com o suporte.