Compatibilidad con Segment | Convertmax Docs

Convertmax acepta payloads de eventos estilo Segment en la API de eventos (event.convertmax.io) y los normaliza al esquema de tracking de Convertmax antes de ingerirlos. Esto es independiente de la API Convertmax usada para datos de productos, contactos y pedidos de la plataforma.

Usa esta guía cuando ya envías llamadas track, identify, page, screen, group o batch de Segment y quieres que Convertmax reciba los mismos eventos con cambios mínimos.

Endpoints admitidos

Convertmax acepta JSON compatible con Segment en estos endpoints:

POST /v1/track/
POST /v1/identify/
POST /v1/page/
POST /v1/screen/
POST /v1/group/
POST /v1/batch/

POST /v1/track/ puede autodetectar un payload de Segment a partir del cuerpo de la solicitud. Las demás rutas fuerzan el tipo de evento de Segment esperado.

Autenticación

Usa las mismas opciones de autenticación que la API de eventos estándar:

Authorization: Bearer <api_key>
?key=<api_key>

Compatibilidad con RudderStack y PostHog

RudderStack: compatible de forma natural porque RudderStack sigue el diseño de la API de Segment.
PostHog: compatible como fuente de datos de eventos cuando PostHog envía payloads con formato Segment. Usa la compatibilidad con la API de Segment para ingerir eventos de PostHog en Convertmax.

Cómo mapea Convertmax los eventos de Segment

Convertmax transforma los payloads de Segment al formato interno de eventos usando estas reglas:

Tipo de Segment	`event_type` de Convertmax	Notas
`track`	mapeado desde `event`	Nombres comunes como `Purchase` se mapean a `convert`; los nombres desconocidos vuelven a `custom`
`identify`	`custom`	Los traits se conservan en `data.traits`
`page`	`page_view`	Los metadatos de página se conservan en `data`
`screen`	`page_view`	El nombre de pantalla se conserva en `data.screen_name`
`group`	`custom`	Los traits de grupo se conservan en `data.group_traits`
`batch`	por elemento de evento	Cada elemento se normaliza y se ingiere de forma independiente

Normalización de nombres de evento para `track`

Convertmax mapea nombres de eventos comunes de Segment así:

Purchase, Order Completed, y nombres estilo checkout se convierten en convert
Add To Cart y nombres estilo carrito se convierten en add_cart
los nombres estilo página se convierten en page_view
los nombres estilo clic se convierten en click
los nombres estilo búsqueda se convierten en search
todo lo demás se convierte en custom

Mapeo de visitante y sesión

Convertmax extrae valores de identidad del payload de Segment así:

visitor usa primero userId, luego anonymousId
session_id usa context.sessionId, context.session_id, o sessionId

Metadatos conservados en `data`

El evento normalizado de Convertmax conserva el contexto original de Segment en data, incluyendo:

source: "segment"
segment_type
message_id
timestamp, sent_at, y original_timestamp
event_name
user_id, anonymous_id, y group_id
properties, traits, o group_traits cuando están presentes
integrations
context
campos de página derivados como page, page_title, page_path, y page_referrer

Ejemplo de track

curl -X POST "https://event.convertmax.io/v1/track/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Purchase",
    "userId": "user_123",
    "anonymousId": "anon_123",
    "messageId": "msg_001",
    "context": {
      "sessionId": "sess_abc",
      "page": {
        "url": "https://example.com/checkout/success",
        "title": "Order complete"
      }
    },
    "properties": {
      "revenue": 100,
      "currency": "USD"
    }
  }'

Este payload se normaliza a un evento de Convertmax con:

event_type: "convert"
visitor: "user_123"
session_id: "sess_abc"
metadatos de Segment almacenados en data

Ejemplo de identify

curl -X POST "https://event.convertmax.io/v1/identify/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "traits": {
      "email": "buyer@example.com",
      "plan": "pro"
    }
  }'

Esto se ingiere como un evento custom de Convertmax con los traits originales conservados en data.traits.

Ejemplo de page

curl -X POST "https://event.convertmax.io/v1/page/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymousId": "anon_123",
    "name": "Pricing",
    "context": {
      "page": {
        "url": "https://example.com/pricing",
        "path": "/pricing",
        "title": "Pricing"
      }
    }
  }'

Esto se ingiere como un evento page_view de Convertmax.

Ejemplo de batch

curl -X POST "https://event.convertmax.io/v1/batch/?key=<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batch",
    "userId": "user_123",
    "context": {
      "sessionId": "sess_abc"
    },
    "batch": [
      {
        "type": "page",
        "name": "Home",
        "context": {
          "page": {
            "url": "https://example.com/"
          }
        }
      },
      {
        "type": "track",
        "event": "Add To Cart",
        "properties": {
          "product_id": "sku_001",
          "quantity": 1
        }
      }
    ]
  }'

Para las solicitudes por lotes, Convertmax aplica los valores de nivel superior userId, anonymousId, context, e integrations a cada elemento cuando esos campos faltan en el evento individual.

Referencia relacionada

API de eventos
Seguimiento de eventos
API Convertmax — API de plataforma independiente en api.convertmax.io