Enviar ventas y datos propios a LinkHarbor

LinkHarbor también acepta datos desde fuera. Para dos casos hay endpoints propios con sus propios secretos, y para ellos no necesitas una clave de API: los callbacks de venta comunican las ventas de tu tienda, para que veas en tus estadísticas qué enlace trajo ingresos. La integración «Custom (API)» lleva datos en vivo de tus propias herramientas a tu página como widget y puede disparar notificaciones push.

#Callbacks de venta: asignar ventas

Cómo encajan el ID de clic (lt_click_id), la asignación y los informes se explica en Atribuir conversiones y ventas; aquí encontrarás todos los campos y respuestas para desarrolladores. En resumen: cuando LinkHarbor redirige un clic contabilizado a un destino http o https, añade el parámetro lt_click_id; tu tienda lo guarda y lo devuelve después de la compra.

Crear un secreto de callback

1. Abre «Callback y API»
2. En la tarjeta «Secretos de callback», haz clic en «+ Crear nuevo secreto»
3. Si quieres, ponle un nombre, por ejemplo «Callback de la tienda», y haz clic en «Crear secreto»
4. Copia el secreto enseguida; solo se muestra una vez

Quién

Propietarios y admins, desde Creator Pro. En Creator Free aparece «Los secretos de callback están disponibles desde Creator Pro.»

Cuántos

Hasta 5 secretos por espacio de trabajo, por ejemplo uno por tienda.

«Editar»

Cambia el nombre y pon el estado en «Activo» o «Inactivo». Con un secreto inactivo, la API rechaza los callbacks.

«↺ Rotar»

Genera un secreto nuevo; el anterior deja de funcionar de inmediato.

«Último callback:»

Muestra cuándo se usó el secreto con éxito por última vez.

Enviar un callback

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

Firma opcional

Además del secreto, puedes enviar el encabezado X-Callback-Signature. Contiene sha256= y la firma HMAC-SHA256 del cuerpo sin procesar en hexadecimal. La clave no es el secreto en sí, sino su hash SHA-256 en forma binaria. Si envías el encabezado, tiene que ser correcto; si no, el callback se rechaza.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // hash binario del secreto
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Encabezados: X-Callback-Secret y X-Callback-Signature: $sig, cuerpo: $body

Dónde ves las ventas

Las ventas comunicadas aparecen como conversiones en tus estadísticas; consulta Atribuir conversiones y ventas. Mediante la API, las lees con read:stats en /v1/stats/…/conversions/breakdown.

#Custom (API): tus propios datos en vivo

Con la integración «Custom (API)», cualquier programa capaz de enviar peticiones HTTP (un plugin de servidor de juego, un bot, un script de cron) puede enviar datos a LinkHarbor. Se convierten en un widget en vivo en tu página, y las reglas push pueden avisar a tus seguidores.

Conectar

1. Abre «Integraciones» en el espacio de trabajo
2. Elige «Custom (API)» y escribe un nombre
3. Una vez conectada, el diálogo muestra la «URL de ingesta» y el «Secreto» (con «Mostrar secreto»)
4. Guarda ambos en tu herramienta

Las integraciones están disponibles desde Creator Pro. Solo los propietarios y admins ven la URL de ingesta y el secreto, también después en la vista de detalle de la integración. Al desconectar y volver a conectar se crea un secreto nuevo. Cómo se conectan las integraciones en general se explica en Conectar una integración.

Enviar datos

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

Nombre libre del evento, por ejemplo player.joined. Se convierte a minúsculas y es el nombre al que reaccionan las reglas push. Sin event, el evento se llama state.updated.

event_id

Clave opcional que evita el procesamiento doble. Si se vuelve a enviar el mismo event_id, LinkHarbor responde con duplicate: true y no hace nada.

data

Valores para los marcadores de los textos push, por ejemplo {player}. Hasta 40 claves, solo valores simples.

state

El estado completo del widget. Sustituye por completo al anterior. type es game_server (tarjeta de servidor de juego) o status (tarjeta de estado).

En lugar de Authorization: Bearer, también puedes enviar el secreto en el encabezado X-LinkHarbor-Secret. Se permiten 120 llamadas por minuto por dirección IP. Opcionalmente, firmas el cuerpo: el encabezado X-LinkHarbor-Signature contiene sha256= y la firma HMAC-SHA256 del cuerpo sin procesar con el secreto como clave. Si lo envías, tiene que ser correcto.