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.Ejemplos de body
Cada ejemplo es el body completo dePOST /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 encurrencyy los productos enitems. Los ejemplos están en dólares (USD); mandá la moneda de tu negocio con su código ISO 4217, comoCOPoMXN. - 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.
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.
valueycurrencypueden ir dentro deparams, como en GA4, o al mismo nivel queevent_name, como en Solo contactos existentes. Si vienen en los dos lugares, gana el de afuera.occurred_atacepta cualquier fecha ISO 8601 con zona horaria. Sinoccurred_at, el evento toma la hora en que llegó.- Todo lo que mandes en
paramsqueda 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, comostoreopayment_method, además se pueden usar en los reportes a medida para filtrar y separar. Lo que va dentro deitemsno: 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_idysession_idno pueden tener espacios. Los de los extremos se recortan; uno en el medio hace que el evento salgainvalid, con un mensaje que dice qué mandar.external_idygroup.idlos aceptan, porque llegan tal cual de tus sistemas, pero conviene evitarlos.- Se comparan exactos:
CLI-9001ycli-9001son dos ids distintos. - Son de tu organización: el mismo id en otra organización no se mezcla.
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 comoduplicatey 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.
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 objetocontact 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.nameo, si no viene, el email o el teléfono. Crear contactos consume el cupo de contactos del plan. Concreate_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 objetocontact. La respuesta dice cómo encontró al contacto en matched_by: contact_id, external_id, phone, email, session, o null si lo creó.
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:
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 engroup. Con eso ContactShip arma las empresas: junta a los contactos de cada una y suma lo que compraron.
ides 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.namees el nombre que se muestra. Si cambia, la empresa se actualiza.propertiesson 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 planenterprise.- 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 sincontact 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
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 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
session_id. Eso ya identifica la sesión: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.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 ejemploGA1.1.1234567890.1726000000. - Sin espacios, de 1 a 200 caracteres. Un
session_idcon un espacio en el medio hace que el evento salgainvalid, y queidentifyresponda400. - 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.
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 ejemplopurchase-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_idysession_idsin espacios: uno en el medio vuelve el eventoinvalid. - 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,currencyeitems. Los reportes de ventas buscan primeropurchase. - Mandá la moneda en cada compra. Los montos en monedas distintas nunca se suman entre sí.
- Usá el mismo
session_iden todos los eventos de una visita y en elidentify. - Mandá la empresa en
groupsi 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
¿Por qué mi evento aparece con otro nombre?
¿Por qué mi evento aparece con otro nombre?
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ó.¿Puedo mandar eventos de visitantes que todavía no se identificaron?
¿Puedo mandar eventos de visitantes que todavía no se identificaron?
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.¿Qué nombres no puedo usar?
¿Qué nombres no puedo usar?
Los que empiezan con
cs_: están reservados para lo que ContactShip registra por su cuenta, como llamadas y campañas.¿Mandar eventos cuesta créditos?
¿Mandar eventos cuesta créditos?
No. Los eventos entran en el plan. Lo que sí consume cupo es crear contactos nuevos.
¿Qué pasa si mando el mismo evento dos veces?
¿Qué pasa si mando el mismo evento dos veces?
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.¿Puedo crear un evento desde la app, sin mandarlo?
¿Puedo crear un evento desde la app, sin mandarlo?
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.
