Skip to main content

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.

This guide walks you from a fresh clone to a working rate comparison request against a locally running Ship Quote API. The only hard prerequisites are Node.js 18+ and a running MongoDB 4.4+ instance — either local or a remote connection string.
1

Clone the repository and install dependencies

Clone the repository and install dependencies for both the API and the optional web frontend.
git clone <repo-url>
cd ship-quote
Install the API dependencies:
cd api
npm install
Install the web frontend dependencies (optional — only needed if you want the UI):
cd ../web
npm install
2

Configure environment variables

Copy the example environment files and fill in your values. The API will not start without a valid MongoDB connection string.
# From the repo root
cd api && cp .env.example .env
cd ../web && cp .env.example .env
Open api/.env and set the required values:
NODE_ENV=test

LOG_LEVEL=

PORT=3000

CORS_ORIGIN=http://localhost:5173

API_URL=http://localhost:3000/api

MONGODB_URI_TEST=mongodb://127.0.0.1:27017/shipQuote-db_test
MONGODB_URI=mongodb://127.0.0.1:27017/shipQuote-db

# Scope detection — shipments to this country are classified as national
DEFAULT_COUNTRY=ES

COUNTRIES_API_ENABLED=false
COUNTRIES_URL=https://api.restcountries.com/countries/v5?response_fields=names.translations,codes.alpha_2,names.common
COUNTRIES_API_KEY=

DEFAULT_PALLET_VOLUME=1000000
DEFAULT_PARCEL_VOLUME=6000

# External carrier API keys (optional — carriers are skipped if key is absent)
DACHSER_API_KEY=
DACHSER_API_N_CUSTOMER=
Open web/.env and set the API URL:
VITE_NODE_ENV=test

VITE_API_URL_DEV=http://localhost:3000/api/v1

VITE_API_URL_PROD=/api/v1
Leave DACHSER_API_KEY blank during local development if you do not have a key. Ship Quote will skip Dachser and still return quotes from every static carrier (Cayco, Tecum, MRW, Correosexpress).
3

Seed the database with bootstrap data

The seed script loads the initial geographic data, agency records, pallet types, zones, and rate tables that the rate engine depends on. Run this once before starting the server for the first time.
cd api
npm run seed
You should see log output confirming that provinces, countries, agencies, and tariffs have been inserted. If you re-run the seed it is safe — duplicate records are handled gracefully.
4

Start the API development server

cd api
npm run dev
Nodemon loads server.js with your .env file, connects to MongoDB, initialises the in-memory cache (provinces, countries, agency tariffs), and begins listening.
Server running on port 3000
The API base URL is now http://localhost:3000/api/v1. The interactive OpenAPI documentation is available at http://localhost:3000/api-docs.
5

Make your first rate comparison request

Send a POST request to /api/v1/rates/compareByPostalCode with a destination postal code, country code, and at least one shipment item. The example below quotes a single pallet bound for Madrid (28001).
curl -X POST http://localhost:3000/api/v1/rates/compareByPostalCode \
  -H "Content-Type: application/json" \
  -d '{
    "destinationPostalCode": "28001",
    "countryCode": "ES",
    "items": [
      {
        "typeServices": "pallet",
        "weight": 215,
        "length": 80,
        "width": 90,
        "height": 80
      }
    ]
  }'
Each object in the response array represents one carrier. The available flag tells you whether that carrier returned at least one valid price. When available is false, the incidents array explains why (e.g. no tariff configured for that zone, dimension exceeded, API timeout).
The countryCode field drives scope detection. Sending "countryCode": "ES" with DEFAULT_COUNTRY=ES classifies the shipment as national, so only carriers that support national coverage are queried.
6

Start the web frontend (optional)

The web frontend is a React + Vite application that provides a UI for running comparisons and browsing results. It is completely optional for API usage.
cd web
npm run dev
The development server starts at http://localhost:5173 and proxies API calls to the URL defined in VITE_API_URL_DEV.
Make sure the API is running on port 3000 before opening the web UI, otherwise rate comparison requests from the browser will fail with a network error.

​
Next Steps

  • Read the Configuration page for a full reference of every environment variable.
  • Explore the interactive OpenAPI docs at http://localhost:3000/api-docs to try every endpoint.
  • To quote a parcel instead of a pallet, change "typeServices" to "parcel" and omit the dimension fields — only weight is required for parcels.

Build docs developers (and LLMs) love

Get started for freeTalk to us