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 |
Nombre del Parámetro
| Descripción |
Descripción
| Tipo de Dato |
Tipo de Dato
| Requerido |
Requerido
| firstName |
firstName
| Nombre del cliente |
Nombre del cliente
| string |
string
| Sí |
Sí
| lastName |
lastName
| Apellido del cliente |
Apellido del cliente
| string |
string
| Sí |
Sí
| phone |
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 ❌ |
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 |
string
| Sí |
Sí
| email |
| Email del cliente |
Email del cliente
| string |
string
| Opcional. |
Opcional.
| optionals |
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} |
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 |
object
| Si |
Si
| tags |
tags
| Etiquetas para el cliente |
Etiquetas para el cliente
| string |
string
| Opcional. |
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 |
Tipo de Conexión
| Acceso público por Internet |
Acceso público por Internet
| Endpoint |
Endpoint
| Método |
Método
| POST |
POST
| Encabezados |
Encabezados
| Content-type: application/jsonCharset: utf-8Authorization: Bearer (token público) |
Content-type: application/json
Charset: utf-8
Authorization: Bearer (token público)
| Cuerpo |
Cuerpo
| {“firstName”: “nombredelcliente”,“lastName”: apellidodelcliente”,“phone”: “numerodetelefono”,“email”: “emaildelcliente”,“optionals”: {“option1”: “valor”,“option2”: “valor”,…},“tags”: [“tag 1”, “tag2”]} |
{
“firstName”: “nombredelcliente”,
“lastName”: apellidodelcliente”,
“phone”: “numerodetelefono”,
“email”: “emaildelcliente”,
“optionals”: {
“option1”: “valor”,
“option2”: “valor”,
…
},
“tags”: [“tag 1”, “tag2”]
}
Respuestas
Las respuestas esperadas para la petición realizada, son las siguientes:
| Escenario |
Escenario
| Código de Respuesta |
Código de Respuesta
| Cuerpo de la Respuesta |
Cuerpo de la Respuesta
| Cliente nuevo |
Cliente nuevo
| 200 |
200
| {"client":"clientID"} |
{
"client":"clientID"
}
| Token incorrecto |
Token incorrecto
| 400 |
400
| {"context": {"key": "Authorization","label": "headers.authorization","value":Bearer},"message": "Cannot find a channel associated with the public tokenBearer","path": ["headers.authorization"],"type": "Bad format"} |
{
"context": {
"key": "Authorization",
"label": "headers.authorization",
"value":Bearer
},
"message": "Cannot find a channel associated with the public tokenBearer",
"path": [
"headers.authorization"
],
"type": "Bad format"
}
| No se pudo crear el cliente |
No se pudo crear el cliente
| 500 |
500
| {message: "Cannot perform the creation of the client at ${new Date()}"} |
{
message: "Cannot perform the creation of the client at ${new Date()}"
}
| No se pudo actualizar el cliente |
No se pudo actualizar el cliente
| 500 |
500
| {message: "Cannot perform the update of the client"} |
{
message: "Cannot perform the update of the client"
}
| No se pudo actualizar el cliente |
No se pudo actualizar el cliente
| 500 |
500
| {message: "Cannot perform the update of the client at ${new Date()}"} |
{
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 |
Nombre del Parámetro
| Descripción |
Descripción
| Tipo de Dato |
Tipo de Dato
| Requerido |
Requerido
| page |
page
| Indicador de la página sobre la cual se desea obtener los registros. Default: 1 |
Indicador de la página sobre la cual se desea obtener los registros. Default: 1
| string |
string
| NO. Por defecto 1 |
NO. Por defecto 1
| size |
size
| Cantidad de registros a recuperar. Default: 10 |
Cantidad de registros a recuperar. Default: 10
| string |
string
| NO. Por defecto 10 |
NO. Por defecto 10
| tags |
tags
| Etiquetas para filtrar, opcionales |
Etiquetas para filtrar, opcionales
| string |
string
| NO |
NO
| sort |
sort
| Orden de los resultados. Valores aceptados: asc | desc. Default: asc |
Orden de los resultados. Valores aceptados: asc | desc. Default: asc
| string |
string
| NO |
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 |
Tipo de Conexión
| Acceso público por Internet |
Acceso público por Internet
| Endpoint |
Endpoint
| https://us-central1-atomchat-io.cloudfunctions.net/clients?page={string}&size={string}&sort={string} |
https://us-central1-atomchat-io.cloudfunctions.net/clients?page={string}&size={string}&sort={string}
| Método |
Método
| GET |
GET
| Encabezados |
Encabezados
| Content-type: application/jsonCharset: utf-8Authorization: Bearer (token público) |
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 |
Escenario
| Código de Respuesta |
Código de Respuesta
| Cuerpo de la Respuesta |
Cuerpo de la Respuesta
| Listar clientes |
Listar clientes
| 200 |
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},]} |
{
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 |
No hay lista de clientes
| 500 |
500
| {message: "Something went wrong while the operation was being performed"} |
{
message: "Something went wrong while the operation was being performed"
}
| Token incorrecto |
Token incorrecto
| 400 |
400
| {"context": {"key": "Authorization","label": "headers.authorization","value":Bearer},"message": "Cannot find a channel associated with the public tokenBearer","path": ["headers.authorization"],"type": "Bad format"} |
{
"context": {
"key": "Authorization",
"label": "headers.authorization",
"value":Bearer
},
"message": "Cannot find a channel associated with the public tokenBearer",
"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 |
Tipo de Conexión
| Acceso público por Internet |
Acceso público por Internet
| Endpoint |
Endpoint
| Método |
Método
| GET |
GET
| Encabezados |
Encabezados
| Content-type: application/jsonCharset: utf-8Authorization: Bearer (token público) |
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 |
Escenario
| Código de Respuesta |
Código de Respuesta
| Cuerpo de la Respuesta |
Cuerpo de la Respuesta
| Cliente recuperado |
Cliente recuperado
| 200 |
200
| {id: string,firstName: string,lastName: string,email: string,optionals: [clave: valor]phone: string,tags: [],user: {id: string,name: string},updatedAt: Date,createdAt: Date}, |
{
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 |
Cliente inexistente
| 404 |
404
| {message: "Cannot find the client - companyId ${companyId} - phone ${phone}"} |
{
message: "Cannot find the client - companyId ${companyId} - phone ${phone}"
}
| Token incorrecto |
Token incorrecto
| 400 |
400
| {"context": {"key": "Authorization","label": "headers.authorization","value":Bearer},"message": "Cannot find a channel associated with the public tokenBearer","path": ["headers.authorization"],"type": "Bad format"} |
{
"context": {
"key": "Authorization",
"label": "headers.authorization",
"value":Bearer
},
"message": "Cannot find a channel associated with the public tokenBearer",
"path": [
"headers.authorization"
],
"type": "Bad format"
}
| Error genérico |
Error genérico
| 500 |
500
| {message: "Something went wrong while the operation was being performed} |
{
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 |
Tipo de Conexión
| Acceso público por Internet |
Acceso público por Internet
| Endpoint |
Endpoint
| Método |
Método
| GET |
GET
| Encabezados |
Encabezados
| Content-type: application/jsonCharset: utf-8Authorization: Bearer (token público) |
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 |
Escenario
| Código de Respuesta |
Código de Respuesta
| Cuerpo de la Respuesta |
Cuerpo de la Respuesta
| Cliente recuperado |
Cliente recuperado
| 200 |
200
| {id: string,firstName: string,lastName: string,email: string,optionals: [clave: valor]phone: string,tags: [],user: {id: string,name: string},updatedAt: Date,createdAt: Date}, |
{
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 |
Cliente inexistente
| 404 |
404
| {message: "Cannot find the client - companyId ${companyId} - phone ${phone}"} |
{
message: "Cannot find the client - companyId ${companyId} - phone ${phone}"
}
| Token incorrecto |
Token incorrecto
| 400 |
400
| {"context": {"key": "Authorization","label": "headers.authorization","value":Bearer},"message": "Cannot find a channel associated with the public tokenBearer","path": ["headers.authorization"],"type": "Bad format"} |
{
"context": {
"key": "Authorization",
"label": "headers.authorization",
"value":Bearer
},
"message": "Cannot find a channel associated with the public tokenBearer",
"path": [
"headers.authorization"
],
"type": "Bad format"
}
| Error genérico |
Error genérico
| 500 |
500
| {message: "Something went wrong while the operation was being performed} |
{
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"
}