# Create a document

Create a new document record and receive a pre-signed URL for uploading the file.

## Workflow

1. Call this endpoint with document metadata (type, fileName, contentType)
2. Receive the created document with an uploadUrl
3. Upload the file directly to S3 using the uploadUrl (PUT request)
4. Document status changes from PENDING_UPLOAD to UPLOADED automatically

## Upload Instructions

The uploadUrl is a pre-signed S3 URL. Upload your file with:

bash
curl -X PUT -H "Content-Type: application/pdf" \
  --data-binary @your-file.pdf \
  "https://s3.amazonaws.com/bucket/key?signature=..."


Important:
- The uploadUrl expires after 15 minutes
- Use the exact contentType specified in the request
- Maximum file size: 100MB

Endpoint: POST /documents
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `key` (string)
    Optional client-defined key for external reference
    Example: "doc-inv-2025-001"

  - `type` (string, required)
    Type of document.

Common types:
- INVOICE: Customer invoice
- BILL_OF_LADING: Bill of lading document
- RATE_CON: Rate confirmation
- PROOF_OF_DELIVERY: Proof of delivery (POD)
- CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
- W9: W-9 tax form
- CARRIER_INVOICE: Carrier invoice/bill
- LUMPER_RECEIPT: Lumper receipt
- DETENTION: Detention documentation
- DELIVERY_ORDER: Delivery order
- LOAD_TENDER: Load tender
- HOUSE_AIRWAY_BILL: House airway bill (HAWB)
- MASTER_AIRWAY_BILL: Master airway bill (MAWB)
- QUOTE: Quote document
- OTHER: Other document type
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `fileName` (string, required)
    File name (including extension)
    Example: "invoice-2025-001.pdf"

  - `contentType` (string, required)
    MIME content type of the file
    Example: "application/pdf"

  - `fileSize` (integer)
    File size in bytes (optional, for validation)
    Example: 102400

  - `tags` (object)
    Optional key-value tags
    Example: {"invoiceNumber":"INV-2025-001"}

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier for the document
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string,null)
    Client-defined key for external reference
    Example: "doc-inv-2025-001"

  - `type` (string, required)
    Type of document.

Common types:
- INVOICE: Customer invoice
- BILL_OF_LADING: Bill of lading document
- RATE_CON: Rate confirmation
- PROOF_OF_DELIVERY: Proof of delivery (POD)
- CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
- W9: W-9 tax form
- CARRIER_INVOICE: Carrier invoice/bill
- LUMPER_RECEIPT: Lumper receipt
- DETENTION: Detention documentation
- DELIVERY_ORDER: Delivery order
- LOAD_TENDER: Load tender
- HOUSE_AIRWAY_BILL: House airway bill (HAWB)
- MASTER_AIRWAY_BILL: Master airway bill (MAWB)
- QUOTE: Quote document
- OTHER: Other document type
    Enum: "INVOICE", "BILL_OF_LADING", "RATE_CON", "PROOF_OF_DELIVERY", "CERTIFICATE_OF_INSURANCE", "W9", "CARRIER_INVOICE", "LUMPER_RECEIPT", "DETENTION", "DELIVERY_ORDER", "LOAD_TENDER", "HOUSE_AIRWAY_BILL", "MASTER_AIRWAY_BILL", "QUOTE", "OTHER"

  - `fileName` (string, required)
    Original file name
    Example: "invoice-2025-001.pdf"

  - `extension` (string)
    File extension (without dot)
    Example: "pdf"

  - `contentType` (string, required)
    MIME content type
    Example: "application/pdf"

  - `fileSize` (integer,null)
    File size in bytes
    Example: 102400

  - `status` (string, required)
    Upload status of the document.
- PENDING_UPLOAD: Document record created, file not yet uploaded
- UPLOADED: File has been uploaded to storage
    Enum: "PENDING_UPLOAD", "UPLOADED"

  - `uploadUrl` (string,null)
    Pre-signed URL for uploading the file.
Only present immediately after document creation.
Expires after 15 minutes.
    Example: "https://s3.amazonaws.com/bucket/key?signature=..."

  - `downloadUrl` (string,null)
    Pre-signed URL for downloading the file.
Present when document status is UPLOADED.
Expires after 1 hour.
    Example: "https://s3.amazonaws.com/bucket/key?signature=..."

  - `tags` (object,null)
    Arbitrary key-value tags for the document
    Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}

  - `createdAt` (string, required)
    When the document was created
    Example: "2025-01-15T10:30:00Z"

  - `updatedAt` (string,null)
    When the document was last updated
    Example: "2025-01-15T10:35:00Z"

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message