API REST

RT.FAQ-133101

O Eligo oferece uma API de integração REST para permitir sistema externos interagirem com o Eligo.

Introdução

Os serviços disponibilizados via API são semelhantes (muitas as vezes os mesmos) que um usuário tem acessando o sistema de forma interativa. Enquanto as interfaces permitem operações de pesquisa, consulta, inclusão, alteração, exclusão, entre outras através de formulários acessados por uma navegador WEB, a API oferece as mesmas operações para serem realizadas por mensagens entre 2 sistemas.
Todos os blocos de interface do sistema podem ser disponibilizados por API.

Consultas por relatórios customizados

Além dos blocos de interface tradicionais, as informações presentes em relatórios customizados também podem ser disponibilizadas através da API REST. Nestes casos, os dados que seriam normalmente apresentados na tela são disponibilizados em um array de objetos JSON.

Implantação/Configuração

A API REST já vem automaticamente instalada. A única coisa necessária para o seu uso é:

Configurar quais serviços estarão disponíveis.
Disponibilizar as credenciais de acesso a serem utilizadas.
Disponibilizar a documentação dos serviços disponíveis.

Configurar serviços

A configuração de serviços que estarão disponíveis pela API é feita da mesma forma que é feita para o acessos dos usuários. Sugere-se criar uma função específica para acesso por API. Se existirem diferentes parceiros que acessam o sistema através de API para contextos diferentes, sugere-se ter uma função para cada tipo de integração. Exemplo: API_FINANCEIRO, API_COMERCIAL, etc.

Disponibilizar credenciais

As credenciais são um usuário normal do sistema, que terá acesso apenas à função criada acima.
Ao cadastrar este usuário, remova a função "TODOS_USUARIOS" (se houver) e inclua a função cadastrada com os serviços desejados.
Em seguida cadastre um token de acesso através da interface Tokens de acesso.

Disponibilizar a documentação

Para que o parceiro consiga integrar, ele terá de receber uma documentação técnica sobre os serviços disponíveis para ele. Essa documentação pode ser gerada a partir da interface Documentação API (REST).

Uso

O controller REST suporta o acesso às seguintes operações dos blocos do sistema:

Relação operações x método REST

Operações suportadas:

Operação	Método	URI	Observações
CUSTOM	PUT	/feature?query	Ver funcionamento em tópico abaixo
CUSTOM_ACTION	POST	/feature	Ver funcionamento em tópico abaixo
DELETE	DELETE	/id	Exclui o registro do ID informado
DELETE_ALL	DELETE	/?query	Exclui todos os registros conforme filtro indicado
INSERT	POST	/	Cria um novo registro
LIST	GET	/?query	Retorna ARRAY com todos os registros atendidos pela query
QUERY	-	-	Usada através das operações de LIST, CUSTOM e DELETE_ALL
RECORD_ACTION	POST	/id/feature	Executa a record action em um registro
UPDATE	PUT	/id	Altera um registro
VIEW	GET	/id	Retorna os dados de um registro

Operações não suportadas:

Operação	Método	URI
CALENDAR	-	-
CHART	-	-
EXPORT	-	-
IMPORT	-	-
LABEL	-	-
PIVOT_TABLE	-	-
REPORT	-	-
ROLE	-	-
SEARCH	-	-
SHEET	-	-
UPDATE_ALL	-	-
UPGRADE	-	-

Convenção

id: ID do registro em questão
feature: Nome da feature (RECORD_ACTION, CUSTOM ou CUSTOM_ACTION)
query: Parâmetros de query, incluindo query-operators com sintaxe própria
parms: Outros parâmetros

query

Nas operações que utilizam filtros (LIST, DELETE_ALL e CUSTOM), os parâmetros devem ser informados na URL (após o caracter "?") separados por "&". Para o uso de operadores de query diferentes da simples igualdade, deve-se informar o operador entre colchetes antes do "=". Quando o filtro utiliza mais de um valor, estes deverão ser separados por ";".
Exemplos:

nome=ABC
data[between]=2018-01-01;2018-12-31
data[gt]=2018-01-01
estabelecimento[in]=MATRIZ;FILIAL1;FILIAL2
estabelecimento[notin]=MATRIZ;FILIAL1;FILIAL2

parâmetros de contexto

Parâmetros de contexto do bloco deverão ser informados pré-fixados de "P_" e informados com letras maiúsculas. Exemplo:

GET /itensPedido?P_PEDIDO_ID=23989832

Respostas

JSON contendo as informações.
Nome dos campos em lowercase separados por "_".
Campos com valor nulo não são simplesmente omitidos no JSON.

Erros

Códigos HTTP e JSON com mensagem.

CUSTOM

POST /feature?parms

Apenas executa a operação.
Se a ela tiver formulário, então retorna os dados contidos nele.

CUSTOM_ACTION

POST /feature?parms

Executa a operação.
Quando a mesma tiver formulário, o mesmo deverá ser enviado no corpo do POST.