Upload Document

This endpoint is used to upload a consignment document to the system. Uploaded documents can be associated with consignments using the documents parameter when creating a consignment.

Endpoint Information

Property Value
URL {{BASE_URL}}/api/v1/consignment-documents
HTTP Method POST
Content Type multipart/form-data
Authentication APIKEY header

When to Use?

Scenario Description
Micro Export (ETGB) E-archive invoice upload is required for post_type: 2 consignments
Sale Consignments E-archive invoice upload is required for post_type: 4 consignments
Customs Documents Proforma invoice, certificate of origin, etc.
Special Documents Product-specific required documents such as MSDS, FDA, TSCA

Important: If you try to create a consignment without uploading an e-archive invoice for micro export (post_type: 2) and sale (post_type: 4) consignments, the carrier may reject your shipment.


Request Parameters

Parameter Type Required Description
document_file File REQUIRED File to be uploaded. Maximum 4MB. Supported formats: PDF, JPEG, PNG
document_type Integer REQUIRED Document type. Available Values
status Integer REQUIRED Document status. Available Values
consignment_id Integer OPTIONAL Consignment ID to link to an existing consignment
document_reference String RECOMMENDED Document reference number (E-Archive No, Invoice No, etc.)
document_issued_at DateTime RECOMMENDED Document issue date (ISO 8601 format)

Document Types

Value Code Description
1 INVOICE Invoice / E-Archive Invoice
2 PACKING_LIST Packing List
3 CUSTOMS_FORM Customs Form
4 MSDS Material Safety Data Sheet
5 FDA FDA Certificate
6 TSCA TSCA Certificate
7 OTHER Other
8 PROFORMA Proforma Invoice
9 BILL_OF_LADING Bill of Lading
10 CN22 Customs Declaration (CN22)
11 CN23 Customs Declaration (CN23)
12 COO Certificate of Origin
13 ETD Electronic Trade Document

Document Statuses

Value Code Description
0 IN_REVIEW Pending approval
1 APPROVED Approved
2 REJECTED Rejected

Note: When uploading an e-archive invoice for micro export, use status: 1 (Approved).


Example Usage

Uploading E-Archive Invoice for Micro Export

curl -X POST "{{BASE_URL}}/api/v1/consignment-documents" \
  -H "APIKEY: {{APIKEY}}" \
  -F "document_file=@/path/to/e-archive-invoice.pdf" \
  -F "document_type=1" \
  -F "status=1" \
  -F "document_reference=GIB2024000012345" \
  -F "document_issued_at=2024-12-17T10:30:00+03:00"

API Response

Successful Response

{
    "status": true,
    "message": "Consignment document created successfully",
    "data": {
        "id": 12345,
        "fileName": "e-archive-invoice.pdf",
        "fileSize": 102400,
        "mimeType": "application/pdf",
        "status": 1,
        "documentType": 1,
        "documentReference": "GIB2024000012345",
        "documentIssuedAt": "2024-12-17T10:30:00+03:00",
        "consignment": null
    }
}

Response Fields

Field Type Description
id Integer Document ID. Use this value when creating a consignment
fileName String Uploaded file name
fileSize Integer File size (bytes)
mimeType String File MIME type
status Integer Document status
documentType Integer Document type
documentReference String Document reference number
documentIssuedAt String Document issue date
consignment Object/null Associated consignment (if any)

Associating with a Consignment

To use your uploaded document when creating a consignment, add the id value returned in the API response to the documents array:

{
    "provider_id": 7,
    "preference": 0,
    "address_resolver_type": 0,
    "consignor": { ... },
    "consignee": { ... },
    "packages": [
        {
            "package_type": 1,
            "post_type": 2,
            ...
        }
    ],
    "documents": [
        {
            "id": 12345
        }
    ]
}

Multiple documents: To add multiple documents, you can add multiple objects to the documents array.


Error Responses

Missing File

{
    "status": false,
    "errors": [
        {
            "message": "documentFile:This value should not be null.",
            "code": 400
        }
    ]
}

File Size Exceeded

{
    "status": false,
    "errors": [
        {
            "message": "The file is too large. Allowed maximum size is 4 MB.",
            "code": 400
        }
    ]
}

Invalid File Format

{
    "status": false,
    "errors": [
        {
            "message": "The mime type of the file is invalid. Allowed types are: application/pdf, image/jpeg, image/png.",
            "code": 400
        }
    ]
}

Important Notes

Topic Description
File Retention Period Files uploaded without specifying consignment_id will be automatically deleted if not associated with a consignment within 3 days
File Size Maximum 4 MB
Supported Formats PDF, JPEG, PNG
E-Archive Invoice Use document_type: 1, status: 1 for micro export (post_type: 2) and sale (post_type: 4)
Reference Information document_reference and document_issued_at fields are forwarded to the carrier

Related Endpoints