API Rest (WEB)

Início » API Rest (WEB)

A API Pública permite que aplicações de terceiros interajam com o Uniplus Web ou Desktop. O processo envolve conectar ao servidor, obter o token de autorização e por fim a comunicação propriamente dita. Este documento detalha cada parte do processo com exemplos.

Os exemplos utilizam o comando curl que é nativo para os sistemas operacionais Linux, OSX. Caso for usar Windows é possível fazer o download na página https://curl.haxx.se/download.html

Obtendo o código de autorização

O acesso seguro aos dados é baseado em código de autorização: cada conta do Uniplus possui um código de autorização único. Garanta que o código de autorização não fique visível e pessoas mal-intencionadas tenham estes acesso a estas informações.

A geração do código de autorização é feita no Uniplus Web no menu Ferramentas/Configuração da API conforme imagem abaixo:

Simplesmente clique no botão para gerar uma nova chave de acesso e não esqueça de gravar. É boa prática renovar o código de autorização regularmente.

Testando as chamadas para a API

As chamadas para a API podem ser facilmente testadas pelo comando curl ou se preferir fique a vontade para converter para outro utilitário como o POSTMAN.
No caso do curl optamos por definir algumas variáveis de ambiente para simplificar os comandos. As variáveis serão identificadas por ${}
Seguindo o exemplo acima:conta=uniplus codigo_de_autorizacao=dW5pcGx1czoxODM1YjQ3Ni1mYzA2LTRhYmItYjk5My00MDE2ZjE0NjFiZjE=

Conectando com o servidor

O Uniplus pode ser instalado em diversos ambientes como Amazon, GetTI, On Premise ou desktop. O servidor pode ser endereçado por IP ou por URL.

Especialmente na Amazon cada instância tem um IP/URL próprio. Então, cada vez que uma nova versão é instanciada um novo IP/URL será gerado.
Neste caso, para garantir sempre o sucesso da conexão é possível fazer uma chamada para o serviço de roteamento do UniplusWeb,
a fim de obter a URL atualizada de uma conta.curl https://server-portal.intelidata.inf.br/roteador/endereco-servidor/${conta}

Conectando com o servidor desktop

Para usar a API no ambiente desktop é necessário que o servidor Yoda esteja configurado e em execução.

Note que neste caso não existe o conceito de contas e por este motivo o código de autorização é fixo:dW5pcGx1czpsNGd0cjFjazJyc3ByM25nY2wzZW50

Um detalhe importante também é o endereço do servidor, que deve ter fixo a porta 8443. Ex: https://localhost:8443

Por último, o servidor Yoda utiliza um certificado auto-assinado (self-signed). Sendo assim, caso for usar o curl para executar os testes é necessário usar a opção -k para que o curl aceite este tipo de certificado.

Obtendo o token de acesso

O Uniplus usa o padrão OAuth2 para autorização de uso de recursos.
Neste padrão em cada acesso remoto é necessário passar um token que irá garantir o acesso aos dados no servidor.
O próprio Uniplus atua como um servidor de autorização.
Use o seguinte comando para gerar o token de acesso, substituindo as variáveis conforme o seu caso:curl -X POST -H “Authorization: Basic ${codigo_de_autorizacao}” -H “Content-Type: application/x-www-form-urlencoded” -d “grant_type=client_credentials&scope=public-api” “${endereco_do_servidor}/oauth/token”

Exemplo de saída gerado no formato JSON:{“access_token”:”eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsidW5pcGx1c3dlYiJdLCJzY29wZSI6WyJwdWJsaWMtYXBpIl0sImV4cCI6MTU5NTg2MTM5MCwianRpIjoiYWIxMDZjYTQtZGVhNy00MGE1LWEzYzQtZDdkZjAyZTU3ZDNhIiwiY2xpZW50X2lkIjoidW5pcGx1cyJ9.DCqIfrNY9rqxFgTEDL7ldjLwNSnD1PX2x96wJqEh4jg”,”token_type”:”bearer”,”expires_in”:3599,”scope”:”public-api”,”jti”:”ab106ca4-dea7-40a5-a3c4-d7df02e57d3a”}

O token de acesso é extraído do valor access_token. No exemplo acima o token de acesso éeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsidW5pcGx1c3dlYiJdLCJzY29wZSI6WyJwdWJsaWMtYXBpIl0sImV4cCI6MTU5NTg2MTM5MCwianRpIjoiYWIxMDZjYTQtZGVhNy00MGE1LWEzYzQtZDdkZjAyZTU3ZDNhIiwiY2xpZW50X2lkIjoidW5pcGx1cyJ9.DCqIfrNY9rqxFgTEDL7ldjLwNSnD1PX2x96wJqEh4jg

O token de acesso tem validade de 60 minutos. Após este período será necessário gerar novamente o token.
Sugerimos adotar uma das seguintes estratégias para manter sempre o token de acesso válido:

Esperar o servidor retornar o código de erro 401, que indica que o token se tornou inválido, e gerar novamente o token;
Programar a sua aplicação para gerar o token de acesso com menos de 60 minutos;
Gerar o token de acesso no inicio de cada processo de atualização. Por exemplo, a API é utilizada para atualizar produtos e preços algumas vezes ao dia. O token pode ser gerado no início de cada iteração.

Escolha a melhor estratégia de acordo com a sua aplicação.
A única estratégia que não recomendamos é gerar o token de acesso a cada requisição para a API porque isto deixaria a aplicação lenta.

Manipulação dos Objetos

A API expõe uma lista de objetos que podem ser manipulados, tais como produto, entidade (cliente, fornecedor, transportadora, etc), DAV (pré-vendas, orçamento, pedido).

Cada objeto tem sempre as mesmas características:

os objetos são expressos em formato JSON
o id interno do objeto não é exposto. A chave primária neste caso sempre é o campo código
somente alguns campos são obrigatórios
campos do JSON que não definidos serão simplesmente ignorados

Verbos

De uma forma geral, a API aceita os seguintes verbos:

POST – para incluir um novo objeto

PUT – para alterar um objeto

DELETE – para apagar um objeto

GET/{codigo} – para ler um objeto pelo seu código

GET – para ler uma lista de objetos com suporte a paginação e filtro

POST – Inclusão

Formato geral:curl –verbose –header “Authorization: Bearer ${token_de_acesso}” –header “Content-Type: application/json” –data “${json}” –request “POST” “${endereco_do_servidor}/public-api/v1/${objeto}”

Quando a chamada para a API for executada com sucesso a resposta conterá o status 200 (OK).
Caso o servidor rejeite a chamada por algum motivo a resposta conterá o status 422 (Unprocessable Entity) e no corpo da resposta um JSON com um array de avisos e outro de erros com todas as críticas agrupadas.

PUT – Alteração

Formato geral:curl –verbose –header “Authorization: Bearer ${token_de_acesso}” –header “Content-Type: application/json” –data “${json}” –request “PUT” “${endereco_do_servidor}/public-api/v1/${objeto}”

DELETE – Exclusão

Formato geral:curl –header “Authorization: Bearer ${token_de_acesso}” –header “Content-Type: application/json” –request “DELETE” “${endereco_do_servidor}/public-api/v1/${objeto}/${codigo}”

Quando a chamada para a API for executada com sucesso a resposta conterá o status 200 (OK). Caso o servidor rejeite a chamada por algum motivo a resposta conterá o status 422 (Unprocessable Entity) e no corpo da resposta uma mensagem explicando o problema.

GET – consulta por código

Formato geral:curl –header “Authorization: Bearer ${token_de_acesso}” –header “Content-Type: application/json” –request “GET” “${endereco_do_servidor}/public-api/v1/${objeto}/${codigo}”

A consulta por código retorna apenas um objeto identificado pelo código.
Quando a chamada para a API for executada com sucesso a resposta conterá o status 200 (OK).
Caso o servidor rejeite a chamada por algum motivo a resposta conterá o status 422 (Unprocessable Entity) e no corpo da resposta uma mensagem explicando o problema.

GET – Consulta paginada com filtro

A consulta paginada com filtro retorna uma lista de objetos após a API aplicar o filtro passado por parâmetro e posicionar-se na página solicitada.
Quando a chamada para a API for executada com sucesso a resposta conterá o status 200 (OK).
Caso o servidor rejeite a chamada por algum motivo a resposta conterá o status 422 (Unprocessable Entity) e no corpo da resposta uma mensagem explicando o problema.

A página solicitada é definida pelo parâmetro offset. Caso não for passado por parâmetro a API irá sempre posicionar-se na página 0.

A API retorna no máximo 100 objetos por chamada mas é possível definir outro valor com o parâmetro limit. Caso não seja informado, a API irá sempre retornar 25 objetos por chamada.
Sendo assim, para retornar a lista completa de objetos do servidor é necessário chamar continuamente a API incrementando o parâmetro offset até que nenhum objeto seja retornado ou o número de objetos retornados seja menor que o tamanho da página.
A API suporta uma lista de filtros separador por &. Cada filtro tem o formato padrão campo.operação=valor.
Note que todos os campos que pertencem a um objeto podem ser usados como filtro. As seguintes operações são suportadas:

eq = igual
ne = diferente
gt = maior que
ge = maior ou igual a
lt = menor que
le = menor ou igual a

O filtro suporta valores que contenham apenas letras e números.
Caso precise especificar algum caracter especial é preciso utilizar ASCII ENCODING conforme a página https://www.w3schools.com/tags/ref_urlencode.asp

Seguem alguns exemplos de filtros e seus significados:?cnpjCpf.eq=123.456.789-10 = 25 primeiras entidades cujo CPF for igual a 123.456.789-10 ?estado.eq=SP&nome.ge=ANTONIO = 25 primeiras entidades do estado de SP com nomes que iniciam com ANTONIO ?extra1.eq=40%25&dataNascimento.ge=2010-01-01&offset=0&limit=100 = 100 primeiras entidades cujo campo extra1 for igual a 40% e que nasceram após 01/01.2010