Skip to Content
¡Rastrea tus conversiones de Telegram con Meta Ads — comienza en minutos!
Referencia de APIIdempotency

Idempotency

Every endpoint accepts an optional Idempotency-Key header. Use it to safely retry requests when your network or our backend has a hiccup.

How it works

  1. Your first request runs normally. We store the response body keyed on (apiKeyId, idempotencyKey).

  2. Any request with the same key within 24h returns the same response with a header:

    X-Idempotent-Replay: true

  3. Two days later the cached row is purged. Calling with the same key again will re-execute the request.

Guidelines

  • The key is string ≤ 128 characters.
  • Generate one per business action: order_<order_id>, signup_<user_id>_<timestamp>, etc.
  • Don’t reuse keys across different operations. Each key represents one logical “attempt”.
  • The Idempotency-Key is scoped per API key — two different keys may use the same string without conflict.

Example

Fire a Purchase event with retry safety:

curl -X POST https://adtarget.io/api/v1/events/conversion \
  -H "Authorization: Bearer atk_live_..." \
  -H "Idempotency-Key: order_98765" \
  -H "Content-Type: application/json" \
  -d '{ "telegramUserId": 1234567890, "channelId": "-1001234567890", "eventType": "Purchase", "value": 49.00, "currency": "USD" }'

If your network drops the response and you retry with the same Idempotency-Key, AdTarget returns the original conversionId without firing a second Meta event.

We don’t validate that the body matches the original request. If you reuse a key with a different body, you’ll get back the original response — not the new one. Always generate a fresh key for a different intent.

What gets cached

  • The full response body and HTTP status code.
  • The conversionId for forensic linking.

We do not cache anything about the request body itself. The key is the sole replay identifier.

Combined with Meta dedup

AdTarget has two layers of duplicate protection:

  1. Idempotency-Key replays the same API response for the same logical request within 24h.
  2. Conversion upsert logic reuses recent matching events for the same resolved site, Telegram user, channel, and event type. Pending/failed/skipped events are updated and retried; sent events are returned with deduplicated: true and are not sent again.

Meta CAPI also deduplicates within 48h based on event_id.

Deduplicación opcional de visitas para /track/init

POST /backend/track/init acepta un UUID opcional visitRequestId en el cuerpo JSON. Es el campo público recomendado; el nombre anterior gatewayRequestId sigue aceptándose como alias retrocompatible. Si se envían ambos campos, deben contener el mismo UUID; valores diferentes devuelven HTTP 400. Reutiliza el mismo UUID al reintentar una misma vista de página: AdTarget devuelve la misma visita y completa solo los datos de atribución que faltaban. Los valores existentes y el enrutamiento nunca se sobrescriben. Los reintentos deben conservar los mismos websiteId, tempId y sessionId; se rechaza cualquier cambio de identidad del navegador.

Sin visitRequestId, se conserva el comportamiento histórico: cada llamada crea una visita distinta, incluso en la misma sesión del navegador. Usa un UUID nuevo para cada vista de página real.

Reintentos direct-invite sin clave API

POST /backend/track/direct-invite usa visitRequestId (UUID) en el cuerpo, no la cabecera Idempotency-Key. El alias anterior gatewayRequestId sigue aceptándose. Reutiliza el mismo UUID para los reintentos de una redirección.

Las llamadas repetidas crean una visita, una entrada PageView y una invitación de Telegram. Solo completan campos ausentes sin sobrescribir valores existentes. websiteId, tempId y sessionId deben identificar la visita original. Usa un UUID nuevo para un clic nuevo.

Last updated on
EndpointsErrors & Rate Limits