Ship Quote gives developers a unified REST API to compare shipping costs across multiple carrier agencies in one call. Submit a shipment (pallets, parcels, or a mix) with a destination postal code or province code, and the engine fans out to every configured carrier — querying static database rates and live external APIs in parallel — then returns normalized, side-by-side quotes.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/plantasur-dev/ship-quote/llms.txt
Use this file to discover all available pages before exploring further.
Quickstart
Get a running API and your first rate comparison in under five minutes.
Configuration
Configure environment variables, database connection, and carrier API keys.
Rate Engine
Understand how Ship Quote resolves zones, calculates surcharges, and normalizes responses.
API Reference
Full reference for every endpoint — request schemas, response shapes, and error codes.
How It Works
Ship Quote sits between your application and your carrier accounts. You send one request; the API handles the rest.Submit a shipment
POST to
/api/v1/rates/compareByPostalCode with a destination postal code, country code, and a list of items (pallets or parcels with weight and dimensions).Scope detection
The engine automatically classifies the shipment as national or international based on the destination country code, then filters to only the carriers that cover that scope.
Parallel rate fetching
Static carriers are queried from the in-memory MongoDB-backed rate tables. API carriers (e.g. Dachser) are called concurrently via their configured external endpoints.
Key Features
Dual-Provider Engine
Queries static database rates and live carrier APIs in parallel. A failure in one carrier never blocks results from others.
Pallet & Parcel Support
Full dimension and weight validation for both pallet and parcel shipment types, with automatic pallet type classification.
Dynamic Surcharges
Configurable fuel surcharges, weight overages, and dimension-based supplements per agency — calculated automatically on every quote.
O(1) Lookups
Zone and rate data is loaded into in-memory Maps at startup, giving near-instant lookups on every request without extra database round trips.
Geographic Resolution
Resolve postal codes to provinces automatically, or pass a province code directly. Supports Spain-wide coverage with per-postal-code zone exceptions.
Built-in Observability
Winston-based structured logging forwarded to Loki via Promtail, visualized in a Grafana dashboard — all wired up in Docker Compose.
Technology Stack
| Layer | Technology |
|---|---|
| API | Node.js 18+, Express 5, Mongoose 9 |
| Database | MongoDB 4.4+ |
| Frontend | React 19, Vite, Tailwind CSS |
| Testing | Vitest, Supertest |
| Observability | Winston, Loki, Promtail, Grafana |
| Containers | Docker, Docker Compose |
Ship Quote v2.0 uses the
luma theme and follows the OpenAPI 3.0 specification. An interactive Swagger UI is served at /api-docs when the API server is running.