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 no personales para su propio uso. No incluya datos personales ni datos de categorías especiales. Máx. 4 KB.

Mantenga los datos personales fuera de metadata

No envíe datos personales innecesarios y nunca envíe datos de categorías especiales (artículo 9 del RGPD — por ejemplo, datos sobre salud, origen étnico, religión u opiniones políticas) en el campo metadata. Selgeo no trata intencionadamente datos de categorías especiales y no puede detectarlos de forma fiable en campos de texto libre, por lo que mantenerlos fuera es su responsabilidad como responsable del tratamiento. Tenga en cuenta que prospect_email es un dato personal: usted lo proporciona únicamente para la detección de fraude por autorreferencia, y se trata bajo su responsabilidad como responsable del tratamiento.

Ejemplo de solicitud

curl -X POST https://app.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

Pruebas

1. Configure un programa de prueba y un socio. Cree el programa en el panel del comerciante e invite a un socio de prueba, luego inicie sesión en el portal de socios como ese socio y cree un enlace de referido (en Enlaces).
2. Visite su sitio a través del enlace de seguimiento para registrar un clic.
3. Lea el click_id desde la consola del navegador:

   __selgeo.getClickId()

4. Envíe una conversión de prueba desde su terminal:

   curl -X POST https://app.selgeo.com/api/v1/conversions \
     -H "Authorization: Bearer sk_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "click_id": "PEGUE_AQUI_EL_CLICK_ID",
       "external_transaction_id": "test_001",
       "event_type": "signup",
       "amount_cents": 0
     }'

5. Compruebe la respuesta — attributed debería ser true y attribution_source debería ser "link".
6. Verifique en el panel de control — la conversión debería aparecer en Analytics, atribuida al socio de prueba.

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