API consumidores v4

Article author
Bunker DB Support
  • Actualización

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. Posteriormente, 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.

 

Paso a paso – cómo crear un API token

  1. Haz clic en la pestaña Campañas.
  2. Selecciona la campaña y ve a «Edición de campaña».



  3. Dentro de las opciones, selecciona «API Tokens».


    Solo los usuarios con rol Superuser o los usuarios con permiso para administrar API tokens pueden acceder al módulo «API Tokens».

  4. Haz clic en «Crear API token».
  5. La plataforma solicitará que ingreses nuevamente la contraseña de usuario (la misma que empleas para acceder a la plataforma) para ingresar al modo Sudo.



  6. Agrega una breve descripción para el token.

Luego de generado, el token se muestra en la tabla de tokens 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.

 



 

El correcto y seguro manejo de los tokens es total responsabilidad del usuario que los genera. Bunker DB analytics no se hace responsable por el manejo inseguro de estas credenciales de acceso.



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.

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.


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.

 

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 caracter 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, se describen 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

Este método recibe el mismo json que las versión 2 de la API, excepto por el id de campaña, que ya no es necesario gracias al token.

 

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.
    • Driver: 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.

 


 

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:

  • Si/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?


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.

 

 

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, se podrán 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

https://sandbox.bunkerdb.com/api/v4/preferences

https://sandbox.bunkerdb.com/api/v4/consumers

 

Ejemplo de formato de API 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 testapi@bunkerdb.com 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 generan alteración sobre el negocio ni la base de datos siempre y cuando se realicen con la dirección testapi@bunkerdb.com. En caso de que existan dudas comunicarse con support@bunkerdb.com.

 

Paso a paso — cómo hacer pruebas con la API

  1. Crear un API token para integrar el formulario con Bunker DB analytics.
  2. Sobre el formulario ya integrado, insertar un usuario test con la dirección: testapi@bunkerdb.com. El resto de los datos pueden ser aleatorios.
  3. 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».

  • Los datos creados con la dirección testapi@bunkerdb.com se guardarán en la instalación durante una semana.
  1. Para eliminar todos los registros manualmente, haz clic en «Vaciar registros».

 

 

 

 

Solo los usuarios con rol Superuser o los usuarios con permiso para administrar API tokens pueden acceder al módulo «API Tokens».

¿Fue útil este artículo?

¿Tiene más preguntas? Enviar una solicitud