voila-api

Voila API Comprehensive Integration Guide

The Voila API is a RESTful service for managing shipping, labeling, and tracking across multiple couriers.

Base Configuration

• Base URL: https://app.heyvoila.io
• Authentication Headers:
  • api-user: <your_api_user>
  • api-token: <your_api_token>
  • OR api-key: <your_api_key>
  • OR Authorization: Basic <base64(api-user:api-token)>
• Common Headers:
  • Content-Type: application/json
  • Accept: application/json

1. Common Integration Flows (Step-by-Step)

A. The "Smart Shipping" Flow (Recommended)

Automatically select the best courier/service based on rules.

1. Request: POST /api/couriers/v1/smart-shipping/create-label
2. Body: Include shipment with ship_to, parcels, and items. (See Core Objects)
3. Success: Response contains tracking_code, label (Base64), and shipment_id.
4. Error Handling: Check success: false or smart_shipping_errors.

B. The "Manual Choice" Flow

1. Get Services: POST /api/couriers/v1/{courier}/get-services to see available options for a shipment.
2. Pick Service: Extract the service_identifier from the response.
3. Create Label: POST /api/couriers/v1/{courier}/create-label with that service_code.

C. The "Bulk Asynchronous" Flow (High Volume)

1. Submit: POST /api/couriers/v1/bulk/create-label-async with an array of requests and a webhook.url.
2. ID: Capture the bulk_request_id.
3. Webhook: Wait for the shipment.created or shipment.failed event at your webhook URL.

---

2. Core Data Objects (Full Schema)

These objects are reused across almost all endpoints. See Labeling & Shipping for full definitions.

Address

interface Address {
  name: string;
  company_name?: string;
  address_1: string;
  address_2?: string;
  address_3?: string;
  city: string;
  county?: string;
  postcode: string;
  /** ISO 3166-1 alpha-2 (e.g., "GB", "US"). */
  country_iso: string;
  country?: string;
  phone: string;
  email: string;
  tax_id?: string;
  eori_id?: string;
  ioss_number?: string;
  ukims_number?: string;
  /** Only for ship_from: looks up a saved address by friendly name. */
  address_name?: string;
  // Additional: abn_number, arn_number, gst_number, voec_number, company_id
}

Parcel

interface Parcel {
  weight: number;
  weight_unit: 'kg' | 'g' | 'lb' | 'oz';
  dim_length: number;
  dim_width: number;
  dim_height: number;
  dim_unit: 'cm' | 'mm';
  items: ShipmentItem[];
  packaging_weight?: number;
  packaging_weight_unit?: string;
  packageId?: string;
  value?: number;
  value_currency?: string;
}

ShipmentItem

interface ShipmentItem {
  description: string;
  quantity: number;
  /** Value per unit. */
  value: number;
  /** e.g., "GBP", "USD". */
  value_currency: string;
  weight: number;
  weight_unit: 'kg' | 'g' | 'lb' | 'oz';
  sku?: string;
  hs_code?: string;
  /** ISO 2-letter origin country code. */
  origin_country?: string;
  image_url?: string;
}

---

3. API Documentation Index

For exhaustive schemas, field definitions, and implementation details for every route, refer to these dedicated files:

• Authentication & User Management: Managing API users, keys, and OAuth tokens.
• Courier Management: Listing couriers, registering credentials, and service presets.
• Labeling & Shipping: Creating labels (Single/Bulk/Async), manifests, and cancellations.
• Tracking & Information: Real-time tracking, shipment history, and document retrieval.
• Smart Shipping Rules: Automating service selection with groups and rules.
• Pricing & Services: Quotes, service lists, and pickup locations.
• Webhooks: Real-time event notifications and delivery logs.
• Third-Party Integrations: Sorted, Peoplevox, Mintsoft, Veeqo, and JD Joybuy mappings.
• Miscellaneous Utilities: Hosted pages, PackEye, and insurance plugins.

4. Bundled API Scripts

The skill includes pre-configured scripts to fetch live information from the Voila API using the playground credentials. These are located in the scripts/ directory.

List Supported Couriers

Fetches the current list of all couriers supported by Voila.

• Node.js: node scripts/list-couriers.js
• Python: python scripts/list-couriers.py

Get Courier Specifics

Fetches required and optional fields for a specific courier (e.g., UPSv2).

• Node.js: node scripts/get-courier-specifics.js <courier_key>
• Python: python scripts/get-courier-specifics.py <courier_key>

5. Troubleshooting & Errors

Standard Error Response

{
  "success": false,
  "message": "Detailed error message here.",
  "errors": {
    "field_name": ["Specific validation error"]
  }
}

Common Issues

1. Validation (422): Usually missing country_iso (must be 2 chars) or invalid postcode format for the destination.
2. Auth (401/403): Check Authentication Headers. Ensure the API User is not disabled.
3. Courier Errors: If success: true but label is empty, check smart_shipping_errors or the message field.
4. Testing Mode: Real labels won't be created unless testing: false is explicitly set (default is often true in examples).