Getting started

E-Parcel ships parcels inside Finland. You send one parcel (recipient, sender, weight, dimensions and a preferred delivery method) to POST /api/v1/shipments. In that same request E-Parcel picks the carrier, registers the parcel with it, and returns the carrier’s tracking number and a printable PDF label.

The call is synchronous. There is no queue, no webhook and nothing to poll: when the call returns, the outcome is final.

Send your first shipment

1. Get a test API key. Keys are issued by E-Parcel, one per environment. Ask your E-Parcel contact for a key for the test environment.

2. Put it in your environment, never in code:

   export EPARCEL_BASE_URL=https://api-test.e-parcel.fi
   export EPARCEL_API_KEY=...   # your test key

3. Create a shipment. The idempotency key identifies this parcel, so a retry can never create a second shipment.

   curl

   curl -sS "$EPARCEL_BASE_URL/api/v1/shipments" \
     -H "Authorization: Bearer $EPARCEL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: TEST-order-1001-parcel-1" \
     --max-time 60 \
     -d '{
       "customer_reference": "TEST-ORDER-1001",
       "recipient_name": "Anna Aalto",
       "recipient_email": "anna@example.com",
       "recipient_phone": "+358401234567",
       "address_line1": "Mannerheimintie 1",
       "city": "Helsinki",
       "zipcode": "00100",
       "country": "FI",
       "sender_name": "Example Store Oy",
       "sender_address_line1": "Testikatu 5",
       "sender_city": "Turku",
       "sender_zipcode": "20100",
       "sender_country": "FI",
       "weight_g": 1340,
       "length_mm": 370,
       "width_mm": 370,
       "height_mm": 270
     }' > shipment.json

   Python

   import os
   import httpx
   
   response = httpx.post(
       f"{os.environ['EPARCEL_BASE_URL']}/api/v1/shipments",
       headers={
           "Authorization": f"Bearer {os.environ['EPARCEL_API_KEY']}",
           "Idempotency-Key": "TEST-order-1001-parcel-1",
       },
       json={
           "customer_reference": "TEST-ORDER-1001",
           "recipient_name": "Anna Aalto",
           "recipient_email": "anna@example.com",
           "recipient_phone": "+358401234567",
           "address_line1": "Mannerheimintie 1",
           "city": "Helsinki",
           "zipcode": "00100",
           "country": "FI",
           "sender_name": "Example Store Oy",
           "sender_address_line1": "Testikatu 5",
           "sender_city": "Turku",
           "sender_zipcode": "20100",
           "sender_country": "FI",
           "weight_g": 1340,
           "length_mm": 370,
           "width_mm": 370,
           "height_mm": 270,
       },
       timeout=60,
   )
   response.raise_for_status()
   shipment = response.json()

   TypeScript

   const response = await fetch(`${process.env.EPARCEL_BASE_URL}/api/v1/shipments`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.EPARCEL_API_KEY}`,
       "Content-Type": "application/json",
       "Idempotency-Key": "TEST-order-1001-parcel-1",
     },
     body: JSON.stringify({
       customer_reference: "TEST-ORDER-1001",
       recipient_name: "Anna Aalto",
       recipient_email: "anna@example.com",
       recipient_phone: "+358401234567",
       address_line1: "Mannerheimintie 1",
       city: "Helsinki",
       zipcode: "00100",
       country: "FI",
       sender_name: "Example Store Oy",
       sender_address_line1: "Testikatu 5",
       sender_city: "Turku",
       sender_zipcode: "20100",
       sender_country: "FI",
       weight_g: 1340,
       length_mm: 370,
       width_mm: 370,
       height_mm: 270,
     }),
     signal: AbortSignal.timeout(60_000),
   });
   const shipment = await response.json();

4. Read the result. A 200 with state: "ROUTED" means the parcel is registered with a carrier:

   {
     "shipment_id": 42,
     "state": "ROUTED",
     "carrier": "POSTI",
     "carrier_number": 2,
     "tracking_number": "JJFI67863998958478726",
     "label_pdf_base64": "JVBERi0xLjQK...",
     "error": null
   }

5. Save the label. Base64-decode label_pdf_base64 and print the PDF at actual size on 101 × 200 mm label stock:

   jq -r .label_pdf_base64 shipment.json | base64 --decode > label.pdf

Test on the test environment only

Every shipment routed on production (https://api.e-parcel.fi) is a real, billable consignment. Develop and run every test against https://api-test.e-parcel.fi.

What to read next

• Create a shipment: every field and where it comes from in your system.
• Errors and retries: the outcomes your code must handle, and how to retry without creating duplicates.
• Go-live checklist: what a finished integration looks like.

What the API does not do (today)

There are no endpoints to cancel or amend a shipment, list shipments, quote prices, choose a specific parcel locker or pickup point, or receive webhooks and carrier tracking events. Destinations outside Finland are not served. If your integration needs one of these, contact E-Parcel.