Skip to main content
Un evento es algo que hizo un contacto fuera de ContactShip: una compra en tu e-commerce, un pedido en tu POS, un formulario, una visita a tu sitio, un paso de un flujo en Make o n8n. Lo mandás a la API con un nombre y los datos que quieras, y queda en la actividad del contacto. Después lo usás para segmentar, mandar campañas y armar reportes de ventas sin integrar cada sistema por separado. El formato es el de Google Analytics 4: un event_name y params libres. Si ya mandás eventos a GA4, podés reusar los mismos nombres y parámetros.

Mandar el primer evento

1

Pedí el add-on

Los eventos se activan a pedido. Sin el add-on, la API responde 403. Escribinos a soporte.
2

Copiá la clave API

Usá la clave API de la organización en el encabezado x-api-key.
3

Mandá el evento

Cada request lleva entre 1 y 100 eventos. Este manda una compra:
4

Revisá el resultado

La respuesta trae un resultado por evento. created quiere decir que se guardó en el contacto que figura en contact.id. Los campos completos están en Enviar eventos.
¿Querés ver cómo se ve un evento antes de programar nada? En Ajustes → Organización → Eventos, tocá Mandar evento de prueba. Ver Catálogo de eventos.

Ejemplos de body

Cada ejemplo es el body completo de POST /v1/events. Podés juntar eventos de distintos tipos en el mismo array, hasta 100 por request.
  • Compra, carrito, inicio de pago y reembolso siguen el formato de comercio electrónico de GA4: el monto en value, la moneda en currency y los productos en items. Los ejemplos están en dólares (USD); mandá la moneda de tu negocio con su código ISO 4217, como COP o MXN.
  • Formulario y registro son los típicos de un sitio que capta clientes.
  • Visita anónima es un visitante que todavía no se identificó; ver Visitantes que todavía no se identificaron.
  • Historial carga compras viejas con su fecha real.
  • Solo contactos existentes suma el evento sin crear contactos nuevos.
Con los nombres de estos ejemplos (purchase, add_to_cart, begin_checkout, refund, generate_lead, sign_up, page_view, view_item), la actividad del contacto ya los muestra traducidos, como Compra o Agregó al carrito, sin configurar nada.
  • value y currency pueden ir dentro de params, como en GA4, o al mismo nivel que event_name, como en Solo contactos existentes. Si vienen en los dos lugares, gana el de afuera.
  • occurred_at acepta cualquier fecha ISO 8601 con zona horaria. Sin occurred_at, el evento toma la hora en que llegó.
  • Todo lo que mandes en params queda guardado tal cual. La actividad del contacto muestra los datos más importantes de cada evento, empezando por los que elijas como destacados en el catálogo.
  • Los datos del primer nivel de params, como store o payment_method, además se pueden usar en los reportes a medida para filtrar y separar. Lo que va dentro de items no: si querés separar las ventas por producto o por categoría, mandá también ese dato en el primer nivel, por ejemplo "product_name": "Pizza grande".
  • Para ver qué eventos mandan restaurantes, clínicas, financieras o institutos, y cómo los usan con campañas, llamadas y reportes, mirá Casos de uso con eventos.

Cómo se nombran los eventos

ContactShip guarda cada nombre en minúscula y con guion bajo (snake_case), el mismo estilo que usa Google Analytics: purchase, add_to_cart, begin_checkout. Si mandás el nombre escrito de otra forma, se normaliza antes de guardarlo, así un mismo evento nunca queda repartido en varios: Para normalizar se sacan los acentos, se separan las palabras por mayúsculas, espacios, guiones o puntos, y se pasa todo a minúscula. El resultado tiene que empezar con una letra y tener hasta 40 caracteres: 1st purchase se rechaza como invalid porque empieza con un número. La respuesta te dice con qué nombre quedó cada evento en event_name y, si lo cambió, cómo lo mandaste en original_event_name. Los nombres que empiezan con cs_ están reservados para los eventos que ContactShip registra solo (ver más abajo).

Los ids que elegís

Además de los datos del contacto, un evento puede llevar hasta cuatro ids que definís vos. Cada uno identifica algo distinto: Ejemplo: Ana entra a tu tienda, mira dos productos y compra. Son tres eventos con el mismo session_id, porque son la misma visita, y la compra lleva además su event_id, purchase-10025. Las reglas de los cuatro:
  • De 1 a 200 caracteres.
  • event_id y session_id no pueden tener espacios. Los de los extremos se recortan; uno en el medio hace que el evento salga invalid, con un mensaje que dice qué mandar. external_id y group.id los aceptan, porque llegan tal cual de tus sistemas, pero conviene evitarlos.
  • Se comparan exactos: CLI-9001 y cli-9001 son dos ids distintos.
  • Son de tu organización: el mismo id en otra organización no se mezcla.
No uses un nombre como id. ACME Warner Bros como group.id funciona, pero cuando el nombre cambie o llegue escrito distinto vas a tener dos empresas. Usá el id que ya le da tu sistema: el NIT, el código de cliente, el id del CRM.

event_id: único y el mismo en cada reintento

Identifica el hecho en tu sistema. Si un request falla y lo reintentás, el evento con el mismo event_id responde duplicate y no se guarda dos veces.
  • Armalo con el evento y el id del hecho: purchase-10025, refund-10025, payment_received-551902-3. Así sale igual en cada reintento sin tener que guardar nada.
  • Tiene que ser único entre todos tus eventos, no solo entre los del mismo nombre: si la compra y su devolución llevan solo 10025, la devolución vuelve como duplicate y no se guarda.
  • Si preferís un UUID, generalo una vez y guardalo junto al hecho: uno nuevo en cada intento no evita duplicados.
  • Es opcional, pero sin él no hay forma de detectar un reintento.
El session_id se explica en Visitantes que todavía no se identificaron; el external_id, en Cómo se encuentra el contacto; y el group.id, en La empresa del contacto.

Cómo se encuentra el contacto

Cada evento lleva un objeto contact con al menos uno de estos datos. ContactShip los prueba en este orden y se queda con el primero que encuentra:
  • Si varios contactos tienen el mismo teléfono, el evento va al que tuvo la conversación o la llamada más reciente.
  • Un email que tienen varios contactos no se usa para buscar.
  • Si el teléfono y el email apuntan a contactos distintos, gana el teléfono y el resultado lo avisa en conflict.
  • Si no encuentra a nadie y el evento trae teléfono o email, crea el contacto, con el nombre de contact.name o, si no viene, el email o el teléfono. Crear contactos consume el cupo de contactos del plan. Con create_contact: false, el evento sólo se suma a contactos que ya existen.
  • Los contactos nunca se fusionan: a uno que ya existe sólo se le completan el teléfono o el email si los tenía vacíos.

Ejemplos por forma de identificar

Cambia solo el objeto contact. La respuesta dice cómo encontró al contacto en matched_by: contact_id, external_id, phone, email, session, o null si lo creó.
Con contact_id nunca se crea un contacto: si el id no existe, se prueba con los demás datos, y si no hay otros, el evento queda unresolved. Cómo queda asociado un external_id. La primera vez mandalo junto con el teléfono o el email; desde ahí alcanza con el id solo:
Un external_id que nunca se asoció no encuentra a nadie: si llega solo, el evento queda unresolved.

La empresa del contacto

Si le vendés a empresas, mandá en cada evento la empresa del contacto en group. Con eso ContactShip arma las empresas: junta a los contactos de cada una y suma lo que compraron.
  • id es obligatorio: el id de la empresa en tu sistema (el NIT, el código de cliente o el id de tu CRM), no su nombre. Hasta 200 caracteres (ver Los ids que elegís). Con él se reconoce a la empresa en los eventos siguientes.
  • name es el nombre que se muestra. Si cambia, la empresa se actualiza.
  • properties son datos de la empresa, como el plan o la industria. Cada evento suma o actualiza los que trae y deja los demás. Sirven para filtrar, por ejemplo, a los contactos de empresas con plan enterprise.
  • La primera vez que llega un id se crea la empresa y se vincula al contacto. Otro evento con el mismo id no la duplica.
  • Si ya habías armado empresas desde una propiedad de tus contactos y una tiene el mismo nombre, se usa esa.

Visitantes que todavía no se identificaron

“Vio el catálogo” o “agregó al carrito” suelen pasar antes de que sepas quién es la persona. Para no perder ese recorrido, mandá esos eventos sin contact y con un session_id: el id de la visita, el mismo en todos sus eventos. Más abajo está cómo generarlo.
1

Mandá los eventos anónimos

El resultado de cada uno es pending: todavía no aparecen en ningún contacto, filtro ni reporte, y se guardan hasta 30 días.
2

Identificá la sesión cuando sepas quién es

Si en ese momento mandás un evento con los datos del contacto, por ejemplo la compra, agregale el mismo session_id. Eso ya identifica la sesión:
Si no tenés un evento para mandar, porque inició sesión, se registró o terminó un checkout que no mandás como evento, llamá a POST /v1/identify:
contact acepta cualquiera de los datos del orden de búsqueda, igual que en un evento. La respuesta dice linked y, en pending_events, cuántos eventos estaban esperando. identify no lleva group: la empresa va dentro de un evento.
3

Los eventos pasan al contacto

En menos de un minuto, con su fecha original, marcados como Antes de identificarse en la actividad. Lo que llegue después con ese session_id va directo al contacto, aunque no traiga sus datos.
Una sesión es de la primera persona que se identifica en ella. Si después llegan datos de otra en la misma sesión, por ejemplo en una computadora compartida, la sesión sigue siendo de la primera y la respuesta lo avisa: already_linked en identify, conflict en un evento. Por eso conviene generar un session_id nuevo al cerrar sesión.
Los eventos anónimos de una organización tienen un tope diario de 100.000. Pasado ese número se rechazan con anonymous_daily_limit hasta el día siguiente; si necesitás más, escribinos. Los requests que traen eventos anónimos usan además un cupo de requests propio, más chico que el del resto de los eventos (Límites y reintentos).

Cómo generar el session_id

Lo genera tu sitio o tu app, no ContactShip. Lo más simple es un UUID por navegador, creado la primera vez y reusado en cada evento:
  • Si ya usás Google Analytics, también sirve su client id: la cookie _ga, por ejemplo GA1.1.1234567890.1726000000.
  • Sin espacios, de 1 a 200 caracteres. Un session_id con un espacio en el medio hace que el evento salga invalid, y que identify responda 400.
  • Se compara exacto: distingue mayúsculas.
  • Nunca uses algo que identifique a la persona, como su email o su teléfono: si ya lo tenés, mandalo en contact.
La clave API nunca va en el código del navegador. Tu sitio le pasa el session_id a tu servidor, y es tu servidor el que llama a la API.

Qué significa cada resultado

Un evento con problemas no afecta a los demás del mismo request.

Eventos que registra ContactShip

Además de los que mandás vos, ContactShip registra por su cuenta lo que pasa dentro de la plataforma. Aparecen en la actividad del contacto y se pueden usar en filtros y reportes igual que los tuyos: Por eso podés preguntar cosas que cruzan los dos mundos, como “compró en los 7 días siguientes a recibir la campaña”.

Buenas prácticas

  • Mandá siempre event_id, por ejemplo purchase-10025: único entre todos tus eventos y el mismo en cada reintento. Así podés reintentar un request que falló sin duplicar eventos.
  • Mandá event_id y session_id sin espacios: uno en el medio vuelve el evento invalid.
  • Cargá la historia con occurred_at. Los eventos viejos cuentan para segmentar y reportar como si hubieran llegado en su momento.
  • Mandá el teléfono en formato internacional. Es el dato que mejor identifica al contacto.
  • Usá los nombres de GA4 (purchase, add_to_cart, begin_checkout, sign_up) y, en las compras, transaction_id, value, currency e items. Los reportes de ventas buscan primero purchase.
  • Mandá la moneda en cada compra. Los montos en monedas distintas nunca se suman entre sí.
  • Usá el mismo session_id en todos los eventos de una visita y en el identify.
  • Mandá la empresa en group si le vendés a empresas: sin ella, las compras quedan solo en cada persona.
  • Agrupá hasta 100 eventos por request. Este endpoint tiene su propio límite de requests, aparte del resto de la API.

Preguntas frecuentes

Porque se normalizó: addToCart o Add To Cart se guardan como add_to_cart. Mirá original_event_name en la respuesta para ver cómo llegó.
Sí, con un session_id y sin datos del contacto. Quedan en espera hasta 30 días y pasan al contacto cuando la sesión se identifica. Ver Visitantes que todavía no se identificaron.
Los que empiezan con cs_: están reservados para lo que ContactShip registra por su cuenta, como llamadas y campañas.
No. Los eventos entran en el plan. Lo que sí consume cupo es crear contactos nuevos.
Si trae el mismo event_id, la segunda vez el resultado es duplicate y no se guarda de nuevo. Sin event_id no hay forma de detectarlo.
No. Cada evento aparece en el catálogo la primera vez que llega. Si querés verlo antes de integrar, usá el evento de prueba.

Seguí con

Enviar eventos

Todos los campos, resultados y errores.

Identificar una sesión

Unir los eventos anónimos de una visita a un contacto.

Eventos del contacto

Dónde se ven y cómo filtrar contactos por lo que hicieron.

Reportes de ventas

Ventas, recompra y ventas atribuidas a ContactShip.

Casos de uso con eventos

Qué mandar y qué hacer en restaurantes, clínicas, cobranzas y más.