Drone API Reference

The Drone API provides specialized endpoints for in-store operations, such as picking, packing, and fulfillment. It's designed to be used by store associates and in-store systems.

Key Features

• Product Information: Access product details with comprehensive image support
• Order Management: Handle orders with visual product identification
• In-Store Operations: Support picking, packing, and fulfillment workflows
• Image Support: Product responses include image metadata and URLs for visual identification

⚠️ Important: Picking App Scope Restrictions

The picking app has limited status control scope for system integrity:

Allowed Status Changes for Picking App

The picking app can ONLY set these statuses via /dts/drone/order/set_status:

Read-Only Statuses for Picking App

These statuses can be READ but NOT SET by the picking app:

Valid Transitions for Picking App

• pending → picking ✅ (start picking)
• pending → cancelled ✅ (cancel before picking)
• processing → picking ✅ (start picking from processing)
• processing → cancelled ✅ (cancel before picking)
• picking → picked ✅ (complete picking)
• picking → cancelled ✅ (cancel during picking)
• picked → cancelled ✅ (cancel after picking)

❌ Invalid transitions (will return HTTP 422 error):

• Any transition to shipped, completed, or pending from other statuses
• Any transition from terminal states like completed or shipped

Error Handling

When the picking app attempts invalid status changes, the API returns:

{
  "responseType": "failure",
  "status": 422,
  "message": {
    "error": "Picking app transition not allowed: ...",
    "data": {
      "current_status": "picked",
      "requested_status": "shipped", 
      "allowed_transitions": ["cancelled"],
      "error_code": "PICKING_APP_TRANSITION_NOT_ALLOWED"
    }
  }
}

API Endpoints Overview

Health Endpoints

Places Endpoints

Orders Endpoints

Storage Location Endpoints

Product Endpoints

Store Endpoints

Delivery Endpoints

Substitution Endpoints

Authentication

All endpoints require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

For more details on authentication, see the Authentication Guide.

Response Format

Drone API responses follow a consistent format:

{
  "responseType": "success",
  "status": 200,
  "message": {
    "error": null,
    "message": null,
    "data": {
      // The response data, varies by endpoint
    }
  }
}

For errors:

{
  "responseType": "failure",
  "status": 400,
  "message": {
    "error": "Error message",
    "message": null
  }
}

⚠️ API Format Updates

Substitution Products Format (Updated 2025-08-15)

Important Change: The substitution products format has been updated for consistency:

• Substitute products now use ean instead of barcode for product identification
• Added image_guid structure to substitute products (consistent with main products)
• Backward compatibility: Main products continue to include both barcode and ean fields
• Recommendation: Use the ean field as the standardized identifier

Example of Updated Substitution Format:

{
  "allowed_substitutions": [
    {
      "ean": "5053990139545",
      "product": {
        "name": "Substitute Product",
        "ean": "5053990139545",
        "images": 0,
        "image_guid": []
      }
    }
  ]
}

For detailed information, see the /dts/drone/order/products documentation.

Product Image Support

The Drone API provides comprehensive image support for products:

• Image Count: Each product includes an images field indicating the number of available images
• Image Metadata: Products include detailed image information with URLs, dimensions, and metadata
• Visual Identification: Images support visual product identification during picking and packing
• Format Support: Supports common image formats (JPEG, PNG) with metadata

Image Response Structure

Product responses include image data in the following format:

{
  "id": "product-123",
  "name": "Product Name",
  "images": 1,
  "image_guid": [{
    "id": "img-product-123",
    "url": "https://example.com/product-image.jpg",
    "width": 1024,
    "height": 1024,
    "mime_type": "image/png",
    "media_type_code": "PICTURE",
    "file_size": 0,
    "created_at": "2023-12-07T10:00:00Z",
    "updated_at": "2023-12-07T10:00:00Z"
  }]
}

Common Use Cases

Picking Process with Visual Identification

1. Get a list of orders for a store using /dts/drone/orders
2. Get order details using /dts/drone/order/info
3. Get order products with image data and substitute options using /dts/drone/order/products
4. Use product images for visual identification during picking
5. Assign storage locations using /dts/drone/order/set_storage_locations
6. Update picking status using /dts/drone/order/set_picking_status
7. Set the number of bags using /dts/drone/order/set_num_bags
8. Update order status using /dts/drone/order/set_status

Product Search with Images

1. Search for products by barcode using /dts/drone/product/search
2. View product images for verification
3. Get substitution options using /dts/drone/substitution/info or from order products
4. Compare substitution product images using the new image_guid structure in substitutes

Order Management

1. Mark an order as printed using /dts/drone/order/set_printed
2. Suspend an order using /dts/drone/order/set_suspended
3. Resume an order using /dts/drone/order/unset_suspended
4. Add a message to an order using /dts/drone/order/add_message

Image-Enhanced Workflows

• Visual Product Verification: Use images to verify correct products during picking
• Training and Guidance: Display product images to help new staff identify items
• Quality Control: Visual comparison of picked items against product images
• Customer Communication: Include product images in communication workflows