Webservices & Webhooks
Webservices
Actito tiene como objetivo ofrecerte una gran conectividad en tu enfoque de marketing. Por lo tanto, prestamos especial atención a habilitar intercambios de datos entre Actito y otros sistemas específicos en tu negocio.
La API pública disponible te permite interactuar directamente con Actito sin tener que pasar por la interfaz. A través de los servicios web, puedes llamar a los datos presentes en Actito y obtener estos datos como respuesta. También puedes programar el envío de datos desde tu sistema a Actito.
Más que un simple proceso de intercambio de datos, los servicios web de Actito también te permiten activar el uso de estos datos, así como automatizar su procesamiento.
De hecho, la API consiste en una serie de rutas, agrupadas en categorías que corresponden a los diferentes canales y aplicaciones de Actito. Prácticamente todo lo que se puede hacer en la interfaz de Actito se puede automatizar a través de nuestra API pública.
Acceso a las API públicas
Actito proporciona acceso a servicios web en 4 entornos: 1 entorno PREPROD y 3 entornos PROD.
La documentación técnica está disponible en línea y en inglés en nuestro portal para desarrolladores. Se actualiza constantemente.
La sección "Servicios web" de la documentación de la plataforma tiene como objetivo proporcionarte una perspectiva empresarial sobre lo que es posible a través de la API de Actito.
Para obtener detalles de implementación, los desarrolladores siempre deben consultar las especificaciones de la API en el Portal para Desarrolladores (enlace arriba).
Creación de cuenta de usuario y autenticación de servicios web
El uso de las API se realiza de manera autenticada. Estas son cuentas específicas separadas de las cuentas de usuario de la plataforma.
La API de Actito utiliza la autenticación basada en el principio de clave de API.
Autenticación mediante clave de API
Los administradores de tu licencia tienen la capacidad de configurar directamente tus claves de API (ver "Gestión de usuarios de API")
Cuando se crea un usuario de API, se recomienda asociarlo con la dirección de correo electrónico de la persona responsable de mantener sus APIs. De esta manera, serán notificados de cualquier cambio que pueda afectar sus integraciones.
Para configurar las llamadas a la API, no se debe utilizar la clave de API directamente como identificador.
Se utilizará para generar un token de acceso con un período de validez limitado (15 minutos), que debe incluirse en todas las llamadas.
Por ejemplo, para generar un token en un entorno de PRUEBA, la llamada sería
GET https://api-pre1.actito.com/auth/token
con la clave de API en el encabezado 'Authorization'.
Obtener Token
curl
-X GET 'https://api-pre1.actito.com/auth/token' \
-H 'Authorization: qhdfbvdh747R49FRHrthqXXXXXXX' \
-H 'Accept: application/json'
Recibirá un token (en el parámetro 'accessToken' de la respuesta).
Respuesta de Obtener Token
{
"accessToken": "AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F",
"tokenType": "bearer",
"expiresIn": "900s",
"scope": "read write",
"jti": "ce6c1d3c-ab49-4b62-8f4c-964351ac5d58"
}
El token obtenido se utilizará para autenticar todas las llamadas durante los próximos 15 minutos. Debe incluirse como 'Authorization' de tipo 'Bearer' en todas las llamadas.
Ejemplo de Token Bearer
curl
-X GET 'https://api-pre1.actito.com/v5/entities/MyEntity/etls' \
-H "Authorization: Bearer
AAAAAAAAAAAAAAAAAAAAAMLheAAAAAAA0%2BuSeid%2BULvsea4JtiGRiSDSJSI%3DEUifiRBkKG5E2XzMDjRfl76ZC9Ub0wnz4XsNiRVBChTYbJcE3F" \
-H 'Accept: application/json'
Versiones Públicas de la API
Actito mejora continuamente su producto y trabaja activamente en la expansión de su plataforma de integración.
Todas las últimas rutas desarrolladas se pueden reconocer por el v5 en su ruta. La filosofía de V5 es seguir de cerca las prácticas estándar de la API REST y mejorar la consistencia de su comportamiento basado en recursos.
No hay planes para deprecar completamente V4 o reemplazarlo por completo con rutas V5. Sin embargo, pueden ocurrir cambios en rutas individuales de V4. Se anunciarán a través del proceso documentado aquí.
Conceptos de Actito Accesibles a través de Servicios Web
Cada operación se agrupa bajo un concepto, que corresponde a la categoría de los recursos de Actito a los que se aplicará la operación.
Each operation is grouped under a concept, which corresponds to the category of Actito resources to which the operation will be applied.
Cada operación se agrupa bajo un concepto, que corresponde a la categoría de los recursos de Actito a los que se aplicará la operación.
Para familiarizarse con los diferentes conceptos con los que se puede interactuar a través de la API de Actito, le invitamos a leer el capítulo dedicado a los "Conceptos de Actito accesibles a través de servicios web".
Webhooks
La misión de Actito es proporcionarte una gran conectividad en tu enfoque de marketing. Por lo tanto, prestamos especial atención a habilitar intercambios de datos entre Actito y otros sistemas específicos de tu negocio.
Varias soluciones te permiten interactuar directamente con Actito sin tener que pasar por la interfaz. La API pública de Actito ya te permite recuperar datos de Actito y enviar datos a Actito.
Los webhooks ofrecen el servicio inverso de los servicios web. Ya no es necesario hacer una llamada cada vez que necesites información. De hecho, los webhooks escuchan información. Al suscribirte a los webhooks, te permiten recibir notificaciones directamente de los eventos que ocurren en un perfil o una entrada en una tabla morada. Estos eventos se comunicarán a una URL que hayas proporcionado.
Esta sección de la documentación de la plataforma tiene como objetivo brindarte una perspectiva empresarial sobre lo que es posible a través de la plataforma de integración de Actito.
Para obtener detalles de implementación, los desarrolladores siempre deben consultar las especificaciones en el Portal de Desarrolladores.
Contexto
Eventos de interés
Los webhooks te permiten recibir notificaciones de eventos relacionados con las tablas de perfiles y las tablas personalizadas en el modelo de datos.
Estos eventos son de la siguiente naturaleza:
- CREATE: Esto te permite recibir notificaciones cuando se crea un nuevo perfil o un nuevo registro de datos.
- UPDATE: Esto te permite recibir notificaciones de cualquier cambio en un perfil o un registro de datos. Es posible especificar exactamente qué campos de la tabla deben tenerse en cuenta.
- DELETE: Esto te permite recibir notificaciones cuando se elimina un perfil o un registro.
- UPDATED_SEGMENT y UPDATED_SUBSCRIPTION: Estos eventos son específicos de las tablas de perfiles. Te permiten recibir notificaciones cuando hay un cambio en la suscripción o segmentación.
Para las tablas personalizadas del modelo en estrella, es necesario especificar los eventos en el archivo JSON de definición de la tabla (en el parámetro "eventToTrigger").
Siempre existe un evento CREATE por defecto en las tablas personalizadas, pero los eventos de UPDATE deben ser definidos (especialmente para definir qué campos actualizados desencadenan un evento).
No dude en contactar a su administrador de cuenta si necesita ayuda para configurar eventos en sus tablas.
Además de recuperar información de sus tablas, los webhooks también pueden obtener el estado de sus ETL y sincronización de archivos, o conectar sus escenarios con sistemas externos mediante acciones personalizadas.
Protocolo
Cada vez que se registra un evento que coincide con la definición de suscripción del webhook en Actito, el webhook enviará la información a la URL que ha proporcionado.
Para ayudarlo a manejar volúmenes más grandes, las llamadas pueden realizarse en modo unitario o en modo masivo. El modo masivo es útil cuando varios elementos se ven afectados al mismo tiempo (como en una importación por archivo), para agrupar las actualizaciones en una sola llamada. Sin embargo, los webhooks siempre obtienen la información en tiempo real: incluso en modo masivo, si se registra un evento y no se registra un segundo evento en los segundos siguientes, se enviará la notificación por webhook.
Acceso
Para recibir notificaciones cada vez que ocurre uno de los eventos en la tabla monitoreada, es necesario crear una suscripción a un webhook. Se debe crear una suscripción de webhook por evento monitoreado y por tabla monitoreada.
La creación y gestión de estas suscripciones se realiza a través de las APIs de Actito. Su definición está disponible en la documentación técnica.