# Generate Pre-signed Upload URL

Generates a pre-signed URL suitable for uploading a document directly to Cybersign's secure storage (e.g., S3). The URL expiry depends on the selected file tier.

Endpoint: POST /documents/upload-url
Version: 1.1.0
Security: user_bearer_auth

## Request fields (application/json):

  - `file_tier` (string, required)
    Determines the expiry time of the generated pre-signed URL based on expected file size:
* tier-1: Up to 20MB (7 min expiry)
* tier-2: Up to 40MB (14 min expiry)
* tier-3: Up to 80MB (28 min expiry)
* tier-4: Up to 100MB (35 min expiry)
* tier-5: Up to 120MB (42 min expiry)
    Enum: "tier-1", "tier-2", "tier-3", "tier-4", "tier-5"

  - `file_name` (string, required)
    The intended filename for the document being uploaded (e.g., 'contrato-laboral.pdf'). Used to construct the storage path.
    Example: "documento.pdf"

## Response 200 fields (application/json):

  - `url` (string, required)
    The base URL endpoint to which the upload request should be sent.
    Example: "https://your-bucket-name.s3.your-region.amazonaws.com/"

  - `fields` (object, required)
    Key-value pairs that must be included as form fields in the upload request (e.g., multipart/form-data).

  - `fields.key` (string, required)
    The full path/key where the object will be stored in the bucket.
    Example: "user-uuid/onboarding-ulid/documento.pdf"

  - `fields.x-amz-algorithm` (string, required)
    Example: "AWS4-HMAC-SHA256"

  - `fields.x-amz-credential` (string, required)
    Example: "AKIAEXAMPLE/20240101/us-east-1/s3/aws4_request"

  - `fields.x-amz-date` (string, required)
    Example: "20240101T120000Z"

  - `fields.policy` (string, required)
    Base64-encoded policy document governing the upload permissions.
    Example: "eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0wMVQxMjowNzowMFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJ5b3VyLWJ1Y2tldC1uYW1lIn0seyJrZXkiOiJ1c2VyLXV1aWQvb25ib2FyZGluZy11bGlkL2RvY3VtZW50by5wZGYifV19"

  - `fields.x-amz-signature` (string, required)
    The calculated signature for the request.
    Example: "a1b2c3d4e5f6..."

  - `doc_ulid` (string, required)
    A unique ULID generated by Cybersign to identify this specific document upload instance.
    Example: "01JE9KCR0H22PDY9C1GYZABCDE"

  - `doc_path` (string, required)
    The storage path/key assigned to this document. Matches the 'key' field within 'fields'.
    Example: "user-uuid/onboarding-ulid/documento.pdf"

## Response 400 fields (application/json):

  - `code` (string, required)
    An application-specific error code string.
    Example: "INVALID_OTP"

  - `message` (string, required)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "The OTP provided is invalid or has expired."

## Response 401 fields (application/json):

  - `code` (string, required)
    An application-specific error code string.
    Example: "INVALID_OTP"

  - `message` (string, required)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "The OTP provided is invalid or has expired."

## Response 500 fields (application/json):

  - `code` (string, required)
    An application-specific error code string.
    Example: "INVALID_OTP"

  - `message` (string, required)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "The OTP provided is invalid or has expired."