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.

Por Lyntev. Atualizado a .
Cerca de 5 minutos de leitura.

Um pedido com continuidadeA mesma referência acompanha o pedido e evita duplicações.

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.

Escolha a fonte responsável por cada campo
Campo do exemploFonte responsávelDestino
order_idSistema comercialReferência externa do trabalho
service_codeCatálogo aprovadoTipo de trabalho
requested_datePedido confirmadoPreferência, sujeita a planeamento
work_statusSistema operacionalInformaçã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.

Contrato fictício: entrada e resultado apresentados em conjuntoJSON
{
  "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.

Aprove estados e recuperação com provas concretas
TesteProva de aprovação
Mesmo evento duas vezesUma operação de negócio e resultado reutilizado
Resposta perdidaReconciliação encontra o resultado sem duplicar
Revisão anterior chega depoisEstado atual preservado conforme a política
Várias páginas de dadosTodas as referências esperadas conferidas
Acesso a outra contaOperaçã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.