EcoTrack Courier Integration

Hard rules (traps that bite)

1. Auth is Bearer everywhere — EXCEPT GET /api/v1/get/orders/status, which authenticates via an api_token query param. If you send only the Bearer header there, you get an auth error.
2. Rate limit: 50 requests/minute → HTTP 429 {"message": "Too Many Attempts."}. Auto-validate flows make 2 calls per order (create + valid) — a bulk dispatch of 25+ orders can hit the ceiling. Surface 429 distinctly; pace or back off.
3. Response shapes are not uniform. Memorize:
   • get/maj → plain JSON array
   • get/tracking/info → object with activity array
   • get/communes → object keyed by index (never assume array)
   • get/wilayas, get/orders data → plain array / paginated object
   • get/desks → { my_desk: {...}, other_desks: [...] }
   • bulk create/orders results → keyed by reference when the order had one, else by index string
   • Single create errors → HTTP 200 with {success: false, error: 1000x} OR HTTP 422 Laravel errors bag. Handle BOTH.
4. montant is the COD amount INCLUDING delivery fees (official param doc). CodFlow currently sends order.price (product subtotal) at dispatch.ts createShipment call — see CONFORMANCE.md before shipping a fix; confirm merchant intent (delivery fee charged to customer ⇒ must be included).
5. type param: 1=Livraison, 2=Échange, 3=PICKUP, 4=Recouvrement. Our adapter always sends 1. capabilities.ts claiming canExchange: false contradicts the official docs — all four types are allowed.
6. Update semantics: officially all params optional, but Packers (one tenant) rejects calls missing type, wilaya, commune, adresse, montant, tel. The caller must pre-fill ALL fields from the order, then apply overrides — the route handler already does this; keep it that way.
7. Update after validation is a silent no-op: EcoTrack answers success: true but ignores the change (Packers-confirmed). We guard client-side (status must be dispatched). Never trust a post-validation update response.
8. Delete only works pre-validation (error 10001 after). Post-validation, the only carrier-side actions are ask/for/order/return (courier may IGNORE it) and valid/returns (confirming received returns).
9. Labels are raw PDF bytes behind Bearer auth — the URL is never public. Always serve through proxyShipmentLabel (server-side fetch), never expose the token to the browser.
10. No webhooks. Tracking is pull-only: get/tracking/info (single) and get/trackings/info (bulk, ≤100). The /orders/:id/tracking endpoint is the only freshness source for EcoTrack orders.
11. Status wording drifts per tenant. Never treat French display labels as stable identifiers. The stable vocabulary is the activity enum keys and the status enum keys (both listed in API-REFERENCE.md). An unknown label must surface as-is, never be guessed into a status.
12. Tracking queries answer list-style — a lazy "take the first row" client can attach the wrong parcel's status. Always query with the exact tracking number and match exactly.
13. Validation limits: phone 9–10 digits numeric; wilaya code 1–58 integer; every string field max 255 chars. commune is a NAME (string), matched against the tenant's enabled commune list — a wrong/misspelled commune name is a 422, and a disabled wilaya returns error 10002.
14. Bulk endpoint reliability is per-tenant: Packers' create/orders returned HTTP 500 (server-side bug, documented in dispatch.ts). Verify on the specific tenant before relying on bulk dispatch; fall back to sequential single creates.
15. The _ecotrack suffix is load-bearing: adapter selection, the autoValidate default, and the update guard all key off isEcotrackCompany(code). A company code without the suffix silently loses all three.

What "done right" looks like

• Every param name matches API-REFERENCE.md exactly (French, snake_case).
• Every response parse handles the endpoint's actual shape (rule #3).
• 429 and success:false + error-code responses are surfaced with their codes.
• npm run typecheck and npm test pass in cod-server.
• The adapter test file covers create/validate/update/delete/remarks/tracking.
• No credentials, tokens, or tenant URLs in code or tests — only in wrangler secrets / .dev.vars.