Testing your integration

Unit tests (no network)

Mock the HTTP layer and cover each outcome with these responses:

Case	Status	Body
Routed	200	The success response from Create a shipment
Contact missing	400	{"detail": "this parcel's routing tier requires recipient_email, recipient_phone", "field": "recipient_contact", "missing": ["recipient_email", "recipient_phone"]}
Bad key	401	{"detail": "invalid API key"}
Validation	422	{"detail": [{"type": "literal_error", "loc": ["body", "country"], "msg": "Input should be 'FI'"}]}
No route	422	{"detail": "no routing rule matched this parcel"}
Carriers rejected	422	{"detail": "all carriers rejected the shipment", "shipment_id": 42, "state": "UNROUTABLE"}
Carriers down	502	{"detail": "all carriers unavailable", "shipment_id": 43, "state": "FAILED"}
Timeout	—	Raise your HTTP library’s timeout error

Assert that:

• the API key and base URL come from configuration;
• the same Idempotency-Key is sent on every retry of a parcel;
• weights and dimensions are integers, and zipcode stays a string;
• 400 and 422 are not retried; 502 and timeouts are;
• batch items are checked one by one.

Live tests (test environment only)

Caution

Run these once against https://api-test.e-parcel.fi with a test key, not in CI on every commit: each routed parcel is registered with a carrier.

Prefix customer_reference with TEST-. Start from the example request and use a fresh Idempotency-Key per scenario unless noted.

#	Scenario	Change from the example request	Expected
1	Letterbox-size parcel	1000 g, 25 × 200 × 300 mm, omit delivery_method	200, ROUTED, tracking number and label
2	Door-size parcel	As in the example (1340 g, 370 × 370 × 270 mm)	200, ROUTED
3	Locker	2500 g, 300 × 250 × 200 mm, "delivery_method": "LOCKER"	200, ROUTED
4	Pickup only	"delivery_method": "PICKUP"	422, no route
5	Too heavy	30000 g	422, no route
6	Missing phone	Omit recipient_phone	400, missing: ["recipient_phone"]
7	Foreign destination	"country": "SE"	422, validation error on country
8	Bad key	Authorization: Bearer wrong	401
9	Idempotent retry	Repeat scenario 2 with the same key	200, same shipment_id and tracking number
10	Read back	GET /api/v1/shipments/{id} from scenario 2	200, delivery_type set
11	Label download	GET /api/v1/shipments/{id}/label	200, application/pdf
12	Unknown id	GET /api/v1/shipments/999999999	404
13	Mixed batch	Batch of scenario 1 and scenario 5	200; item 1 ROUTED, item 2 UNROUTABLE with error

Postman

Prefer clicking through? Every request is also in the interactive reference, which can send it to the test environment from your browser. Ask E-Parcel for the Postman collection if your team uses Postman.