Yalidine Integration

Yalidine (Guepex) Delivery Integration

Yalidine is Algeria's largest courier network. Its API is exposed under the brand name Guepex (base URL api.guepex.app, dashboard guepex.app) — same company, same API, same webhooks. Treat "Yalidine" and "Guepex" as the same integration.

This skill gives a coding agent everything needed to wire a platform up to Yalidine end-to-end: creating parcels, looking up delivery zones, calculating fees, and reacting to delivery-status changes via webhooks — without ever needing to see the user's real API credentials.

Before you write any code

Read the reference file(s) that match what you're building. Don't load both up front if the task only needs one — this keeps context lean.

• references/api-reference.md — every REST endpoint (parcels, wilayas, communes, centers, fees, histories): params, filters, fields, full request and response shapes.
• references/webhooks-reference.md — event types, payload formats, CRC challenge validation, HMAC signature verification, retry policy.
• references/human-only-steps.md — the dashboard actions only the account owner can do. Read this first if the user hasn't mentioned having credentials yet.
• references/troubleshooting.md — check here before improvising a fix when a call fails, a webhook doesn't fire, or a signature check rejects a real delivery. Most "weird" failures map to a known cause.

assets/.env.example — copy this into the project as a starting point for the required environment variables.

Two ready-to-adapt implementations are in scripts/:

• scripts/yalidine-client.ts — typed API client (fetch-based, no dependencies) covering all endpoints, pagination, and rate-limit headers.
• scripts/webhook-handler.ts — a Supabase Edge Function (Deno) implementing CRC validation + signature verification + event routing. Adapt the request/response wrapper for Express/Next.js/etc. if the project isn't on Supabase — the validation and security logic underneath is identical.

The integration workflow

1. Confirm the user has generated credentials. You cannot get an API ID, API TOKEN, or webhook secret key yourself — these only exist inside the user's own Guepex Developer Dashboard and Webhooks Dashboard. If they haven't mentioned having them, point them to references/human-only-steps.md and wait. Never ask them to paste a screenshot of their dashboard or the raw key values into chat — have them put the values straight into an env file instead (see Security below).

2. Set up configuration, not hardcoded values:

   YALIDINE_API_ID=...
   YALIDINE_API_TOKEN=...
   YALIDINE_BASE_URL=https://api.guepex.app/v1/
   YALIDINE_WEBHOOK_SECRET=...   # only needed if implementing webhooks
   

   Add these to .env.example with empty values so the user knows what to fill in, and to the project's actual env file (gitignored) if the user gives you the real values directly (not via screenshot).

3. Build the API client layer first using references/api-reference.md — start with whichever endpoints the feature needs (usually: wilayas/communes for address forms, fees for a checkout price preview, parcels for order creation, histories for tracking pages).

4. Cache static lookup data. Wilayas, communes, and centers change rarely. Don't call these endpoints on every request — fetch once, store in the app's DB or a cache with a daily/weekly refresh, and read from there. This also protects the user's rate-limit quota (see below).

5. Build the webhook endpoint last, once parcel creation works, using references/webhooks-reference.md. The endpoint must exist and pass CRC validation before the user can create the webhook in their dashboard — tell them the order of operations if they ask you to "just set up the webhook."

6. Tell the user what to do in the dashboard once your code is ready — see references/human-only-steps.md for the exact list, in order.

Non-negotiable security rules

• Never put YALIDINE_API_TOKEN in front-end/client-side code (browser JS, mobile app bundles). It's a backend-only secret — every Yalidine call must go through the user's own server or edge function, never directly from a browser.
• Always verify the X-YALIDINE-SIGNATURE header (HMAC-SHA256 of the raw request body, keyed with the webhook secret) before trusting any webhook payload. Reject anything that doesn't match with a 400 — see references/webhooks-reference.md for the exact algorithm.
• Always keep the CRC challenge-response check (?subscribe=...&crc_token=... → echo crc_token back, 200 status) live in the webhook endpoint permanently. Yalidine re-validates it periodically; if it ever fails, the webhook is auto-disabled and the user stops getting delivery updates silently.
• Never write real API IDs, tokens, secret keys, webhook URLs, or alert emails into code comments, example files, or documentation you generate — use env var references only, even in "here's an example" snippets.
• The webhook endpoint must respond within 10 seconds. If the user's business logic (sending SMS, updating other systems, etc.) might be slow, have the endpoint just persist the raw payload and return 200 immediately, then process it in a background job/queue.

Key domain gotchas (read before generating parcel-creation code)

• Addresses are matched by name, not ID, when creating/editing a parcel. from_wilaya_name and to_wilaya_name/to_commune_name must exactly match a name from the wilayas/communes endpoints. Validate against your cached list before sending — a typo fails the whole parcel.
• Personal data comes back masked (firstname, familyname, contact_phone, address, and the phone segment of qr_text) on every GET and PATCH response — e.g. "M*****d". This is intentional privacy protection on Yalidine's side. Never overwrite your own stored values with these masked ones. POST (creation) responses are not masked.
• Stop-desk deliveries require a real stopdesk_id. Look it up from the centers endpoint (filter by wilaya_id/commune_id) — don't let a user type one in freely.
• Edit and delete only work while the parcel's last_status is "En préparation." Once Yalidine picks it up, both PATCH and DELETE fail. Surface this constraint in the UI rather than letting users hit an API error.
• Exchange parcels: if has_exchange is true, product_to_collect is required.
• Oversize fee applies past 5kg billable weight, where billable weight = max(actual_weight, length*width*height*0.0002). Formula and worked examples are in references/api-reference.md under Fees.
• Rate limits (default): 5/sec, 50/min, 1000/hour, 10000/day. Every response includes x-second-quota-left, x-minute-quota-left, x-hour-quota-left, x-day-quota-left headers — read them, and back off before hitting 429. Repeated 429s extend the ban period.
• Bulk creation: POST /v1/parcels takes an array of parcels, even for one. The response is keyed by order_id, and partial failure is normal — some parcels in a batch can fail while others succeed. Always check each entry's success field individually rather than assuming an all-or-nothing result.

If something looks like it needs a dashboard action mid-build

Stop and tell the user — don't guess or fabricate a credential/URL/ID to keep going. Point them at references/human-only-steps.md.

If a call or a webhook doesn't behave as expected

Check references/troubleshooting.md before improvising — most failures (401s, rejected commune names, signature mismatches, silently-stopped webhooks) have a known cause and fix there rather than needing a guess.

Definition of done — verify before calling the integration finished

Don't declare the integration complete on "the code compiles." Actually run these checks, and tell the user which ones you could/couldn't verify yourself (some need their real credentials or a live deployment):

• A real call to GET /v1/wilayas succeeds with the user's credentials (proves auth is wired correctly).
• Wilaya/commune names used in parcel creation are validated against a cached lookup, not typed freely.
• Stop-desk flows resolve stopdesk_id from /v1/centers, never from free user input.
• Parcel creation handles partial batch failure — each entry's success field is checked individually, not just the HTTP status.
• The API token/ID never appear in any client-side/browser-reachable code path — grep the frontend bundle for the env var names if unsure.
• If webhooks are in scope: the CRC endpoint returns the exact token for a manual curl "<url>?subscribe=1&crc_token=test123" check, and this logic has no code path that could ever be removed by mistake.
• If webhooks are in scope: signature verification uses the raw request body, not re-serialized JSON, and rejects on mismatch.
• If webhooks are in scope: the endpoint returns 200 well under 10 seconds even under real processing load (heavy logic deferred to a queue/background job).
• Event event_id values are deduplicated before side effects run (e.g. don't send a "your parcel shipped" SMS twice for a retried delivery).