As palavras API, webservice e integração aparecem no atendimento como nomes gerais para processos muito diferentes. Cinco perguntas descrevem as partes de qualquer integração e indicam qual registro e qual teste correspondem à falha relatada.
As cinco perguntas
- Por onde os componentes conversam? O canal pode ser o HTTP ou o HTTPS, um socket TCP, arquivos em uma pasta ou em um servidor de transferência, um serviço de mensageria, um banco de dados compartilhado, uma biblioteca local ou o e-mail.
- Como as operações estão organizadas? O estilo pode ser REST, OData, SOAP, GraphQL, JSON-RPC, XML-RPC, gRPC, um protocolo próprio, um layout de arquivo ou um padrão EDI.
- Em que formato vêm os dados? Os dados podem vir em JSON, XML, texto posicional, texto delimitado, pares de chave e valor ou formato binário.
- Como a troca acontece no tempo? A resposta pode ser imediata, e a troca também pode ter um aceite com conclusão posterior, consultas periódicas, avisos por webhook, uma conexão permanente, uma fila ou um lote programado.
- Como o acesso é identificado e permitido? A credencial pode ser usuário e senha, API Key, Client ID e Client Secret, token ou certificado, sempre com as permissões e o ambiente correspondentes.
Cada pergunta trata de um aspecto diferente, embora algumas tecnologias andem sempre juntas, como o SOAP e o XML. A credencial não define o estilo, o JSON não define o REST, e uma resposta imediata pode informar apenas o aceite.
Três integrações descritas
- gateway de pagamento: o canal é o HTTPS, o estilo é REST, o formato é JSON e a credencial é um token Bearer. A criação da cobrança responde na hora, e a aprovação é acompanhada depois.
- PBM: o canal é o HTTPS, e o estilo pode ser GraphQL, com JSON, ou SOAP, com XML, conforme o fornecedor. O login costuma ser trocado por um token, e a consulta do benefício tem resposta imediata.
- SEFAZ: o canal é o HTTPS, o estilo é SOAP, o formato é XML assinado e o acesso exige o certificado do cliente. O resultado vem na resposta ou em uma consulta posterior, conforme o serviço.
O nome do processo comercial não responde a nenhuma das cinco perguntas. A configuração e o contrato de cada instalação mostram as respostas.
O que as cinco perguntas não respondem
A descrição pelas cinco perguntas localiza o contrato, mas não substitui as regras dele. A expressão HTTPS, JSON e Bearer ainda não informa se uma cobrança pode ser reenviada depois de um tempo esgotado. Para o atendimento, a descrição ganha mais quatro informações:
- o identificador que acompanha a operação de negócio, como o número do pedido;
- quem confirma cada etapa, do envio ao resultado final;
- onde ficam registradas as tentativas;
- a política de consulta e de repetição prevista no contrato.
Essas informações explicam o que fazer quando a mensagem chega ao destino e o resultado não aparece.
No suporte
Diante de uma integração, convém responder às cinco perguntas e marcar as respostas que ainda faltam confirmar. O canal orienta os testes de rede e de acesso, o estilo e o formato orientam a leitura das mensagens, o tempo orienta o acompanhamento, e a credencial orienta a autenticação.
Para guardar
- Canal, estilo, formato, tempo e acesso descrevem aspectos diferentes de uma integração.
- Algumas tecnologias andam juntas, mas a credencial não define o estilo, e o JSON não define o REST.
- O mesmo tipo de serviço pode usar combinações diferentes em cada fornecedor.
- As cinco perguntas localizam o contrato, e as regras de confirmação e de repetição vêm dele.
Uma integração pede usuário e senha e troca esses dados por um token em uma operação GraphQL. Quais perguntas essa informação responde?
A do estilo, GraphQL, e parte da pergunta sobre o acesso, com o login trocado por um token. O canal, o formato de transporte, a forma de apresentar o token e o acompanhamento das operações ainda precisam de confirmação.
Saber que uma integração é de TEF permite concluir que ela usa um socket TCP?
Não. As soluções de TEF podem usar uma biblioteca local, pastas de troca de arquivos ou outros canais. A configuração e a documentação do fornecedor mostram a combinação em uso.