SusConecta — Hub de Integração para Sistemas Externos
Bem-vindo ao SusConecta Integration Hub. Este espaço foi desenvolvido para engenheiros de software, arquitetos de soluções e equipes técnicas que precisam integrar os dados públicos padronizados do Sistema Único de Saúde (SUS) às suas aplicações e plataformas.
🎯 Para Quem é Esta Documentação?
A documentação está estruturada para atender dois perfis principais de desenvolvimento:
- Sistemas Existentes (Brownfield): Aplicações corporativas, prontuários eletrônicos (PEP), ERPs de saúde, ferramentas de BI ou portais já em produção que desejam incorporar métricas e dados territoriais do SusConecta sem refatorações invasivas.
- Novas Aplicações (Greenfield): Novos softwares em fase de concepção e desenvolvimento, cuja arquitetura já pode ser desenhada adotando as melhores práticas de desacoplamento, tipagem estrita, isolamento de segredos e caching orientado a releases.
🗺️ Mapa de Navegação do Hub de Integração
1. Arquitetura & Fundamentos
- Arquitetura Recomendada: Topologia ideal de comunicação, desacoplamento frontend/backend e proteção de credenciais.
- Segurança no Frontend: Por que nunca expor API Keys no navegador/mobile e como criar um BFF (Backend-For-Frontend).
- Variáveis de Ambiente: Padrão seguro de configuração e gerenciamento de secrets via
.env. - Design Orientado a Releases: Semântica de competências (
reference_period), statusFINAL/PRELIMINARYe proveniência. - Tratamento Semântico de Ausência de Dados (No-Data): A distinção fundamental entre
0,NO_OFFICIAL_DATA,NOT_YET_PUBLISHEDeOUT_OF_SCOPE.
2. Implementação por Linguagem & Framework
- Construindo um Cliente de API Reutilizável: Padrão de design para encapsular chamadas HTTP, retries e autenticação.
- Guias por Linguagem:
- Integração com Frameworks Populares: Exemplos práticos para Next.js, Express, NestJS, FastAPI, Django, Laravel, ASP.NET Core e Spring Boot.
3. Tutoriais Práticos, Receitas & Ferramentas
- Do cURL ao Código de Produção: Passo a passo da primeira requisição manual até um client tipado e resiliente.
- Guia de Testes com Postman: Importação do OpenAPI 3.1, configuração de variáveis de ambiente e testes automatizados.
- Receitas Prontas para o Mundo Real: 12 receitas com payloads completos e exemplos de consumo (leitos, equipamentos, produção ambulatorial, despesas municipais, comparações multiestado GO+MT).
- Casos de Uso de Aplicação: Dashboards municipais, auditoria do SUS, planejamento orçamentário e healthtechs.
4. Resiliência, Caching & Governança
- Estratégias de Cache: Caching orientado ao ciclo de publicação de dados oficiais do governo (sem TTLs arbitrários).
- Padrões de Persistência em Banco Próprio: Quando persistir snapshots e quais metadados canônicos preservar.
- Tratamento de Erros e Códigos HTTP: Guia definitivo para tratar
2xx,400,401,403,404,429e5xx. - Geração de Tipos e Schemas a partir do OpenAPI: Automatizando SDKs e interfaces TypeScript/Python via OpenAPI Generator.
- Integração Segura contra Mudanças de Versão: Como consumir endpoints com versionamento estrito (
/v1) e compatibilidade futura. - Ambiente de Desenvolvimento Local: Como mockar fixtures e testar integrações sem dependências externas frágeis.
- Checklist de Produção: 11 verificações obrigatórias antes de habilitar a integração em produção.
- Aplicação de Exemplo Completa: Projeto Node.js + TypeScript funcional de ponta a ponta pronto para execução.
⚡ Contrato Canônico da API
| Propriedade | Valor Canônico |
|---|---|
| API Host Produção | https://api.susconecta.com.br |
| Base URL (v1) | https://api.susconecta.com.br/v1 |
| Protocolo | HTTPS Obrigatório (TLS 1.3) |
| Formato de Troca | JSON (application/json) |
| Autenticação | Authorization: Bearer <SUSCONECTA_API_KEY> |
| Contrato OpenAPI 3.1.0 | [docs/openapi/openapi.yaml](file:///docs/openapi/openapi.yaml) |
| Escopo Territorial Ativo | Goiás (GO - 246 municípios) + Mato Grosso (MT - municípios piloto homologados: 5106174, 5107941) |
IMPORTANT
Princípio Zero Invenção: Todas as métricas, domínios e parâmetros documentados neste hub refletem 100% dos endpoints e tabelas homologados na API do SusConecta. Nenhum endpoint ou método fictício é apresentado.