Introdução

Bem-vindo à documentação da API MedReader. Esta API REST permite que você processe prescrições médicas de forma inteligente, extraindo informações estruturadas de imagens e PDFs.

Base URL

https://api.medreader.com

Formato de Dados

Todas as requisições e respostas utilizam JSON, exceto o upload de arquivos que utiliza multipart/form-data.

Autenticação

A API utiliza autenticação baseada em JWT (JSON Web Token). Você deve primeiro obter um token através do endpoint de login e incluí-lo no header Authorization de todas as requisições subsequentes.

POST /api/v1/auth/login

Descrição

Autentica um usuário e retorna um token JWT para acesso aos demais endpoints.

Headers

Content-Type: application/json
X-Tenant-ID: {seu-tenant-id}

Request Body

{
  "email": "usuario@exemplo.com",
  "password": "sua-senha-segura"
}

Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "João Silva",
    "email": "usuario@exemplo.com",
    "phone": "+5511999999999"
  }
}

Possíveis Erros

Código Error Descrição
400 validation_error Email ou senha não fornecidos ou inválidos
401 invalid_credentials Email ou senha incorretos
401 tenant_invalid Tenant ausente ou inválido
429 too_many_attempts Muitas tentativas de autenticação falhadas

Endpoints

Folders

Gerencie pastas para organizar suas prescrições médicas.

POST /api/v1/folders

Descrição

Cria uma nova pasta para organizar prescrições.

Permissões Necessárias

Este endpoint requer autenticação via token JWT. O usuário deve estar autenticado e ter acesso ao tenant especificado.

Normalização de Nome

O nome da pasta é automaticamente normalizado para formato URL-safe:

  • Acentos são removidos (ã → a, é → e, ç → c)
  • Convertido para minúsculas
  • Espaços e caracteres especiais são substituídos por hífen (-)
  • Múltiplos hífens são reduzidos a um único
  • Hífens no início e fim são removidos

Exemplo: "Pacientes Cardiologia" → "pacientes-cardiologia"

Exemplo: "Documentos Ações 2025" → "documentos-acoes-2025"

Headers

Content-Type: application/json
Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Request Body

{
  "folder_name": "Pacientes Cardiologia",
  "parent_folder_id": "550e8400-e29b-41d4-a716-446655440000"
}

Nota: O nome será normalizado para "pacientes-cardiologia" automaticamente.

Nota: O campo parent_folder_id é opcional. Se não fornecido, a pasta será criada na raiz.

Response (201 Created)

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "folder_name": "pacientes-cardiologia",
  "parent_folder_id": "550e8400-e29b-41d4-a716-446655440000",
  "full_path": "pacientes/pacientes-cardiologia",
  "created_at": "2024-01-18T14:30:00Z",
  "updated_at": "2024-01-18T14:30:00Z"
}

Possíveis Erros

Código Error Descrição
400 validation_error Nome da pasta é obrigatório
401 unauthorized Usuário não autorizado
409 folder_name_duplicate Já existe uma pasta com este nome no mesmo nível
409 parent_folder_not_found Pasta pai não encontrada
GET /api/v1/folders/:folder-id

Descrição

Busca informações detalhadas de uma pasta específica, incluindo subpastas e contagem de arquivos.

Permissões Necessárias

Este endpoint requer autenticação via token JWT. O usuário deve estar autenticado e ter acesso ao tenant especificado.

Headers

Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Path Parameters

  • folder-id - ID da pasta (UUID)

Response (200 OK)

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "folder_name": "pacientes-cardiologia",
  "parent_folder_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-18T14:30:00Z",
  "updated_at": "2024-01-18T14:30:00Z",
  "full_path": "pacientes/pacientes-cardiologia",
  "prescription_files_count": 15,
  "child_folders": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "folder_name": "janeiro-2024",
      "created_at": "2024-01-18T15:00:00Z",
      "updated_at": "2024-01-18T15:00:00Z",
      "full_path": "pacientes/pacientes-cardiologia/janeiro-2024",
      "prescription_files_count": 8
    }
  ]
}

Possíveis Erros

Código Error Descrição
400 bad_request ID da pasta é obrigatório
401 unauthorized Usuário não autorizado
404 folder_not_found Pasta não encontrada

Prescrições

Faça upload e consulte resultados de análise de prescrições médicas.

POST /api/v1/prescription-files

Descrição

Faz upload de um arquivo de prescrição médica para processamento. O arquivo será processado de forma assíncrona e o resultado será enviado via webhook.

Permissões Necessárias

Este endpoint requer autenticação via token JWT. O usuário deve estar autenticado e ter acesso ao tenant especificado.

Headers

Content-Type: multipart/form-data
Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Form Data

  • folder_id - ID da pasta onde o arquivo será armazenado (UUID, obrigatório)
  • file - Arquivo da prescrição (obrigatório)

Formatos Suportados

  • PDF (application/pdf)
  • JPEG (image/jpeg)
  • PNG (image/png)
  • TIFF (image/tiff)

Response (202 Accepted)

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "folder_id": "660e8400-e29b-41d4-a716-446655440001",
  "file_path": "prescriptions/2024/01/18/prescription-123.pdf",
  "file_type": "application/pdf",
  "file_size": 245678,
  "original_filename": "prescricao-paciente.pdf",
  "processed": false,
  "uploaded_at": "2024-01-18T16:00:00Z",
  "message": "File uploaded successfully and will be processed asynchronously"
}

Possíveis Erros

Código Error Descrição
400 bad_request Arquivo ou folder_id não fornecido, formato não suportado ou arquivo vazio
401 unauthorized Usuário não autorizado
GET /api/v1/prescriptions/:prescription-id/result

Descrição

Busca o resultado detalhado de análise de uma prescrição específica pelo seu ID.

Permissões Necessárias

Este endpoint requer autenticação via token JWT. O usuário deve estar autenticado e ter acesso ao tenant especificado.

Headers

Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Path Parameters

  • prescription-id - ID da prescrição (UUID)

Response (200 OK)

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "created_at": "2024-01-18T16:00:00Z",
  "prescription_confidence_score": 95,
  "prescription_confidence_notes": "Prescrição clara e legível",
  "status": "completed",
  "folder_id": "660e8400-e29b-41d4-a716-446655440001",
  "folder_fullpath": "pacientes/pacientes-cardiologia"
}

Campos da Resposta

Campo Tipo Descrição
id string ID único da prescrição
created_at timestamp Data e hora de criação do resultado
prescription_confidence_score integer Pontuação de confiança da leitura (0-100), pode ser null
prescription_confidence_notes string Notas sobre a confiança da leitura, pode ser null
status string Status do processamento (processing, completed, error)
folder_id string ID da pasta onde a prescrição está armazenada
folder_fullpath string Caminho completo da pasta

Possíveis Erros

Código Error Descrição
400 bad_request ID da prescrição é obrigatório
401 unauthorized Usuário não autorizado
404 prescription_file_not_found Prescrição não encontrada
GET /api/v1/prescriptions/results?folder-id=:folder-id

Descrição

Lista todos os resultados de análise de prescrições de uma pasta específica.

Permissões Necessárias

Este endpoint requer autenticação via token JWT. O usuário deve estar autenticado e ter acesso ao tenant especificado.

Headers

Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Query Parameters

  • folder-id - ID da pasta (UUID, obrigatório)

Response (200 OK)

{
  "folder_id": "660e8400-e29b-41d4-a716-446655440001",
  "folder_fullpath": "/Pacientes/Pacientes Cardiologia",
  "results": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "status": "completed"
    },
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440005",
      "status": "processing"
    },
    {
      "id": "bb0e8400-e29b-41d4-a716-446655440006",
      "status": "error"
    }
  ]
}

Possíveis Status

  • processing - Arquivo em processamento
  • completed - Processamento concluído com sucesso
  • error - Erro no processamento

Possíveis Erros

Código Error Descrição
400 bad_request Parâmetro folder-id é obrigatório
401 unauthorized Usuário não autorizado

Webhook de Resultados

Quando uma prescrição é processada, a API envia automaticamente o resultado para a URL de webhook configurada no seu tenant.

POST {sua-url-webhook-configurada}

Descrição

A MedReader enviará uma requisição POST para sua URL de webhook configurada sempre que uma prescrição for processada.

Headers

Content-Type: application/json
Authorization: Basic {base64(webhook_user:webhook_password)}

Nota: A autenticação utiliza Basic Auth. O header Authorization contém as credenciais webhook_user e webhook_password configuradas no seu tenant, codificadas em Base64 no formato user:password.

Payload

{
  "id": "cc0e8400-e29b-41d4-a716-446655440007",
  "created_at": "2024-01-18T16:30:00Z",
  "prescription_confidence_score": 95,
  "prescription_confidence_notes": "Prescrição clara e legível"
}

Campos do Payload

Campo Tipo Descrição
id string ID único da análise da prescrição
created_at timestamp Data e hora de criação da análise
prescription_confidence_score integer Pontuação de confiança da leitura (0-100)
prescription_confidence_notes string Notas sobre a confiança da análise da prescrição

Resposta Esperada

Seu webhook deve responder com status 200 OK para confirmar o recebimento. Caso contrário, a MedReader poderá tentar reenviar a notificação.

Configuração do Tenant

Cada tenant possui configurações específicas que controlam o comportamento da API, incluindo credenciais de armazenamento S3 e configurações de webhook. Você pode consultar e atualizar essas configurações através dos endpoints abaixo.

Permissões Necessárias

Os endpoints de configuração requerem permissões especiais de admin ou configurations. Usuários sem essas permissões receberão erro 401 (unauthorized).

GET /api/v1/tenant/configurations

Descrição

Consulta as configurações atuais do tenant.

Headers

Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Response (200 OK)

{
  "s3_bucket_name": "medreader-prescriptions",
  "s3_region": "us-east-1",
  "s3_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "s3_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "s3_base_path": "tenant-123/prescriptions",
  "webhook_url": "https://seu-sistema.com/api/webhooks/medreader",
  "webhook_user": "webhook-user",
  "webhook_password": "webhook-password-secret"
}

Possíveis Erros

Código Error Descrição
401 unauthorized Usuário não possui permissões necessárias
404 tenant_configuration_not_found Configuração do tenant não encontrada
PUT /api/v1/tenant/configurations

Descrição

Atualiza as configurações do tenant. Todos os campos são opcionais - apenas os campos fornecidos serão atualizados.

Headers

Content-Type: application/json
Authorization: Bearer {seu-token-jwt}
X-Tenant-ID: {seu-tenant-id}

Request Body

{
  "s3_bucket_name": "medreader-prescriptions",
  "s3_region": "us-east-1",
  "s3_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "s3_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "s3_base_path": "tenant-123/prescriptions",
  "webhook_url": "https://seu-sistema.com/api/webhooks/medreader",
  "webhook_user": "webhook-user",
  "webhook_password": "webhook-password-secret"
}

Nota: Todos os campos são opcionais. Envie apenas os campos que deseja atualizar.

Parâmetros de Configuração

Parâmetro Tipo Descrição
s3_bucket_name string Nome do bucket S3 para armazenamento de arquivos
s3_region string Região AWS do bucket S3
s3_access_key_id string Access Key ID para acesso ao S3
s3_secret_access_key string Secret Access Key para acesso ao S3
s3_base_path string Caminho base no bucket S3
webhook_url string URL para receber notificações de prescrições processadas
webhook_user string Usuário para autenticação Basic Auth do webhook
webhook_password string Senha para autenticação Basic Auth do webhook

Response (200 OK)

{
  "s3_bucket_name": "medreader-prescriptions",
  "s3_region": "us-east-1",
  "s3_access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "s3_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "s3_base_path": "tenant-123/prescriptions",
  "webhook_url": "https://seu-sistema.com/api/webhooks/medreader",
  "webhook_user": "webhook-user",
  "webhook_password": "webhook-password-secret"
}

Possíveis Erros

Código Error Descrição
400 invalid_json Corpo da requisição não é um JSON válido
400 no_fields_to_update Pelo menos um campo deve ser fornecido
401 unauthorized Usuário não possui permissões necessárias
404 tenant_configuration_not_found Configuração do tenant não encontrada

Suporte

Para dúvidas, sugestões ou suporte técnico, entre em contato: