Aymakan

Aymakan

This connector uses the Aymakan API v2 (https://api.aymakan.net/v2) of the Saudi courier Aymakan: tracking and full shipment details by tracking number or by your order reference, your shipment list, AWB label links, pickup requests, cities, PUDO points, warehouses and the collection addresses of your account. Creating and cancelling shipments and pickups is included but installed switched off.

Setup (about 2 minutes)

1. Sign in to the Aymakan customer dashboard.
2. Open Technical > AyMakan API and copy the API key (security code). Paste it into AYMAKAN_API_KEY. It is sent as is in the Authorization header, without Bearer.
3. Install and run aymakan_ping: logged_in must be Yes.

Use the production key. A key from Aymakan's development environment answers Invalid Credentials here; regenerating the key in the dashboard invalidates the old one, so update every other integration that uses it.

Tracking: aymakan_get_tracking takes one or more tracking numbers (comma-separated, no spaces, e.g. AY2866494373,AY2866494374) and aymakan_get_shipments_by_reference one or more of your own order references. Both return the full shipment: delivery and collection details, COD amount, weight and pieces, status and status_label, and tracking_info, the history of status codes (AY-0001 created, then pickup, hub, out for delivery, delivered, returned and so on) with English and Arabic descriptions. Only shipments of your own account are found; a reference that does not exist answers 422 No Shipments Found. Shipments created without a reference cannot be fetched by reference.

Your shipments: aymakan_list_shipments lists every shipment of the account with tracking number, reference, receiver, COD amount, delivery attempts, status_code and status_label and the main dates, 100 per page (fixed, about 110 KB); page with page and follow last_page. For one shipment prefer aymakan_get_tracking.

Labels (AWB): aymakan_get_awb_label returns a link to the PDF label of one shipment and aymakan_get_bulk_awb_labels one PDF for several. Aymakan only returns the link while the shipment is still in AY-0001 (created, not yet picked up).

Pickups: aymakan_list_pickup_requests lists your pickup requests with status, date, time slot and number of shipments; aymakan_list_pickup_cities the cities where pickups are possible and aymakan_get_time_slots the slots for a date (today or later, YYYY-MM-DD).

Reference data: aymakan_list_cities lists the cities Aymakan delivers to in English and Arabic (use the English name exactly in a shipment), aymakan_list_pudo_locations pickup and drop-off points (lockers and shops, optionally for one city, the id goes into pudo_location_id for service LOC), aymakan_list_dropoff_locations Aymakan's warehouses and aymakan_list_addresses the collection addresses saved on your account.

Writes (switched off): aymakan_create_shipment, aymakan_cancel_shipment, aymakan_create_pickup_request and aymakan_cancel_pickup_request book or cancel real courier work and are installed switched off; an admin turns them on deliberately. Before each call show the user the shipment (receiver, city, COD amount, pieces) or the tracking number or pickup request and get a yes. A shipment can only be cancelled while in AY-0001, a pickup request while pending or processing.

Errors: 401 Invalid Credentials means a wrong, old or development key. 422 carries the reason in message (not found, validation errors per field in errors). Without the Accept: application/json header, which the connector always sends, Aymakan would answer in HTML.