Documentación · Referencia de la API

/v1/conversions

Un solo endpoint cubre todos los tipos de conversión. Autenticado con Bearer usando la site key de tu workspace. Idempotente en (workspace_id, external_id).

Autenticación

Todas las solicitudes llevan un token Bearer en el encabezado Authorization. El token es la site key de tu workspace, con el prefijo dcs_sk_. La encuentras en Configuración → Claves de API.

Authorization: Bearer dcs_sk_live_…

Las site keys tienen alcance de workspace. Rótalas desde la misma página de configuración; las claves antiguas dejan de autenticar en un plazo de 60 segundos.

Endpoint

POST https://api.decisa.ai/v1/conversions
Content-Type: application/json
Authorization: Bearer dcs_sk_live_…

Cuerpo de la solicitud

{
  "type": "signup",
  "external_id": "user-1234",
  "visitor_id": "v_abc123...",
  "customer_email": "[email protected]",
  "value_cents": 0,
  "currency": "USD",
  "occurred_at": "2026-05-25T18:14:22Z",
  "metadata": {
    "plan": "pro",
    "trial": false
  }
}

Campo	Tipo	Descripción
type	string · obligatorio	Uno de: signup, trial_start, subscription_start, sale, lead, app_install, custom.
external_id	string · obligatorio	Tu ID único para el registro. Se usa para la deduplicación.
visitor_id	string · recomendado	Valor de la cookie propia dcs_vid. Sin esto, la conversión no puede unirse a un clic.
customer_email	string · opcional	Se le aplica hash SHA256 antes de almacenarlo. Se usa para el pushback de CAPI.
value_cents	integer · opcional	Ingresos en unidades menores. Obligatorio para los tipos que generan ingresos.
currency	string · opcional	ISO 4217. Por defecto, la moneda del workspace.
occurred_at	ISO 8601 · opcional	Se usa la marca de tiempo del servidor si se omite.
metadata	object · opcional	Formato libre. No se usa para la atribución; se muestra en los paneles.

Respuesta exitosa (201)

{
  "data": {
    "id": "conv_01HZX...",
    "type": "signup",
    "external_id": "user-1234",
    "attributed": true,
    "attribution_model": "last-click",
    "attribution_model_version": "1.0.0",
    "matched_click_id": "clk_01HZX...",
    "matched_campaign_id": null,
    "occurred_at": "2026-05-25T18:14:22Z"
  },
  "meta": null,
  "error": null
}

attributed: false significa que aceptamos la conversión pero no encontramos un clic que calificara. La fila sigue siendo consultable en el panel bajo Sin atribuir.

Códigos de error

Campo	Tipo	Descripción
401	unauthorized	Site key ausente o inválida.
403	workspace_disabled	El workspace está pausado por facturación o cumplimiento.
422	invalid_payload	Falló la validación del esquema. Consulta `error.fields` para más detalles.
429	rate_limited	Se excedió la tasa de ingesta del workspace. Reintenta con backoff.
500	server_error	Transitorio. Es seguro reintentar: el endpoint es idempotente.

Idempotencia y reintentos

El endpoint es idempotente en (workspace_id, external_id). Reenviar el mismo payload devuelve la fila de conversión original con HTTP 200 (no 201). Úsalo sin restricciones: los reintentos de webhooks de Stripe, Shopify y Kiwify nunca crean duplicados.

Límites de tasa

Plan gratuito: 60 solicitudes / minuto. Planes de pago: 600 / minuto. Las ráfagas de hasta 2× la tasa sostenida se absorben sin generar 429. Hay límites más altos disponibles bajo solicitud.