Um ateliê que virou especialista em ponte por falta de escolha.
Nenhum produto por assinatura vive sozinho. Ele conversa com o ERP do cliente, com o emissor de nota, com o banco e com um sistema que ninguém documentou em 2011.
O trabalho que abriu a casa era simples no papel: ligar um serviço novo ao sistema de estoque que o cliente usava desde 2011. O fornecedor daquele sistema tinha fechado as portas e a documentação eram quatro páginas impressas.
Levamos duas semanas capturando chamadas para entender o que aquilo realmente devolvia. No fim, o comportamento verdadeiro não batia com nenhuma das quatro páginas, e o cliente descobriu junto conosco.
De lá saiu o costume de escrever o contrato de interface antes de tudo e de isolar a ponta estranha atrás de uma camada própria. O produto passa a depender do nosso contrato, não do humor do sistema antigo.
Hoje isso vale também para a interface que o nosso cliente publica: mesma página de contrato, mesmo ambiente de teste, mesmo prazo de aposentadoria para cada versão.
Contrato primeiro
Campos, erros e exemplos aprovados antes de a primeira chamada existir.
Teste antes de produto
Quem integra precisa de ambiente para errar desde o começo.
Ponta estranha isolada
Sistema antigo fica atrás de uma camada nossa, não no meio do código.
Quebra visível cedo
Pendência e erro aparecem na área interna, não no telefonema.
Sete costumes que evitam o remendo de terça-feira
Integração quebra: a outra ponta muda campo, cai, devolve um erro novo. Estes sete costumes não impedem isso — eles fazem a quebra aparecer cedo, em lugar visível, com caminho de volta. Role de lado para ler.
Contrato antes do código
Quais campos entram, quais saem, o que é obrigatório e qual erro cada caso devolve. Uma página, aprovada pelos dois lados.
Ambiente de teste desde cedo
Chaves separadas, dados falsos e um botão para zerar tudo. Quem integra precisa errar à vontade antes de tocar em produção.
Nova tentativa com espera crescente
Quando a outra ponta não responde, a fila tenta de novo em intervalos maiores e guarda o que ficou pendurado.
Aviso automático que pode ser reenviado
Todo evento importante sai como aviso assinado, com registro do que foi entregue e botão para mandar outra vez.
Versão com data de aposentadoria
Interface muda. Quando muda, a versão antiga continua de pé por um prazo anunciado, e quem usa recebe o aviso antes.
Limite de chamadas explicado
Quantas chamadas por minuto, o que acontece ao passar disso e como o sistema avisa que está perto do teto.
Registro que serve para discutir
Cada chamada guarda pedido, resposta e horário por um prazo combinado. Sem isso, «funcionou aqui» é a única prova de qualquer lado.
O que nos perguntam antes de encomendar
Seis respostas, com o que conseguimos sustentar por escrito no contrato.
Pedir um encontroVocês fazem o produto inteiro ou só a camada de integração?
O produto inteiro: definição, telas, código, planos e pagamento, área do assinante, área interna e acompanhamento depois do lançamento. As integrações e a interface pública são o exemplo que usamos porque é onde mais projetos tropeçam.
E se a outra ponta for antiga e mal documentada?
É o caso mais comum. Começamos capturando chamadas reais para descobrir o comportamento de verdade, escrevemos o contrato a partir disso e isolamos essa ponta atrás de uma camada nossa, para que o resto do produto não dependa dela.
Quanto tempo a versão antiga da interface continua funcionando?
O prazo é combinado em contrato, normalmente entre seis e doze meses, com aviso aos usuários no momento em que a versão nova sai.
Como vocês tratam queda de uma integração?
Fila com nova tentativa em intervalos crescentes, pendências visíveis na área interna, aviso por mensagem para quem estiver de plantão e registro de tudo o que ficou para trás. Instabilidade da outra ponta acontece; o que combinamos é quanto tempo até alguém saber.
A documentação fica com quem?
Com a sua empresa, no mesmo repositório do código. A página pública da interface é gerada a partir dela, para não existirem duas verdades.
Como é o pagamento?
Encomenda em três parcelas — contrato de interface aprovado, ambiente de teste no ar e produto em produção. A manutenção de pontes é mensal, com trinta dias de aviso para encerrar.
Diga quais sistemas o seu produto vai ter de encarar
Com a lista das pontas e um exemplo de cada retorno já conseguimos dizer o que é ponte curta, o que é obra e o que é melhor não integrar agora.