API Examples

This document provides practical examples for the most common HFT71 plugin integration flows.

1) Authenticate to HFT71

Endpoint:

• POST /authentication/login

Example request:

{
  "username": "api-user@example.com",
  "password": "your-password"
}

Example response:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer"
}

2) Send order (POST /order)

Example minimal payload generated by plugin:

{
  "referenceId": "72774",
  "orderDate": "2026-03-02",
  "address": {
    "address1": "Main Street 10",
    "address2": "",
    "city": "Wroclaw",
    "zip": "50-001",
    "state": "DS",
    "country": "PL",
    "customerName": "John Doe",
    "email": "john@example.com",
    "mobile": "+48123456789"
  },
  "items": [
    {
      "sku": "BY004-00007-0046",
      "quantity": 2
    }
  ]
}

Example success response:

{
  "orderId": 123456,
  "sendDate": "2026-03-02T12:00:00Z"
}

3) Poll order status

Endpoint:

• GET /order/{orderId}/status

Example response:

[
  {
    "sku": "BY004-00007-0046",
    "status": "In Production"
  }
]

The plugin maps status values to WooCommerce statuses using hft71_status_mapping.

4) Get customer-facing status

Endpoint:

• GET /order/{orderId}/customer-status

Example response:

[
  {
    "sku": "BY004-00007-0046",
    "status": "Item Finished"
  }
]

Plugin stores this in order meta:

• _hft71_customer_status (order-level array)
• _hft71_item_status (line-item meta, mapped by SKU)

5) Webhook call into WooCommerce

Endpoint:

• POST /wp-json/hft71/v1/order-status

Headers (optional, if secret configured):

• X-HFT71-Webhook-Secret: your-shared-secret

Request body:

{
  "external_id": "123456",
  "status": "Closed"
}

Example response:

{
  "success": true,
  "message": "Status zaktualizowany."
}

6) Stock available sync source

Endpoint:

• GET /stock/available?page=1&count=200

Example response shape:

[
  {
    "sku": "BY004-00007-0046",
    "stock": 18
  }
]

Plugin behavior:

• finds product by SKU
• updates stock quantity and stock status
• saves _hft71_stock_available

7) Bidirectional update (PUT /order/{orderId})

When enabled, plugin may send:

Status update payload example:

{
  "orderStatus": "Closed"
}

Address update payload example:

{
  "address": {
    "address1": "Main Street 11",
    "address2": "",
    "city": "Wroclaw",
    "zip": "50-001",
    "state": "DS",
    "country": "PL",
    "customerName": "John Doe",
    "email": "john@example.com",
    "mobile": "+48123456789"
  }
}

8) Read model configuration (WordPress helpers)

Since v1.3.0, product model data is stored in plugin DB tables and exposed via public PHP helpers (not REST endpoints):

$models  = hft71_get_models();
$config  = hft71_get_model( 'BY004' );
$sku_m   = hft71_get_model_sku( 'BY004', 'Black', 'M' );          // BY004-00007-0046
$sku_s   = hft71_get_model_sku( 'BY004', 'Black', 'S' );          // BY004-00007-0051
$sku_xxl = hft71_get_model_sku( 'BY004', 'Heather Grey', 'XXL' ); // BY004-00431-0060
$map     = hft71_get_model_sku_map( 'BY004' );
$black   = hft71_get_color( 'Black' ); // ['id' => …, 'name' => 'Black', 'hex' => '#000000']

Example normalized object returned by hft71_get_model() (see schemas/model-config.schema.json):

{
  "code": "BY004",
  "label": "Classic T-Shirt",
  "description": "<p>…</p>",
  "base_price": 29.99,
  "double_sided_surcharge": 5.0,
  "wc_category_id": 42,
  "sizes": ["S", "M", "L", "XL", "XXL"],
  "colors": [
    { "name": "Black", "hex": "#000000" },
    { "name": "Heather Grey", "hex": "#9B9B9B" }
  ],
  "skus": {
    "Black": {
      "S": "BY004-00007-0051",
      "M": "BY004-00007-0046"
    },
    "Heather Grey": {
      "XXL": "BY004-00431-0060"
    }
  }
}

All helpers are filterable (hft71_get_models, hft71_get_model, hft71_get_model_sku, hft71_get_model_sku_map, hft71_get_color, etc.). Price changes fire the hft71_model_price_changed action.