HI — Histórias de Integração (B)

Ponto de vista: ESP — Especificação · Pasta: ESP (Especificação)/02-historias/HI/

O que é

Requisitos de integração com sistemas externos: APIs externas, sistemas legados, barramentos de mensageria, webhooks, importação e exportação de dados. Toda integração relevante deve ter uma HI correspondente.

Como usar

Elabore e refine conforme Regras de validação e o fluxo de vida das histórias.
Critérios de aceite mensuráveis; respeite HNI e demais histórias de nível superior quando aplicável.
Monorepo: ESP (Especificação)/02-historias/<TIPO>/ (pasta deste tipo de história).

Exemplo

---
id: ESP-HI-0001
tipo: HI
titulo: "Integração com Gateway de Autenticação gov.br"
status: rascunho
autor: fulano.de.tal
data: 2026-04-11
versao: "1.0"
sistema-externo: "gov.br — Acesso Digital"
protocolo: REST
formato: JSON
frequencia: "Tempo real"
disponibilidade-exigida: "99,5% em horário comercial"
hs-vinculadas:
  - ESP-HS-0001
hne-vinculadas: []
criticidade: alta
criterios-de-aceite:
  - "Integração via OAuth2 com timeout de 5 segundos"
  - "Fallback local em caso de indisponibilidade do gov.br"
  - "Toda chamada registrada em log de auditoria"
---

Tipos de integração

Tipo	Protocolo	Quando usar
API REST	HTTP/JSON	Integrações síncronas em tempo real
API SOAP	HTTP/XML	Sistemas legados com contratos SOAP
Mensageria	AMQP, Kafka	Integrações assíncronas e de alto volume
Arquivo	SFTP, S3	Transferência em lote (batch)
Webhook	HTTP/JSON	Notificações de eventos externos
Barramento	ESB/API Gateway	Múltiplos sistemas via ponto central

Requisito obrigatório: camada de abstração

Onde se aplica

Destino	Link
Framework ESP	/framework/esp/
Índice ESP	/artefatos/esp/
Fluxo de vida	/artefatos/esp/fluxo-de-vida/
IMP	/framework/imp/

Trânsito entre artefatos

Artefato	Direção
HS	HS identifica a necessidade de integração; HI detalha os requisitos
IMP-API	Contrato de API gerado a partir das HI
INF-HIOP	Infraestrutura de integração operacional
GDA	Dados trocados nas integrações precisam de classificação
PDP	Dados pessoais em integrações requerem avaliação de impacto

← HIVC · Fluxo de Vida →