Tabla de contenidos
Para conectar una aplicación a una campaña de Bunker DB Analytics, es necesario, en una primera etapa, generar un token. Cada token es único por campaña y —por motivos de seguridad— se muestra una única vez. Luego, el token se emplea para establecer la conexión con la API de Bunker DB analytics incluyéndose en el código del desarrollo. Finalmente, se testea la implementación directamente en el ambiente de producción.
La versión 4 de nuestra API ofrece las mismas características de integración que la versión 3 y agrega la posibilidad de establecer campos custom.
Crea un API token
Selecciona «Editar campaña».
😉 También puedes acceder a la edición de la campaña desde Campañas:
Dirígete a la pestaña «API» y selecciona «Crear API Token»
Ingresa tu contraseña de usuario para acceder al modo Sudo.
Agrega una breve descripción y haz clic en «Crear API token».
El token se muestra en la tabla por una única vez y desde allí se puede copiar para compartirlo con el desarrollador que llevará adelante, en una segunda etapa, la integración con la plataforma
🦸🏽
Para acceder a estas opciones en Bunker DB, debes tener rol de Superuser en la plataforma.
Conexión con la API
La autenticación se realiza enviando un Authorization header que contiene el Bearer token generado en Bunker DB analytics. Todos los métodos de la API requieren autenticación.
Ejemplo:
“Authorization: Bearer 0420036fa63cbde636703216a7ee235c7ba7ab96”
🚨
Todas las instalaciones de Bunker DB analytics se encuentran bajo protocolo https, por lo cual el tráfico punto a punto está encriptado.
Es responsabilidad de los terceros que se conectan a Bunker DB analytics el realizar una conexión segura, comprobando la vigencia y autenticidad del certificado SSL.
Cómo utilizar los endpoints
La integración debe ser realizada server-to-server (server side) con el propósito de no exponer el token ya que es de carácter sensitivo.
Toda interacción con la API se realiza en formato json, por lo cual el header ContentType: Application/json debe estar siempre presente.
A continuación encuentra los métodos que pueden emplearse para testear el funcionamiento de la integración:
Preferencias
GET: /api/v4/preferences
Este método devuelve, en formato json, las preferencias configuradas en la campaña, que luego serán enviadas a través de la API, al crear consumidores. Es importante que crees las mismas preferencias en la campaña de Bunker DB Analytics para que se asignen a los consumidores a medida que se insertan en la base de datos.
Consumidores
POST: /api/v4/consumers
Con este método, la API permite insertar un consumidor al que se le puede incluir un campo custom con su correspondiente valor directamente en el json. La inserción fue exitosa, si la respuesta de la API es 201:
En el caso de que se utilicen campos inexistentes, el consumidor es almacenado en Bunker DB analytics, pero sin la información del campo. La API arroja una advertencia —unknown field— cuando desconoce un campo.
PUT: /api/v4/consumers
Con este método, la API permite modificar un consumidor al que se le puede incluir un campo custom con su correspondiente valor directamente en el json. La modificación fue exitosa, si la respuesta de la API es 201:
🚨 Importante: Para que la modificación sea exitosa, debes contar con un userdata_id o external_id
En el caso de que se utilicen campos inexistentes, el consumidor es almacenado en Bunker DB analytics, pero sin la información del campo. La API arroja una advertencia —unknown field— cuando desconoce un campo.
Este update generará eventos que podrán ser visualizados en la sección de Consumidores de Bunker DB para los registros respectivos cuya actualización haya sido exitosa.
A diferencia de la importanción de eventos hecha a través de un CSV, en este caso no se enviará un mail confirmando si la actualización fue exitosa o no.
Ventas
POST: /api/v4/sales
La información requerida para registrar cada venta es, por un lado, el dato match_key que refiere al modelo de búsqueda y asignación a un correspondiente registro preexistente.
Por otro lado, tenemos la información de la venta:
event_time: (requerido) - día y hora en formato YYYY-MM-DD HH:MM:SS.
order_id: (string) - Nro de orden para asociar con el sistema de ventas externo.
external_sale_id: (string) - Identificador de la venta en el sistema externo.
value - Monto de la venta.
currency - Moneda usada en la transacción, si no es provista, se utilizará la moneda definida para la marca. Se sigue el estándar internacional ISO 4217.
Ejemplo de venta:
[
{
"match_key": {
"phone": "4692023332"
},
"event_time": "2019-07-13 12:34:21",
"order_id": "12332223421"
}
]
Como se muestra, el match_key es un elemento que contiene la expresión de búsqueda para resolver el registro posible.
Los campos disponibles son:
id
document
email
phone
cellphone
La asignación es directa y puede producir los siguientes resultados:
created/updated: Venta creada o actualizada correctamente para el registro.
not found: No se encontró el registro según id, email, phone, cellphone, documento - Estos campos refieren al modelo de atribución implementado en Bunker DB analytics donde pueden devolver los mismos estados que el anterior caso, sí se pudo detectar con exactitud el registro relacionado. O bien devolver:
not unique: En este caso no se pudo identificar un registro único, y se incluyen las coincidencias en la respuesta para que el operador pueda seleccionar el que más se ajuste (volviendo a registrar la venta pero en este caso usando el id correspondiente).
Estados de respuesta
Created, updated, not_found y not_unique a los que se les suma invalid, que solo aplica cuando la fecha de event_time está mal formada o no se pudo reconocer.
La respuesta mantiene el mismo orden que la información de entrada, agregando:
sale_id: Identificador de la venta solo para los estados created/updated.
status: Refiere a uno de los estados previamente citados (created, updated, not found, not unique, invalid).
reason: Información complementaria al estado, en caso que lo requiera.
matches: Solo para el estado not unique y es donde se proporciona la lista de registros que corresponde con el macheo por atribución y para los que no se pudo identificar un único registro.
userdata_id: Se retorna el identificador del registro matcheado, solo para los estados: created/updated.
Respuesta de ejemplo para caso: not_unique
[
{
"match_key": {
"email": "[email protected]"
},
"event_time": "2016-08-10 11:14:13",
"value": 2200,
"response": {
"status": "not unique",
"reason": "Can't resolve unique registry by attribution",
"matches": [
{
"BunkerID": "41369",
"CampaignRefID": null,
"First Name": "Mateo",
"Last Name": "Menestrina",
"Email": "[email protected](opens in new tab)",
"Record created at": "2015-12-03 00:00:00",
"Document": null,
"Document Type": null,
"Document Country": null,
"Phone": null,
"Cellphone": null,
"Gender": null,
"Birthday": null,
"Address": null,
"City": null,
"State": null,
"Country": null,
"Postal Code": null,
"Device": null
},
{
"BunkerID": "41370",
"CampaignRefID": null,
"First Name": "Joe",
"Last Name": "Doe",
"Email": "[email protected]",
"Record created at": "",
"Document": null,
"Document Type": null,
"Document Country": null,
"Phone": null,
"Cellphone": null,
"Gender": null,
"Birthday": null,
"Address": null,
"City": null,
"State": null,
"Country": null,
"Postal Code": null,
"Device": null
}
]
}
}
]
Respuesta de ejemplo para caso: created y updated
[
{
"match_key": {
"id": "41367"
},
"event_time": "2019-07-13 12:34:21",
"order_id": "12332223421",
"response": {
"sale_id": 5,
"status": "created",
"userdata_id": "41367"
}
},
{
"match_key": {
"email": "[email protected]"
},
"event_time": "2016-02-10 11:14:13",
"order_id": "3325-uy",
"response": {
"sale_id": 3,
"status": "updated",
"userdata_id": "41367"
}
}
]
Respuesta de ejemplo para caso: not_found
[
{
"match_key": {
"id": "4136799999"
},
"event_time": "2019-07-13 12:34:21",
"order_id": "12332223421",
"response": {
"status": "not_found",
"reason": "Userdata not found",
"userdata_id": "4136799999"
}
}
]
Respuesta de ejemplo para caso: invalid
[
{
"match_key": {
"id": "4136799999"
},
"event_time": "30-02-2020",
"value": 545.5,
"response": {
"status": "invalid",
"reason": "The parsed event_time was invalid",
"userdata_id": "4136799999"
}
}
]
Campos
GET: /api/v4/fields
Este método devuelve todos los campos —fijos o custom—, que se pueden atribuir a los consumidores.
Listado de campos fijos
En la respuesta de la llamada, los campos fijos se identifican como “false” en el campo “dynamicField”.
Las propiedades marcadas con (*) deben estar presentes en todas las solicitudes, el resto de las propiedades son opcionales y sólo se deben especificar cuando el cliente disponga de valores válidos y significativos.
El cuerpo de la solicitud es un objeto con las siguientes propiedades:
*platform_id: (string [3-254]).
Identificador de la plataforma: “facebook_app”, “web”, “google”.
external_id: (string [1-45]) Identificador externo del objeto. Si fue utilizado en una solicitud anterior para adicionar un objeto ActionPersonData cuya propiedad campaign_id tenía el mismo valor, se eliminará el objeto anterior para evitar que existan dos objetos en la misma campaña con el mismo identificador externo.
obtained_time: (datetime) Fecha y hora en la que fueron obtenidos los datos de esta persona. Tiene que seguir el formato definido en ISO 8601. El valor por defecto es la fecha y hora en la que el servidor recibe la solicitud.
facebook_uid: (string [1 -50]) Identificador de Facebook.
email: (string [3 -254]) Correo electrónico.
twitter_uid: (string [1 -50]) Identificador de Twitter.
linkedin_uid: (string [1-50]) Identificador de LinkedIn.
google_uid: (string [1 -50]) Identificador de Google.
cellphone: (string [4 -50]) Móvil.
document: (string [5 -20]) Documento.
document_type: (string) Tipo de documento.
Por defecto se asignará “DNI”. Debe ser alguno de los siguientes valores:
citizen: Credencial.
dfi: Documento de identificación Federal.
dni: Documento de identificación Nacional.
friver: Licencia de conducir.
militar: Identificación militar.
passport: Pasaporte.
social: Identificación de la seguridad social.
cpf: Cadastro de Pessoas Físicas.
document_country: (string [2]) País emisor del documento.
Tiene que seguir el formato definido por la ISO 3166-1, con la representación de dos letras. Se puede ver el listado en la ISO 3166-1-alpha-2. Por defecto se asignará: “UY”.
phone: (string [4-50]) Teléfono.
first_name: (string [1-100]) Nombre.
last_name: (string [1-100]) Apellido.
gender: (char [1]) Género.
“f” = femenino.
“m” = masculino.
birthday: (date) Fecha de nacimiento. Tiene ser en el formato YYYY-MM-DD. Ejemplo: 1983-02-26. Debe estar en el rango de los últimos 130 años.
address_country: (string [2]) País de residencia. Debe estar definida según ISO 3166-1, con la representación de dos letras.
address: (string [1-65535]) Domicilio. En lugar del domicilio puedes incluir address_line_one and address_line_two, ten en cuenta que el domicilio tendrá precedencia.
address_line_one: (string [1-65535]) Primera línea del domicilio, ten en cuenta que, si empleas address, este campo tendrá precedencia.
address_line_two: (string [1-65535]) Segunda línea del domicilio, ten en cuenta que, si empleas address, este campo tendrá precedencia.
address_postal_code: (string [1-50]) Código postal.
address_state: (string [1-255]) Estado/Departamento.
address_city: (string [1-255]) Ciudad.
allow_newsletters: (Booleano) Define si la persona acepta recibir el boletín.
allow_sms: (booleano) Define si la persona acepta recibir el sms.
allow_brand: (booleano) Define si el consumidor acepta recibir información sobre campañas de la marca.
allow_global: (booleano) Define si la persona permite al sistema enviarle información sobre otras campañas.
device: (string [15]) Dispositivo.
“desktop”
“tablet”
“phone”
preferences: Las preferencias asignadas al consumidor en formato json. Estas preferencias deben coincidir con las preferencias de la campaña.
utm_medium: (string [0-100]) Convencionalmente utilizado para referenciar el medio. Por ejemplo, cpc, banner, email newsletter.
utm_source: (string [0-100]) Convencionalmente utilizado para referenciar la Red.
Ejemplo: Facebook.utm_campaign: (string [0-100]) Convencionalmente utilizado para referenciar el nombre individual de la campaña.
Ejemplo: el eslogan, el código de promoción, etc.utm_term: (string [0-100]) Convencionalmente utilizado para referenciar la palabra clave paga en Google Search, o la referencia al grupo de anuncios.
utm_content: (string [0-100]) Convencionalmente utilizado para referenciar el anuncio.
Campos fijos propios de Facebook Lead Ads
form_id: (string [0-255]) Requerido. Identificador del formulario.
lead_id: (string [0-255]) Requerido. Identificador del lead.
ad_id: (string [0-255]) Requerido. Identificador del anuncio.
ad_name: (string [0-255]) Nombre del anuncio.
adset_id: (string [0-255]) Requerido. Identificador del grupo de anuncios.
adset_name: (string [0-255]) Nombre del grupo de anuncios.
campaign_id: (string [0-255]) Requerido. Identificador de la campaña.
campaign_name: (string [0-255]) Nombre de la campaña.
created: (datetime) Fecha de creación del lead.
platform: (string [0-255]) Placement del anuncio: "Facebook", "Instagram".
is_organic: (boolean) Identificador de Leads orgánicos.
Campos custom
El objetivo de los campos custom—“dynamicField” = true— es almacenar datos que no están contemplados en los campos fijos de la API.
Se desplegará un .json con los siguientes atributos:
fieldName
displayName
description
type
size (solo para tipos Text)
options
A través de este endpoint, la API devolverá los campos custom disponibles, previamente creados en Bunker DB analytics, estos pueden ser:
Sí/No: podrán tener un valor del tipo sí/no, o estar vacíos. Ejemplo: ¿Es madre?
Numérico: podrán tener un valor numérico. Ejemplo: ¿Cuántos hijos tienes?
Texto: podrán tener como valor un texto cualquiera que será completado por el consumidor que participa en la promoción.
Ejemplo: ¿Cómo te gusta pasar tu cumpleaños?Fecha: podrán ingresar una fecha (datetime). Ejemplo: Fecha de inscripción.
Múltiple opción: podrán seleccionar un valor en una lista de opciones definidos por el usuario administrador o brand manager a nivel de instalación.
Ejemplo: ¿Cuál es tu color de pelo?
Verificar los datos de consumidores
GET: /api/v4/consumers
Con los mismos datos de autenticación que se emplearon para crear un consumidor, se puede traer los datos utilizando el método GET sobre la URL https://sandbox.bunkerdb.com/api/v4/consumers/ConsumerID
De esta forma, puedes verificar los datos ingresados para un consumidor.
Sandbox
Los desarrolladores deben dirigir la implementación a producción solo una vez que se haya probado exhaustivamente empleando el endpoint de sandbox. Es importante tener en cuenta que la información que se ingresa en sandbox es de prueba, es pública —todos los desarrolladores utilizan el mismo entorno de sandbox— y se elimina cada 48 horas.
Endpoints
Test token:
“120d03c9b55600f2cba445ca2d021364dba504d5”
Probar la integración en entorno de producción
Para testear que la integración de una app con la API v4 de Bunker DB analytics fue exitosa, se puede emplear la dirección [email protected] como registro en el formulario. Si el registro se completó con éxito, se verá en la sección «API token user test» dentro de la pestaña API en la edición de campaña durante una semana.
Las pruebas realizadas en el entorno de producción no afectan la base de datos siempre y cuando se realicen con la dirección [email protected]. En caso de que existan dudas comunicarse con [email protected]
Paso a paso cómo hacer pruebas con la API
Crear un API token para integrar el formulario con Bunker DB analytics.
Sobre el formulario ya integrado, insertar un usuario test con la dirección: [email protected]. El resto de los datos pueden ser aleatorios.
Si el registro fue exitoso, la información de testeo debería verse en la edición de campaña, dentro de la pestaña «API Tokens» en la sección «API token user test».
Para eliminar todos los registros manualmente haz clic en «Vaciar registros».
👉🏽Los datos creados con la dirección [email protected] se guardarán en la instalación durante una semana.