Como identificar a integração no dia a dia

Uma integração desconhecida chega ao atendimento como o nome de um processo, uma tela de configuração ou um trecho de log. A configuração, o endereço, a mensagem e o momento da troca, lidos juntos, mostram qual interface está em uso, sem transformar cada sinal isolado em certeza.

Quem executa a chamada

O primeiro passo é descobrir qual componente executa a chamada: o caixa 01, o servidor da loja, o servidor geral, o integrador do site de vendas ou uma biblioteca instalada na estação. A tela que mostra o erro nem sempre fica na máquina que faz a chamada. A configuração do componente indica o canal:

• um endereço que começa com http ou https sugere um serviço web;
• uma pasta, ou um servidor FTP ou SFTP, sugere uma integração por arquivo;
• um servidor de banco, com usuário e senha, sugere o acesso direto aos dados;
• uma DLL ou um componente COM sugere uma biblioteca local;
• um servidor de mensagens, com filas ou tópicos, sugere mensageria.

Um endereço IP com porta aparece em todos esses casos e, sozinho, não indica um protocolo próprio. Uma biblioteca local também pode usar outro canal por trás da interface que oferece.

O endereço completo

Partes do endereço dão pistas do estilo da interface:

• .asmx, .svc e ?wsdl sugerem um serviço SOAP;
• /graphql sugere uma API GraphQL;
• /odata/ e as opções iniciadas por $, como $filter, sugerem OData;
• ws:// e wss:// indicam WebSocket;
• os recursos com identificadores, como /pedidos/0001, são comuns nas APIs REST.

Nenhuma dessas pistas, sozinha, comprova o contrato. O endereço usado de fato pelo programa, o método, a versão e o ambiente completam a leitura.

A mensagem da operação

A estrutura da mensagem também revela o estilo:

• um XML com o elemento Envelope no namespace do SOAP indica uma mensagem SOAP;
• os elementos methodCall e methodName sugerem XML-RPC;
• um JSON com os campos jsonrpc e method é característico do JSON-RPC;
• um JSON com o campo query, cujo texto traz uma operação GraphQL, indica GraphQL;
• um texto posicional, delimitado ou no formato chave=valor pode circular por arquivo, por socket ou por outro canal.

Um JSON comum não identifica uma API REST, e um conteúdo binário não identifica, sozinho, um protocolo específico. O primeiro registro de um arquivo de log também pode não ser a primeira etapa da operação, e a busca pelos identificadores da operação localiza o começo da troca.

Quando o log não mostra o método

Alguns logs registram só o conteúdo enviado e o recebido, sem o método, a URL e o status HTTP. A ausência do método no trecho analisado significa apenas que ele não foi registrado ali. O programa pode omitir o método, registrá-lo em outro lugar ou usar um canal que não é HTTP. Nesses casos, as pistas permitem hipóteses, e não certezas:

• um corpo com dados é compatível com POST, PUT ou PATCH, entre outras possibilidades;
• uma operação GraphQL de alteração costuma ir por POST, e uma consulta GraphQL pode usar GET quando o servidor aceita;
• uma mensagem SOAP costuma ir por POST;
• um caminho com identificador e sem corpo pode ser uma consulta, uma remoção ou outra operação.

Nas interfaces organizadas por operações, como SOAP, RPC e GraphQL, o POST transporta tanto consultas quanto alterações, e a intenção aparece no nome da operação. O registro completo da chamada, a configuração e a documentação confirmam o que as pistas sugerem. A documentação mostra o comportamento esperado, e o registro completo mostra o que aconteceu naquela tentativa.

Exemplos de classificação

As integrações do cenário mostram como a mesma descrição se aplica a casos diferentes:

• gateway de pagamento: HTTPS, API REST, JSON e token Bearer. A criação da cobrança responde na hora, e a aprovação é acompanhada depois.
• PBM: HTTPS com uma API GraphQL e JSON, com login trocado por token, ou HTTPS com SOAP e XML, com as credenciais na mensagem. Dois PBMs podem usar interfaces diferentes.
• SEFAZ: serviços SOAP sobre HTTPS, com XML assinado e certificado do cliente.
• TEF: biblioteca local, pasta de troca de arquivos ou socket, conforme a solução. A comunicação com a rede de cartões fica por trás dessa interface.
• plataforma de cotação: HTTPS e JSON, com consultas de produtos e de distribuidores.
• serviço de sincronização: troca de dados entre o servidor geral da matriz e as lojas pela porta 9000, com o formato e as regras definidos pelo fabricante do sistema.

Outras integrações comuns no varejo seguem a mesma leitura:

• uma cobrança PIX por API bancária usa HTTPS, JSON, OAuth e certificado do cliente, com avisos por webhook, e a criação da cobrança não equivale ao recebimento do pagamento;
• um marketplace de delivery costuma oferecer uma API REST com OAuth, e os pedidos novos podem ser buscados por consultas periódicas ou recebidos por webhook;
• a conciliação de cartões costuma usar arquivos disponibilizados pela operadora, baixados e importados no sistema em lotes;
• o envio dos XMLs fiscais para a contabilidade costuma usar arquivos copiados para uma pasta ou enviados por FTP ou SFTP;
• os pedidos eletrônicos aos distribuidores podem usar arquivos posicionais, um layout próprio ou EDI, entregues por FTP, SFTP ou portal.

O nome do processo comercial não define a tecnologia. A configuração e o contrato de cada instalação mostram a combinação em uso.

A ficha da integração

Para cada integração atendida, uma ficha curta reúne o que já foi confirmado e o que ainda é hipótese:

• o componente que executa a chamada e a máquina em que ele roda;
• o canal, a organização das operações e o formato;
• o momento da troca, com resposta imediata, aceite e acompanhamento, consulta periódica, aviso, fila ou lote;
• a credencial, a validade e as permissões;
• o fornecedor, a versão do contrato e a documentação;
• a configuração e os logs de cada componente.

A separação entre o que está registrado e o que foi deduzido evita que uma pista vire certeza no meio do atendimento.