# Teste da unidade — API CPC / UPA Santo Antônio

Este ambiente usa exclusivamente dados fictícios e contrato SQL v3. O endereço
base é informado junto com a credencial privada. Use sempre **HTTPS**. A API é
voltada a integração via Postman ou sistema consumidor; não possui tela de login.
Não envie dados reais para este ambiente.

## Arquivos disponíveis

- `/openapi.json`: todos os endpoints, parâmetros, campos e respostas.
- `/schemas.json`: JSON Schema 2020-12; modelos em `$defs`.
- `/postman_collection.json`: coleção completa, sem segredo.
- `/manual.md`: este manual.

O arquivo privado `pacote-unidade.zip`, entregue separadamente pelo responsável,
contém esses arquivos, `credenciais.json` e o ambiente Postman com a credencial.
Não publique nem compartilhe esse pacote em canais abertos. Importe a coleção e
o ambiente no Postman, selecione o ambiente e execute **Emitir token** antes das
consultas. A coleção grava o token automaticamente. Evite sincronizar a credencial
em espaços públicos do Postman.

## Autenticação

`POST /api/v1/auth/token`, com `Content-Type: application/json`:

```json
{"client_id":"upa_santoantonio_dev","client_secret":"SEGREDO_ENTREGUE_SEPARADAMENTE"}
```

A resposta contém `access_token`, `token_type: Bearer` e `expires_in: 900`.
Nas demais chamadas envie `Authorization: Bearer SEU_TOKEN`. O token vale
15 minutos; emita outro quando expirar. `GET /api/v1/auth/me` confirma a identidade,
o ambiente e as permissões. Não coloque token nem segredo na URL.

Há um limite de **20 tentativas de emissão por minuto por endereço IP** neste
ambiente. Resposta 429 inclui `Retry-After`, em segundos. Reaproveite o token
durante sua validade. Todas as consultas clínicas exigem autenticação.

## Rotas e exemplos completos

Todos os caminhos abaixo são relativos ao endereço base, sem barra final.

| Método | Caminho | Uso |
| --- | --- | --- |
| GET | `/health` | Saúde HTTP; não consulta o banco; sem autenticação |
| POST | `/api/v1/auth/token` | Emissão do token |
| GET | `/api/v1/auth/me` | Identidade autenticada |
| GET | `/api/v1/pacientes/cpf/52998224725` | Pacientes por CPF, com histórico |
| GET | `/api/v1/pacientes/cns/700000000000000` | Pacientes por CNS, com histórico |
| GET | `/api/v1/pacientes/busca?nome=PACIENTE%20FICTICIO%20SEM%20DADOS%20REAIS&data_nascimento=1990-01-15` | Nome e nascimento, ambos obrigatórios |
| GET | `/api/v1/atendimentos/910001` | Atendimento e histórico do paciente |
| GET | `/api/v1/unidades/0000000/atendimentos` | Snapshot de atendimentos ativos ou encerrados nas últimas 24 horas |
| GET | `/api/v1/unidades/0000000/internacoes` | Snapshot de internações |
| GET | `/api/v1/unidades/atendimentos?cnes=0000000&data_atendimento=2026-10-20` | Atendimentos pela data da entrada |
| GET | `/api/v1/unidades/internacoes?cnes=0000000&data_internacao=2026-10-21` | Internações pela data da entrada |

Nas duas últimas rotas, o parâmetro de data pode ser substituído por
`data_inicial=2026-10-20&data_final=2026-10-21`. Não misture data única e período.
O intervalo máximo é de 31 dias. Use datas `AAAA-MM-DD`.

Paginação: `pagina=1&limite=10`, limite máximo 20. Consultas por paciente e
número também aceitam `pagina_historico=1&limite_historico=10`. Siga
`pagination.tem_proxima`; não presuma que a primeira página contém tudo.

Os códigos fictícios são pacientes `900001`, `900002`, `900003`, atendimentos
`910001` e `910002`, CNES `0000000`. CPF `11144477735` exemplifica paciente sem
histórico. Há homônimos/duplicidades na massa fake: trate `data` como lista.
`meta.dados_ficticios` deve ser `true` e `meta.versao_contrato` deve ser `3`.
Campos sem informação podem ser `null`. Evoluções, medicações e procedimentos
constam nos eventos, conforme os schemas; não existem rotas separadas de escrita.

As datas da massa são fixas, de 20 e 21/10/2026. O snapshot de atendimentos pode
retornar lista vazia depois da janela de 24 horas; consulte a data fixa para um
teste positivo. A internação fictícia ativa continua disponível no snapshot.
Ausência de resultado é resposta 200 com `data: []`, sem criar pacientes reais.

## Erros e coleta de evidências

| Código | Significado e ação |
| --- | --- |
| 400 | Parâmetro/JSON inválido; consulte OpenAPI |
| 401 | Credencial/token ausente, inválido, expirado ou revogado |
| 403 | Permissão insuficiente ou acesso bloqueado pelo proxy |
| 404 | Rota inexistente |
| 405 | Método não permitido |
| 413 | Corpo ou resposta acima do limite; reduza a página quando aplicável |
| 415 | Emita token usando `application/json` |
| 429 | Aguarde o tempo indicado por `Retry-After` |
| 500/503 | Falha de serviço/contrato; informe o responsável |

Erros da aplicação usam `error.status`, `error.message` e `error.request_id`.
Bloqueios do proxy/Cloudflare podem ter outro formato. Ao relatar falha, informe
horário, método, caminho fictício, status e cabeçalho `X-Request-ID`, quando
disponível. Remova `Authorization`, `client_secret` e tokens das evidências.

## Disponibilidade do teste

Endereço base: **https://api-prontuario.cpcbrasil.com**.

O serviço está instalado no servidor CPC, com Apache, PHP 8.4-FPM e certificado
próprio emitido pelo Certbot. O acesso não depende da máquina de desenvolvimento
nem do túnel temporário. HTTP redireciona para HTTPS. A credencial deste servidor
é própria e está no pacote privado atualizado.

Este ambiente contém somente dados fictícios e serve à validação funcional da
integração. A homologação clínica e a validação de carga no destino são etapas
separadas.