Yalidine Delivery 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.