# A API é só uma parte de uma integração complexa O trabalho difícil costuma começar onde a documentação termina. Os modelos de dados não batem, o sistema antigo precisa conviver com o novo, outra empresa controla uma aprovação e alguém precisa responder pelo que acontece depois da primeira requisição bem-sucedida. ## O conector já funciona. Depender dele ainda não dá Uma integração complexa não é uma requisição saindo de um sistema e chegando a outro. É uma mudança em como dados, responsabilidade e falhas atravessam a empresa. ### O mesmo conceito não significa a mesma coisa nos dois sistemas Os dois lados têm campos para o mesmo dado, mas as regras, o histórico e as exceções não encaixam um a um. ### O antigo e o novo precisam conviver A operação não pode parar para um corte limpo. Contas, registros ou fluxos mudam por etapas sem criar duas verdades concorrentes. ### Parte do prazo está nas mãos de outra empresa Certificação, revisão de segurança, fila de merge ou acesso à produção podem estar fora do seu controle sem sair da sua responsabilidade. ### Alguém vai construir sobre essa integração Endpoint sem documentação é só um endpoint. Quem constrói em cima precisa de exemplos, erros bem definidos e um jeito de descobrir o que aconteceu. ## Um adaptador pode passar nos testes e ainda falhar na operação A maioria das estimativas cobre o cenário em que tudo dá certo entre os endpoints. O risco de produção mora ao redor: histórico, falha parcial, retentativas, revisão externa, corte, monitoramento e a pessoa que responde quando a realidade não cabe no modelo previsto. - Regras de tradução somem dentro do código sem uma decisão de negócio por trás. - Uma migração parcial deixa dois sistemas disputando qual é a fonte confiável. - O go-live é prometido em cima de um calendário que vários times controlam. ## Onde o “é só integrar a API” dá errado A tarefa visível de programação ganha escopo. Tudo que torna o resultado confiável fica implícito. ### Orçar de endpoint a endpoint A estimativa cobre autenticação e payload, mas não quem manda no dado, migração, conciliação ou o fluxo nos dois lados. ### Prometer o calendário externo A engenharia pode estar pronta para revisão no prazo enquanto a aprovação continua com outro time. Tratar os dois como o mesmo compromisso cria uma falsa certeza. ### Deixar a operação para depois Documentação, observabilidade, retentativas, suporte e reversão só viram urgentes quando alguém já depende da integração. ## Desenhar a mudança inteira, não só o conector A gente trata a integração como um produto: implementação, migração, coordenação externa e operação são planejadas juntas, e alguém responde por ela depois do go-live. 1. **Mapear o caminho inteiro.** Identificar quem cria o dado, quem altera, onde vivem as exceções e qual sistema manda em cada etapa. 2. **Provar tradução e falha.** Testar exemplos reais, casos-limite, retentativas e estados parciais antes que volume e dependências tornem tudo caro. 3. **Fazer o corte por etapas.** Mover primeiro um recorte controlado, manter a operação atual disponível e tornar a conciliação explícita antes de expandir. 4. **Operar e explicar.** Entregar monitoramento, logs acionáveis, documentação, exemplos e um responsável claro por incidentes e revisão externa. ## Uma camada de dados única em vez de infraestrutura repetida À medida que a Silo crescia, cada nova rede poderia criar outro indexador, outra API, outro caminho de monitoramento e novas instruções de integração. A Bleu construiu uma camada de dados documentada para todas elas e assumiu sua operação em produção. **[Silo Finance](https://bleu.builders/pt/cases/silo-finance/)** — Um único time respondeu pela camada de dados inteira: indexação, APIs, monitoramento e controle do custo de infraestrutura. > “É fácil trabalhar com vocês. Vocês assumem responsabilidade, o que é raro. Dá pra confiar na entrega, o que também é raro.” > > — Siros, Silo Finance ## Comece pela integração que parece “quase simples” A conversa útil começa fora da lista de endpoints: dados, dependências externas, migração, risco operacional e quem precisa confiar no resultado. - Os sistemas e times dos dois lados da integração - Registros reais, incluindo as exceções que um exemplo limpo esconde - As aprovações externas e o prazo operacional que moldam o trabalho ## Útil quando a integração carrega risco operacional Alguns conectores são realmente simples, e aí você não precisa da gente. O modelo faz sentido quando as decisões ao redor importam tanto quanto os endpoints. ### Faz sentido quando - Vários sistemas ou times discordam sobre dados ou responsabilidade - Migração, convivência, certificação ou revisão externa fazem parte do trabalho - A integração precisa de operação, documentação e monitoramento em produção ### Provavelmente não faz sentido - Um conector comum, com modelos estáveis e documentação completa - Sem histórico, corte, aprovação externa ou consequência operacional - Um responsável interno precisa apenas de uma implementação curta ## Problemas vizinhos - [Tem trabalho de software que fica mais difícil quando você tenta delegar](https://bleu.builders/pt/problems/hard-to-delegate/) - [Mais gente não resolve uma frente de produto que continua sem dono](https://bleu.builders/pt/problems/ownership-not-headcount/) - [O piloto de IA funcionou. A operação ainda não pode depender dele](https://bleu.builders/pt/problems/ai-stuck-before-production/) ## Conte qual é a integração e onde ela emperra hoje.