Solus Proxy — Documentação

Autenticação

Acesso liberado por IP

As rotas de dados são liberadas apenas para o IP autorizado do sistema consumidor. Vindo desse IP, a chamada é direta — sem token. Qualquer outra origem recebe 403. As rotas /docs, /swagger e /health são públicas.

Do IP autorizado: acesso direto, sem header de token
Outra origem: 403 · acesso negado: IP não autorizado
Liberar novo IP: solicitar à equipe de infra (configuração no servidor)

Segurança

Como os dados são protegidos

O proxy foi desenhado para tratar dado sensível de saúde (LGPD). Camadas em vigor:

Transporte: HTTPS/TLS obrigatório — todo acesso por http é redirecionado para https (certificado com renovação automática)
Acesso: rotas de dados liberadas apenas para o IP autorizado do consumidor (bloqueio no nginx pelo IP real da conexão); demais origens recebem 403
Credenciais Solus: login, senha e token do software ficam só no servidor — o cliente nunca os recebe; o proxy autentica internamente
Dado sensível: o hash de senha que a Solus devolve no cadastro é removido antes de responder e de registrar
Auditoria: toda requisição e todo retorno são registrados (horário de São Paulo), com segredos redigidos — retenção de 6 meses
Servidor: acesso administrativo só por chave SSH; serviço roda sem privilégios de root; atualizações de segurança automáticas

Reforços recomendados para produção: chaves por consumidor, restrição por IP e limite de requisições (anti-abuso). Sob avaliação.

Endpoints

Consultas disponíveis

Todos são GET e devolvem JSON. Teste interativamente no Swagger UI.

GET/paciente/:cpfprincipal

Busca o beneficiário pelo CPF e devolve os dados dele — a consulta de elegibilidade. CPF com ou sem pontuação. A resposta traz { cpf, total, beneficiarios[] }; cada beneficiário tem resumo (campos-chave já decodificados) e completo (100% dos campos retornados pela Solus).

CPFs de teste (APAS): 92307354859 (APAS TESTE — titular) e 19874159065 (APAS TESTE ESPOSO — dependente).

Parâmetro	Onde	Obrigatório	Descrição
cpf	rota	sim	CPF do beneficiário (11 dígitos)
situacao	query	opcional	filtra pela situação

# buscar paciente por CPF
# a partir do IP autorizado — sem token
curl "https://apasapi.healthplatformsuite.com.br/paciente/92307354859"

# resposta:
# { "cpf": "92307354859", "total": 1,
#   "beneficiarios": [ { "resumo": {…}, "completo": {…104 campos…} } ] }

GET/elegibilidade/:cpfatalho

Retorna somente o registro ATIVO (filtra situacao=A na APAS) e inclui elegivel: true/false. total:0 / elegivel:false = não há cadastro ativo para o CPF. Use para checar elegibilidade; use /paciente/:cpf para todos os registros (inclusive cancelados).

GET/beneficiario/:id

Dados completos pelo ID (vem no retorno da busca por CPF). ?incluir=cobertura,status traz blocos extras.

GET/carteira/:codigo

Busca pelo número da carteira, quando não há CPF.

GET/auth/checkdiagnóstico

Verifica se o proxy autentica na Solus. ok:true quando o token está válido.

GET/health

Sinal de vida. Sem chave, não chama a Solus.

Retornos

O que esperar

200: Sucesso — dados do beneficiário (JSON da Solus)
400: CPF inválido (≠ 11 dígitos)
401: Chave do proxy errada ou token Solus expirado
502: Falha ao falar com a Solus — ver campo detalhe

Erros sempre em JSON: { "erro": "...", "detalhe": "...", "dica": "..." }.