Para facilitar a compreensão das informações operacionais deste manual, é importante conhecer os termos mais utilizados e os principais conceitos relacionados à Bimer API.
API
API (Application Programming Interface) ou, em português, Interface de Programação de Aplicativos, é um conjunto de padrões de programação que permite a construção e a integração de aplicativos. As APIs são amplamente utilizadas para conectar sistemas diferentes, possibilitando o envio e o recebimento de informações. Veja alguns exemplos:
-
Um aplicativo pode se conectar ao relógio do Windows para utilizar informações de data e hora do computador.
-
Aplicativos podem se conectar ao Google Maps® para localizar e exibir endereços.
-
Sites de pesquisa de preços, como o Buscapé®, podem consultar informações em diversas lojas para apresentá-las nos resultados de busca.
-
Quando uma empresa realiza uma venda com cartão, o sistema da administradora se conecta ao sistema da instituição financeira para obter autorização da transação.
Todos esses processos são realizados por meio do uso de APIs.
Modelagem das APIs
Todos os serviços disponibilizados pela API utilizam a tecnologia REST (Representational State Transfer), uma arquitetura que permite interações com serviços web RESTful. Esses serviços disponibilizam recursos por meio de sistemas distribuídos, normalmente acessados via HTTP.
O serviço é estruturado da seguinte forma: http://hostname/versaoapi/recursoRaiz
Onde:
-
Hostname: endereço principal do serviço.
-
Versão da API: versão do serviço que está sendo consumido.
-
Recurso raiz: nome do serviço.
|
Exemplo: |
|---|
|
https://seuservidordaAPI.com.br/api/clientes |
No recurso raiz, é possível acessar as principais operações do serviço (CRUD) por meio dos métodos do padrão HTTP, conforme a tabela abaixo:
|
CRUD |
Métodos HTTP |
|---|---|
|
Create |
POST |
|
Read |
GET |
|
Update |
PUT |
|
Delete |
DELETE |
Ou seja, no serviço /clientes do exemplo acima, ao executar uma operação POST, um novo cliente será salvo. A tabela abaixo apresenta algumas operações que podem ser executadas em determinados serviços:
|
Recursos |
GET |
POST |
|---|---|---|
|
/clientes |
* |
Cria um cliente |
|
/produtos |
Lista todos os produtos cadastrados |
* |
|
/produtos/00A0000001 |
Lista os detalhes do produto com identificador 00A0000001 |
* |
O símbolo * na tabela acima indica que o método não está disponível. Nesse caso, espera-se o retorno ERRO 405 - method not allowed.
HTTP 1.1
O protocolo padrão para comunicação com as APIs é o HTTP versão 1.1. Para mais informações sobre esse protocolo, consulte:
http://www.w3.org/Protocols/rfc2616/rfc2616.html
http://www.ietf.org/rfc/rfc2616.txt
UTF-8
O charset padrão para chamadas às APIs é o UTF-8. Para mais informações sobre essa codificação, consulte:
https://tools.ietf.org/html/rfc3629
JSON
JSON (JavaScript Object Notation) é um padrão de descrição de dados utilizado para intercâmbio entre sistemas. Ele é mais simples e mais leve que o XML. Por padrão, toda a API trafega dados em JSON, tanto no recebimento de informações (métodos POST e PUT) quanto no retorno (método GET). Devido a essa padronização, nas chamadas POST e PUT é necessário informar o cabeçalho HTTP content-type:application/json. Caso contrário, será retornado o erro HTTP 415: Unsupported Media Type.
Bimer API
A Bimer API é a API criada pela Alterdata para que outros sistemas, serviços e aplicativos possam se conectar à base de dados do Bimer para consultar e/ou gravar informações.
Um exemplo comum é o de um cliente que possui um sistema web próprio ou um e-commerce e deseja utilizar o Bimer como retaguarda. Nesse caso, a comunicação ocorre por meio da Bimer API, permitindo o acesso a dados estratégicos, como níveis de estoque mínimo, máximo e crítico por empresa e setor. Essas informações são essenciais para que o sistema externo gerencie automaticamente a reposição de produtos e evite rupturas de estoque.
Para utilizar esses recursos, é necessário programar o sistema para se comunicar com a Bimer API, conforme os primeiros passos disponibilizados neste manual.
Tipos de Requisições (HTTP)
Entre os métodos de requisição utilizados pela Bimer API, os quatro abaixo são os mais comuns e merecem atenção. Para quem conhece comandos básicos de SQL, é possível estabelecer o seguinte paralelo:
A Bimer API pode funcionar tanto em HTTP quanto em HTTPS, dependendo da infraestrutura em que foi instalada.
-
GET: retorna dados. Pode ser comparado ao comando select no SQL.
-
POST: adiciona dados. É semelhante ao comando insert no SQL.
-
PUT: altera dados. Equivale ao comando update no SQL.
-
DELETE: exclui dados. Corresponde ao comando delete no SQL.
Erros Comuns
Alguns erros comuns podem ocorrer ao utilizar a API, entre eles:
|
Erro |
Possível solução |
|---|---|
|
Erro 405 - The requested resource does not support http method '...' |
Pode ser causado pela utilização de uma versão mais antiga da API. |
|
Erro 400 - Não foi possível hidratar a entidade '...' com identificador 00000 |
|
|
Erro 401 - Authorization has been denied for this request |
O token de autenticação utilizado expirou ou é inválido. |
|
Erro 403 - Forbidden |
O usuário atual não possui acesso a essa rota. Libere o acesso no módulo de cadastro de usuários. |
Dúvidas e Sugestões
Está com dúvidas ou gostaria de sugerir um novo recurso? Acesse a Central do Cliente e fale com o time de especialistas. Caso o problema persista, entre em contato com o time de suporte. Estamos sempre felizes em ajudar!