API – Hi Timeline


API do Hi Timeline

## Versão 1.0 ##

Endereços base

Antes de começar

O que é um sistema origem?

Entende-se por sistema origem qualquer sistema que detenha o dado original que está sendo enviado para o Hi Timeline. Exemplos:

  • Sistemas ERP
  • Sistemas CRM
  • Plataformas de comércio eletrônico
  • etc…

O que é um evento?

Um evento é uma ação vinculada a um consumidor que deve aparecer na linha do tempo que descreve sua jornada de relacionado junto à empresa que utiliza o Hi Timeline. Exemplos:

  • Uma compra feita pelo consumidor, cuja origem é o sistema ERP da empresa.
  • Uma tentativa mal sucedida de realizar uma operação na página para comprar um produto.
  • Uma opção de configuração feita pelo consumidor feita no aplicativo, cuja origem é o backend que suporta ao aplicativo.
  • Um atendimento do Hi Chat (suportado implicitamente pela plataforma da Hi Platform)
  • Um atendimento do Hi Bot (suportado implicitamente pela plataforma da Hi Platform)
  • Outros eventos do consumidor na plataforma da Hi Platform
  • etc…

Como é composto um evento?

Um evento é composto por duas partes:

  • Meta documento
  • Documento do sistema origem

O meta documento descreve, de forma abstrata, “o que é” e “como deve ser localizável” um evento do sistema origem no Hi Timeline.

A maioria destes dados não tem semântica para o Hi Timeline e estão 100% relacionados ao sistema origem. O que o Hi Timeline faz é utilizar estas informações para tornar o evento localizável.

O documento do sistema origem é exatamente o conteúdo que o sistema origem deseja que seja tratado durante a renderização para os usuários do Hi Timeline. O Hi Timeline não faz qualquer tipo de validação no conteúdo desta informação.

Comportamentos importantes para integradores

  • O Hi Timeline sempre recebe o documento inteiro, mesmo durante as alterações.
  • Alguns processamentos ocorrem de forma assíncrona. Ou seja, o evento pode não estar disponível para os usuários da plataforma logo após seu envio.

Tipos de eventos

Antes de iniciar o envio de eventos para o Hi Timeline, o cliente deve habilitar seu tipo de evento de evento junto à Hi Platform.

Um tipo de evento é vinculado a um cliente (e somente a um) e define “o que” será enviado ao Hi Timeline e “como” o Hi Timeline deve renderizar.

Autenticação/Autorização

A Hi Platform irá fornecer um usuário e uma senha de acesso exclusivo
para o uso da API. A autenticação da API será feita utilizando o protocolo Basic.

Vamos descrever brevemente o como autenticar usando o protocolo Basic.

Considere hipoteticamente que o usuário da API passado é usuarioApi e a senha é senhaApi.

Primeiro, calcule um token da seguinte forma:

  • Concatene o usuario e a senha separado por :. No nosso exemplo usuarioApi:senhaApi;
  • Codifique o resultado acima utilizando o formato Base64. No nosso exemplo o exemplo o resultado (token) dessa operação é dXN1YXJpb0FwaTpzZW5oYUFwaQ==.

O token deve ser passado em todas as requisições através do header HTTP Authorization. O valor do header é a junção do esquema de autenticação (no caso Basic) com o token previamente enviado, separados por um espaço em branco. Exemplo:

Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==

Caso o token de autenticação seja inválido, o acesso será negado e um status code HTTP 401 (Unauthorized) será devolvido. Caso, tente acessar com um usuário e senha válidos da DirectTalk, mas que não seja um usuário da API o acesso será negado e um status code HTTP 403 (Forbidden) será devolvido.

Cotas de consumo

O cliente que usar essa API estará sujeito a um limite na quantidade de requisições que poderá enviar em um dado período de tempo. Essa prática é conhecida como Rate Limiting e é fundamental para garantir a qualidade do serviço.

A cada ‘X’ minutos (variável conforme a operação solicitada) o cliente tem direito a fazer um determinado número de requisições (também variável conforme a operação solicitada). Passado o tempo especificado, o limite é reiniciado.

O consumo do limite pode variar conforme a operação solicitada e será acompanhado pelos seguintes http headers:

  • X-Rate-Limit-Limit: informa o total de requisições permitidas dentro de uma janela de X minutos.
  • X-Rate-Limit-Remaining: informa quantas requisições para API ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição for feita após esse valor retornar 0, a API retornará o HTTP status code 429 (Too many connections.).
  • X-Rate-Limit-Reset: devolve o número de segundos disponíveis na janela atual.

Tratamento de datas ao enviar eventos

Eventos do Hi Timeline possuem datas que são utilizados pelo próprio Hi Timeline, além de datas com significado para o sistema origem. As primeiras são enviadas através de metadados para e não possuem nenhuma semântica para o Timeline, enquanto as últimas estão no documento do evento e tem semântica bem definida para o sistema origem. Portanto, esses dois tipos de data terão tratamento diferenciado pelo Hi Timeline.

Datas do meta documento

Estas datas devem ser enviadas no formato ISO8061.

Datas no evento do sistema origem

O Hi Timeline não realiza nenhum tratamento para datas no documento do evento do sistema origem. Eventualmente, o template pode fazer uso de funções do Hi Timeline, que devem ser implementadas conforme a necessidade, para realizar conversões de datas.

Tipos de dados suportados para identificação de consumidores

O Hi Timeline suporta os seguintes tipos de dados para identificação de consumidores:

  • CPF
  • CNPJ
  • Email
  • Telephone
  • Integer
  • Text
  • RG

Tipos de dados suportados para atributos de consumidores

O Hi Timeline suporta os seguintes tipos de dados para atributos de consumidores:

  • Cpf
  • Cnpj
  • Email
  • Telephone
  • Integer
  • Text
  • Name
  • Date
  • DateTime
  • Bool
  • Rg

[OPERAÇÃO] Publicar/alterar um evento

Parâmetros de rate limiting

  • Limite de requisições: 60
  • Janela de tempo: 10 minutos

Corpo da requisição

{
  "baseVersion": "",  
  "eventTypeName": "",
  "eventTypeVersion": "",
  "originId": "",
  "originGeneratedDate": "",
  "originTokens": [
    "string"
  ],
  "originDates": [
    {
      "key": "string",
      "value": ""
    }
  ],
  "originData": [
    {
      "key": "",
      "value": ""
    }
  ],
  "customerIdentifications": [
    {
      "key": "",
      "value": "",
      "type": ""
    }
  ],
  "customerAttributes": [
    {
      "key": "",
      "value": "",
      "type": ""
    }
  ],
  "customerLocation": {
    "latitude": 0,
    "longitude": 0
  },
  "root": {
    "originId": "",
    "eventTypeName": ""
  },
  "document": {}
}
  • baseVersion: Versão base do documento no Hi Timeline em que o envio está sendo baseado.
  • eventTypeName: Tipo do evento conforme o que foi habilitado junto à Hi Platform.
  • eventTypeVersion: Versão do tipo do evento conforme o que foi habilitado junto à Hi Platform.
  • root: Informações do evento que deu origem ao evento que está sendo enviado.
  • originId: Identificação do evento no sistema origem.
  • originGeneratedDate: Data de geração do evento no sistema origem.
  • originDates: Lista de chave e valor com informações de datas no sistema origem, como data de abertura, data de fechamento, data de envio, data da resposta, etc…
  • originData: Lista de chave e valor com informações do evento no sistema origem, como “prioridade=sim”, “departamento=876”, “grupo=Todos”, etc…
  • originTokens: array de strings que possam ser utilizadas na busca do Hi Timeline para encontrar o evento do sistema origem.
  • customerIdentifications: Identificações do consumidor.
  • customerAttributes: Atributos do consumidor.
  • customerLocation: Localização do consumidor.
  • document: Documento origem propriamente dito.

Corpo da resposta

200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
    "status": "",
    "data": {
        "id": ""
    },
    "errors":[""]
}
  • status: Há três tipos de status possíveis:
    • OK: A requisição foi recebida com sucesso pelo Hi Timeline.
    • NOTVALID: A requisição foi recebida pelo Hi Timeline, mas não passou na etapa de validação. Os detalhes da validação estarão na lista errors.
    • ERROR: Um erro não esperado ocorreu durante a requisição.
  • id: Id do evento no Hi Timeline.
  • errors: Lista com erros sempre que o status não for OK“.

HTTP Status Code

  • 200: A requisição foi recebida pelo Hi Timeline. Importante: HTTP Status Code 200 NÃO significa que o evento foi armazenado no Hi Timeline com sucesso. Para certificar-se disso, o sistema origem deve verificar o conteúdo da propriedade status.
  • 401: A requisição foi negada devido autenticação.
  • 429: A requisição foi negada devido controle de rate limiting.
  • 500: Um erro não esperado ocorreu durante a requisição.

[OPERAÇÃO] Recuperar a versão de um evento

Parâmetros de rate limiting

  • Limite de requisições: 60
  • Janela de tempo: 10 minutos

Corpo da resposta

"status": "",
"data":
{
  "baseVersion": "string"
}
  • status: Há três tipos de status possíveis:
    • OK: A requisição foi recebida com sucesso pelo Hi Timeline.
    • NOTVALID: A requisição foi recebida pelo Hi Timeline, mas não passou na etapa de validação. Os detalhes da validação estarão na lista errors.
    • ERROR: Um erro não esperado ocorreu durante a requisição.
  • baseVersion: versão atual do evento no Hi Timeline.

HTTP Status Code

  • 200: A requisição foi recebida pelo Hi Timeline.
  • 401: A requisição foi negada devido autenticação.
  • 429: A requisição foi negada devido controle de rate limiting.
  • 500: Um erro não esperado ocorreu durante a requisição.

[OPERAÇÃO] Recuperar o conteúdo de um evento

Parâmetros de rate limiting

  • Limite de requisições: 60
  • Janela de tempo: 10 minutos

Corpo da resposta

"status": "",
"data":
{
  "baseVersion": "",  
  "eventTypeName": "",
  "eventTypeVersion": "",
  "originId": "",
  "originGeneratedDate": "",
  "originTokens": [
    "string"
  ],
  "originDates": [
    {
      "key": "string",
      "value": ""
    }
  ],
  "originData": [
    {
      "key": "",
      "value": ""
    }
  ],
  "customerIdentifications": [
    {
      "key": "",
      "value": "",
      "type": ""
    }
  ],
  "customerAttributes": [
    {
      "key": "",
      "value": "",
      "type": ""
    }
  ],
  "customerLocation": {
    "latitude": 0,
    "longitude": 0
  },
  "root": {
    "originId": "",
    "eventTypeName": ""
  },
  "document": {}
}
  • status: Há três tipos de status possíveis:
    • OK: A requisição foi recebida com sucesso pelo Hi Timeline.
    • NOTVALID: A requisição foi recebida pelo Hi Timeline, mas não passou na etapa de validação. Os detalhes da validação estarão na lista errors.
    • ERROR: Um erro não esperado ocorreu durante a requisição.

HTTP Status Code

  • 200: A requisição foi recebida pelo Hi Timeline.
  • 401: A requisição foi negada devido autenticação.
  • 429: A requisição foi negada devido controle de rate limiting.
  • 500: Um erro não esperado ocorreu durante a requisição.