D2 API — Vendor Integration Guide

Authentication

D2 is Paltrack's message switch service — it receives structured data from authorised vendors and routes it to the relevant parties on the network. This API is the integration point for that exchange.

Every endpoint accepts either a bearer token or an API key — pick whichever suits your integration, no need to send both. The examples on this page show the Authorization: bearer header for brevity, but an x-api-key header works identically on every endpoint in this guide.

Bearer Token

Request a token using the OAuth 2 Resource Owner Password flow. Tokens are valid for 60 minutes; request a new one before expiry.

POST https://helpdesk.paltrack.co.za/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={your_username}&password={your_password}

The response returns an access_token:

{
  "access_token": "eyJ0eXAiOiJKV1QiLC...",
  "token_type":   "bearer",
  "expires_in":   3599
}

Pass the token on every subsequent request:

Authorization: bearer {access_token}

API Key

A simpler alternative to Bearer tokens for server-to-server integrations that don't want to manage token refresh. API keys don't expire on a fixed cycle — they're valid until you revoke them, or until an optional expiry date you set yourself.

x-api-key: {your_api_key}

Getting a key:

• Self-service — log in to Paltrack's client portal (PalPortal) and go to API Keys. Click Generate to issue a new key for your company.
• Via Paltrack support — if you don't have PalPortal access, ask your Paltrack contact to issue one from your company record in Helpdesk.

Each key is tied to a single company (not an individual user), so any of your integrations can share one key. You can view your keys and revoke them any time from the same API Keys screen.

Credential scoping

Both bearer tokens and API keys are scoped to your Paltrack Location Code(s) and Location ID(s) — Depots, Packhouses, and Exporters can only access data linked to their own location codes, and only the data D2's Split rule engine has determined they should receive. This is the same scoping logic D2 Classic (flat files) uses — nothing changes here for vendors migrating from flat files to the API.

Testing

A QA environment is available so you can test your integration before going live:

https://papiqa.paltrack.co.za

Endpoint paths and request/response formats are identical to production — just point your integration at this host instead. For a QA API key, contact your Paltrack representative — QA keys are issued directly rather than through self-service PalPortal. Credential scoping applies in QA exactly as it does in production.

Rate Limiting & Content Type

All clients are limited to 60 requests per minute per IP address. Exceeding this returns HTTP 429. Implement exponential back-off and retry logic in your client.

All requests and responses use JSON only. Set Content-Type: application/json on every POST request.

Submit Dispatch

The tables below cover the fields most integrations need. Several request bodies have deeply nested objects (e.g. Consignments[].Pallets[], Consignments[].Container) with many more optional fields than are practical to list here — for the complete field list on any endpoint, see the Swagger UI.

{
  "trackingId": "550e8400-e29b-41d4-a716-446655440000",
  "status":     "Received"
}

{
  "trackingId":  "550e8400-e29b-41d4-a716-446655440000",
  "payloadType": "Dispatch",
  "errors": [
    { "field": "POFileName", "message": "Required field missing" }
  ]
}

Submit Intake

Submit Stock

Submit Mates

Submit Day Instruction

Submit Load Instruction

Find Payloads

[
  {
    "fileType":          "PO",
    "fileName":          "PO_PACKHOUSE_20260630_001.txt",
    "sourceDepot":       "PACKHOUSE",
    "destinationDepot":  "COLDSTORE",
    "exporterLocnId":    "P01",
    "documentNumber":    "DOC001",
    "season":            "2026",
    "statsDetailId":     12345
  }
]

Get Payload

{
  "fileType":          "PO",
  "fileName":          "PO_PACKHOUSE_20260630_001.txt",
  "sourceDepot":       "PACKHOUSE",
  "destinationDepot":  "COLDSTORE",
  "exporterLocnId":    "P01",
  "documentNumber":    "DOC001",
  "season":            "2026",
  "statsDetailId":     12345
}

Payload Received

{ "result": true }

Validation

Submitted payloads (Submit Dispatch / Submit Intake / Submit Stock / Submit Mates / Submit Day Instruction / Submit Load Instruction) go through two validation layers, in order. Which layer rejects your payload determines the shape of the error response.

Layer 1 — required fields

Fields marked REQ in the endpoint tables above (e.g. POFileName, TruckHeader, Consignments) are checked before your payload is looked at further. If one is missing, you get back a field-level error shape rather than the errors[] shape used elsewhere in this guide:

{
  "model.POFileName": [ "The POFileName field is required." ],
  "model.TruckHeader": [ "The TruckHeader field is required." ]
}

This guide's tables cover the common fields only — nested objects (Consignment, TruckHeader, Pallet, etc.) have their own required fields too. The Swagger UI schema reflects all of these, since it's generated directly from the same model.

Layer 2 — business-rule validation

Once required fields pass, Paltrack runs payload-specific business rules and returns errors in the errors[] shape shown earlier in this guide.

Integration Flow

Error Codes