Como integrar sistemas por API: contrato, estados e recuperação
Integrar sistemas por API permite trocar dados e executar operações através de interfaces definidas. O trabalho fica completo quando é possível explicar a origem de cada valor, o estado de cada operação e a recuperação após falhas. Este guia prepara uma ligação verificável entre dois sistemas, com um exemplo pequeno e critérios para aprovar a entrega.
No final, consegue:
- Especificar entrada, saída e estados
- Distinguir eventos de sincronização completa
- Testar repetição, acesso e recuperação
Escolha a fonte responsável por cada campo
Descreva o percurso em termos de negócio: «uma ordem confirmada no sistema comercial cria um trabalho no sistema operacional». Identifique a referência comum e a direção dos dados. Se ambos os sistemas podem alterar a mesma data, determine qual prevalece e como um conflito chega a revisão.
Faça um mapa por campo, não apenas por aplicação. O sistema comercial pode ser responsável pelo pedido e o operacional pelo estado de execução. Evite uma sincronização bidirecional genérica que faz cada mudança voltar ao ponto de origem. Defina quais alterações são relevantes e quando é necessário consultar o estado atual.
| Campo do exemplo | Fonte responsável | Destino |
|---|---|---|
| order_id | Sistema comercial | Referência externa do trabalho |
| service_code | Catálogo aprovado | Tipo de trabalho |
| requested_date | Pedido confirmado | Preferência, sujeita a planeamento |
| work_status | Sistema operacional | Informação de acompanhamento |
Escreva o contrato antes de ligar credenciais
Registe operações, campos, tipos, valores permitidos, respostas e erros. A OpenAPI define uma forma de descrever interfaces HTTP para pessoas e ferramentas. Se o fornecedor disponibiliza essa descrição, confira a versão e os exemplos; se não, documente o contrato mínimo da ligação. A documentação não substitui o ensaio da operação real.
Defina o significado de ausente, vazio e nulo. Uma propriedade omitida pode significar «não alterar», enquanto null pode significar «limpar», conforme a API. Especifique também formatos de datas, unidades, limites e campos calculados. Estas decisões evitam que uma sincronização apague informação apenas porque um sistema não a enviou.
Use um pedido fictício com resultado esperado
No exemplo, a ordem ORD-104 está confirmada e deve originar um trabalho. O evento tem identificador próprio e uma revisão da ordem. A data pedida é uma preferência, não uma reserva automática. Os nomes e o formato abaixo são uma proposta didática; têm de ser adaptados às APIs efetivamente contratadas.
O processamento esperado valida o evento, procura a referência externa, cria ou atualiza o rascunho permitido e guarda o identificador do trabalho. Repetir o mesmo evento deve devolver o resultado já registado. Uma revisão posterior pode alterar campos autorizados; uma revisão antiga recebida depois não deve substituir o estado mais recente.
{
"entrada": {
"schema_version": 1,
"event_id": "evt-demo-104-3",
"event_type": "order.confirmed",
"order": {
"order_id": "ORD-104",
"revision": 3,
"service_code": "MANUTENCAO",
"requested_date": "2026-11-25"
}
},
"resultado": {
"event_id": "evt-demo-104-3",
"processing_status": "completed",
"work_id": "TRAB-208",
"work_status": "draft"
}
}Autorize a operação e o registo concreto
Guarde credenciais no componente servidor e atribua apenas as operações necessárias. Separe ambientes de teste e produção e defina como rodar credenciais sem perder controlo da ligação. Os registos técnicos devem permitir investigar por referência sem copiar segredos ou dados pessoais em excesso.
A autenticação identifica quem faz o pedido; a autorização decide se pode agir sobre aquele registo. A OWASP destaca a necessidade de verificar acesso ao objeto quando uma API recebe o seu identificador. Teste uma referência que pertence a outra conta fictícia: uma credencial válida não deve abrir todos os dados por consequência.
Combine eventos com uma forma de conferir o conjunto
Um webhook informa sobre um acontecimento; uma consulta obtém dados segundo o contrato da API. Verifique autenticidade das notificações com o mecanismo do fornecedor antes de confiar no conteúdo. A Stripe documenta, por exemplo, verificação de assinaturas, repetições e ausência de garantia de ordem na entrega. Confirme o comportamento do seu fornecedor em vez de o presumir igual.
A reconciliação periódica compara referências e estados para encontrar diferenças que um evento perdido deixou para trás. Ao consultar listas, percorra a paginação: a primeira resposta pode conter apenas parte dos registos, como mostra a documentação do GitHub. Registe o cursor ou ponto de continuação e trate alterações durante a leitura conforme as garantias da API.
Distinga uma falha temporária de um pedido inválido
Uma ligação interrompida pode deixar o resultado incerto: o destino pode ter gravado antes de a resposta se perder. Use a referência e o mecanismo de idempotência disponibilizado, confirmando o âmbito e o prazo de validade. A Stripe documenta esse mecanismo; não significa que qualquer API aceite a mesma chave ou tenha as mesmas garantias.
Limite tentativas, respeite indicações de espera do fornecedor e envie falhas persistentes para revisão. Uma fila pode voltar a entregar uma mensagem, como acontece no modelo de entrega pelo menos uma vez documentado pela Cloudflare. Por isso, o consumidor também precisa de reconhecer repetições. Um campo inválido não se corrige repetindo indefinidamente o mesmo pedido.
Aprove estados e recuperação com provas concretas
No teste de aceitação, confirme que ORD-104 gera um único TRAB-208 mesmo após repetição e que o estado completed se refere ao processamento da integração, enquanto draft se refere ao trabalho. São estados de entidades diferentes. Depois simule falha, retome e compare os registos nos dois lados.
Inclua versão antiga, evento fora de ordem, limite de utilização, credencial revogada e lista com várias páginas. Defina responsável por alertas e alterações do contrato. Quando uma API anuncia uma descontinuação, a atualização deve repetir estes ensaios antes de substituir a ligação utilizada pela equipa.
| Teste | Prova de aprovação |
|---|---|
| Mesmo evento duas vezes | Uma operação de negócio e resultado reutilizado |
| Resposta perdida | Reconciliação encontra o resultado sem duplicar |
| Revisão anterior chega depois | Estado atual preservado conforme a política |
| Várias páginas de dados | Todas as referências esperadas conferidas |
| Acesso a outra conta | Operação recusada sem alteração de dados |
Ficha para o seu projeto
Percurso de negócio e resultado esperado: Sistemas, ambientes e responsáveis: Campos e fonte responsável por cada um: Contrato, versão, entrada, saída e erros: Referência comum, evento e revisão: Permissões e conservação dos registos técnicos: Autenticidade dos eventos: Paginação, continuidade e reconciliação: Idempotência, tentativas e falhas persistentes: Estados de processamento e de negócio: Casos de teste e evidência dos dois lados: Alertas, manutenção e procedimento de recuperação:
Fontes e critérios
Conteúdo elaborado com apoio de IA e pesquisa em fontes técnicas, com revisão dos exemplos e cálculos aplicáveis. As referências apoiam as decisões do guia; os exemplos identificados como fictícios servem para experimentar o método.