O sistema da farmácia precisa consultar um benefício, cobrar um pagamento ou obter a autorização de uma nota fiscal sem que uma pessoa abra a tela de outro sistema. Para isso, um programa conversa diretamente com outro programa, por meio de uma interface criada para essa conversa. Entender o que essa interface oferece e o que ela promete é o primeiro passo para investigar uma falha de integração.
Interface para pessoas e interface para programas
Uma pessoa usa um sistema pelas telas. Ela preenche campos, aciona botões e lê os resultados. Um programa não usa telas. Para que um programa use as funções de outro, o outro oferece uma API, sigla de Application Programming Interface, interface de programação de aplicações.
A API é um conjunto de operações que um programa pode solicitar a outro, com regras para os dados de cada solicitação e para as respostas. O sistema da loja, por exemplo, solicita a um serviço de pagamentos a criação de uma cobrança, informa o valor e os dados do pedido e recebe de volta o número da cobrança e a situação dela.
O contrato
O contrato de uma API descreve como usá-la:
- as operações disponíveis, como criar uma cobrança ou consultar um benefício;
- os dados que cada operação aceita, com os nomes, os tipos e as regras de preenchimento;
- as credenciais exigidas para usar a interface;
- o formato e o significado das respostas, inclusive dos erros.
Quem oferece a API publica o contrato, normalmente em uma documentação. Quem usa a API segue esse contrato para montar as solicitações e interpretar as respostas. Uma resposta só é interpretada corretamente com o contrato em mãos, porque o mesmo código pode ter significados diferentes em interfaces diferentes.
API local e API remota
Uma API não precisa estar na Internet. Uma biblioteca instalada no computador, como a de um equipamento ou a de um sistema de pagamento com cartão, também oferece funções a outros programas, e essas funções formam uma API local. O programa chama a função, e a execução acontece no próprio computador.
Uma API remota atende chamadas feitas pela rede, a partir de outro computador. Os serviços de pagamento, de benefícios e de emissão fiscal costumam oferecer APIs remotas, acessadas pela Internet.
Uma API local pode, por sua vez, conversar com um serviço remoto. Uma biblioteca de pagamento com cartão, por exemplo, recebe a solicitação do sistema da loja no próprio computador e depois se comunica com a operadora pela rede.
API e integração
Integração é qualquer forma de troca de dados entre sistemas, e a API é uma dessas formas. Dois sistemas também se integram por arquivos gravados em uma pasta, por tabelas de um banco de dados, por filas de mensagens e até por e-mail. Cada forma tem um contrato próprio. Em uma integração por arquivo, por exemplo, o contrato define o formato do arquivo, a pasta usada e o momento da troca.
Os nomes REST, SOAP, GraphQL e RPC aparecem com frequência ao lado da palavra API. Eles indicam formas diferentes de organizar as operações e as mensagens de uma API, e nenhum deles é sinônimo de API.
As integrações do cenário
Nos exemplos, a farmácia usa estas integrações:
- o PBM, programa de benefício em medicamentos, consultado pelo caixa 01 antes de conceder o desconto de um programa de benefícios;
- o TEF, transferência eletrônica de fundos, que leva o pagamento com cartão do caixa 01 até a operadora, com o uso do PinPad;
- a SEFAZ, a secretaria da fazenda do estado, que autoriza as notas fiscais emitidas pela loja;
- o site de vendas, cujos pedidos são lidos por um programa chamado integrador, que cobra cada pedido no gateway de pagamento, um serviço de cobrança pela Internet;
- a plataforma de cotação, que reúne os preços e as condições dos distribuidores de medicamentos para as compras da farmácia;
- o serviço de sincronização do servidor geral, que troca dados entre a matriz e as lojas.
O retorno nem sempre encerra a operação
A resposta de uma API informa o que aconteceu até aquele momento, e nem sempre o resultado final da operação. Uma biblioteca de TEF pode informar que a transação foi iniciada enquanto ainda conversa com a operadora. O gateway de pagamento pode registrar a cobrança e informar que a aprovação ainda está pendente. O contrato explica o que cada resposta confirma e como acompanhar a operação até o resultado final.
Essa distinção também organiza o atendimento. Carregar a biblioteca, ser aceito com a credencial, enviar a operação e aplicar o resultado no sistema da loja são etapas diferentes, que podem pertencer a componentes diferentes. Cada etapa tem a sua confirmação, e a confirmação de uma etapa não garante a seguinte.
No suporte
Diante de uma falha de integração, convém identificar qual interface o programa usa, quem oferece essa interface e qual operação falhou. A palavra API, sozinha, não informa o canal, o formato nem a credencial envolvidos.
Para guardar
- A API é a interface que permite a um programa usar as funções de outro.
- O contrato define as operações, os dados, as credenciais e o significado das respostas.
- Uma API pode ser local, em uma biblioteca do computador, ou remota, acessada pela rede.
- Integração é qualquer troca de dados entre sistemas, e a API é uma das formas de integração.
- Uma resposta pode confirmar apenas uma etapa, e o contrato define quando o resultado é final.
A biblioteca de TEF instalada no caixa 01 oferece funções para iniciar uma transação. Essa biblioteca tem uma API?
Sim. As funções e as regras de uso formam uma interface para o sistema da loja. É uma API local, mesmo que a biblioteca depois se comunique com a operadora pela rede.
Dois sistemas trocam arquivos em uma pasta compartilhada. O que é preciso conhecer para entender essa integração?
O formato do arquivo, a pasta, o momento da troca e a forma de confirmação ou de retorno. É uma integração por arquivo, e o contrato dela descreve essas condições. Chamá-la apenas de API não ajuda a investigar uma falha.