Fluxo de envio

Enviar um exame em 3 passos

O envio de um exame é um fluxo de 3 passos. Os arquivos vão direto ao Cloudflare R2 com URLs pré-assinadas (não passam pelos nossos servidores), então é rápido mesmo com exames de 500 MB+.

Passo 1 — Criar o exame

Envie metadados do paciente e a lista de arquivos (nome + tamanho em bytes). Você recebe um exam_id e URLs pré-assinadas (válidas por 15 minutos).

bash
POST /api/v1/exams
{
  "name": "CBCT mandíbula",
  "patient_name": "Juan Pérez",
  "files": [
    { "name": "ct_001.dcm", "size": 524288 }
  ]
}

Passo 2 — Enviar os arquivos ao R2

Para cada URL pré-assinada, faça um PUT com o conteúdo binário do arquivo. O R2 responde 200 OK se o upload foi bem-sucedido. Sem autenticação adicional: a URL já está assinada.

bash
PUT https://r2.cloudflarestorage.com/.../ct_001.dcm
Content-Type: application/dicom

<bytes>

Passo 3 — Confirmar

Após enviar todos os arquivos, chame /confirm para marcar o exame como ready. Você recebe share_url (link com marca) e viewer_url (visualizador 3D direto).

bash
POST /api/v1/exams/{exam_id}/confirm

→ {
  "ok": true,
  "exam_id": "...",
  "status": "ready",
  "share_url": "https://cbcthub.com/share/...",
  "viewer_url": "https://cbcthub.com/viewer/..."
}

Diagrama do fluxo

TU SISTEMA                CBCTHub API             Cloudflare R2
    │                         │                       │
    ├──POST /v1/exams────────►│                       │
    │                         │                       │
    │◄────exam_id, upload_urls┤                       │
    │                                                 │
    ├──PUT ct_001.dcm ────────────────────────────────►│
    ├──PUT ct_002.dcm ────────────────────────────────►│
    │◄───── 200 OK ───────────────────────────────────┤
    │                                                 │
    ├──POST /v1/exams/{id}/confirm ►│                 │
    │◄────share_url, viewer_url─────┤                 │

ℹ Idempotência

/confirm é idempotente: chamá-lo várias vezes não duplica o exame. Se sua conexão caiu logo após um confirm bem-sucedido, você pode reintentar sem riscos.

E se o upload demorar mais de 15 minutos?

As URLs pré-assinadas expiram em 15 minutos. Se seu cliente não terminou o upload nesse prazo, chame POST /api/v1/exams novamente para regerar as URLs. O exam_id antigo permanece em status uploading até que você o exclua.

Próximo →

Referência de endpoints