Shipping Rate Comparison by Destination Postal Code

This is the primary rate comparison endpoint. Submit a destination postal code, a country code, and a list of shipment items and Ship Quote will auto-resolve the postal code to its corresponding province, determine whether the shipment is national or international, fan out requests to every active agency that covers that scope in parallel, and return a normalized per-agency result array. Both static (database-backed) and API-integrated agencies are queried simultaneously, so you always receive the most complete picture in a single call.

The DEFAULT_COUNTRY environment variable controls which country code is treated as national. When the server is configured for Spain (DEFAULT_COUNTRY=ES), sending countryCode: "ES" triggers national agency matching; any other ISO-2 code triggers international agency matching.

Endpoint

POST /api/v1/rates/compareByPostalCode

Middleware chain

Requests pass through three middleware layers before reaching the controller:

Order	Middleware	What it checks
1	`schemaValidation`	Request body must be present and non-empty
2	`rateDestinationValidation`	`destinationPostalCode` and `countryCode` must be non-null strings; when the country matches `DEFAULT_COUNTRY`, postal code must match the 5-digit format (`\d{5}`)
3	`rateItemsValidation`	`items` must be a non-empty array; each item must have a positive `weight`, positive `large`/`width`/`height`, and a valid `typeServices` value

Request body

destinationPostalCode

string

required

The destination postal code. Must be a 5-digit string when shipping within the default country (e.g. "18001" for Granada, Spain). For international destinations the format constraint is relaxed.

countryCode

string

required

ISO 3166-1 alpha-2 country code for the destination (e.g. "ES", "FR", "DE"). The value determines whether national or international agencies are queried.

items

array

required

List of shipment items to price. Must contain at least one entry.

Show Item object

typeServices

string

required

Type of shipment. Accepted values: "pallet" or "parcel".

weight

number

required

Item weight in kilograms. Must be greater than 0.

large

number

required

Item length in centimetres. Must be greater than 0. Required for all items (pallet and parcel).

width

number

required

Item width in centimetres. Must be greater than 0. Required for all items.

height

number

required

Item height in centimetres. Must be greater than 0. Required for all items.

Response body

The response is a flat JSON array. Each element represents one active agency and its computed services.

[]

array

Array of per-agency result objects.

Show Agency result object

agency

string

Display name of the shipping agency (e.g. "Cayco", "Dachser").

available

boolean

true when at least one priced service was found for this agency; false when no applicable rate exists (the agency is active but has no tariff covering this route or item type).

zone

string

The agency-specific zone name resolved for the destination (e.g. "ZONA 3", "NACIONAL").

services

array

List of service options offered by this agency for the shipment.

Show Service object

service

string

Service level name as defined by the agency (e.g. "economy", "premium", "targoflex (500380)"). Set to "Sin tarifa disponible" when available is false.

total

number

Total price for this service in EUR (all surcharges included). 0 when no rate is available.

itemCount

number

Number of shipment items that were successfully priced under this service. 0 when no rate is available.

breakdown

array

Itemized price components that sum to total.

Show Breakdown entry

type

string

Component label (e.g. "Tarifa base", "fuel surcharge", "Product surcharge").

price

number

Cost of this component in EUR.

palletType

string

Pallet category matched for this item (e.g. "CUARTO", "QUARTER PALLET"). Present on static-agency base-rate entries.

quantity

number

Number of units priced at this rate. Present on static-agency base-rate entries.

unitPrice

number

Price per unit before multiplication by quantity. Present on static-agency base-rate entries.

items

array

Echo of the input item(s) that generated this breakdown line. Present on static-agency base-rate entries.

incidents

array

Warnings or errors generated while computing this service. Empty array on success.

Show Incident object

type

string

Short incident label (e.g. "Sin tarifa disponible").

message

string

Optional human-readable detail.

Examples

curl -X POST http://localhost:3000/api/v1/rates/compareByPostalCode \
  -H "Content-Type: application/json" \
  -d '{
    "destinationPostalCode": "18001",
    "countryCode": "ES",
    "items": [
      {
        "typeServices": "pallet",
        "weight": 215,
        "large": 80,
        "width": 90,
        "height": 80
      }
    ]
  }'

HTTP status codes

Code	Meaning
`200 OK`	Rate comparison completed. The array always contains one entry per active agency in scope, even when `available` is `false`.
`400 Bad Request`	Validation failed. The response body contains a `message` field describing which field failed (e.g. `"Postal Code invalid"`, `"items cannot be empty"`, `"Item 1: weight must be a number > 0"`).
`404 Not Found`	The postal code could not be resolved to a known province for the default country, or no rate comparison result was produced.
`500 Internal Server Error`	An unhandled server-side error occurred.

A 200 response does not guarantee all agencies returned a price. Always check available on each result entry and inspect incidents for service-level warnings before presenting rates to end users.

How scope detection works

The controller calls getProvinceByPostalCode(destinationPostalCode) to resolve the province from an in-memory map loaded at server startup. If the country code matches DEFAULT_COUNTRY (default: ES) and no province is found, a 404 is returned immediately. For international shipments the province defaults to an empty string and international-scoped agencies are queried instead. The rates service then calls getScope(countryCode), which returns "national" when countryCode === DEFAULT_COUNTRY and "international" otherwise. Only agencies whose rules.coverage array includes the detected scope are included in the comparison.

If you already know the province code (e.g. from a prior call to GET /api/v1/locations/provinces), use compareByProvinceCode to skip the postal-code resolution step entirely and reduce latency.

Rates

Agencies

Locations

Pallets & Zones

Shipping Rate Comparison by Destination Postal Code

Endpoint

Middleware chain

Request body

Response body

Examples

HTTP status codes

How scope detection works

Build docs developers (and LLMs) love

Rates

Agencies

Locations

Pallets & Zones

Documentation Index

​Endpoint

​Middleware chain

​Request body

​Response body

​Examples

​HTTP status codes

​How scope detection works

Build docs developers (and LLMs) love

Endpoint

Middleware chain

Request body

Response body

Examples

HTTP status codes

How scope detection works