API de Clientes: Cómo Utilizar y Configurar

Esta API (sigla en inglés de Interfaz de Programación de Aplicaciones) permite la integración entre sus aplicaciones con la administración de clientes de Atom. Esta API permite:

Crear o Actualizar un cliente.
Obtener un listado de clientes.
Ver datos de un cliente a través de su ID.
Ver datos de un cliente a través de su número de teléfono

Endpoint: Create client - Crear/Actualizar Cliente

Este servicio permite la creación o actualización de un cliente en Atom.

Parámetros

A continuación describimos los parámetros que se deben incluir dentro de la petición de manera obligatoria, y otros que se pueden agregar opcionalmente:

Nombre del Parámetro	Descripción	Tipo de Dato	Requerido
firstName	Nombre del cliente	string	Sí
lastName	Apellido del cliente	string	Sí
phone	Número telefónico del cliente. Se debe anteponer el código del país, sin utilizar el signo + Correcto: 50755667788 ✅ Incorrecto: +50555667788 ❌ Incorrecto: 55667788 ❌	string	Sí
email	Email del cliente	string	Opcional.
optionals	Parámetros adicionales para hacer el mapeo de los campos de información asociados al cliente, los valores se escriben a modo de {key: value}	object	Si
tags	Etiquetas para el cliente	string	Opcional.

La petición para realizar la creación de un cliente utilizando la API de AtomChat, se realiza de la siguiente manera:

Tipo de Conexión	Acceso público por Internet
Endpoint	https://us-central1-atomchat-io.cloudfunctions.net/clients
Método	POST
Encabezados	Content-type: application/json Charset: utf-8 Authorization: Bearer (token público)
Cuerpo	{ "firstName": "nombre_del_cliente", "lastName": apellido_del_cliente", "phone": "numero_de_telefono", "email": "email_del_cliente", "optionals": { "option1": "valor", "option2": "valor ", … }, "tags": ["tag 1", "tag2"] }

Respuestas

Las respuestas esperadas para la petición realizada, son las siguientes:

Escenario	Código de Respuesta	Cuerpo de la Respuesta
Cliente nuevo	200	{ "client":"clientID" }
Token incorrecto	400	{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" }
No se pudo crear el cliente	500	{ message: "Cannot perform the creation of the client at ${new Date()}" }
No se pudo actualizar el cliente	500	{ message: "Cannot perform the update of the client" }
No se pudo actualizar el cliente	500	{ message: "Cannot perform the update of the client at ${new Date()}" }

Endpoint: Client list - Obtener listado de clientes

Este servicio permite obtener un listado de todos los clientes.

Parámetros

A continuación explicamos los parámetros que se deben incluir dentro de la petición de manera obligatoria, y otros que se pueden agregar opcionalmente

Nombre del Parámetro	Descripción	Tipo de Dato	Requerido
page	Indicador de la página sobre la cual se desea obtener los registros. Default: 1	string	NO. Por defecto 1
size	Cantidad de registros a recuperar. Default: 10	string	NO. Por defecto 10
tags	Etiquetas para filtrar, opcionales	string	NO
sort	Orden de los resultados. Valores aceptados: asc \| desc. Default: asc	string	NO

La petición para realizar la recepción de listado de clientes utilizando la API de AtomChat, se realiza de la siguiente manera:

Tipo de Conexión	Acceso público por Internet
Endpoint	https://us-central1-atomchat-io.cloudfunctions.net/clients?page={string}&size={string}&sort={string}
Método	GET
Encabezados	Content-type: application/json Charset: utf-8 Authorization: Bearer (token público)

Respuestas

Las respuestas esperadas para la petición realizada, son las siguientes:

Escenario	Código de Respuesta	Cuerpo de la Respuesta
Listar clientes	200	{ length: int, page: int, items: [ { id: string, firstName: string, lastName:string, email: string, optionals: [clave: valor] phone: string, tags: [], user: { id: string, name: string }, updatedAt: Date, createdAt: Date }, ] }
No hay lista de clientes	500	{ message: "Something went wrong while the operation was being performed" }
Token incorrecto	400	{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" }

Ejemplo de estructura

JSON

{
    "page": 1,
    "length": 1,
    "items": [
        {
            "id": "V2EON8A6SPwC2VudgFbp",
            "firstName": "Silvio Nicole",
            "lastName": "Carballo",
            "email": null,
            "optionals": {
                "texto 3": "Excelente",
                "texto 1": "¡Excelente!",
                "texto 9": "Hola",
                "texto 8": "1",
                "dos": "¡Excelente! 🤩 ",
                "nuevo4": "martillo",
                "Monto": "21",
                "Referido1": "123123",
                "texto 5": "asesor",
                "texto 2": "asesor",
                "referido2": "Silvio"
            },
            "phone": "50588541975",
            "tags": [
                null,
                "test-label-2sss",
                null
            ],
            "user": {
                "id": "qa-sinsa-ni-qchsjn",
                "name": "Develop - Sinsa QA"
            },
            "updatedAt": "2022-04-22T13:26:31.139Z",
            "createdAt": "2022-08-15T22:18:05.683Z"
        }
    ]
}

Endpoint: Get Client by ID - Ver datos de un cliente

Este servicio permite obtener los detalles pertenecientes a un cliente en particular a través de su ID.

La petición para realizar la recepción de los datos de un cliente utilizando la API de AtomChat, se realiza de la siguiente manera:

Tipo de Conexión	Acceso público por Internet
Endpoint	https://us-central1-atomchat-io.cloudfunctions.net/clients?id={clientId}
Método	GET
Encabezados	Content-type: application/json Charset: utf-8 Authorization: Bearer (token público)

Respuestas

Las respuestas esperadas para la petición realizada, son las siguientes:

Escenario	Código de Respuesta	Cuerpo de la Respuesta
Cliente recuperado	200	{ id: string, firstName: string, lastName: string, email: string, optionals: [clave: valor] phone: string, tags: [], user: { id: string, name: string }, updatedAt: Date, createdAt: Date },
Cliente inexistente	404	{ message: "Cannot find the client - companyId ${companyId} - phone ${phone}" }
Token incorrecto	400	{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" }
Error genérico	500	{ message: "Something went wrong while the operation was being performed }

Ejemplo de estructura

JSON

{
    "id": "V2EON8A6SPwC2VudgFbp",
    "firstName": "Silvio Nicole",
    "lastName": "Carballo",
    "email": null,
    "optionals": {
        "texto 1": "¡Excelente!",
        "texto 9": "Hola",
        "Monto": "21",
        "texto 5": "asesor",
        "texto 3": "Excelente",
        "Referido1": "123123",
        "nuevo4": "martillo",
        "dos": "¡Excelente! 🤩 ",
        "referido2": "Silvio",
        "texto 8": "1",
        "texto 2": "asesor"
    },
    "phone": "50588541975",
    "tags": [
        null,
        "test-label-2sss",
        null
    ],
    "user": {
        "id": "qa-sinsa-ni-qchsjn",
        "name": "Develop - Sinsa QA"
    },
    "updatedAt": "2022-04-22T13:26:31.139Z",
    "createdAt": "2022-08-15T22:18:05.683Z"
}

Endpoint: Get Client by Phone - Ver datos de un cliente

Este servicio permite obtener los detalles pertenecientes a un cliente en particular a través de su número de teléfono.

La petición para realizar la recepción de los datos de un cliente utilizando la API de AtomChat, se realiza de la siguiente manera:

Tipo de Conexión	Acceso público por Internet
Endpoint	https://us-central1-atomchat-io.cloudfunctions.net/clients?phone={phoneNumber}
Método	GET
Encabezados	Content-type: application/json Charset: utf-8 Authorization: Bearer (token público)

Respuestas

Las respuestas esperadas para la petición realizada, son las siguientes:

Escenario	Código de Respuesta	Cuerpo de la Respuesta
Cliente recuperado	200	{ id: string, firstName: string, lastName: string, email: string, optionals: [clave: valor] phone: string, tags: [], user: { id: string, name: string }, updatedAt: Date, createdAt: Date },
Cliente inexistente	404	{ message: "Cannot find the client - companyId ${companyId} - phone ${phone}" }
Token incorrecto	400	{ "context": { "key": "Authorization", "label": "headers.authorization", "value": Bearer }, "message": "Cannot find a channel associated with the public token Bearer", "path": [ "headers.authorization" ], "type": "Bad format" }
Error genérico	500	{ message: "Something went wrong while the operation was being performed }

Ejemplo de estructura

JSON

{
    "id": "V2EON8A6SPwC2VudgFbp",
    "firstName": "Silvio Nicole",
    "lastName": "Carballo",
    "email": null,
    "optionals": {
        "texto 1": "¡Excelente!",
        "texto 9": "Hola",
        "Monto": "21",
        "texto 5": "asesor",
        "texto 3": "Excelente",
        "Referido1": "123123",
        "nuevo4": "martillo",
        "dos": "¡Excelente! 🤩 ",
        "referido2": "Silvio",
        "texto 8": "1",
        "texto 2": "asesor"
    },
    "phone": "50588541975",
    "tags": [
        null,
        "test-label-2sss",
        null
    ],
    "user": {
        "id": "qa-sinsa-ni-qchsjn",
        "name": "Develop - Sinsa QA"
    },
    "updatedAt": "2022-04-22T13:26:31.139Z",
    "createdAt": "2022-08-15T22:18:05.683Z"
}

¡Conecta tus sistemas como un experto! 🚀

Con la API de Clientes, tienes el poder de sincronizar la información de tu base de datos en tiempo real entre Atom y tus plataformas internas. Asegúrate de configurar correctamente tus tokens y parámetros, y lleva la gestión de tus contactos al siguiente nivel. ✅