Conceptos básicos

Idempotencia

Reintenta una solicitud que modifica datos sin ejecutarla dos veces. Envía una Idempotency-Key y Gemlead responde a la repetición con el primer resultado.

Envía una clave

Añade el encabezado Idempotency-Key a cualquier POST, PATCH, PUT o DELETE. Usa un valor único para la operación, de hasta 255 caracteres. Un UUID v4 es una buena opción.

Si la conexión se corta antes de recibir la respuesta, envía la misma solicitud con la misma clave. Gemlead hace el trabajo una sola vez y te devuelve su resultado, así un endpoint de webhook nunca se crea dos veces.

Las claves se guardan 24 horas. Las solicitudes GET nunca modifican datos y no necesitan clave.

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4f5e-3b0a-4f7e-9d2c-6a8b1e2d4c7f" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot"]
  }'

Cómo responde Gemlead

Solicitud	Respuesta
Misma clave, mismo método, ruta y cuerpo, en menos de 24 horas	La primera respuesta otra vez, con el mismo estado y cuerpo, y el encabezado `Idempotent-Replayed: true`.
Misma clave, con otro método, ruta o cuerpo	409 `idempotency_error` con el código `idempotency_key_reused`.
Misma clave mientras la primera solicitud sigue en curso	409 con el código `idempotency_key_in_use`. Vuelve a intentarlo un segundo después.
Una clave de más de 255 caracteres	400 con el código `idempotency_key_invalid`.

Cuándo reintentar

Ante un error de red o un timeout, reintenta con la misma clave.
Ante un 500, reintenta con la misma clave tras una breve espera.
Ante un 400, 401, 403 o 404, corrige la solicitud y envíala con una clave nueva.