API REST

RT.RQ-001

Descrição

O acesso ao sistema pode ser realizado através de sua API REST de alto nível.
Este documento descreve os procedimentos necessários para preparar o ambiente para realizar os acessos através de sua API REST.

Fluxo normal

Introdução

A API REST permite a integração do sistema ELIGO com outros sistemas permitindo permitindo que as operações realizadas normalmente através de interfaces Web sejam também acessíveis através de web-services.

Estes serviços são disponibilizados com o estilo arquitetural REST, e fornecem interoperabilidade entre sistemas de computadores na Internet através de mensagens JSON.

Os serviços que são disponibilizados são as operações das interfaces assim como as interfaces tradicionais que são disponibilizadas para usuários humanos. Na verdade, a API pode disponibilizar exatamente as mesmas operações que são realizadas por usuários humanos. A única diferença é que a interface Web é substituída por um protocolo de comunicação.

Requisições

Para cada objeto disponível na API, o modelo de requisições seguem o seguinte padrão:

Criar um novo objeto

POST .../objeto

Consultar um objeto específico

GET .../objeto/{id}

Excluir um objeto específico

DELETE .../objeto/{id}

Listar objetos

GET .../objeto?ofsset=0&limit=100&q=expressao

Alterar um objeto

PUT .../objeto/{id}

Disparar uma ação específica em um objeto. As ações variam de objeto para objeto e são normalmente definidas como verbos específicos como cancelar, emitir, renovar, etc.

POST .../objeto/{id}/{acao}

Respostas

200 - Sucesso
201 - Criado (na inclusão de um registro)
204 - Sem conteúdo
400 - Indica que o objeto informado não existe.
401 - Sem autorização ou autorização inválida.
403 - Acesso negado
404 - Registro informado não existe

Todas as respostas com erro também são acompanhadas por um JSON contendo um atributo "error" com uma mensagem auxiliar.

Exemplo:

{
   "status": "404"
   "message": "Não foi encontrado um registro com ID = 4454955700 na entidade CONTRATO.CONTRATOS_SERVICOS",
}

Autenticação

Cada sistema que acessar o ELIGO deverá ter um usuário específico para uso pela API. O cadastramento deste usuário é realizado pela interface Usuários, exatamente igual ao realizado para usuários humanos.

Da mesma forma com que é realizado para usuários humanos, o cadastramento deste usuário também irá definir quais operações de quais interfaces (recursos) estarão disponíveis para este usuário.

Como já é de conhecimento, a relação destes recursos é definida através de funções Funções de usuários. Sugere-se criar uma função específica para grupos de usuários que devem ter determinados recursos disponíveis.

A método de autenticação dos serviços utiliza o modelo "Bearer" onde o token será obtido através de um processo de login. De posse deste login, os acessos deverão conter o header abaixo:

Authorization: Bearer <token>

Para obter este token, deve-se gerar 1 pela interface Tokens de acesso

Convenções

Todos os atributos de data devem ser informados no formato YYYY-MM-DD.

Todos os atributos de valor que precisam ser informados com casas decimais devem ser informados com o "." (ponto) como separador decimal e sem uso de separador de milhar.

Pessoas

Métodos disponíveis:

/POST .../pessoas
/GET .../pessoas/{id}
/PUT .../pessoas/{id}

Atributos

[fields:PESSOA.WS_PESSOAS.INSERT]

Contratos usuários

Métodos disponíveis:

/POST .../contratos_usuarios - Cria um novo contrato
/GET .../contratos_usuarios/{id} - Consulta um contrato
/POST .../contratos_usuarios/{id}/cancelar - Cancela um contrato

Atributos

[fields:SGPRC_USUARIO.WS_CONTRATOS_USUARIOS.INSERT]