Caso 05 Integração de APIs · Diagnóstico visual
DPMS e Equinor: integração de APIs com diagnóstico visual
Assumi integralmente a responsabilidade técnica pelo backend da integração entre o DPMS e a API ISO Work Details da Equinor, do entendimento dos contratos e regras ao envio e à conferência dos dados. Também criei integralmente o jobs-viewer, uma interface para acompanhar relatórios de execução e depurar visualmente o caminho de cada registro entre os sistemas.
Contexto
O fluxo anterior passava por uma planilha Excel. A integração direta exigiu entender como solicitações, escopos e serviços do DPMS se relacionam com ordens de trabalho, especificações e itens da Equinor.
O trabalho foi desenvolvido no contexto do DPMS via Oxeanbits. A autoria individual descrita aqui é da integração e do jobs-viewer, não das plataformas que eles conectam.
Problema
Não bastava copiar campos entre endpoints. Era preciso conciliar contratos, catálogos, fases e regras de negócio diferentes, mantendo referências que permitissem voltar do destino ao registro de origem.
Uma resposta HTTP de sucesso não explica, sozinha, o que entrou, o que ficou de fora ou por que os valores retornados diferem. A investigação precisava mostrar o percurso dos dados e as causas de cada estado.
Minha responsabilidade
Fui o responsável por toda a parte técnica do backend da integração, das decisões técnicas à implementação e à verificação do fluxo.
Estudei os contratos das APIs e o fluxo anterior em Excel, defini mapeamentos e implementei o caminho de autenticação, leitura, transformação, envio e conferência do retorno.
Desenvolvi integralmente o visual do jobs-viewer, com resumo de cada execução, grafo entre origem e destino, legenda de estados e detalhes para investigar registros e falhas.
A interface consulta as APIs para inspecionar os nós do grafo e exibe status HTTP, corpo da resposta e divergências de valores. Os relatórios dos jobs permanecem armazenados e autorizados pelo DPMS.
Decisão
Preservar referências determinísticas para relacionar especificações e itens aos registros do DPMS, em vez de perder a identidade durante a transformação dos dados.
Tratar a leitura de retorno como parte da verificação e transformar os relatórios de execução em um grafo legível, com estados e motivos explícitos.
Alternativas e trade-offs
Análise atual, escrita para este site. Não é um registro das alternativas avaliadas na época.
- Referências estáveis ajudam na reconciliação, mas não tornam qualquer operação idempotente: um POST que acrescenta especificações exige cuidado com reenvios.
- O grafo foi desenhado para o contrato de origem e destino desta integração. Essa restrição mantém o visual simples e útil para investigação, sem exigir um motor genérico de grafos.
Implementação
Integração e diagnóstico foram desenvolvidos em conjunto para tornar o fluxo rastreável.
Contratos e mapeamento
Reconciliação dos modelos de dados, catálogos e regras, com referências de origem preservadas nos itens enviados.
Comunicação entre sistemas
Autenticação para acesso às APIs, transformação dos dados e envio de especificações, seguido de leitura para conferir o resultado.
Relatórios e grafo
Resumo da execução e conexões entre solicitações, escopos, serviços e os registros correspondentes na Equinor. Estados distinguem inclusões, exclusões, bloqueios e registros órfãos.
Investigação visual
Inspeção dos registros nas APIs, respostas HTTP e diferenças entre valores do DPMS e da Equinor. O visual foi implementado com HTML, CSS e SVG, sem JavaScript no viewer.
Visualização
Resultado
O repositório de descoberta registra um ciclo validado no ambiente de teste: envio de estimativas de isolamento, leitura das especificações criadas e limpeza verificada das referências de teste.
O jobs-viewer transforma relatórios dos jobs em uma visão navegável do fluxo, com contexto para investigar falhas e divergências. Essa evidência não equivale à validação de todos os cenários nem à confirmação de uma implantação em produção.