Adds docs
This commit is contained in:
294
docs/api.md
Normal file
294
docs/api.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Documentação da API
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
http://<host>:8000
|
||||
```
|
||||
|
||||
## Autenticação
|
||||
|
||||
Todos os endpoints protegidos requerem o header:
|
||||
|
||||
```
|
||||
X-API-Key: <sua-chave-de-api>
|
||||
```
|
||||
|
||||
Respostas de erro de autenticação:
|
||||
|
||||
```json
|
||||
HTTP 403 Forbidden
|
||||
{ "detail": "Invalid API key" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### `GET /health`
|
||||
|
||||
Verifica se o serviço está ativo.
|
||||
|
||||
**Autenticação:** Não requerida
|
||||
|
||||
**Resposta:**
|
||||
```json
|
||||
HTTP 200 OK
|
||||
{ "status": "healthy" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `GET /rules`
|
||||
|
||||
Lista os códigos de procedimento que possuem regras de autorização configuradas.
|
||||
|
||||
**Autenticação:** Não requerida
|
||||
|
||||
**Resposta:**
|
||||
```json
|
||||
HTTP 200 OK
|
||||
{
|
||||
"codes": [
|
||||
"40808130",
|
||||
"40808122",
|
||||
"31303293",
|
||||
"31005470",
|
||||
"41501012",
|
||||
"40901254",
|
||||
"40901262",
|
||||
"..."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /process`
|
||||
|
||||
Processa uma lista de guias de autorização médica. Para cada guia, extrai texto dos documentos anexados e avalia cada serviço solicitado usando o agente de IA.
|
||||
|
||||
**Autenticação:** Requerida (`X-API-Key`)
|
||||
|
||||
**Content-Type:** `application/json`
|
||||
|
||||
#### Corpo da Requisição
|
||||
|
||||
```json
|
||||
{
|
||||
"operadora": {
|
||||
"organizacaoId": "string",
|
||||
"processId": "string"
|
||||
},
|
||||
"guias": [ <lista de objetos guia> ]
|
||||
}
|
||||
```
|
||||
|
||||
#### Estrutura de uma Guia
|
||||
|
||||
```json
|
||||
{
|
||||
"atendimento": {
|
||||
"codigoGuia": "GUIA-2025-0001",
|
||||
"nomeAtendente": "Maria da Silva",
|
||||
"codigoContratante": "UNIMED-SP",
|
||||
"nomeContratante": "Unimed São Paulo",
|
||||
"codigoPlanoContratado": "PLANO-OURO",
|
||||
"planoRegulamentado": "true",
|
||||
"carteirinhaBeneficiario": "1234567890",
|
||||
"nomeBeneficiario": "João Pereira",
|
||||
"dataNascimentoBeneficiario": "1980-05-20",
|
||||
"idadeBeneficiario": 45,
|
||||
"generoBeneficiario": "M"
|
||||
},
|
||||
"guia": {
|
||||
"codigoGuiaLocal": "GUIA-2025-0001",
|
||||
"tipoGuia": "SP/SADT",
|
||||
"nomePrestadorSolicitante": "Dr. Fulano",
|
||||
"nomePrestadorExecutante": "Hospital X",
|
||||
"caraterAtendimento": "eletivo",
|
||||
"tipoAtendimento": "ambulatorial",
|
||||
"codigoCid": "S72.0",
|
||||
"indicacaoClinica": "Paciente com fratura de fêmur."
|
||||
},
|
||||
"servicos": [
|
||||
{
|
||||
"sequenciaServico": 1,
|
||||
"codigoServico": "40808130",
|
||||
"descricaoServico": "Densitometria óssea",
|
||||
"tipoServico": "EXAME",
|
||||
"quantidadeSolicitada": 1,
|
||||
"servicoCobertoPlano": "true",
|
||||
"dataSolicitacao": "2025-11-17T10:15:00"
|
||||
}
|
||||
],
|
||||
"historico": {
|
||||
"quantidadeHistoricoProcedimento365dias": 1,
|
||||
"quantidadeHistoricoProcedimentoTotal": 1
|
||||
},
|
||||
"anexos": [
|
||||
{
|
||||
"codigoGuia": "GUIA-2025-0001",
|
||||
"tipoAnexo": "LAUDO",
|
||||
"descricao": "Laudo do exame.",
|
||||
"nomeArquivo": "laudo.pdf",
|
||||
"idAnexo": "IMG-000001",
|
||||
"mimeType": "application/pdf",
|
||||
"URLAnexo": "s3://meu-bucket/documentos/laudo.pdf"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Campos Importantes
|
||||
|
||||
| Campo | Tipo | Descrição |
|
||||
|--------------------------------|--------|------------------------------------------------------------|
|
||||
| `atendimento.nomeBeneficiario` | string | Nome do paciente (verificado nos documentos pelo agente) |
|
||||
| `servicos[].codigoServico` | string | Código TUSS do procedimento solicitado |
|
||||
| `anexos[].URLAnexo` | string | URI S3 do documento (`s3://bucket/chave`) |
|
||||
| `guia.indicacaoClinica` | string | Indicação clínica usada pelo agente na decisão |
|
||||
|
||||
#### Resposta de Sucesso
|
||||
|
||||
```json
|
||||
HTTP 200 OK
|
||||
{
|
||||
"status": "success",
|
||||
"operadora": {
|
||||
"organizacaoId": "asasasabb-1234-5678-aabb-123456abcdef",
|
||||
"processId": "ihjas1212rjaklpastash"
|
||||
},
|
||||
"guias": [
|
||||
{
|
||||
"atendimento": { ... },
|
||||
"guia": { ... },
|
||||
"servicos": [ ... ],
|
||||
"historico": { ... },
|
||||
"anexos": [
|
||||
{
|
||||
"nomeArquivo": "laudo.pdf",
|
||||
"URLAnexo": "s3://meu-bucket/documentos/laudo.pdf",
|
||||
"textoExtraido": "João Pereira\nDensitometria Óssea\nResultado: ...",
|
||||
"pageCount": 2,
|
||||
"tempoExtracaoSegundos": 3.14
|
||||
}
|
||||
],
|
||||
"avaliacaoAgente": [
|
||||
{
|
||||
"codigoServico": "40808130",
|
||||
"resultado": "Aprovado",
|
||||
"agentOutput": "{\"status\": \"Aprovado\", \"criterio\": \"Mulher acima de 45 anos\", \"documentos\": [{\"nome\": \"laudo.pdf\", \"pertence_ao_paciente\": true}]}",
|
||||
"input_tokens": 1523,
|
||||
"output_tokens": 87,
|
||||
"tempoAgentSegundos": 4.32
|
||||
}
|
||||
],
|
||||
"tempoProcessamento": {
|
||||
"extracaoSegundos": 3.14,
|
||||
"agentSegundos": 4.32,
|
||||
"totalSegundos": 7.86
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Campos da Avaliação (`avaliacaoAgente`)
|
||||
|
||||
| Campo | Tipo | Valores possíveis | Descrição |
|
||||
|------------------------|--------|------------------------------------------|---------------------------------------------------|
|
||||
| `codigoServico` | string | — | Código original conforme enviado na requisição |
|
||||
| `resultado` | string | `"Aprovado"`, `"Reprovado"`, `"SKIPPED"` | Decisão final do agente |
|
||||
| `agentOutput` | string | JSON string | Resposta completa do agente (status + critério + documentos) |
|
||||
| `input_tokens` | int | — | Total de tokens de entrada consumidos |
|
||||
| `output_tokens` | int | — | Total de tokens de saída gerados |
|
||||
| `tempoAgentSegundos` | float | — | Tempo de execução do agente em segundos |
|
||||
|
||||
#### Resultado `"SKIPPED"`
|
||||
|
||||
Retornado quando o código de procedimento não possui regras configuradas no `rules.yaml`:
|
||||
|
||||
```json
|
||||
{
|
||||
"codigoServico": "99999999",
|
||||
"resultado": "SKIPPED",
|
||||
"motivo": "Codigo '99999999' nao encontrado nas regras",
|
||||
"agentOutput": "",
|
||||
"tempoAgentSegundos": 0
|
||||
}
|
||||
```
|
||||
|
||||
#### Erro em Guia Individual
|
||||
|
||||
Se uma guia falhar completamente, ela é substituída por um objeto de erro na lista (as demais guias continuam sendo processadas):
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "mensagem de erro",
|
||||
"guia": "GUIA-2025-0001"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemplo Completo
|
||||
|
||||
### Requisição
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/process \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: sua-chave-aqui" \
|
||||
-d '{
|
||||
"operadora": {
|
||||
"organizacaoId": "org-123",
|
||||
"processId": "proc-456"
|
||||
},
|
||||
"guias": [
|
||||
{
|
||||
"atendimento": {
|
||||
"nomeBeneficiario": "Ana Paula Costa",
|
||||
"idadeBeneficiario": 52,
|
||||
"generoBeneficiario": "F",
|
||||
"carteirinhaBeneficiario": "9876543210"
|
||||
},
|
||||
"guia": {
|
||||
"codigoGuiaLocal": "GUIA-2025-0042",
|
||||
"indicacaoClinica": "Rastreamento de osteoporose pós-menopausa.",
|
||||
"codigoCid": "M81.0"
|
||||
},
|
||||
"servicos": [
|
||||
{
|
||||
"codigoServico": "40808130",
|
||||
"descricaoServico": "Densitometria óssea",
|
||||
"quantidadeSolicitada": 1
|
||||
}
|
||||
],
|
||||
"historico": {},
|
||||
"anexos": [
|
||||
{
|
||||
"nomeArquivo": "pedido_medico.pdf",
|
||||
"URLAnexo": "s3://meu-bucket/guias/pedido_medico.pdf"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
|
||||
## Formato de Saída no S3
|
||||
|
||||
Após cada chamada ao `/process`, os resultados são salvos automaticamente:
|
||||
|
||||
```
|
||||
s3://<OUTPUT_BUCKET>/<API_VERSION>/<codigoGuiaLocal>_<YYYYMMDD_HHMMSS>.json
|
||||
```
|
||||
|
||||
Exemplo:
|
||||
```
|
||||
s3://upflux-doc-analyzer/v1/GUIA-2025-0042_20251117_143022.json
|
||||
```
|
||||
|
||||
O conteúdo é o mesmo objeto da guia processada (JSON completo, incluindo texto extraído e avaliações).
|
||||
Reference in New Issue
Block a user