Print API

The Print API sends unredacted labels from Data Border storage to your tenant's Device Hub for secure printing.

Send Print Job

Sends labels to a printer via the tenant's configured Device Hub.

POST /api/print/send

Authentication

Header	Required	Description
`x-seller-access-token`	Yes	Valid seller access token
`x-amazon-token-secret`	Yes	Secret used during OAuth

Request Body

{
  "shipment_id": "ship_abc123def456",
  "printer_type": "label",
  "printer_id": "warehouse-zebra-01",
  "label_uuids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Field	Type	Required	Description
`shipment_id`	string	Yes	Data Border shipment ID from label proxy/passthrough
`printer_type`	string	Yes	`"label"` (thermal) or `"laser"`
`printer_id`	string	Yes	Printer identifier in Device Hub
`label_uuids`	string	Yes	Document UUIDs to print

Response

{
  "success": true,
  "data": {
    "status": "sent",
    "shipment_id": "ship_abc123def456",
    "documents_sent": 1,
    "print_count": 1,
    "is_reprint": false
  }
}

Field	Description
`status`	`"sent"` on success
`shipment_id`	The shipment that was printed
`documents_sent`	Number of documents sent to printer
`print_count`	Total times this shipment has been printed
`is_reprint`	Whether this is a reprint

Reprint Detection

When a shipment has been printed before:

{
  "success": true,
  "data": {
    "status": "sent",
    "shipment_id": "ship_abc123def456",
    "documents_sent": 1,
    "print_count": 2,
    "is_reprint": true,
    "warning": "Reprint detected. First printed: 2024-01-15T10:30:00.000Z"
  }
}

Example

curl -X POST "https://adb.example.com/api/print/send" \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -d '{
    "shipment_id": "ship_abc123def456",
    "printer_type": "label",
    "printer_id": "warehouse-zebra-01",
    "label_uuids": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Errors

Status	Message	Cause
400	`shipment_id is required`	Missing shipment ID
400	`Invalid printer_type`	Must be `label` or `laser`
400	`Invalid label UUIDs`	UUIDs not part of shipment
404	`Shipment not found`	Shipment doesn't exist
400	`Device Hub not configured`	Tenant lacks Device Hub setup

Flow Diagram

sequenceDiagram
    participant WMS
    participant ADB
    participant S3 as S3 Storage
    participant Hub as Device Hub
    participant Printer

    WMS->>ADB: POST /api/print/send
    ADB->>ADB: Validate shipment & UUIDs
    ADB->>ADB: Check tenant Device Hub config
    ADB->>S3: GET unredacted labels
    S3->>ADB: Return PDF files
    ADB->>Hub: POST print job
    Hub->>Printer: Send to printer
    ADB->>ADB: Increment print count
    ADB->>WMS: Return status + reprint warning

Loading diagram...

Device Hub Configuration

Device Hub must be configured for your tenant. Contact your Data Border administrator to set up:

Setting	Description
`device_hub_host`	Base URL of your Device Hub instance
`device_hub_api_key`	API key for authentication

Print Types

Label Printer

Optimized for thermal label printers (Zebra, DYMO, etc.):

{
  "printer_type": "label",
  "printer_id": "zebra-zd420"
}

Sends native ZPL if available
Falls back to PDF/image conversion
Standard 4x6" label format

Laser Printer

For standard office printers:

{
  "printer_type": "laser",
  "printer_id": "hp-laserjet-m404"
}

Sends PDF format
Supports multiple labels per page
Letter/A4 paper format

Implementation Example

async function printShipmentLabels(shipment, printerId) {
  const { token, secret } = await tokenManager.getSellerAccessToken(shipment.sellerId)
  
  const response = await fetch(`${ADB_URL}/api/print/send`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-seller-access-token': token,
      'x-amazon-token-secret': secret
    },
    body: JSON.stringify({
      shipment_id: shipment.adbShipmentId,
      printer_type: 'label',
      printer_id: printerId,
      label_uuids: shipment.documents.map(d => d.uuid)
    })
  })
  
  const data = await response.json()
  
  // Handle reprints
  if (data.data.is_reprint) {
    await logReprintWarning(shipment, data.data)
    
    // Optional: require confirmation for reprints
    if (!await confirmReprint(shipment)) {
      throw new Error('Reprint cancelled by user')
    }
  }
  
  // Update shipment record
  await db.shipments.update(shipment.id, {
    printCount: data.data.print_count,
    lastPrinted: new Date()
  })
  
  return data.data
}

Handling Reprints

Why Track Reprints?

Reprints may indicate:

Lost or damaged labels
Printer issues
Potential label fraud
Process inefficiencies

Reprint Monitoring

// Alert on excessive reprints
async function monitorReprints() {
  const reprints = await db.shipments.findMany({
    where: { 
      printCount: { gt: 1 },
      lastPrinted: { gt: oneDayAgo }
    }
  })
  
  if (reprints.length > threshold) {
    await alertOperations('High reprint rate detected', reprints)
  }
}

Audit Trail

All print operations are logged:

{
  "type": "print",
  "shipment_id": "ship_abc123",
  "documents": ["uuid1", "uuid2"],
  "printer_id": "zebra-01",
  "print_count": 2,
  "is_reprint": true,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Best Practices

Batch Printing

Print all documents in a single request:

// Good: Single request for all docs
await print({
  shipment_id: shipment.id,
  label_uuids: shipment.documents.map(d => d.uuid)
})

// Avoid: Multiple requests
for (const doc of shipment.documents) {
  await print({ shipment_id: shipment.id, label_uuids: [doc.uuid] })
}

Error Recovery

async function printWithRetry(shipment, printerId, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await printLabels(shipment, printerId)
    } catch (error) {
      if (error.message.includes('Device Hub not configured')) {
        // Configuration error - don't retry
        throw error
      }
      if (i < retries - 1) {
        await delay(1000 * (i + 1)) // Exponential backoff
      }
    }
  }
  throw new Error('Print failed after retries')
}