Documents API

The Documents API manages all shipment-related documents including shipping labels, bills of lading (BOL), proof of delivery (POD), customs forms, and invoices.

Overview

The Documents API provides:

Shipping labels in multiple formats (PDF, PNG, ZPL)
Bills of lading for freight shipments
Proof of delivery with signatures
Customs documentation for international shipments
Commercial invoices and packing lists
Document versioning and history

Endpoints

Method	Endpoint	Description
GET	`/documents/{id}`	Download document by ID
GET	`/shipments/{id}/documents`	List shipment documents
GET	`/shipments/{id}/labels`	Get shipping labels
POST	`/documents/generate`	Generate custom document
PUT	`/documents/{id}`	Update document metadata
DELETE	`/documents/{id}`	Delete document

Document Types

Type	Description	Format Options
`SHIPPING_LABEL`	Shipping label with barcode	PDF, PNG, ZPL, EPL
`BOL`	Bill of lading	PDF
`POD`	Proof of delivery	PDF
`CUSTOMS_FORM`	Customs declaration	PDF
`COMMERCIAL_INVOICE`	Commercial invoice	PDF
`PACKING_LIST`	Packing list	PDF
`CERTIFICATE_OF_ORIGIN`	Certificate of origin	PDF
`HAZMAT_DECLARATION`	Hazardous materials form	PDF

Download Document

Download a specific document by its ID.

Request

GET /documents/{id}http

GET https://api.flashamericas.com/api/v1/documents/doc_123456789
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`format`	string	Override document format (pdf, png, zpl)
`download`	boolean	Force download instead of inline display

Response

Document metadata responsejson

{
"success": true,
"data": {
  "documentId": "doc_123456789",
  "type": "SHIPPING_LABEL",
  "format": "PDF",
  "filename": "shipping_label_1234567890.pdf",
  "url": "https://api.flashamericas.com/documents/doc_123456789.pdf",
  "downloadUrl": "https://api.flashamericas.com/documents/doc_123456789.pdf?download=true",
  "size": 245760,
  "contentType": "application/pdf",
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "trackingNumber": "1234567890",
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-22T10:30:00Z",
  "metadata": {
    "provider": "FEDEX",
    "service": "FEDEX_GROUND",
    "labelSize": "4x6",
    "orientation": "portrait"
  }
}
}

Direct File Download

To download the actual file content:

Direct file downloadhttp

GET https://api.flashamericas.com/api/v1/documents/doc_123456789?download=true
Authorization: Bearer YOUR_API_KEY
Accept: application/pdf

List Shipment Documents

Get all documents associated with a shipment.

Request

GET /shipments/{id}/documentshttp

GET https://api.flashamericas.com/api/v1/shipments/660e8400-e29b-41d4-a716-446655440001/documents
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`type`	string	Filter by document type
`format`	string	Filter by format
`includeExpired`	boolean	Include expired documents

Response

Shipment documents responsejson

{
"success": true,
"data": [
  {
    "documentId": "doc_123456789",
    "type": "SHIPPING_LABEL",
    "format": "PDF",
    "filename": "shipping_label_1234567890.pdf",
    "url": "https://api.flashamericas.com/documents/doc_123456789.pdf",
    "size": 245760,
    "createdAt": "2025-01-15T10:30:00Z",
    "expiresAt": "2025-01-22T10:30:00Z"
  },
  {
    "documentId": "doc_234567890",
    "type": "BOL",
    "format": "PDF", 
    "filename": "bill_of_lading_PRO123456.pdf",
    "url": "https://api.flashamericas.com/documents/doc_234567890.pdf",
    "size": 156432,
    "createdAt": "2025-02-20T14:30:00Z",
    "expiresAt": "2025-02-27T14:30:00Z"
  },
  {
    "documentId": "doc_345678901",
    "type": "POD",
    "format": "PDF",
    "filename": "proof_of_delivery_1234567890.pdf", 
    "url": "https://api.flashamericas.com/documents/doc_345678901.pdf",
    "size": 89234,
    "createdAt": "2025-02-21T16:45:00Z",
    "expiresAt": "2025-02-28T16:45:00Z",
    "metadata": {
      "recipient": "J. DOE",
      "signatureUrl": "https://api.flashamericas.com/documents/signature_123.png",
      "deliveredAt": "2025-02-21T16:45:00Z"
    }
  }
]
}

Get Shipping Labels

Retrieve shipping labels specifically, with format options.

Request

GET /shipments/{id}/labelshttp

GET https://api.flashamericas.com/api/v1/shipments/660e8400-e29b-41d4-a716-446655440001/labels?format=PDF
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`format`	string	Label format (PDF, PNG, ZPL, EPL)
`size`	string	Label size (4x6, 8.5x11)
`combine`	boolean	Combine multiple labels into single document

Response

Shipping labels responsejson

{
"success": true,
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "trackingNumber": "1234567890",
  "labels": [
    {
      "documentId": "doc_123456789",
      "type": "SHIPPING_LABEL",
      "format": "PDF",
      "size": "4x6",
      "url": "https://api.flashamericas.com/documents/doc_123456789.pdf",
      "downloadUrl": "https://api.flashamericas.com/documents/doc_123456789.pdf?download=true",
      "thumbnailUrl": "https://api.flashamericas.com/documents/doc_123456789_thumb.png",
      "createdAt": "2025-01-15T10:30:00Z",
      "expiresAt": "2025-01-22T10:30:00Z"
    }
  ],
  "combinedLabel": {
    "url": "https://api.flashamericas.com/documents/combined_labels_660e8400.pdf",
    "format": "PDF",
    "pageCount": 1
  }
}
}

Generate Custom Document

Create custom documents using templates.

Request

POST /documents/generatehttp

POST https://api.flashamericas.com/api/v1/documents/generate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Generate document requestjson

{
"template": "COMMERCIAL_INVOICE",
"format": "PDF",
"shipmentId": "660e8400-e29b-41d4-a716-446655440001",
"data": {
  "invoiceNumber": "INV-12345",
  "invoiceDate": "2025-02-20",
  "seller": {
    "companyName": "Acme Corp",
    "address": "123 Main Street, Dallas, TX 75201, USA",
    "phone": "214-555-0123",
    "email": "export@acme.com"
  },
  "buyer": {
    "companyName": "Customer Corp",
    "address": "456 Oak Avenue, Houston, TX 77001, USA",
    "phone": "713-555-0456",
    "email": "import@customer.com"
  },
  "items": [
    {
      "description": "Electronic Components",
      "quantity": 1,
      "unitPrice": 1500.00,
      "totalPrice": 1500.00,
      "weight": 25.5,
      "hsCode": "8542.31.0000",
      "countryOfOrigin": "US"
    }
  ],
  "totals": {
    "subtotal": 1500.00,
    "tax": 0.00,
    "shipping": 12.45,
    "total": 1512.45,
    "currency": "USD"
  },
  "terms": "FOB Origin",
  "reasonForExport": "Sale"
}
}

Response

Generated document responsejson

{
"success": true,
"data": {
  "documentId": "doc_456789012",
  "type": "COMMERCIAL_INVOICE",
  "format": "PDF",
  "filename": "commercial_invoice_INV-12345.pdf",
  "url": "https://api.flashamericas.com/documents/doc_456789012.pdf",
  "size": 187392,
  "createdAt": "2025-02-20T15:00:00Z",
  "expiresAt": "2025-02-27T15:00:00Z"
}
}

Label Formats

PDF Labels

Use case: Standard printing, email, web display
Sizes: 4x6 inches, 8.5x11 inches
Features: High quality, scalable, universally supported

PNG Labels

Use case: Web display, mobile apps, image processing
Sizes: Various resolutions (300, 600, 1200 DPI)
Features: Transparent background option, optimized file size

ZPL Labels

Use case: Zebra thermal printers
Features: Direct printer commands, fast printing, compact size
Compatibility: Zebra ZPL-compatible printers

ZPL label examplezpl

^XA
^MMT
^PW812
^LL0203
^LS0
^BY3,3,91^FT67,155^BCN,,Y,N
^FD>:1234567890^FS
^FT29,181^A0N,28,28^FH^FDTracking: 1234567890^FS
^FT29,209^A0N,20,19^FH^FDFrom: Dallas, TX^FS
^FT29,229^A0N,20,19^FH^FDTo: Houston, TX^FS
^XZ

EPL Labels

Use case: Eltron thermal printers
Features: Legacy printer support, simple commands

Document Security

Access Control

Documents are accessible only with valid API key
URLs include secure tokens for direct access
Documents expire after 7 days by default

Encryption

All documents transmitted over HTTPS
At-rest encryption for stored documents
Secure token-based access URLs

Examples

Download Shipping Label

Download labeljavascript

async function downloadShippingLabel(shipmentId, format = 'PDF') {
try {
  const response = await fetch(`/api/v1/shipments/${shipmentId}/labels?format=${format}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  
  const labels = await response.json();
  
  if (labels.success && labels.data.labels.length > 0) {
    const labelUrl = labels.data.labels[0].downloadUrl;
    
    // Open in new window or download
    window.open(labelUrl, '_blank');
    
    return labelUrl;
  } else {
    throw new Error('No labels available');
  }
} catch (error) {
  console.error('Error downloading label:', error);
  throw error;
}
}

Bulk Document Download

Download all shipment documentsjavascript

async function downloadAllDocuments(shipmentId) {
const response = await fetch(`/api/v1/shipments/${shipmentId}/documents`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const documents = await response.json();

if (documents.success) {
  // Create ZIP file with all documents
  const downloads = documents.data.map(doc => ({
    url: doc.downloadUrl,
    filename: doc.filename
  }));
  
  // Download each document
  downloads.forEach(download => {
    const link = document.createElement('a');
    link.href = download.url;
    link.download = download.filename;
    link.click();
  });
  
  return downloads;
}
}

Generate Commercial Invoice

Generate customs invoicejavascript

async function generateCommercialInvoice(shipmentData) {
const invoiceData = {
  template: 'COMMERCIAL_INVOICE',
  format: 'PDF',
  shipmentId: shipmentData.shipmentId,
  data: {
    invoiceNumber: `INV-${Date.now()}`,
    invoiceDate: new Date().toISOString().split('T')[0],
    seller: shipmentData.shipper,
    buyer: shipmentData.consignee,
    items: shipmentData.cargo.map(item => ({
      description: item.description,
      quantity: item.quantity,
      unitPrice: item.value / item.quantity,
      totalPrice: item.value,
      weight: item.weight,
      hsCode: item.hsCode || '9999.99.9999',
      countryOfOrigin: 'US'
    })),
    totals: {
      subtotal: shipmentData.totalValue,
      tax: 0,
      shipping: shipmentData.shippingCost,
      total: shipmentData.totalValue + shipmentData.shippingCost,
      currency: 'USD'
    },
    terms: 'FOB Origin',
    reasonForExport: 'Sale'
  }
};

const response = await fetch('/api/v1/documents/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(invoiceData)
});

const invoice = await response.json();
return invoice.data;
}

Print Labels to Thermal Printer

Send ZPL to thermal printerjavascript

async function printLabelToThermalPrinter(shipmentId) {
// Get ZPL format label
const response = await fetch(`/api/v1/shipments/${shipmentId}/labels?format=ZPL`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const labels = await response.json();

if (labels.success && labels.data.labels.length > 0) {
  const zplUrl = labels.data.labels[0].url;
  
  // Download ZPL content
  const zplResponse = await fetch(zplUrl);
  const zplContent = await zplResponse.text();
  
  // Send to printer (example using browser printing or print server)
  await sendToPrinter(zplContent);
  
  return true;
}

return false;
}

async function sendToPrinter(zplContent) {
// This would depend on your printer setup
// Could be direct USB, network printer, or print server API

try {
  // Example: Send to print server
  await fetch('/print-server/zebra', {
    method: 'POST',
    headers: {
      'Content-Type': 'text/plain'
    },
    body: zplContent
  });
} catch (error) {
  console.error('Printing failed:', error);
  throw error;
}
}

Document Templates

Available Templates

Template	Description	Required Data
`COMMERCIAL_INVOICE`	Standard commercial invoice	Seller, buyer, items, totals
`PACKING_LIST`	Detailed packing list	Items, packaging, weights
`CERTIFICATE_OF_ORIGIN`	Certificate of origin	Items, origin country, certification
`HAZMAT_DECLARATION`	Hazardous materials form	Hazmat details, classifications

Custom Templates

Custom template requestjson

{
"template": "CUSTOM_FORM",
"format": "PDF",
"templateData": {
  "title": "Export Declaration",
  "fields": [
    {
      "name": "exporterName",
      "label": "Exporter Name",
      "value": "Acme Corp"
    },
    {
      "name": "exportDate", 
      "label": "Export Date",
      "value": "2025-02-20"
    }
  ]
}
}

Error Handling

Common Errors

Document not foundjson

{
"success": false,
"error": {
  "code": "DOCUMENT_NOT_FOUND",
  "message": "Document not found or expired"
}
}

Document generation failedjson

{
"success": false,
"error": {
  "code": "DOCUMENT_GENERATION_FAILED",
  "message": "Failed to generate document",
  "details": {
    "template": "COMMERCIAL_INVOICE",
    "errors": [
      "Missing required field: invoiceNumber",
      "Invalid currency code: XYZ"
    ]
  }
}
}

Best Practices

Download immediately - Document URLs expire after 7 days
Store locally - Cache frequently accessed documents
Handle expiration - Regenerate expired documents as needed
Verify formats - Check printer compatibility for thermal labels
Secure storage - Don't expose document URLs publicly

Rate Limiting

Document API calls are rate limited:

Production: 500 requests per minute
Sandbox: 100 requests per minute

Large document downloads may have separate bandwidth limits.

Next Steps

Track shipments to know when documents are available
Set up webhooks for document generation notifications
View examples for complete document handling implementations
Manage shipments for the complete shipping workflow

Documents API

Overview

Endpoints

Document Types

Download Document

Request

Query Parameters

Response

Direct File Download

List Shipment Documents

Request

Query Parameters

Response

Get Shipping Labels

Request

Query Parameters

Response

Generate Custom Document

Request

Response

Label Formats

PDF Labels

PNG Labels

ZPL Labels

EPL Labels

Document Security

Access Control

Encryption

Examples

Download Shipping Label

Bulk Document Download

Generate Commercial Invoice

Print Labels to Thermal Printer

Document Templates

Available Templates

Custom Templates

Error Handling

Common Errors

Best Practices

Rate Limiting

Next Steps

On this page