Transport Documents

The Transport Documents API provides complete document workflow management for transport-related files. Upload, validate, approve, reject, and track the lifecycle of AWBs, manifests, customs declarations, and delivery confirmations.

Base Path: /api/v1/transport/documents Permission: Sanctum token authentication required

Document types

Type	Code	Description
Air Waybill	`awb`	AWB documents for air shipments
Manifest	`manifest`	Shipping manifests
Customs	`customs`	Customs declarations and forms
Delivery	`delivery`	Delivery confirmations
Other	`other`	Other transport documents

Document states

State	Description
`uploaded`	Document uploaded, pending validation
`validated`	Document verified, pending approval
`approved`	Document approved and finalized
`rejected`	Document rejected with reason
`superseded`	Replaced by newer version

POST/api/v1/transport/documents/upload

Upload document

Upload a new transport document using multipart file upload or base64-encoded content. Supports idempotency to prevent duplicate uploads.

Headers

Name
Authorization
Type
string
Description
Bearer {token} - Sanctum API token.
Name
Idempotency-Key
Type
string
Description
UUID to prevent duplicate uploads.

Required attributes

Name
document_type
Type
string
Description
Document type: awb, manifest, customs, delivery, other.
Name
file
Type
file
Description
Document file (multipart upload). Max 10MB. Required if file_base64 not provided.
Name
file_base64
Type
string
Description
Base64-encoded document content. Required if file not provided.
Name
filename
Type
string
Description
Original filename. Required with file_base64.

Optional attributes

Name
manifest_id
Type
string
Description
Related manifest identifier.
Name
awb_number
Type
string
Description
Related AWB number.
Name
metadata
Type
object
Description
Additional metadata as JSON object.

Allowed file types: pdf, jpg, jpeg, png, xlsx, xls

Request

POST

/api/v1/transport/documents/upload

curl -X POST https://app.price2b.com/api/v1/transport/documents/upload \
  -H "Authorization: Bearer {token}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@awb-12345.pdf" \
  -F "document_type=awb" \
  -F "manifest_id=MAN-20250124-001" \
  -F "awb_number=AWB123456"

Response (201 Created)

{
  "success": true,
  "message": "Document uploaded successfully",
  "data": {
    "id": 1234,
    "manifest_id": "MAN-20250124-001",
    "awb_number": "AWB123456",
    "document_type": "awb",
    "document_type_label": "Air Waybill",
    "file_name": "awb-12345.pdf",
    "file_size": 245678,
    "file_size_human": "240 KB",
    "mime_type": "application/pdf",
    "checksum": "sha256:abcdef1234567890",
    "state": "uploaded",
    "state_label": "Uploaded",
    "version": 1,
    "metadata": {"notes": "Priority shipment"},
    "created_at": "2026-01-24T10:30:00+00:00",
    "updated_at": "2026-01-24T10:30:00+00:00"
  }
}

GET/api/v1/transport/documents

List documents

Retrieve a paginated list of transport documents with optional filtering.

Query parameters

Name
manifest_id
Type
string
Description
Filter by manifest identifier.
Name
awb_number
Type
string
Description
Filter by AWB number.
Name
document_type
Type
string
Description
Filter by document type.
Name
state
Type
string
Description
Filter by state: uploaded, validated, approved, rejected, superseded.
Name
per_page
Type
integer
Description
Items per page (default: 15, max: 100).
Name
page
Type
integer
Description
Page number.

Request

GET

/api/v1/transport/documents

curl -G https://app.price2b.com/api/v1/transport/documents \
  -H "Authorization: Bearer {token}" \
  -d document_type=awb \
  -d state=approved \
  -d per_page=20

Response

{
  "success": true,
  "data": [
    {
      "id": 1234,
      "manifest_id": "MAN-20250124-001",
      "awb_number": "AWB123456",
      "document_type": "awb",
      "document_type_label": "Air Waybill",
      "file_name": "awb-12345.pdf",
      "file_size": 245678,
      "file_size_human": "240 KB",
      "mime_type": "application/pdf",
      "state": "approved",
      "state_label": "Approved",
      "version": 1,
      "created_at": "2026-01-24T10:30:00+00:00",
      "updated_at": "2026-01-24T11:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 93
  }
}

GET/api/v1/transport/documents/{id}

Get document details

Retrieve complete details of a specific transport document including metadata, validation status, and approval information.

Request

GET

/api/v1/transport/documents/1234

curl https://app.price2b.com/api/v1/transport/documents/1234 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": 1234,
    "manifest_id": "MAN-20250124-001",
    "awb_number": "AWB123456",
    "document_type": "awb",
    "document_type_label": "Air Waybill",
    "file_name": "awb-12345.pdf",
    "file_size": 245678,
    "file_size_human": "240 KB",
    "mime_type": "application/pdf",
    "checksum": "sha256:abcdef1234567890",
    "state": "approved",
    "state_label": "Approved",
    "version": 1,
    "metadata": {"notes": "Priority shipment"},
    "uploader": {
      "id": 5,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "validator": {
      "id": 3,
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "approver": {
      "id": 2,
      "name": "Admin User",
      "email": "admin@example.com"
    },
    "validation_notes": "Document verified and valid",
    "approved_at": "2026-01-24T11:00:00+00:00",
    "created_at": "2026-01-24T10:30:00+00:00",
    "updated_at": "2026-01-24T11:00:00+00:00"
  }
}

GET/api/v1/transport/documents/{id}/download

Download document

Generate a signed temporary URL to download the document file. The URL expires after 60 minutes.

Request

GET

/api/v1/transport/documents/1234/download

curl https://app.price2b.com/api/v1/transport/documents/1234/download \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "download_url": "https://storage.price2b.com/documents/signed-url?token=xyz&expires=1234567890",
    "expires_in_minutes": 60,
    "file_name": "awb-12345.pdf",
    "file_size": 245678,
    "mime_type": "application/pdf"
  }
}

PUT/api/v1/transport/documents/{id}/validate

Validate document

Mark a document as validated. This is typically the first step in the approval workflow.

Optional attributes

Name
notes
Type
string
Description
Validation notes or comments.

Request

PUT

/api/v1/transport/documents/1234/validate

curl -X PUT https://app.price2b.com/api/v1/transport/documents/1234/validate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Document format and content verified"
  }'

Response

{
  "success": true,
  "message": "Document validated successfully",
  "data": {
    "id": 1234,
    "state": "validated",
    "state_label": "Validated",
    "validation_notes": "Document format and content verified",
    "validated_at": "2026-01-24T10:45:00+00:00"
  }
}

PUT/api/v1/transport/documents/{id}/approve

Approve document

Approve a validated document. This finalizes the document in the workflow.

Optional attributes

Name
notes
Type
string
Description
Approval notes or comments.

Request

PUT

/api/v1/transport/documents/1234/approve

curl -X PUT https://app.price2b.com/api/v1/transport/documents/1234/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Approved for processing"
  }'

Response

{
  "success": true,
  "message": "Document approved successfully",
  "data": {
    "id": 1234,
    "state": "approved",
    "state_label": "Approved",
    "approved_at": "2026-01-24T11:00:00+00:00"
  }
}

PUT/api/v1/transport/documents/{id}/reject

Reject document

Reject a document with a reason. Rejected documents can be superseded with a corrected version.

Required attributes

Name
reason
Type
string
Description
Reason for rejection.

Request

PUT

/api/v1/transport/documents/1234/reject

curl -X PUT https://app.price2b.com/api/v1/transport/documents/1234/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Document is illegible. Please upload a clearer scan."
  }'

Response

{
  "success": true,
  "message": "Document rejected",
  "data": {
    "id": 1234,
    "state": "rejected",
    "state_label": "Rejected",
    "rejection_reason": "Document is illegible. Please upload a clearer scan.",
    "rejected_at": "2026-01-24T11:00:00+00:00"
  }
}

POST/api/v1/transport/documents/{id}/supersede

Supersede document

Replace an existing document with a new version. The original document is marked as superseded and a new document is created with an incremented version number.

Required attributes

Name
file
Type
file
Description
New document file (multipart). Required if file_base64 not provided.
Name
file_base64
Type
string
Description
Base64-encoded content. Required if file not provided.
Name
filename
Type
string
Description
Original filename. Required with file_base64.

Optional attributes

Name
reason
Type
string
Description
Reason for superseding the document.

Request

POST

/api/v1/transport/documents/1234/supersede

curl -X POST https://app.price2b.com/api/v1/transport/documents/1234/supersede \
  -H "Authorization: Bearer {token}" \
  -F "file=@awb-12345-v2.pdf" \
  -F "reason=Corrected version with proper signature"

Response

{
  "success": true,
  "message": "Document superseded successfully",
  "data": {
    "new_document": {
      "id": 1235,
      "file_name": "awb-12345-v2.pdf",
      "state": "uploaded",
      "version": 2
    },
    "superseded_document": {
      "id": 1234,
      "state": "superseded",
      "superseded_by": 1235
    }
  }
}

GET/api/v1/transport/documents/{id}/history

Get document history

Get the version history of a document, including all superseded versions.

Request

GET

/api/v1/transport/documents/1235/history

curl https://app.price2b.com/api/v1/transport/documents/1235/history \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "current": {
      "id": 1235,
      "version": 2,
      "state": "approved",
      "created_at": "2026-01-24T12:00:00+00:00"
    },
    "history": [
      {
        "id": 1234,
        "version": 1,
        "state": "superseded",
        "superseded_by": 1235,
        "supersede_reason": "Corrected version with proper signature",
        "created_at": "2026-01-24T10:30:00+00:00",
        "superseded_at": "2026-01-24T12:00:00+00:00"
      }
    ],
    "total_versions": 2
  }
}

DELETE/api/v1/transport/documents/{id}

Delete document

Delete a document. Only documents in uploaded or rejected state can be deleted. Approved documents cannot be deleted.

Request

DELETE

/api/v1/transport/documents/1234

curl -X DELETE https://app.price2b.com/api/v1/transport/documents/1234 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Document deleted successfully"
}

Response (403 - Cannot delete)

{
  "success": false,
  "message": "Cannot delete approved documents"
}

Rate limits

Endpoint	Limit	Window
Upload	30 requests	1 minute
List/Show	60 requests	1 minute
Download	60 requests	1 minute
Workflow actions	60 requests	1 minute

Error responses

Code	Description
`400`	Invalid request (bad idempotency key, invalid base64)
`401`	Unauthorized
`403`	Forbidden (cannot delete approved documents)
`404`	Document not found
`413`	File too large (max 10MB)
`422`	Validation error
`429`	Rate limit exceeded