Como usar chaves de idempotência da API Zendesk para evitar tickets duplicados

Falhas de rede acontecem. Sua solicitação de API atinge o tempo limite, então seu cliente a repete. Sem as devidas proteções, essa repetição cria um segundo ticket, um terceiro ticket e, de repente, seu cliente tem três solicitações de suporte idênticas no sistema. As chaves de idempotência resolvem esse problema, garantindo que solicitações repetidas com a mesma chave produzam o mesmo resultado, sem criar duplicados.

Se você estiver criando integrações com a API Zendesk, entender as chaves de idempotência não é opcional. É essencial para sistemas prontos para produção que lidam com dados reais de clientes.

O que são chaves de idempotência e por que elas são importantes?

Uma chave de idempotência é um identificador exclusivo que os clientes incluem com as solicitações de API. Quando seu servidor recebe uma solicitação, ele verifica se já viu essa chave antes. Se a chave for nova, a solicitação é processada normalmente e o resultado é armazenado. Se a chave existir, o resultado armazenado é retornado sem reexecutar a operação.

O conceito vem da matemática, onde uma operação idempotente produz o mesmo resultado, seja executada uma ou várias vezes. Em termos de API, postar um ticket com a mesma chave de idempotência cinco vezes deve criar exatamente um ticket e retornar a mesma resposta a cada vez.

Veja por que isso é importante para o Zendesk especificamente. A criação de tickets é uma operação de gravação com efeitos colaterais. Cada ticket aciona notificações, regras de roteamento e, potencialmente, temporizadores de SLA. Criar tickets duplicados não apenas sobrecarrega seu sistema. Ele desperdiça o tempo do agente, confunde os clientes que recebem vários reconhecimentos e distorce suas métricas.

Cenários do mundo real onde a idempotência salva você:

• Webhooks de pagamento Seu processador de pagamento envia um webhook para criar um ticket para transações com falha. O webhook tenta novamente no tempo limite. Sem idempotência, cada repetição cria um novo ticket.
• Importações em lote Você está migrando tickets de um sistema antigo. O script de importação atinge um erro de rede e é reiniciado. Sem idempotência, você obtém registros duplicados.
• Aplicativos móveis Um usuário toca em enviar duas vezes devido ao atraso. Sem idempotência, eles criam dois tickets.

Construir uma lógica de repetição confiável manualmente é complexo. Você precisa rastrear quais solicitações foram bem-sucedidas, lidar com falhas parciais e reconciliar o estado em sistemas distribuídos. As chaves de idempotência transferem essa complexidade para a camada da API, onde ela pertence.

Se você deseja automatizar a criação de tickets sem lidar com esses casos extremos, nosso Agente de IA gerencia a idempotência automaticamente como parte de sua integração com o Zendesk.

Como funciona a implementação da chave de idempotência do Zendesk

O Zendesk implementa a idempotência por meio de um cabeçalho HTTP simples. Para usá-lo, inclua um cabeçalho Idempotency-Key com um valor exclusivo em sua solicitação:

Idempotency-Key: {chave_única}

O valor pode ser qualquer string de até 255 caracteres. O Zendesk recomenda o uso de UUIDs ou outros identificadores de alta entropia.

Quando você faz uma solicitação com uma chave de idempotência, a resposta do Zendesk inclui um cabeçalho x-idempotency-lookup:

• x-idempotency-lookup: miss Esta é a primeira vez que esta chave é vista. A solicitação é processada normalmente.
• x-idempotency-lookup: hit Esta chave foi usada antes. O Zendesk retorna a resposta armazenada em cache da solicitação original.

Aqui está a parte crítica. O Zendesk armazena chaves de idempotência por 2 horas. Após essa janela, uma solicitação com a mesma chave será tratada como nova. Isso significa que sua lógica de repetição precisa levar em consideração a janela de expiração. Se você estiver repetindo uma solicitação de ontem, criará um duplicado.

O Zendesk também valida se as solicitações com a mesma chave de idempotência têm parâmetros idênticos. Se você enviar a mesma chave com um assunto ou descrição diferente, receberá um erro 400:

{
  "error": "IdempotentRequestError",
  "description": "Os parâmetros da solicitação não correspondem à chave de idempotência fornecida"
}

Isso evita o uso indevido acidental de chaves em diferentes operações. Também significa que você precisa gerar uma nova chave para cada operação distinta, não reutilizar chaves em diferentes tickets.

Limitação importante: a chave de idempotência não é armazenada como parte do ticket. Quando você recuperar um ticket posteriormente, não verá qual chave foi usada para criá-lo. Se você precisar rastrear essa correlação, armazene-a em seu próprio sistema.

Nem todos os endpoints da API Zendesk suportam idempotência. O principal caso de uso é a criação de tickets (POST /api/v2/tickets.json). Consulte a documentação oficial para o endpoint específico que você está usando.

Implementando chaves de idempotência em seu código

Vamos percorrer uma implementação prática. Usaremos Python com a biblioteca requests, mas o padrão se aplica a qualquer idioma.

Passo 1: Gere chaves de idempotência exclusivas

Gere sua chave de idempotência antes de fazer a primeira solicitação, não durante as repetições. A chave deve ser exclusiva por operação lógica.

import uuid

idempotency_key = str(uuid.uuid4())

request_context = {
    'idempotency_key': idempotency_key,
    'payload': ticket_data,
    'attempt': 0
}

Use UUIDv4 ou outra string aleatória com pelo menos 128 bits de entropia. Evite padrões previsíveis, como carimbos de data/hora, IDs sequenciais ou hashes apenas do payload. Estes podem colidir ou ser adivinhados.

Passo 2: Adicione o cabeçalho às suas solicitações de API

Inclua a chave de idempotência nos cabeçalhos de sua solicitação, juntamente com sua autenticação.

Exemplo em Python:

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
api_token = os.getenv('ZENDESK_API_TOKEN')

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
auth = (f'{email}/token', api_token)

headers = {
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotency_key
}

data = {
    'ticket': {
        'subject': 'Notificação de falha de pagamento',
        'comment': {'body': 'Método de pagamento do cliente recusado'},
        'requester': {'email': 'customer@example.com'}
    }
}

response = requests.post(url, json=data, auth=auth, headers=headers)

Exemplo em cURL:

curl https://yourcompany.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "Ticket de teste", "comment": {"body": "Este é um teste"}}}' \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -u your@email.com/token:your_api_token \
  -X POST

Exemplo em JavaScript/Node.js:

const response = await fetch('https://company.zendesk.com/api/v2/tickets.json', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic ' + Buffer.from(`${email}/token:${token}`).toString('base64'),
        'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify(ticketData)
});

Passo 3: Lide com respostas e repetições

Sua lógica de repetição deve verificar o status da resposta e os cabeçalhos para determinar se deve repetir.

import time

def create_ticket_with_retry(ticket_data, max_retries=3):
    idempotency_key = str(uuid.uuid4())

    for attempt in range(max_retries + 1):
        headers = {
            'Content-Type': 'application/json',
            'Idempotency-Key': idempotency_key
        }

        response = requests.post(
            url,
            json=ticket_data,
            auth=auth,
            headers=headers
        )

        # Verifique se esta foi uma resposta armazenada em cache
        lookup_status = response.headers.get('x-idempotency-lookup')
        if lookup_status == 'hit':
            print(f"A solicitação foi armazenada em cache (tentativa {attempt + 1})")

        # Caso de sucesso
        if response.status_code == 201:
            return response.json()

        # Incompatibilidade de idempotência - não tente novamente, isso é um erro de lógica
        if response.status_code == 400 and 'IdempotentRequestError' in response.text:
            raise ValueError(f"Incompatibilidade de chave de idempotência: {response.json()['description']}")

        # Taxa limitada - espere e tente novamente
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        # Erros do servidor - tente novamente com backoff exponencial
        if response.status_code in [500, 502, 503, 504]:
            if attempt < max_retries:
                backoff = (2 ** attempt) + (hash(idempotency_key) % 1000 / 1000)
                time.sleep(backoff)
                continue

        # Erros do cliente (4xx) - não tente novamente
        response.raise_for_status()

    raise Exception("Número máximo de tentativas excedido")

Pontos-chave para sua lógica de repetição:

• Reutilize a mesma chave de idempotência em todas as repetições da mesma operação lógica
• Não tente novamente em erros 400 com IdempotentRequestError isso indica um bug de lógica em seu código
• Respeite os limites de taxa (429) usando o cabeçalho Retry-After
• Use backoff exponencial para erros de servidor para evitar sobrecarregar a API

Para mais detalhes sobre a estrutura da API de tickets do Zendesk, consulte nosso guia sobre como criar tickets do Zendesk usando a API.

Melhores práticas para implementações de produção

Depois de ter o básico funcionando, considere estas práticas prontas para produção.

Estratégias de armazenamento de chaves. Para sistemas de alto volume, você pode querer rastrear as chaves de idempotência em seu próprio banco de dados ou cache. Isso permite que você:

• Detecte se uma chave está prestes a expirar (janela de 2 horas do Zendesk)
• Audite quais operações foram bem-sucedidas ou falharam
• Implemente lógica de desduplicação personalizada além do Zendesk

Redis é uma escolha popular para isso. Defina um TTL ligeiramente menor que a janela de 2 horas do Zendesk para evitar casos extremos:

import redis

redis_client = redis.Redis(host='localhost', port=6379)

redis_client.setex(f"zendesk:idempotency:{key}", 5400, response_data)

Lide com solicitações simultâneas. Se duas solicitações com a mesma chave de idempotência chegarem simultaneamente, o Zendesk processará uma e retornará o resultado armazenado em cache para a outra. No entanto, seu cliente pode ver condições de corrida. Implemente a desduplicação de solicitações em sua camada de aplicativo se isso for uma preocupação.

Impressão digital da solicitação. Para detectar bugs onde você acidentalmente reutiliza uma chave com parâmetros diferentes, faça o hash do payload da solicitação e armazene-o com a chave de idempotência. Antes de enviar, verifique se o hash corresponde:

import hashlib
import json

def get_request_fingerprint(payload):
    return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()

fingerprint = get_request_fingerprint(ticket_data)
store_key_with_fingerprint(idempotency_key, fingerprint)

if get_fingerprint_for_key(idempotency_key) != fingerprint:
    raise ValueError("Payload alterado para chave de idempotência existente")

Registro e monitoramento. Rastreie o uso da chave de idempotência em seus logs:

• Registre a chave e o status x-idempotency-lookup para cada solicitação
• Alerte sobre altas taxas de respostas hit (pode indicar repetições excessivas)
• Monitore IdempotentRequestError (indica bugs)

Testando sua implementação. Escreva testes que verifiquem sua lógica de idempotência:

def test_duplicate_request_returns_same_ticket():
    key = str(uuid.uuid4())

    # Primeira solicitação
    response1 = create_ticket(ticket_data, idempotency_key=key)
    ticket_id = response1['ticket']['id']

    # Segunda solicitação com a mesma chave
    response2 = create_ticket(ticket_data, idempotency_key=key)

    assert response2['ticket']['id'] == ticket_id
    assert response2.headers['x-idempotency-lookup'] == 'hit'

Erros comuns e como evitá-los

Mesmo desenvolvedores experientes cometem esses erros ao implementar a idempotência.

Usando padrões de chave previsíveis. Carimbos de data/hora, IDs sequenciais ou hashes simples do payload podem colidir ou ser adivinhados. Sempre use valores criptograficamente aleatórios como UUIDv4.

Gerando novas chaves na repetição. O objetivo principal é usar a mesma chave para repetições. Se você gerar um novo UUID em cada tentativa, criará duplicados em vez de evitá-los.

Ignorando a expiração de 2 horas. Se sua lógica de repetição durar mais de 2 horas (talvez devido a interrupções prolongadas), sua chave de idempotência não funcionará mais. Para processos de longa duração, implemente sua própria camada de desduplicação.

Não lidando com erros de incompatibilidade de parâmetros. Quando você recebe um IdempotentRequestError, geralmente é um bug em seu código. Você está reutilizando uma chave com dados diferentes. Registre-os agressivamente e corrija a causa raiz.

Armazenando em cache respostas de erro incorretamente. Algumas implementações armazenam em cache todas as respostas, incluindo erros 5xx. Isso significa que um erro de servidor transitório fica "preso" e todas as repetições retornam o mesmo erro. Armazene em cache apenas respostas bem-sucedidas (códigos de status 2xx).

Condições de corrida em ambientes simultâneos. Sem o bloqueio adequado, duas threads podem verificar a existência de uma chave, ambas ver que ela está faltando e ambas enviar solicitações. Use operações atômicas ou bloqueios distribuídos se estiver processando altos volumes.

Automatizando a criação de tickets sem a complexidade

Construir e manter integrações de API leva tempo. Você precisa lidar com autenticação, lógica de repetição de erros, limitação de taxa, idempotência e manutenção contínua à medida que as APIs mudam.

Se seu objetivo é automatizar a criação de tickets em vez de construir uma integração personalizada, considere se você realmente precisa escrever código. Ferramentas como eesel AI podem lidar com a criação de tickets e respostas sem nenhum trabalho de desenvolvimento.

Aqui está a diferença. Com a abordagem da API, você está escrevendo scripts para criar tickets que os humanos responderão. Com um agente de IA, você está treinando um sistema para entender seus negócios e lidar com todo o ciclo de vida do ticket, desde a criação até a resolução. Você o conecta à sua conta Zendesk e ele aprende com seus tickets anteriores, artigos da central de ajuda e macros.

O modelo de lançamento progressivo significa que você começa com a IA redigindo respostas para revisão e, em seguida, expande para automação total à medida que ela se prova. Para equipes que buscam reduzir o volume de tickets em vez de apenas automatizar a criação, isso geralmente oferece resultados mais rápidos do que o desenvolvimento de API personalizado.

Nosso AI Copilot também pode ajudar, redigindo respostas que seus agentes revisam antes de enviar, oferecendo assistência de IA sem a complexidade de construir uma lógica de repetição idempotente você mesmo.