Para melhor compreensão das informações operacionais contidas neste manual, é importante que se tenha uma noção dos termos mais utilizados e dos principais conceitos relacionados a Bimer API.
API
API (Application Programming Interface) ou, em português, Interface de Programação de Aplicativos se trata de um conjunto de padrões de programação que permite a construção de aplicativos. As APIs são muito utilizadas para realizar a integração entre sistemas diferentes, permitindo que se conectem mutualmente para obter ou enviar informações. Veja alguns exemplos:
- Pode ser utilizada por um aplicativo para se conectar ao relógio do Windows para utilizar informações de data e hora do computador;
- Por aplicativos que se conectam ao Google Maps® para localizar e demonstrar endereços;
- Por sites de pesquisa de preços, como o Buscapé®, que consultam informações em diversas lojas para apresentá-las no resultado da pesquisa;
- Quando uma empresa faz uma venda pelo cartão, o sistema da administradora se conecta ao sistema da instituição financeira para obter autorização para a transação.
Tudo isso é realizado através do uso de APIs.
Modelagem das APIs
Todos os serviços disponibilizados através da API utilizam a tecnologia REST (Representational State Transfer), uma arquitetura que permite interações com serviços web RestFul que disponibiliza recursos através de sistemas distribuídos, popularmente utilizados via HTTP.
O serviço é formado 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.
No Recurso Raiz, podemos acessar as principais operações do serviço (CRUD), através dos métodos do padrão HTTP, conforme tabela abaixo:
| CRUD | Métodos HTTP |
|---|---|
| Create | POST |
| Read | GET |
| Update | PUT |
| Delete | DELETE |
Ou seja, no serviço/clientes, do exemplo acima, se fizermos uma operação POST, salvaremos um novo cliente. A tabela abaixo mostra algumas das operações que conseguimos executar sobre determinados serviços:
| Recursos | GET | POST |
|---|---|---|
| /clientes | * | Cria um cliente |
| /produtos | Lista com todos os produtos cadastrados | * |
| /produtos/00A0000001 | Lista detalhes do produto com identificador 00A0000001 | * |
O ' * ' na tabela acima, representa que o método não está disponível, então espera-se o retorno com "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 para descrição de dados para intercâmbio entre sistemas e é mais simples e mais leve que o XML. Por padrão, toda a API trafega JSON, tanto para receber informações (métodos POST e PUT) quanto no retorno (método GET). Devido a essa padronização, para as chamadas POST e PUT é necessário informar o HTTP Header "content-type:application/json". Do contrário, você receberá um erro "HTTP 415: Unsupported Media Type"
Bimer API
A Bimer API é, como o próprio nome indica, é a API criada pela Alterdata para que outros sistemas, serviços e aplicativos possam se conectar à base de dados Bimer, para consultar e/ou gravar informações.
Um cliente que tenha um sistema web próprio e quer usar o Bimer como retaguarda. Nesse caso, a comunicação se dará através da Bimer API, e para isso, você precisa programar seu sistema para comunicar-se com a Bimer API, conforme os primeiros passos disponibilizados neste manual.
Tipos de Requisições (HTTP)
Dentre os métodos de requisição utilizados pela Bimer API, estes quatro são os mais vistos e merecem atenção. Se você conhece alguns comandos básicos de SQL, é possível traçar um paralelo entre as linguagens da seguinte forma:
A Bimer API pode funcionar tanto em HTTP quanto em HTTPs e irá depender da infraestrutura onde foi instalada.
- GET: as requisições com este comando retornam dados. Podemos compará-lo a um select, no SQL;
- POST: por meio deste comando, as requisições adicionam dados. Lembra do insert lá no SQL?! Pois é… É semelhante ao POST na linguagem HTTP;
- PUT: este tipo de requisição realiza alteração de dados. Ele é equivalente a um update no SQL;
- DELETE: “xará” do delete no SQL, este tipo de requisição faz a mesma coisa: exclui dados.
Erros Comuns
Existem alguns erros comuns que podem acontecer ao utilizar a API, dentre eles estão:
| 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 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 o time de especialistas. Caso continue com problemas, você também pode entrar em contato com o time de suporte, estamos sempre felizes em ajudar!