API de conversión

La API de conversión le permite reportar conversiones no-Stripe a Selgeo — registros, envíos de formularios, pruebas gratuitas, actualizaciones o cualquier evento personalizado. Lo llama desde su servidor después de que ocurra una conversión, y Selgeo la atribuye al socio referente basándose en un click_id o un promo_code.

Versión de API: v1

Punto de conexión: POST /api/v1/conversions

Autenticación

Authorization: Bearer sk_test_YOUR_KEY

Nunca exponga claves secretas en el código frontend

Las claves secretas (sk_*) solo deben usarse en código del lado del servidor.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
click_id	string (UUID)	Condicional	El ID de clic del snippet de seguimiento. Requerido si no se proporciona promo_code.
promo_code	string	Condicional	Un código promocional para la atribución. Requerido si no se proporciona click_id.
external_transaction_id	string	Sí	Su identificador único para esta conversión. Usado para deduplicación. Máx. 255 caracteres.
event_type	string	Sí	El tipo de evento de conversión (p. ej., signup, purchase, upgrade). Máx. 100 caracteres.
amount_cents	integer	No	El valor de la conversión en centavos. Predeterminado: 0.
currency	string	Condicional	Código de moneda ISO 4217 de 3 letras. Requerido cuando amount_cents > 0.
occurred_at	string (ISO 8601)	No	Cuándo ocurrió la conversión. Predeterminado a la hora actual.
prospect_email	string (email)	No	El email del usuario que realiza la conversión. Usado para detección de fraude de auto-referido.
metadata	object	No	Pares clave-valor arbitrarios. Máx. 4 KB.

Ejemplo de solicitud

curl -X POST https://api.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

Respuesta

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "conversion_api",
  "event_type": "signup",
  "external_transaction_id": "signup_12345",
  "amount_cents": 0,
  "currency": null,
  "occurred_at": "2026-04-02T10:30:00.000Z",
  "is_test": true,
  "attributed": true,
  "attribution": {
    "attribution_event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "attribution_source": "link",
    "participant_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "explanation": "Attributed to partner via tracking link click"
  },
  "created_at": "2026-04-02T10:30:01.000Z"
}

Prioridad de atribución

Cuando se proporcionan tanto click_id como promo_code, el código promocional tiene prioridad.

Códigos de estado HTTP

Estado	Significado
201	Conversión creada correctamente
400	Error de validación
401	Clave API inválida o faltante
409	external_transaction_id duplicado
422	Sin señal de atribución o incompatibilidad de modo
429	Límite de tasa superado

Próximos pasos

• Webhooks — recibir notificaciones cuando se atribuyen conversiones
• Modo de prueba — guía detallada para probar su integración
• Solución de problemas — problemas comunes y soluciones