FolioPierEstudos de TI

Revisão de integrações

Nota 37 de 37 · 16 min de leitura
Nesta página
  1. Erros comuns
  2. Checklist de leitura do log de uma integração
  3. Checklist da ficha de uma integração
  4. Glossário
  5. Para continuar estudando
  6. Referências

Este capítulo reúne o conteúdo de integrações para revisão: os erros mais comuns, os checklists de leitura do log e de descrição de uma integração, o glossário, as referências e perguntas que misturam vários assuntos.

Erros comuns

  • Classificar a API como REST pela URL ou pelo JSON. A palavra api e o formato JSON também aparecem em GraphQL, em JSON-RPC e em interfaces próprias, e o estilo vem da estrutura das mensagens e do contrato.
  • Tratar webservice como sinônimo de SOAP. A palavra também designa APIs HTTP em geral, e o SOAP se reconhece pelo Envelope e pelo namespace.
  • Concluir que o método não foi usado porque o log não mostra. Um registro parcial não informa tudo o que aconteceu, e o registro completo ou a configuração confirmam a chamada.
  • Deduzir o estilo da API pela credencial. Uma API Key, um usuário e uma senha ou um token aparecem em interfaces de qualquer estilo.
  • Achar que o Client ID e o Client Secret definem o fluxo do OAuth. Esses campos autenticam a aplicação em mais de um fluxo, e o parâmetro grant_type indica o fluxo usado.
  • Ler um JWT decodificado como credencial válida. A decodificação não verifica a assinatura nem a validade, e só o serviço confere essas regras.
  • Ler o código 200 como aprovação. O status descreve o atendimento HTTP, e o corpo pode trazer uma recusa, um erro de execução, dados parciais ou uma pendência.
  • Atribuir os erros 4xx a quem abriu o chamado. Na família 4xx, o cliente é o programa que fez a chamada.
  • Tratar uma lista vazia como consulta bem-sucedida. A lista vazia só indica a falta de dados quando o resultado confirma o processamento.
  • Reformatar um XML assinado e reenviar o arquivo. Qualquer mudança na parte assinada invalida a assinatura, e o original fica preservado.
  • Tratar qualquer cStat como rejeição. O código pode indicar autorização, recebimento ou processamento pendente, e o nível da resposta importa.
  • Concluir que a SEFAZ não analisou o XML depois de um tempo esgotado. O documento pode ter sido processado, e a consulta pela chave de acesso mostra a situação.
  • Desligar a verificação do certificado para a falha desaparecer. A comunicação fica exposta, e a causa continua presente.
  • Esquecer o repositório e a conta que usam o certificado. Um certificado instalado para um usuário não aparece para um serviço do Windows que roda com outra conta.
  • Considerar uma mensagem publicada como processada. A publicação, a entrega e o processamento são etapas diferentes, com confirmações diferentes.
  • Contar com uma DLQ em toda fila. A DLQ existe quando o produto e a configuração oferecem esse recurso.
  • Testar em produção com a ferramenta de teste sem perceber. O endereço e a credencial efetivos definem o ambiente, e a operação enviada tem efeito real.
  • Liberar só a porta 21 para o FTP. O login funciona, e a listagem e a transferência falham na conexão de dados.
  • Registrar um componente com o regsvr32 da arquitetura errada. No Windows de 64 bits, o registrador da pasta SysWOW64 registra os componentes de 32 bits.
  • Gerar uma chave de idempotência nova a cada tentativa. Cada chave nova representa uma operação nova, e a repetição pode gerar outra cobrança.
  • Marcar como recusada uma operação com resultado desconhecido. A marcação esconde uma cobrança que pode ter acontecido.
  • Achar que não existe integração sem HTTP. Uma biblioteca local, um arquivo, um banco, um socket, a mensageria e o e-mail também integram sistemas, com contratos próprios.

Checklist de leitura do log de uma integração

O checklist não substitui o raciocínio. O checklist serve para que as verificações básicas não sejam esquecidas.

Identificação

  • Qual componente executou a chamada, em qual máquina e em qual ambiente?
  • O trecho do log corresponde ao período, à operação e à tentativa analisados?
  • Qual operação foi pedida: o método e o caminho, o procedimento ou o nome da operação?
  • Qual credencial foi usada, com qual validade e quais permissões?

Resultado

  • Existe status HTTP, ou uma exceção localiza a falha antes da resposta?
  • O corpo traz dados, um erro de protocolo ou um resultado de negócio, e o que o contrato diz sobre ele?
  • O resultado é final, pendente ou desconhecido?
  • Os horários têm fuso conhecido e pertencem à mesma operação?

Continuidade

  • Quais identificadores relacionam o pedido, a requisição, a cobrança, o documento ou a mensagem?
  • A situação precisa de consulta antes de uma repetição, e existe proteção contra duplicidade?
  • O registro preserva o contexto completo, inclusive as mensagens de várias linhas?
  • As credenciais e os dados sensíveis estão mascarados antes do compartilhamento?

Checklist da ficha de uma integração

  • O canal é HTTP ou HTTPS, socket, arquivo, mensageria, banco, biblioteca ou e-mail?
  • O estilo é REST, OData, SOAP, GraphQL, RPC, protocolo próprio ou layout de arquivo?
  • O formato é JSON, XML, texto posicional, texto delimitado ou binário?
  • A troca é imediata, assíncrona, por polling, por webhook, contínua ou em lote?
  • Qual é o mecanismo de acesso, com a validade, as permissões e o local da configuração?
  • Quem executa a chamada: o caixa, o servidor da loja, o servidor geral ou um componente intermediário?
  • Onde ficam a configuração, os logs e as tabelas de situação e de tentativas?
  • Quem oferece a interface, em qual versão e onde está o contrato?
  • Como o resultado é confirmado e como a integração trata as novas tentativas?
  • Qual é o alcance e o prazo da chave de idempotência ou do controle de duplicidade?
  • O que a confirmação de recebimento garante: a chegada, a gravação, a entrada na fila ou o negócio aplicado?
  • Como localizar um resultado desconhecido e reconciliar uma divergência entre o fornecedor e o sistema?

Glossário

  • Ack: a confirmação de que o consumidor tratou uma mensagem, com o significado definido pelo protocolo e pela aplicação.
  • API: a interface que permite a um programa usar as funções de outro componente, local ou remoto.
  • API Key: a chave entregue pelo fornecedor e apresentada nas chamadas, com validade e restrições próprias.
  • AS2: o protocolo de troca de documentos de negócio sobre HTTP, com confirmação de recebimento.
  • Autenticação: a verificação de quem está chamando.
  • Autoridade certificadora: a entidade que confere a identidade do titular e emite o certificado digital.
  • Autorização: a definição do que uma identidade pode fazer.
  • Backoff: a pausa entre as tentativas de uma repetição, que pode aumentar a cada falha.
  • Bearer: a forma de apresentar um token no cabeçalho Authorization.
  • Broker: o intermediário que recebe e distribui as mensagens na mensageria.
  • Cadeia de confiança: a sequência de certificados que liga um certificado final a uma autoridade raiz conhecida.
  • Certificado digital: o documento eletrônico que associa uma identidade a uma chave pública.
  • Chave de idempotência: a identidade que permite ao serviço reconhecer a repetição de uma operação.
  • Chave privada: a chave que fica só com o titular do certificado e comprova a identidade dele.
  • Client ID: o identificador da aplicação no OAuth, que não é secreto.
  • Client Secret: o segredo que autentica a aplicação, junto com o Client ID.
  • Contrato: a descrição das operações, dos dados, das credenciais e das respostas de uma interface.
  • cStat e xMotivo: o código e a descrição da situação nas respostas dos serviços fiscais.
  • DLQ: a fila que guarda as mensagens desviadas por uma política configurada.
  • EDI: a troca eletrônica de documentos de negócio em formatos combinados entre as empresas.
  • Endpoint: o endereço de uma operação, que, no HTTP, é identificada junto com o método.
  • Envelope: o elemento raiz da mensagem SOAP, que identifica a versão pelo namespace.
  • Escopo: a indicação das operações permitidas a um token no OAuth.
  • Fault: o elemento do SOAP que representa uma falha no processamento da mensagem.
  • FTP, FTPS e SFTP: a transferência de arquivos sem proteção, a transferência protegida pelo TLS e a transferência sobre o SSH.
  • GraphQL: a linguagem de consulta baseada em um esquema, em que quem chama escolhe os campos da resposta.
  • gRPC: o sistema de chamadas de procedimento que usa o HTTP/2 e mensagens binárias, com status próprios.
  • HMAC: o código calculado sobre a mensagem com um segredo compartilhado, que comprova a integridade e a origem.
  • Homologação: o ambiente de testes do fornecedor, separado da produção.
  • Idempotência: a propriedade de uma operação que mantém o mesmo efeito pretendido quando é repetida.
  • ISO 8583: o padrão de mensagens de transações com cartão, adaptado por cada rede.
  • JSON: o formato de dados com objetos, listas, textos, números, valores lógicos e nulos.
  • JWT: um formato de token com informações assinadas, que pode ser decodificado sem ser validado.
  • Long polling: a consulta em que o servidor segura a resposta até surgir uma novidade ou até um prazo acabar.
  • MDN: a confirmação de recebimento de uma mensagem no AS2.
  • mTLS: o TLS em que o cliente também apresenta um certificado.
  • Mutation: a operação GraphQL de alteração ou de ação.
  • Namespace: o endereço que identifica o vocabulário de um elemento XML.
  • OAuth 2.0: o padrão de autorização por tokens, com fluxos diferentes de obtenção.
  • OData: o protocolo padronizado de consulta e de alteração de dados por HTTP, com opções iniciadas por $.
  • Outbox: a gravação das mensagens a publicar na mesma transação da alteração local.
  • Payload: o conteúdo transportado no corpo de uma mensagem.
  • Polling: a consulta periódica para acompanhar mudanças.
  • Produção: o ambiente que atende as operações reais.
  • Query string: a parte da URL depois do ponto de interrogação, com os parâmetros da consulta.
  • Reconciliação: a comparação entre os registros de dois lados e a regularização das diferenças.
  • Recurso: a coisa do negócio exposta por uma API, como um pedido ou uma cobrança.
  • Refresh token: o código usado em alguns fluxos do OAuth para obter um token novo sem repetir o login.
  • REST: o estilo de arquitetura em que a URL identifica o recurso e o método expressa a operação.
  • RPC: a chamada de um procedimento em outro componente, pelo nome e com parâmetros.
  • Schema: o arquivo que define os elementos, a ordem, os tipos e os tamanhos permitidos em um XML.
  • SOAP: o protocolo de mensagens em XML, com Envelope, Header e Body.
  • Socket: a interface que um programa usa para se comunicar pela rede.
  • SSE: o envio de eventos de texto do servidor ao cliente por uma conexão HTTP.
  • Status HTTP: o código de três dígitos que informa como a camada que respondeu tratou a requisição.
  • TLS: o protocolo que protege a comunicação e permite verificar a identidade dos participantes.
  • Token: o código temporário entregue pelo serviço e apresentado nas chamadas como credencial.
  • Webhook: a chamada que o fornecedor faz ao endereço configurado pelo cliente para avisar sobre um evento.
  • WebSocket: o canal persistente de mensagens nos dois sentidos.
  • WSDL: o documento que descreve as operações e as mensagens de um serviço SOAP.
  • XML: o formato de dados organizado em elementos, atributos e texto, dentro de um elemento raiz.

Para continuar estudando

  • OpenAPI: a leitura de uma descrição de API e a montagem de testes a partir dela.
  • Captura de tráfego: a observação de chamadas reais com ferramentas como o Wireshark e o Fiddler, com cuidado com os dados sensíveis.
  • Assinatura de XML: a canonicalização e a verificação das assinaturas dos documentos fiscais.
  • Arquitetura orientada a eventos: o uso de filas, tópicos e eventos entre vários sistemas.
  • Segurança de APIs: a proteção de tokens, chaves e certificados e os limites de chamadas.

Referências

As referências a seguir reúnem as especificações e a documentação oficial dos principais assuntos de integrações. RFC é o nome dos documentos que definem os protocolos da Internet, e o W3C, a OASIS e o WHATWG são organizações que publicam padrões abertos. A maior parte do material está em inglês, e as páginas da Microsoft abrem no idioma do navegador, em português quando há tradução.

HTTP, URL e formatos

Segurança, credenciais e certificados

Estilos de API

Serviços fiscais e pagamentos

Mensageria, eventos e repetição

Canais sem HTTP, sistemas e ferramentas

No suporte

Qualquer atendimento de integração se organiza em três passos:

  • a descrição da integração pelas cinco perguntas, sobre o canal, o estilo, o formato, o tempo e o acesso;
  • a reconstrução da mesma operação nos registros de cada componente, com os identificadores e os horários;
  • a separação entre o que foi confirmado e o que ainda é hipótese, antes de qualquer correção ou repetição.

Com esses três passos, cada conclusão do atendimento fica apoiada em uma evidência.

Para guardar

  • O status HTTP descreve o atendimento, e o corpo descreve o negócio.
  • Uma conexão aberta não comprova uma operação aceita.
  • A entrega de uma mensagem ou de um arquivo não comprova o processamento.
  • O tempo esgotado à espera da resposta deixa o resultado desconhecido.
  • A repetição segue o contrato, com consulta antes e com a mesma identidade da operação.
  • A credencial não define o estilo, e o JSON não define o REST.
A configuração pede usuário e senha, o log mostra uma mutation de login e, depois, uma resposta com o código 200 e o código de negócio 14. O que é possível concluir?

A integração usa uma operação GraphQL para obter o token. O código 200 informa o atendimento da chamada e não define o resultado do benefício, e o código 14 só ganha significado na tabela do fornecedor.

Uma emissão de nota não tem cStat no registro, e o log mostra uma falha na negociação TLS. O que verificar primeiro?

A negociação daquela tentativa: o certificado do cliente e a chave privada, a cadeia e a validade do certificado do serviço, o relógio da máquina e a versão do TLS. A exceção localiza a etapa, e o histórico da mesma chave de acesso mostra se outras tentativas chegaram à SEFAZ.

Um POST de cobrança terminou em tempo esgotado à espera da resposta, e o usuário quer reenviar. Qual é o caminho?

A consulta da situação da cobrança pelos identificadores e a política de repetição do fornecedor, com a mesma chave de idempotência quando ela existe. A ausência de resposta não comprova que nenhuma cobrança foi criada.

O login no FTP da contabilidade funciona, mas os XMLs do mês não chegam, e o log mostra o código 425. Em qual etapa está a falha?

Na conexão de dados do FTP. A conexão de comandos funciona, e um firewall que libera só a porta 21, ou um modo passivo mal configurado, impede a transferência dos arquivos.

Publicado a partir do Obsidian · FolioPier