Integração
1. O que é API?
API (Application Programming Interface) é um conjunto de rotinas/padrões de programação para acesso a software. Uma API é criada quando a empresa deseja que outras pessoas desenvolvam outros produtos/integrações com outros sistemas. Por exemplo o Google Maps, muitos sites utilizam do serviço por meio da API do google (sites de hotel, aluguel, etc...). É através da API que os programas se comunicam um com o outro sem o conhecimento do usuário final, ela funciona por meio da comunicação feito por código.
Uma API é uma interface, e não um arquivo, ou qualquer coisa do tipo. Essa interface é acessível por meio de variados métodos via programação. Um comparativo a API é pensar como um garçom. O garçom pode trazer inúmeras refeições baseado na sua requisição, então a API irá responder baseado nos seus parâmetros/filtros. Uma documentação da API (igual ao nosso api.mercos.com) seria igualmente relacionado ao menu de um restaurante.
O que é uma API aberta/restrita/fechada?
Nós na MP possuímos uma API aberta, que significa que ela está disponível para qualquer desenvolvedor externo (com a devida autenticação ao sistema), em outras palavras qualquer empresa ou desenvolvedor tem acesso aos nossos métodos. Uma API fechada é de uso apenas interno do próprio sistema. Já uma API restrita é controlada para quais clientes estará liberada.
2. O que é JSON?
JSON (JavaScript Object Notation) é um leve formato para comunicação de dados, no qual a estrutura é baseada em chave/valor. É fácil para qualquer um ler, escrever e entender um documento JSON, assim como é igualmente fácil para uma máquina entender/gerar.
Dito isto, nada mais é que um formato de texto, independente de qualquer linguagem de programação e também familiar para programadores (ex. programadores de linguagens como C, C++, C#, Java, JavaScript, Perl, Python, etc...), essas características fazem do JSON o formato ideal para qualquer troca de dados.
Usamos o JSON tanto para receber entradas de dados (ex. cadastrando uma transportadora), como para enviar os dados quando solicitado (ex. obtendo um pedido). Veja um exemplo de um pedaço de JSON que nossa API irá interpretar para incluir um produto:
{
"nome": "Furadeira de Impacto HGSB13",
"preco_tabela": 254.87,
"codigo": "003",
"unidade": "Un",
"grade_cores": ["Azul", "Verde"],
}
3. O que é REST?
REST é um modo de se comunicar com sistemas na internet de forma clara e fácil. Nesta arquitetura o client envia uma requisição para obter ou modificar recursos e o servidor envia respostas para estas requisições.
Fazendo requisições
Para fazer a requisição via REST é necessário um HTTP verb, um caminho para o recurso, e uma mensagem opcional com o envio de dados.
HTTP Verbs
Os sites que acessamos diariamente funcionam por meio de protocolo HTTP, o qual possui alguns verbos de ação:
GET - obtém um ou vários recursos
POST - cria um novo recurso
PUT - atualiza um recurso específico
DELETE - remove um recurso específico
Exemplificando, quando acessamos algum site pelo navegador, por exemplo o Google, estamos fazendo um GET para google.com. Quando realizamos a pesquisa no site, estamos enviando um POST para o google com uma mensagem contendo o texto que queremos procurar.
Exemplificando uma requisição em nossa API
Acessando a nossa documentação da API escolhemos um recurso, neste caso Segmentos de Cliente, e definimos que queremos usar a API para criar um segmento.
Segundo a documentação, é necessário fazer um POST para o caminho informado, passando como mensagem um JSON com nome. Sendo assim, nossa requisição ficaria:
POST https://integracao.meuspedidos.com.br/api/v1/segmentos
{
"nome": "Novo segmento"
}
4. Como funciona a nossa integração?
A integração com o sistema da MP funciona através de uma API aberta via REST e está com todos os métodos e funções que disponibilizamos documentadas em api.meuspedidos.com.br.
É importante lembrar que na integração com a MP, o nosso sistema não envia dados para nenhum ERP/software a não ser que requisitado. A requisição sempre é feita pelo outro lado. Por exemplo, existem novos pedidos? Essa é a pergunta/requisição que deve ser feito via API pela integração para nós, caso não houver essa requisição, nosso sistema não enviará os dados por conta própria.
5. O que faço quando o cliente pergunta sobre integração quando possui um ERP que não conheço?
Nossa integração independe de linguagem de programação, de ERP, de banco de dados entre outras coisas. A comunicação entre os sistemas deve ser realizada sempre pelo parceiro integrador ou algum outro desenvolvedor que irá consumir nossa API. A resposta certa para esta pergunta é um "depende". Nestes casos é necessário envolver a equipe de Canais para entender melhor e ver se o integrador está disponível para este trabalho.
6. Quais são os outros tipos de integração?
Nós trabalhamos com a API via REST, o qual é o método mais utilizado hoje em dia e também acessível de várias maneiras independente de linguagem. Entretanto existem outros tipos/termos de integração e que não trabalhamos:
SOAP
WSDL
XML
RPC
Texto
UDDI
Nossa API é disponível apenas via REST e em nenhuma outra forma. Porém isto não impede o integrador de conversar com um sistema que possui outros tipos de integrações.
Exemplo: O ERP do cliente X possui uma API em SOAP, porém é possível do integrador fazer um meio campo conversando com o sistema da MP via REST e devolvendo para o ERP via SOAP.