Direct API Integration Integracion Directa por API

Send events directly via REST API for maximum control. Best for server-side tracking, custom integrations, and webhook receivers. Envia eventos directamente por API REST para maximo control. Ideal para tracking server-side, integraciones custom, y receptores de webhooks.

Authentication Autenticacion

All API requests require a Bearer token in the Authorization header. Contact your RELO account manager to receive your token and client_id. Todas las requests de API requieren un Bearer token en el header Authorization. Contacta a tu account manager de RELO para recibir tu token y client_id.

CopyAuthorization: Bearer YOUR_API_TOKEN

Health Check Health Check

Verify the service is running before sending events: Verifica que el servicio esta corriendo antes de enviar eventos:

CopyGET https://ingest.relo.mx/health

// Response 200:
{
  "status": "ok",
  "version": "7.1.0",
  "uptime_sec": 864000,
  "clickhouse": "ok",
  "dragonfly": "ok",
  "supabase": "ok"
}

Batch Event Ingest Ingestion de Eventos en Batch

Send up to 10,000 events per request to the batch endpoint. Events are validated, enriched (GeoIP, identity resolution, fraud scoring), and written to ClickHouse. Envia hasta 10,000 eventos por request al endpoint de batch. Los eventos se validan, enriquecen (GeoIP, resolucion de identidad, scoring de fraude), y se escriben en ClickHouse.

CopyPOST https://ingest.relo.mx/ingest/batch
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "events": [
    {
      "t": "purchase",
      "ts": 1710244800000,
      "cid": 3,
      "did": "device-abc-123",
      "props": {
        "order_id": "ORD-001",
        "revenue": 24999.00,
        "currency": "MXN",
        "product_id": "SM-S921BZKDMXO",
        "product_name": "Galaxy S24 Ultra 256GB",
        "product_line": "MX",
        "quantity": 1
      }
    },
    {
      "t": "page_view",
      "ts": 1710244750000,
      "cid": 3,
      "did": "device-abc-123",
      "url": "https://samsung.com.mx/smartphones/galaxy-s24/",
      "ref": "https://google.com/search?q=galaxy+s24"
    }
  ]
}

// Response 200:
{
  "accepted": 2,
  "rejected": 0,
  "errors": []
}

Event Types Tipos de Eventos

TypeTipo	DescriptionDescripcion	Required PropsProps Requeridos
page_view	Page load / screen viewCarga de pagina / vista de pantalla	url
view_product	Product detail pagePagina de detalle de producto	product_id, price
add_to_cart	Added item to cartAgrego item al carrito	product_id, price, quantity
begin_checkout	Started checkoutInicio checkout	cart_value
purchase	Completed purchaseCompra completada	order_id, revenue, product_id, quantity
install	App installInstalacion de app	(none)(ninguno)
custom	Any custom eventCualquier evento custom	Any key-value pairs in propsCualquier par clave-valor en props

Event Schema Schema de Eventos

FieldCampo	TypeTipo	RequiredRequerido	DescriptionDescripcion
t	string	Yes	Event type (see table above)Tipo de evento (ver tabla arriba)
ts	integer	Yes	Client timestamp (Unix ms)Timestamp del cliente (Unix ms)
cid	integer	Yes	RELO client IDID de cliente RELO
did	string	Yes	Device identifier (GAID, IDFA, fingerprint, or your own ID)Identificador de dispositivo (GAID, IDFA, fingerprint, o tu propio ID)
url	string	No	Page URL (for web events)URL de la pagina (para eventos web)
ref	string	No	Referrer URLURL de referencia
ip	string	No	Client IP (auto-detected if omitted)IP del cliente (auto-detectado si se omite)
ua	string	No	User-Agent (auto-detected if omitted)User-Agent (auto-detectado si se omite)
consent	integer	No	Consent bitmask (default 0xFF = all)Bitmask de consentimiento (default 0xFF = todos)
props	object	No	Event-specific propertiesPropiedades especificas del evento

Purchase Props (inside props) Props de Compra (dentro de props)

FieldCampo	TypeTipo	DescriptionDescripcion
order_id	string	Unique order identifierIdentificador unico de la orden
revenue	number	Total revenue (after discounts)Revenue total (despues de descuentos)
currency	string	ISO 4217 currency code (default MXN)Codigo de moneda ISO 4217 (default MXN)
product_id	string	Product SKUSKU del producto
product_name	string	Product nameNombre del producto
product_line	string	Segment: MX, VD, DA, HA, IT, NWSegmento: MX, VD, DA, HA, IT, NW
quantity	integer	Number of unitsNumero de unidades

Example: Sending a Purchase Event Ejemplo: Enviando un Evento de Compra

Copycurl -X POST https://ingest.relo.mx/ingest/batch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "t": "purchase",
        "ts": 1710244800000,
        "cid": 3,
        "did": "fp_a1b2c3d4e5f6",
        "props": {
          "order_id": "MX260318-12345678",
          "revenue": 24999.00,
          "currency": "MXN",
          "product_id": "SM-S921BZKDMXO",
          "product_name": "Galaxy S24 Ultra 256GB",
          "product_line": "MX",
          "quantity": 1
        }
      }
    ]
  }'

Example: Sending a Batch of 1,000 Events Ejemplo: Enviando un Batch de 1,000 Eventos

Copy# Python example: batch send
import requests
import json
import time

events = []
for i in range(1000):
    events.append({
        "t": "page_view",
        "ts": int(time.time() * 1000) - (i * 1000),
        "cid": 3,
        "did": f"device-{i % 100:03d}",
        "url": f"https://samsung.com.mx/product-{i}"
    })

response = requests.post(
    "https://ingest.relo.mx/ingest/batch",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={"events": events}
)

print(response.json())
# {"accepted": 1000, "rejected": 0, "errors": []}

Error Handling & Retries Manejo de Errores y Reintentos

Status CodeCodigo de Estado	MeaningSignificado	ActionAccion
200	Events acceptedEventos aceptados	Check rejected countRevisa el conteo de rejected
400	Invalid payloadPayload invalido	Fix the request body, do not retryCorrige el body del request, no reintentar
401	Invalid or missing tokenToken invalido o faltante	Check your Bearer tokenRevisa tu Bearer token
429	Rate limitedLimite de tasa	Back off, retry after 1-5 secondsEspera, reintenta despues de 1-5 segundos
500 / 502 / 503	Server errorError del servidor	Retry with exponential backoff (1s, 2s, 4s, max 3 retries)Reintenta con backoff exponencial (1s, 2s, 4s, max 3 reintentos)

Rate Limits Limites de Tasa

EndpointEndpoint	LimitLimite	WindowVentana
/ingest/batch	100 requests100 requests	per minute per tokenpor minuto por token
/ingest/batch	10,000 events10,000 eventos	per request (body size)por request (tamano del body)
/health	No limitSin limite	-

At maximum rate (100 requests x 10,000 events), you can send 1 million events per minute. If you need higher throughput, contact your RELO account manager. A tasa maxima (100 requests x 10,000 eventos), puedes enviar 1 millon de eventos por minuto. Si necesitas mayor throughput, contacta a tu account manager de RELO.