API Dokümantasyonu

// GET /api/v1/loads/42/documents  — load with 2 pickups + 2 drops
// Quota max = 2 + 2 + 1 = 5  (one doc per stop + additional)
{
  "document_quota": {
    "max": 5,
    "used": 0,
    "remaining": 5,
    "pickup_count": 2,
    "drop_count": 2,
    "max_per_stop": 1,
    "slots": [
      { "type": "pickup", "load_stop_id": 10, "slot_index": 0, "stop_name": "Warehouse A", "sequence": 0, "filled": false, "document_id": null, "legacy": false },
      { "type": "pickup", "load_stop_id": 11, "slot_index": 0, "stop_name": "Warehouse B", "sequence": 1, "filled": false, "document_id": null, "legacy": false },
      { "type": "drop",   "load_stop_id": 12, "slot_index": 0, "stop_name": "Store C",     "sequence": 2, "filled": false, "document_id": null, "legacy": false },
      { "type": "drop",   "load_stop_id": 13, "slot_index": 0, "stop_name": "Store D",     "sequence": 3, "filled": false, "document_id": null, "legacy": false },
      { "type": "additional", "load_stop_id": null, "slot_index": 0, "stop_name": null, "sequence": null, "filled": false, "document_id": null, "legacy": false }
    ]
  }
}

// 1) Pickup #1 (stop 10) — full parts
POST /api/v1/loads/42/documents
raw=@pickup1.jpg
processed=@pickup1.pdf
ocr_text=BOL pickup Warehouse A...
type=pickup
load_stop_id=10

// 2) Pickup #2 (stop 11) — PDF only
POST /api/v1/loads/42/documents
file=@pickup2.pdf
type=pickup
load_stop_id=11

// 3) Drop #1 (stop 12) — raw only
POST /api/v1/loads/42/documents
raw=@drop1.jpg
type=drop
load_stop_id=12

// 4) Drop #2 (stop 13) — OCR text only
POST /api/v1/loads/42/documents
ocr_text=Delivery receipt notes...
type=drop
load_stop_id=13

// 5) Additional (no load_stop_id)
POST /api/v1/loads/42/documents
file=@extra.pdf
type=additional

// WRONG when 2+ pickups — omit load_stop_id → 422
POST /api/v1/loads/42/documents
file=@bol.pdf
type=pickup

// List / quota
GET /api/v1/loads/42/documents

// Partial replace — PDF only (keeps existing raw/OCR)
POST /api/v1/loads/42/documents/7
file=@bol-v2.pdf

// Partial replace — OCR text only
POST /api/v1/loads/42/documents/7
ocr_text=Updated OCR text...

// Partial replace — raw pages only replaces ENTIRE raw set (keeps PDF/OCR)
POST /api/v1/loads/42/documents/7
raw[]=@page1.jpg
raw[]=@page2.jpg

// Append raw pages without wiping existing (current + new ≤ 10)
POST /api/v1/loads/42/documents/7/raws
raw[]=@page3.jpg
raw[]=@page4.jpg

// Replace / delete one raw by id
POST /api/v1/loads/42/documents/7/raws/101
raw=@page1-v2.jpg
DELETE /api/v1/loads/42/documents/7/raws/101

// Download / preview binaries
GET /api/v1/loads/42/documents/7/download                 → PDF (attachment; 404 if has_pdf=false)
GET /api/v1/loads/42/documents/7/preview                  → PDF (inline; 404 if has_pdf=false)
GET /api/v1/loads/42/documents/7/download/raw             → primary raw (sort 0, attachment)
GET /api/v1/loads/42/documents/7/preview/raw              → primary raw (sort 0, inline)
GET /api/v1/loads/42/documents/7/raws/{rawId}/download    → specific raw (attachment)
GET /api/v1/loads/42/documents/7/raws/{rawId}/preview     → specific raw (inline)
GET /api/v1/loads/42/documents/7/ocr-text                 → JSON { ocr_text, has_ocr_text }

// Delete document (removes PDF + all raw files when present)
DELETE /api/v1/loads/42/documents/7

// Tip: stop ids also come from load detail
GET /api/v1/loads/42  →  data.stops[].id / type / sequence
// Tip: documents[] on load detail include has_pdf / has_raw / ocr_text

// Response (200)
{
  "success": true,
  "message": "Documents retrieved.",
  "data": {
    "documents": [
      {
        "id": 1,
        "load_id": 42,
        "type": "pickup",
        "load_stop_id": 10,
        "original_name": "bol.pdf",
        "size_bytes": 12345,
        "mime": "application/pdf",
        "uploaded_by": 5,
        "has_pdf": true,
        "has_raw": true,
        "raw_size_bytes": 204800,
        "raw_mime": "image/jpeg",
        "raw_original_name": "page1.jpg",
        "raw_count": 2,
        "raws": [
          { "id": 101, "sort_order": 0, "size_bytes": 204800, "mime": "image/jpeg", "original_name": "page1.jpg" },
          { "id": 102, "sort_order": 1, "size_bytes": 198000, "mime": "image/jpeg", "original_name": "page2.jpg" }
        ],
        "has_ocr_text": true,
        "ocr_text": "BOL #12345 ...",
        "created_at": "2026-07-10T08:00:00+00:00",
        "updated_at": "2026-07-10T08:00:00+00:00"
      }
    ],
    "document_quota": {
      "max": 3,
      "used": 1,
      "remaining": 2,
      "pickup_count": 1,
      "drop_count": 1,
      "max_per_stop": 1,
      "slots": [
        { "type": "pickup", "load_stop_id": 10, "slot_index": 0, "stop_name": "Warehouse A", "sequence": 0, "filled": true, "document_id": 1, "legacy": false },
        { "type": "drop", "load_stop_id": 11, "slot_index": 0, "stop_name": "Store B", "sequence": 1, "filled": false, "document_id": null, "legacy": false },
        { "type": "additional", "load_stop_id": null, "slot_index": 0, "stop_name": null, "sequence": null, "filled": false, "document_id": null, "legacy": false }
      ]
    }
  }
}

// multipart fields
file=@bol.pdf
type=pickup
load_stop_id=10

// same PDF via processed alias
processed=@bol.pdf
type=pickup
load_stop_id=10

raw=@bol-scan.jpg
type=pickup
load_stop_id=10

// or multiple pages
raw[]=@page1.jpg
raw[]=@page2.jpg
type=pickup
load_stop_id=10

ocr_text=BOL #12345 shipper...
type=pickup
load_stop_id=10

// multipart — singular raw + PDF + OCR
raw=@bol-scan.jpg
processed=@bol.pdf
ocr_text=BOL #12345 shipper...
type=pickup
load_stop_id=10

// multipart — multiple raw pages (1..10) + PDF + OCR
raw[]=@page1.jpg
raw[]=@page2.jpg
raw[]=@page3.jpg
processed=@bol.pdf
ocr_text=Combined OCR text from all pages...
type=pickup
load_stop_id=10

// Response (201)
{
  "success": true,
  "message": "Document uploaded.",
  "data": {
    "id": 1,
    "load_id": 42,
    "type": "pickup",
    "load_stop_id": 10,
    "original_name": "bol.pdf",
    "size_bytes": 12345,
    "mime": "application/pdf",
    "uploaded_by": 5,
    "has_pdf": true,
    "has_raw": true,
    "raw_size_bytes": 204800,
    "raw_mime": "image/jpeg",
    "raw_original_name": "bol-scan.jpg",
    "raw_count": 1,
    "raws": [
      { "id": 101, "sort_order": 0, "size_bytes": 204800, "mime": "image/jpeg", "original_name": "bol-scan.jpg" }
    ],
    "has_ocr_text": true,
    "ocr_text": "BOL #12345 shipper...",
    "created_at": "...",
    "updated_at": "..."
  }
}

// OCR text only
ocr_text=Updated OCR text...

// Raw pages only (full-set replace — existing raws are removed)
raw[]=@page1.jpg
raw[]=@page2.jpg

// PDF only
file=@bol-v2.pdf

// Response (200)
{ "success": true, "message": "Document replaced.", "data": { "id": 1, "type": "pickup", "original_name": "bol-v2.pdf", "has_pdf": true, "has_raw": true, "has_ocr_text": true, ... } }

// Append 2 pages to a document that already has 6 (total 8 ≤ 10)
raw[]=@page7.jpg
raw[]=@page8.jpg

// or singular
raw=@extra.jpg

// Response (200)
{ "success": true, "message": "Raw images added.", "data": { "id": 7, "raw_count": 8, "raws": [ ... ], "has_raw": true, ... } }

raw=@page1-v2.jpg

// Response (200)
{ "success": true, "message": "Raw image replaced.", "data": { "id": 7, "raw_count": 6, "raws": [{ "id": 101, "sort_order": 0, "original_name": "page1-v2.jpg", ... }, ...], ... } }

// Response (200)
{ "success": true, "message": "Raw image deleted.", "data": { "id": 7, "raw_count": 5, "has_raw": true, "raws": [ ... ], ... } }

// Response (200)
{ "success": true, "message": "Document deleted.", "data": null }

// Response (200) — binary image stream (NOT a JSON envelope)
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="bol-scan.jpg"

<raw image bytes>

// Response (404) — legacy PDF-only document (no raw)
{
  "success": false,
  "message": "Raw image not found."
}

// Response (200) — OCR present
{
  "success": true,
  "message": "OCR text retrieved.",
  "data": {
    "ocr_text": "BOL #12345 shipper ACME\n...",
    "has_ocr_text": true
  }
}

// Response (200) — no OCR (legacy PDF-only upload)
{
  "success": true,
  "message": "OCR text retrieved.",
  "data": {
    "ocr_text": null,
    "has_ocr_text": false
  }
}