API Rest (WEB)

Atualizado em23 de julho de 2024

Introdução

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 e OSX. Caso seja usado Windows, é possível fazer o download da ferramenta nesta página.

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:

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, mas caso prefira, 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 Uniplus Web, 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 também importante é o endereço do servidor, que deve ter fixo a porta 8443 (por exemplo: 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 caso de acesso remoto é necessário passar um token que 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 não recomendada é 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) e afins.

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}”

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

Formato geral:

curl --header "Authorization: Bearer ${token_de_acesso}" --header "Content-Type: application/json" --request "GET" “${endereco_do_servidor}/public-api/v1/${objeto}”?offset=${offset}&limit=${limit}&filter1

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 caractere especial, é preciso utilizar ASCII ENCODING conforme esta página.

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

Lista completa de objetos

A lista completa de objetos pode ser encontrada aqui: Api Rest – Lista de objetos

Note que cada objeto da API possui uma versão, mas mesmo assim, podem ser acrescentados campos nos objetos já existentes, desde que não interfiram na versão atual.

Conteúdo Relacionado

Os artigos listados abaixo estão relacionados ao que você acabou de ler:
• Yoda
• Layout de importação/exportação de arquivo texto (R2D2)
• API para acesso externo (WEB)
• API Alto Nível (WEB)
• Índice de Endpoints (WEB)
• Comunicação via API (WEB)
• Antes de Falar com o Suporte Técnico
• Obtendo suporte técnico e ajuda