AI-upflux-docprocessor/docs/api.md

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:

HTTP 403 Forbidden
{ "detail": "Invalid API key" }

---

Endpoints

GET /health

Verifica se o serviço está ativo.

Autenticação: Não requerida

Resposta:

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:

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

{
  "operadora": {
    "organizacaoId": "string",
    "processId": "string"
  },
  "guias": [ <lista de objetos guia> ]
}

Estrutura de uma Guia

{
  "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

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:

{
  "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):

{
  "error": "mensagem de erro",
  "guia": "GUIA-2025-0001"
}

---

Exemplo Completo

Requisição

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).