API de Clientes: Como Utilizar e Configurar

Esta API (sigla em inglês de Application Programming Interface) permite a integração entre suas aplicações e a administração de clientes da Atom. Esta API permite:

Criar ou atualizar um cliente
Obter uma lista de clientes
Visualizar os dados de um cliente por meio do seu ID
Visualizar os dados de um cliente por meio do seu número de telefone

Endpoint: Create Client – Criar / Atualizar Cliente

Este serviço permite a criação ou atualização de um cliente na Atom.

Parâmetros

A seguir descrevemos os parâmetros que devem ser incluídos obrigatoriamente na requisição, e outros que podem ser adicionados opcionalmente:

Nome do Parâmetro	Descrição	Tipo de Dado	Obrigatório
firstName	Nome do cliente	string	Sim
lastName	Sobrenome do cliente	string	Sim
phone	Número de telefone do cliente. Deve ser informado com o código do país, sem utilizar o sinal +
Correto: 50755667788 ✅
Incorreto: +50555667788 ❌
Incorreto: 55667788 ❌	string	Sim
email	E-mail do cliente	string	Opcional
optionals	Parâmetros adicionais para realizar o mapeamento dos campos de informação associados ao cliente. Os valores devem ser enviados no formato `{key: value}`	object	Sim
tags	Etiquetas associadas ao cliente	string	Opcional

A requisição para realizar a criação de um cliente utilizando a API da AtomChat é realizada da seguinte forma:

Tipo de Conexão

Acesso público pela Internet

Endpoint

<https://us-central1-atomchat-io.cloudfunctions.net/clients>

Método

POST

Cabeçalhos

Content-type: application/json
Charset: utf-8
Authorization: Bearer (token público)

Corpo

{
    "firstName": "nome_do_cliente",
    "lastName": "sobrenome_do_cliente",
    "phone": "numero_de_telefone",
    "email": "email_do_cliente",
    "optionals": {
        "option1": "valor",
        "option2": "valor"
    },
    "tags": ["tag 1", "tag 2"]
}

Respostas

Cliente novo

Código: 200

{
  "client": "clientID"
}

Token incorreto

Código: 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"
}

Não foi possível criar o cliente

Código: 500

{
  "message": "Cannot perform the creation of the client at ${new Date()}"
}

Não foi possível atualizar o cliente

Código: 500

{
  "message": "Cannot perform the update of the client"
}

Não foi possível atualizar o cliente

Código: 500

{
  "message": "Cannot perform the update of the client at ${new Date()}"
}

Endpoint: Client List – Obter lista de clientes

Este serviço permite obter uma lista de todos os clientes.

Parâmetros

A seguir explicamos os parâmetros que podem ser incluídos na requisição:

Nome do Parâmetro	Descrição	Tipo de Dado	Obrigatório
page	Indicador da página da qual se deseja obter os registros. Default: 1	string	Não. Padrão: 1
size	Quantidade de registros a recuperar. Default: 10	string	Não. Padrão: 10
tags	Etiquetas para filtragem	string	Não
sort	Ordem dos resultados. Valores aceitos: `asc`	`desc`. Default: asc	string

Endpoint

<https://us-central1-atomchat-io.cloudfunctions.net/clients?page={string}&size={string}&sort={string}>

Método

GET

Cabeçalhos

Content-type: application/json
Charset: utf-8
Authorization: Bearer (token público)

Respostas

Listar clientes

Código: 200

{
  "length": int,
  "page": int,
  "items": [
    {
      "id": string,
      "firstName": string,
      "lastName": string,
      "email": string,
      "optionals": { "key": "value" },
      "phone": string,
      "tags": [],
      "user": {
        "id": string,
        "name": string
      },
      "updatedAt": Date,
      "createdAt": Date
    }
  ]
}

Não há lista de clientes

Código: 500

{
  "message": "Something went wrong while the operation was being performed"
}

Token incorreto

Código: 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"
}

Exemplo de estrutura 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"
      },
      "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 dados de um cliente

Este serviço permite obter os detalhes de um cliente específico por meio do seu ID.

Cliente recuperado

Código: 200

{
  "id": string,
  "firstName": string,
  "lastName": string,
  "email": string,
  "optionals": { "key": "value" },
  "phone": string,
  "tags": [],
  "user": {
    "id": string,
    "name": string
  },
  "updatedAt": Date,
  "createdAt": Date
}

Cliente inexistente

Código: 404

{
  "message": "Cannot find the client - companyId ${companyId} - phone ${phone}"
}

Token incorreto

Código: 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"
}

Erro genérico

Código: 500

{
  "message": "Something went wrong while the operation was being performed"
}

Endpoint: Get Client by Phone – Ver dados de um cliente

Este serviço permite obter os detalhes de um cliente específico por meio do seu número de telefone.

Las respostas, códigos e exemplos JSON são idênticos ao endpoint anterior (Get Client by ID), incluindo:

Cliente recuperado – 200
Cliente inexistente – 404
Token incorreto – 400
Erro genérico – 500