API – Hi Timeline

10 Minutes to read

Print
Dark
Light
PDF

API – Hi Timeline

10 Minutes to read

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

# API do Hi Timeline

## Versão 1.0

Endereços base

URL de produção: https://history-api.hiplatform.com/1.0/api/

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

Publicar/alterar um evento

URL: https://history-api.hiplatform.com/1.0/api/event
Objetivo: Publicar eventos no Hi Timeline.
Método HTTP: POST

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.

Recuperar a versão de um evento

URL: https://history-api.hiplatform.com/1.0/api/event/metadata/baseversion?eventTypeName=abc&originId=123
Objetivo: Recuperar a versão de um evento no Hi Timeline com base em sua identificação no sistema origem.
Método HTTP: GET

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.

Recuperar o conteúdo de um evento

URL: https://history-api.hiplatform.com/1.0/api/event?eventTypeName=abc&originId=123
Objetivo: Recuperar o conteúdo de um evento no Hi Timeline com base em sua identificação no sistema origem.
Método HTTP: GET

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.

---

Publicar um evento de consumidor

URL: https://history-api.hiplatform.com/1.0/api/customer/event
Objetivo: Publicar eventos de consumidor no Hi Timeline.
Método HTTP: POST

Parâmetros de rate limiting

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

Corpo da requisição

```javascript

{

  "customerIdentifications": [

    {

      "key": "",

      "value": "",

      "type": ""

    }

  ],

  "customerAttributes": [

    {

      "key": "",

      "value": "",

      "type": ""

    }

  ]

}

```

customerIdentifications: Identificações do consumidor.
customerAttributes: Atributos do consumidor.

Corpo da resposta

```javascript

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. *

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.

* 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.

Pesquisa Informações na TimeLine (endpoint externo)

URL: https://history-api.hiplatform.com/1.0/api/search/List
Objetivo: Permitir a pesquisa de informações na TimeLine através de um Endpoint com limitação configurável do retorno de linhas além da limitação com Rate Limiting para ser liberado ao Cliente Externo.
Método HTTP: POST

Parâmetros de rate limiting

Limite de requisições: 30
Janela de tempo: 10 minutos
Configuração do limite de retorno (hits): 500

Corpo da requisição

'''
{
    "Start": 0,
    "Size": 5666,
    "Filter": null,
    "Query": {
        "Key": "telefone",
        "Field": "customeridentification",
        "Operator": "eq",
        "Value": "5519993487857"
    },
    "SortFields": [
        {
            "field": "createdat",
            "direction": "Asc"
        }
    ],
    "Return": "All"
}
'''

Start: Especifica o deslocamento do primeiro registro de pesquisa que você deseja retornar. Observe que o conjunto de resultados é baseado em zero. O primeiro valor é o índice 0
Size: Especifica o número máximo de registros para incluir na reposta da pesquisa.
Filter: Especifica uma consulta estruturada que filtra os resultados de uma pesquisa sem afetar como os resultados são pontuados e classificados
Query: Especifica os critérios de pesquisa da solicitação. A maneira como você especifica os critérios de pesquisa depende do analisador de consulta usado para a solicitação e das opções do analisador especificadas nos parâmetros.
- Key: Chave para pesquisa.
- Field: Pode ter as opções :
  - originDate: 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…
  - customerIdentifications: Identificações do consumidor.
  - customerAttributes: Atributos do consumidor
  - customerLocation: Localização do consumidor
  - root: Informações do evento que deu origem ao evento que está sendo enviado.
- Operator: Tipos definidos para orientaro criterio de comparação:
  - eq: Igual a.
  - ne: Diferente de.
  - ge: Maior igual que.
  - le: Menor igual que.
  - between: Entre.
  - containsAll: Contém.
  - containsAny: Contém em qualquer parte.
  - startsWith: Inicia com.
  - and: E
  - or: ou
  - not: Negado
- Value: Valor a ser pesquisado.
SortFields:
- field: Campo especificado para ordenação.
- direction: Asc (Ascendente) ou Des (Descendente).
  - id: Ordenação por Id.
  - createdat: Ordenação por data de criação.
  - updatedat: Ordenação por data de atualização.
  - origingenerateddate: Ordenação por data de origem.
  - relevance: Ordenação por relevância.
Return: Tipo de retorno - Opções podem ser definidas
- Id: Somente Ids.
- Summary: Em resumo.
- All: Toda a informação do history.
- Erros: Somente erros.

Corpo da resposta

'''
{
    "status": "NOTVALID",
    "data": {},
    "errors": [
        "Search request Size is not valid ==> 9999."
    ]
}
'''

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

Artigos relacionados:

Gestão de usuários de API

Was this article helpful?

What's Next

API Chat (v1.0) – Status do atendimento

Table of contents

## Versão 1.0
O que é um sistema origem?
O que é um evento?
Como é composto um evento?
Tipos de eventos
Publicar/alterar um evento
Recuperar a versão de um evento
Recuperar o conteúdo de um evento
Publicar um evento de consumidor
Pesquisa Informações na TimeLine (endpoint externo)