Delivery Companies

Server

Download schema

List delivery companies

GET

https://api.wocart.store

/api/delivery-companies

X-API-Key (header)

List all delivery companies with optional filters

List delivery companies › query Parameters

active

string · enum

Filter by active status

Enum values:

true

false

search

string

Search in company name (EN/AR) and code

limit

integer · max: 100

Maximum number of results

Default: 50

offset

integer | null · min: 0

Pagination offset

Default: 0

List delivery companies › Responses

200

List of delivery companies

success

boolean · required

DeliveryCompany[] · required

count

integer · required

Number of items returned

GET/api/delivery-companies

curl https://api.wocart.store/api/delivery-companies \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "comp_abc123",
      "name": "Yalidine",
      "nameAr": "ياليدين",
      "code": "yalidine",
      "website": "https://www.yalidine.com",
      "active": true,
      "apiEndpoint": "https://api.yalidine.app/v1",
      "isConnected": true,
      "supportsHomeDelivery": true,
      "supportsStopDesk": true,
      "autoValidate": true,
      "notes": "Primary carrier for Algiers region",
      "provider": "yalidine",
      "providerConfig": {
        "key": {}
      },
      "webhookSecretSet": true,
      "capabilities": {
        "homeDelivery": true,
        "stopDesk": true,
        "separateValidation": true,
        "bulkCreate": 0,
        "parcelFields": {
          "weight": true,
          "fragile": true,
          "remarks": true
        },
        "limits": {
          "maxAmount": 0,
          "maxDescription": 0
        },
        "update": true,
        "cancel": true,
        "remarks": {
          "add": true,
          "list": true
        },
        "history": true,
        "historyBatch": 0,
        "findByReference": true,
        "updates": "webhook",
        "label": true,
        "askReturn": true,
        "requestNewAttempt": true,
        "confirmReturn": true,
        "stopDeskList": true,
        "geoNames": true,
        "verifyConnection": true
      },
      "webhookEndpointId": "webhookEndpointId",
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ],
  "count": 0
}

json

application/json

Create delivery company

POST

https://api.wocart.store

/api/delivery-companies

X-API-Key (header)

Create a new delivery company integration

Create delivery company › Request Body

name

string · minLength: 1 · required

nameAr

string · minLength: 1 · required

code

string · minLength: 1 · pattern: ^[a-z0-9_]+$ · required

Lowercase alphanumeric with underscores

website

string | null · uri

active

boolean

Default: true

apiEndpoint

string | null · uri

apiToken

string | null

API authentication token

apiUserGuid

string | null

Tenant/user GUID for ZR Express

supportsHomeDelivery

boolean

Default: true

supportsStopDesk

boolean

Default: true

autoValidate

boolean

When true, orders are auto-validated on dispatch (locked at carrier). When false, orders stay editable. If omitted, a safe default is derived per provider.

notes

string | null

provider

string | null · enum

Which carrier adapter serves this company. When omitted it is derived from the code.

Enum values:

yalidine

zr_express

noest

ecotrack

object

The adapter's own settings (e.g. Yalidine: platform, fromWilayaName, proxyBaseUrl, proxySecret). Merged onto the stored settings; a secret sent back masked keeps the stored one; null removes a key.

Create delivery company › Responses

Delivery company created

success

boolean · required

DeliveryCompany · required

Third-party delivery company integration

POST/api/delivery-companies

curl https://api.wocart.store/api/delivery-companies \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "Yalidine",
  "nameAr": "ياليدين",
  "code": "yalidine",
  "website": "https://www.yalidine.com",
  "active": true,
  "apiEndpoint": "https://api.yalidine.app/v1",
  "apiToken": "apiToken",
  "apiUserGuid": "apiUserGuid",
  "supportsHomeDelivery": true,
  "supportsStopDesk": true,
  "autoValidate": true,
  "notes": "notes",
  "provider": "yalidine",
  "providerConfig": {
    "key": {}
  }
}'

Example Request Body

{
  "name": "Yalidine",
  "nameAr": "ياليدين",
  "code": "yalidine",
  "website": "https://www.yalidine.com",
  "active": true,
  "apiEndpoint": "https://api.yalidine.app/v1",
  "apiToken": "apiToken",
  "apiUserGuid": "apiUserGuid",
  "supportsHomeDelivery": true,
  "supportsStopDesk": true,
  "autoValidate": true,
  "notes": "notes",
  "provider": "yalidine",
  "providerConfig": {
    "key": {}
  }
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "comp_abc123",
    "name": "Yalidine",
    "nameAr": "ياليدين",
    "code": "yalidine",
    "website": "https://www.yalidine.com",
    "active": true,
    "apiEndpoint": "https://api.yalidine.app/v1",
    "isConnected": true,
    "supportsHomeDelivery": true,
    "supportsStopDesk": true,
    "autoValidate": true,
    "notes": "Primary carrier for Algiers region",
    "provider": "yalidine",
    "providerConfig": {
      "key": {}
    },
    "webhookSecretSet": true,
    "capabilities": {
      "homeDelivery": true,
      "stopDesk": true,
      "separateValidation": true,
      "bulkCreate": 0,
      "parcelFields": {
        "weight": true,
        "fragile": true,
        "remarks": true
      },
      "limits": {
        "maxAmount": 0,
        "maxDescription": 0
      },
      "update": true,
      "cancel": true,
      "remarks": {
        "add": true,
        "list": true
      },
      "history": true,
      "historyBatch": 0,
      "findByReference": true,
      "updates": "webhook",
      "label": true,
      "askReturn": true,
      "requestNewAttempt": true,
      "confirmReturn": true,
      "stopDeskList": true,
      "geoNames": true,
      "verifyConnection": true
    },
    "webhookEndpointId": "webhookEndpointId",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get delivery company

GET

https://api.wocart.store

/api/delivery-companies/{id}

X-API-Key (header)

Get a single delivery company by ID

Get delivery company › path Parameters

id

string · required

Delivery company ID

Get delivery company › Responses

200

Delivery company details

success

boolean · required

DeliveryCompany · required

Third-party delivery company integration

GET/api/delivery-companies/{id}

curl https://api.wocart.store/api/delivery-companies/:id \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "id": "comp_abc123",
    "name": "Yalidine",
    "nameAr": "ياليدين",
    "code": "yalidine",
    "website": "https://www.yalidine.com",
    "active": true,
    "apiEndpoint": "https://api.yalidine.app/v1",
    "isConnected": true,
    "supportsHomeDelivery": true,
    "supportsStopDesk": true,
    "autoValidate": true,
    "notes": "Primary carrier for Algiers region",
    "provider": "yalidine",
    "providerConfig": {
      "key": {}
    },
    "webhookSecretSet": true,
    "capabilities": {
      "homeDelivery": true,
      "stopDesk": true,
      "separateValidation": true,
      "bulkCreate": 0,
      "parcelFields": {
        "weight": true,
        "fragile": true,
        "remarks": true
      },
      "limits": {
        "maxAmount": 0,
        "maxDescription": 0
      },
      "update": true,
      "cancel": true,
      "remarks": {
        "add": true,
        "list": true
      },
      "history": true,
      "historyBatch": 0,
      "findByReference": true,
      "updates": "webhook",
      "label": true,
      "askReturn": true,
      "requestNewAttempt": true,
      "confirmReturn": true,
      "stopDeskList": true,
      "geoNames": true,
      "verifyConnection": true
    },
    "webhookEndpointId": "webhookEndpointId",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update delivery company

PATCH

https://api.wocart.store

/api/delivery-companies/{id}

X-API-Key (header)

Update an existing delivery company

Update delivery company › path Parameters

id

string · required

Delivery company ID

Update delivery company › Request Body

name

string · minLength: 1

nameAr

string · minLength: 1

code

string · minLength: 1 · pattern: ^[a-z0-9_]+$

website

string | null · uri

active

boolean

apiEndpoint

string | null · uri

apiToken

string | null

apiUserGuid

string | null

supportsHomeDelivery

boolean

supportsStopDesk

boolean

autoValidate

boolean

notes

string | null

provider

string | null · enum

Which carrier adapter serves this company. When omitted it is derived from the code.

Enum values:

yalidine

zr_express

noest

ecotrack

object

The adapter's own settings (e.g. Yalidine: platform, fromWilayaName, proxyBaseUrl, proxySecret). Merged onto the stored settings; a secret sent back masked keeps the stored one; null removes a key.

Update delivery company › Responses

Delivery company updated

success

boolean · required

DeliveryCompany · required

Third-party delivery company integration

PATCH/api/delivery-companies/{id}

curl https://api.wocart.store/api/delivery-companies/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "name",
  "nameAr": "nameAr",
  "code": "code",
  "website": "https://www.example.com/path/to/resource",
  "active": true,
  "apiEndpoint": "https://www.example.com/path/to/resource",
  "apiToken": "apiToken",
  "apiUserGuid": "apiUserGuid",
  "supportsHomeDelivery": true,
  "supportsStopDesk": true,
  "autoValidate": true,
  "notes": "notes",
  "provider": "yalidine",
  "providerConfig": {
    "key": {}
  }
}'

Example Request Body

{
  "name": "name",
  "nameAr": "nameAr",
  "code": "code",
  "website": "https://www.example.com/path/to/resource",
  "active": true,
  "apiEndpoint": "https://www.example.com/path/to/resource",
  "apiToken": "apiToken",
  "apiUserGuid": "apiUserGuid",
  "supportsHomeDelivery": true,
  "supportsStopDesk": true,
  "autoValidate": true,
  "notes": "notes",
  "provider": "yalidine",
  "providerConfig": {
    "key": {}
  }
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "comp_abc123",
    "name": "Yalidine",
    "nameAr": "ياليدين",
    "code": "yalidine",
    "website": "https://www.yalidine.com",
    "active": true,
    "apiEndpoint": "https://api.yalidine.app/v1",
    "isConnected": true,
    "supportsHomeDelivery": true,
    "supportsStopDesk": true,
    "autoValidate": true,
    "notes": "Primary carrier for Algiers region",
    "provider": "yalidine",
    "providerConfig": {
      "key": {}
    },
    "webhookSecretSet": true,
    "capabilities": {
      "homeDelivery": true,
      "stopDesk": true,
      "separateValidation": true,
      "bulkCreate": 0,
      "parcelFields": {
        "weight": true,
        "fragile": true,
        "remarks": true
      },
      "limits": {
        "maxAmount": 0,
        "maxDescription": 0
      },
      "update": true,
      "cancel": true,
      "remarks": {
        "add": true,
        "list": true
      },
      "history": true,
      "historyBatch": 0,
      "findByReference": true,
      "updates": "webhook",
      "label": true,
      "askReturn": true,
      "requestNewAttempt": true,
      "confirmReturn": true,
      "stopDeskList": true,
      "geoNames": true,
      "verifyConnection": true
    },
    "webhookEndpointId": "webhookEndpointId",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Delete delivery company

DELETE

https://api.wocart.store

/api/delivery-companies/{id}

X-API-Key (header)

Delete a delivery company that never carried a parcel, with its API log and webhook inbox. A company that has carried parcels keeps their history: deactivate it instead.

Delete delivery company › path Parameters

id

string · required

Delivery company ID

Delete delivery company › Responses

Delivery company deleted

success

boolean · required

Get company stop desks

GET

https://api.wocart.store

/api/delivery-companies/{id}/stop-desks

X-API-Key (header)

Read stop desks from DB (no live API call). Admin must sync first via POST .../sync-stop-desks

Get company stop desks › path Parameters

id

string · required

Delivery company ID

Get company stop desks › query Parameters

wilayaId

integer | null

Filter by wilaya ID

activeOnly

string · enum

Filter by active flag (default true)

Enum values:

true

false

Default: true

Get company stop desks › Responses

200

Stop desks list

success

boolean · required

object · required

Sync stop desks

POST

https://api.wocart.store

/api/delivery-companies/{id}/sync-stop-desks

X-API-Key (header)

Fetch stop desks from carrier API and upsert into DB. Active flag is preserved.

Sync stop desks › path Parameters

id

string · required

Delivery company ID

Sync stop desks › Responses

Stop desks synced

success

boolean · required

object · required

Sync carrier geo names

POST

https://api.wocart.store

/api/delivery-companies/{id}/sync-geo

X-API-Key (header)

Fetch the carrier's own wilaya/commune name lists and build the per-carrier name map (exact strings the carrier matches parcel addresses against). Yalidine-only for now — carriers that match by name. Response reports matched and unmapped reference rows. Dispatch resolves our wilaya/commune IDs through this map before calling the carrier.

Sync carrier geo names › path Parameters

id

string · required

Delivery company ID

Sync carrier geo names › Responses

Geo names synced

success

boolean · required

object · required

Test carrier connection

POST

https://api.wocart.store

/api/delivery-companies/{id}/test-connection

X-API-Key (header)

Verifies the company's stored credentials against its carrier API. A negative outcome (invalid token, API access disabled) returns 200 with ok:false — the check itself succeeded. Provider support: ecotrack (all 82 companies) ✅ | others ❌ OPERATION_NOT_SUPPORTED.

Test carrier connection › path Parameters

id

string · required

Delivery company ID

Test carrier connection › Responses

Connection check executed

success

boolean · required

object · required

Sync this company's open shipments now

POST

https://api.wocart.store

/api/delivery-companies/{id}/sync-shipments

X-API-Key (header)

Reads the carrier's history of the company's open shipments — up to 50 per request, the longest unsynced first — and records every status not recorded yet (a status already received by webhook or an earlier sync is not recorded twice). Pull-only carriers (EcoTrack platform, NOEST, Guepex) are also synced on a schedule every few minutes; this is the merchant's "now", for any carrier whose history can be read. Replaces reconcile-orders.

Sync this company's open shipments now › path Parameters

id

string · required

Delivery company ID

Sync this company's open shipments now › Responses

What the sync found

success

boolean · required

object · required

Toggle stop desk active flag

PATCH

https://api.wocart.store

/api/delivery-companies/{id}/stop-desks/{code}/toggle

X-API-Key (header)

Toggle the active flag on a single stop desk. Admin can deactivate stop desks that can't be serviced.

Toggle stop desk active flag › path Parameters

id

string · required

Delivery company ID

code

string · required

Stop desk code

Toggle stop desk active flag › Responses

200

Stop desk toggled

success

boolean · required

object · required

Register ZR Express webhook

POST

https://api.wocart.store

/api/delivery-companies/{id}/webhook/register

X-API-Key (header)

Registers a webhook endpoint with ZR Express via their API. Stores the endpointId and signing secret.

Register ZR Express webhook › path Parameters

id

string · required

Delivery company ID

Register ZR Express webhook › Responses

200

Webhook registered

success

boolean · required

webhookUrl

string · uri · required

endpointId

string · required

Unregister ZR Express webhook

DELETE

https://api.wocart.store

/api/delivery-companies/{id}/webhook/register

X-API-Key (header)

Deletes the registered webhook endpoint from ZR Express and clears the DB fields.

Unregister ZR Express webhook › path Parameters

id

string · required

Delivery company ID

Unregister ZR Express webhook › Responses

200

Webhook unregistered

success

boolean · required

Save Yalidine webhook secret

PATCH

https://api.wocart.store

/api/delivery-companies/{id}/webhook/secret

X-API-Key (header)

Stores the Yalidine webhook secret key (entered manually after setting up webhook in Yalidine dashboard).

Save Yalidine webhook secret › path Parameters

id

string · required

Delivery company ID

Save Yalidine webhook secret › Request Body

secret

string · minLength: 1 · required

Webhook secret key from Yalidine dashboard

Save Yalidine webhook secret › Responses

200

Secret saved

success

boolean · required

List inbound webhook events

GET

https://api.wocart.store

/api/delivery-companies/{id}/webhook/events

X-API-Key (header)

The company's webhook inbox, newest first: every event its carrier pushed, with what processing made of it — ok, ignored, unmatched (no shipment has that parcel), unknown_status (recorded, but a status Wocart does not interpret), deferred_settlement (a money event), error (to be retried at nextAttemptAt) or dead (tries spent). Each row names the shipment it was recorded on and its order. rawPayload is left out: the log's value is the outcome.

List inbound webhook events › path Parameters

id

string · required

Delivery company ID

List inbound webhook events › query Parameters

limit

integer · min: 1 · max: 100

Page size (1-100)

Default: 25

offset

integer | null · min: 0

Offset for keyset-free pagination

Default: 0

result

string · enum

Filter by processing result — the operational lens: error and dead need attention, unmatched and unknown_status may need a parcel attached or a status mapped

Enum values:

pending

ignored

unmatched

unknown_status

deferred_settlement

error

dead

List inbound webhook events › Responses

Webhook events page

success

boolean · required

object · required

GET/api/delivery-companies/{id}/webhook/events

curl https://api.wocart.store/api/delivery-companies/:id/webhook/events \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "b537eb81-e24d-4df5-be7a-b3bf3293a524",
        "provider": "yalidine",
        "eventId": "eventId",
        "tracking": "tracking",
        "eventType": "parcel_status_updated",
        "result": "pending",
        "reason": "reason",
        "errorMsg": "errorMsg",
        "shipmentId": "shipmentId",
        "orderId": "orderId",
        "orderNumber": "orderNumber",
        "attempts": 0,
        "nextAttemptAt": "nextAttemptAt",
        "processedAt": "processedAt",
        "createdAt": "2024-08-25T15:00:00Z"
      }
    ],
    "total": 0
  }
}

json

application/json

Process an inbox event again

POST

https://api.wocart.store

/api/delivery-companies/{id}/webhook/events/{eventId}/retry

X-API-Key (header)

Processes an event that ended in error, dead, unmatched or unknown_status again, now — after fixing the company's settings, attaching its parcel, or mapping its status. Its tries start over.

Process an inbox event again › path Parameters

id

string · required

Delivery company ID

eventId

string · required

Inbox event id

Process an inbox event again › Responses

What processing made of it this time

success

boolean · required

object · required

Driver Payments Shipping Profiles