The MesColis REST API gives B2B customers programmatic access to carrier rates, shipment records, package tracking, and address book management. Base URL: https://mescolis.ca/api/v1
9 endpoints across 4 resource groups. All endpoints require Bearer token authentication and respect per-route rate limits.
| Method | Path | Summary | Group | Scope |
|---|---|---|---|---|
| GET | /rates |
Compare shipping rates | Rates | rates:read |
| GET | /shipments |
List shipments | Shipments | shipments:read |
| GET | /shipments/{id} |
Get shipment | Shipments | shipments:read |
| GET | /track |
Track a package | Tracking | track:read |
| GET | /addresses |
List addresses | Addresses | addresses:read |
| POST | /addresses |
Create an address | Addresses | addresses:write |
| GET | /addresses/{id} |
Get an address | Addresses | addresses:read |
| PATCH | /addresses/{id} |
Update an address | Addresses | addresses:write |
| DELETE | /addresses/{id} |
Delete an address | Addresses | addresses:write |
Every request must include a Bearer token in the Authorization header.
Generate keys from your dashboard at Settings → Developer Hub → Generate Key.
Keys are prefixed mc_live_ and shown only once at creation.
Each key carries a set of scopes (rates:read, shipments:write, etc.) — endpoints reject requests with insufficient scope (HTTP 403).
curl https://mescolis.ca/api/v1/rates?from_postal=H2X1Y1&to_postal=M5V2T6&weight_kg=1.5 \ -H "Authorization: Bearer mc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Per-user limits, enforced by Upstash Redis. Responses include standard Retry-After headers on 429 errors.
| Resource | Limit |
|---|---|
/rates | 30 requests / minute |
/shipments | 60 requests / minute |
/track/* | 60 requests / minute |
/addresses | 30 requests / minute |
Subscribe to shipment lifecycle events via webhook subscriptions managed in your Developer Hub. Events fire for:
All webhook deliveries are signed with HMAC-SHA256. Verify the X-MesColis-Signature header against your endpoint secret using timing-safe comparison.
The full schema, every parameter, request/response examples, and a try-it-now console are rendered below by the Scalar OpenAPI viewer. The schema itself is publicly available at /openapi.yaml and /api/openapi (JSON).