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"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', '{{BASE_URL}}/api/v1/consignment-documents', [
'headers' => [
'APIKEY' => '{{APIKEY}}'
],
'multipart' => [
[
'name' => 'document_file',
'contents' => fopen('/path/to/e-archive-invoice.pdf', 'r'),
'filename' => 'e-archive-invoice.pdf'
],
[
'name' => 'document_type',
'contents' => '1'
],
[
'name' => 'status',
'contents' => '1'
],
[
'name' => 'document_reference',
'contents' => 'GIB2024000012345'
],
[
'name' => 'document_issued_at',
'contents' => '2024-12-17T10:30:00+03:00'
]
]
]);
$body = json_decode($response->getBody(), true);
// Save the document ID - it will be used when creating the consignment
$documentId = $body['data']['id'];
print_r($body);
<?php
$ch = curl_init();
$postFields = [
'document_file' => new CURLFile(
'/path/to/e-archive-invoice.pdf',
'application/pdf',
'e-archive-invoice.pdf'
),
'document_type' => 1,
'status' => 1,
'document_reference' => 'GIB2024000012345',
'document_issued_at' => '2024-12-17T10:30:00+03:00'
];
curl_setopt_array($ch, [
CURLOPT_URL => '{{BASE_URL}}/api/v1/consignment-documents',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postFields,
CURLOPT_HTTPHEADER => [
'APIKEY: {{APIKEY}}'
]
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
$result = json_decode($response, true);
// Save the document ID - it will be used when creating the consignment
$documentId = $result['data']['id'];
print_r($result);
}
curl_close($ch);
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("APIKEY", "{{APIKEY}}");
using var content = new MultipartFormDataContent();
// Add file
var fileContent = new ByteArrayContent(File.ReadAllBytes("/path/to/e-archive-invoice.pdf"));
fileContent.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
content.Add(fileContent, "document_file", "e-archive-invoice.pdf");
// Other parameters
content.Add(new StringContent("1"), "document_type");
content.Add(new StringContent("1"), "status");
content.Add(new StringContent("GIB2024000012345"), "document_reference");
content.Add(new StringContent("2024-12-17T10:30:00+03:00"), "document_issued_at");
var response = await client.PostAsync("{{BASE_URL}}/api/v1/consignment-documents", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('document_file', fs.createReadStream('/path/to/e-archive-invoice.pdf'));
form.append('document_type', '1');
form.append('status', '1');
form.append('document_reference', 'GIB2024000012345');
form.append('document_issued_at', '2024-12-17T10:30:00+03:00');
const response = await axios.post(
'{{BASE_URL}}/api/v1/consignment-documents',
form,
{
headers: {
...form.getHeaders(),
'APIKEY': '{{APIKEY}}'
}
}
);
// Save the document ID - it will be used when creating the consignment
const documentId = response.data.data.id;
console.log(response.data);
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Path;
HttpClient client = HttpClient.newHttpClient();
String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
Path filePath = Path.of("/path/to/e-archive-invoice.pdf");
byte[] fileBytes = Files.readAllBytes(filePath);
String body = "--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_file\"; filename=\"e-archive-invoice.pdf\"\r\n" +
"Content-Type: application/pdf\r\n\r\n" +
new String(fileBytes) + "\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_type\"\r\n\r\n1\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"status\"\r\n\r\n1\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_reference\"\r\n\r\nGIB2024000012345\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_issued_at\"\r\n\r\n2024-12-17T10:30:00+03:00\r\n" +
"--" + boundary + "--";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("{{BASE_URL}}/api/v1/consignment-documents"))
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.header("APIKEY", "{{APIKEY}}")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
file, _ := os.Open("/path/to/e-archive-invoice.pdf")
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
// Add file
part, _ := writer.CreateFormFile("document_file", "e-archive-invoice.pdf")
io.Copy(part, file)
// Other parameters
writer.WriteField("document_type", "1")
writer.WriteField("status", "1")
writer.WriteField("document_reference", "GIB2024000012345")
writer.WriteField("document_issued_at", "2024-12-17T10:30:00+03:00")
writer.Close()
req, _ := http.NewRequest(
"POST",
"{{BASE_URL}}/api/v1/consignment-documents",
body,
)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("APIKEY", "{{APIKEY}}")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
fmt.Println(string(respBody))
}
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