Agent Skills: Posti / Matkahuolto merchant shipping

Posti / Matkahuolto merchant shipping

Load this skill when implementing or reviewing Posti or Matkahuolto merchant shipping integrations, including pickup-point discovery, shipment creation, labels, delivery estimates, labelless sending, tracking, or authentication.

Keep the two providers and their API families distinct. In particular, Posti's versioned merchant gateway, Posti's separate service-account OAuth flow, Posti Tracking API v7, and Matkahuolto's XML interfaces use different hosts, credentials, payloads, and response conventions.

Reference index

| Reference | Topics | | --- | --- | | Interface Hub and access | Matkahuolto agreements, credentials, XML labels, EDI, test behavior, pickup-point data, and embedded tracking | | Matkahuolto pickup points | Office-search endpoint, request defaults, filters, reply fields, CSV behavior, and errors | | Matkahuolto shipments and tracking | Shipment XML, routing, products, labels, customs, dangerous goods, replies, errors, and tracking | | Posti merchant services | Gateway authentication, pickup points, delivery estimates, labelless sending, and API errors | | Posti Tracking API v7 | Authentication, lookup aliases, generic search, paging, response schemas, events, and reservations |

Critical compatibility rules

Keep Posti credential profiles separate

For the versioned Posti gateway, exchange client_id and client_secret as form fields at https://gateway-auth.posti.fi/api/v1/token, then send the bearer token on all operations.

The separate Posti service-account flow requires a Posti contract and an account obtained through customer service. It uses HTTP Basic authentication with accountname:secret at https://oauth2.posti.com/oauth/token; QA and UAT use oauth2.barium.posti.com.

Service-account tokens expire after one hour by default. Five invalid logins lock the account for one hour. Installations using oauth.posti.com or oauth.posti.fi must account for the replaced TLS certificate; oauth2.posti.com needs no certificate-related change.

Do not send fields removed from Matkahuolto shipment XML 2.24

Do not send COD fields, shipment- or root-level ADR codes, or special-handover fields. Place dangerous-goods data at parcel level in DangerousGoodsRow.

Replace the old E01 ADR special-handling code with VA or LQ.

Account for Posti Tracking API schema defects

The generic keys parameter's OpenAPI schema encodes its entire choice list as one enum string, and the path form contains malformed !delivery_groupsequence. Generated clients may need this parameter corrected to follow the prose contract.

The tracking specification declares error statuses without bodies and places the typed success payload under default, rather than an explicit 2xx status. Status-based client generators may need an override for SearchResponseDto or ReservationStatusesResponseDto.

None of the 48 component schemas declares required properties. Consumers must tolerate absent fields.

Treat tracking pagination conservatively

Posti Tracking API v7 declares limit as 1–1000 with a default of 100, while the operation text separately warns of a hard 100-shipment return limit. Follow returned counts and test paging semantics. combined=true is typed as a string and is explicitly warned not to work reliably with pagination.

Matkahuolto quick reference

Choose the integration surface

• Submit XML label requests with HTTP POST over HTTPS; unencrypted HTTP is rejected. A successful XML response contains the reply and an address-label PDF.
• Integrate pickup points through the real-time API or periodically download the dataset into the store's database, such as once daily.
• Send shipment information by API or file transfer. EDI messages may be XML or CSV.
• Display Matkahuolto tracking data directly in the store, in addition to the recipient-facing Track & Trace service.

The test environment returns correctly formatted responses but does not process consignments. Production activation only requires changing the contact address.

Search pickup points

POST MHSearchOfficesRequest to:

https://extservices.matkahuolto.fi/noutopistehaku/public/v2/searchoffices

Use Content-Type: application/xml or text/xml. Login is the registered customer number. Address search requires PostalCode or City; use Id to look up one known office.

Defaults are Country=FI, ResponseType=XML, MaxResults=5, and Coordinates=N. The legacy /noutopistehaku/public/searchoffices address runs the same search but URL-encodes the response.

Submit shipments

Send MHShipmentRequest XML with Content-Type: text/xml to:

https://extservices.matkahuolto.fi/mpaketti/mhshipmentxml

Use the extservicestest host for testing. UserId is the supplied account number without leading zeroes. A request may contain multiple Shipment elements, and their labels are returned in one PDF.

The mandatory shipment fields are shipment/message type, weight, package count, sender account, receiver name/postal code/city, and product code. Empty ShipmentNumber asks the service to allocate one. Dates use DD.MM.YYYY, counts are integers, and decimal values use a dot.

Always represent the payer account with SenderId, ReceiverId, or PayerId. PayerCode is S, R, or O; O makes PayerId mandatory.

Query tracking

GET https://extservices.matkahuolto.fi/mpaketti/public/tracking with HTTP Basic authentication. Supply either ids, a comma-separated list of at most ten shipment or parcel IDs, or from/to date-time input. XML is the default; Accept: application/json selects JSON.

A valid query with no matching events returns an empty message rather than an error.

Posti merchant quick reference

Authenticate to the versioned gateway

The merchant specification identifies API version 2026-04.0, with production base URL https://gateway.posti.fi/2026-04 and LTS support through 2029-04-30. Every operation requires a bearer token.

POST /api/v1/token HTTP/1.1
Host: gateway-auth.posti.fi
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Search and retrieve pickup points

POST /pickuppoints with required searchCriteria. Supported searches are street/postcode location, coordinate and radius, rectangle, free text, and parcel locker. Accept-Language defaults to fi and accepts fi, sv, da, en, et, lv, or lt; X-Posti-LogisticsId is optional.

Use GET /pickuppoints/{id} or /pickuppoints/{countryCode}/{pupCode} for targeted lookup. GET /pickuppoints/{countryCode} lists points and returns a reusable pagingContinuationToken.

Request estimates and labelless codes

POST /estimate with required time, origin, destination, and product inside an estimate object. The response is an estimates array whose delivery time may be null.

POST /labelless with a tracking number to obtain a sending code; validation.noEdiCheck is optional and defaults to false. GET /labelless/{trackingNumber} performs the same lookup, and GET /labelless/shipment/{sendingCode} resolves the code back to shipment data.

Request objects declare additionalProperties: false; omit undeclared JSON fields. Error objects always require errorCode, message, and details, even when details is null.

Posti Tracking API v7 quick reference

Use base URL https://api.posti.fi/tracking/7. Every operation inherits an OAuth 2.0 client-credentials scheme with token URL /tracking/oauth/token. Send the bearer token and request either ordinary JSON or application/vnd.tracking.api.v1+json.

Use dedicated identifier paths when appropriate, or GET /tracking/7/shipments/find with a required keywords array of 1–100 unique strings. GET /tracking/7/shipments/find/{keyword} accepts one value of 3–60 characters.

All shipment searches support lastModified, type=ANY|FREIGHT|PARCEL, order=ASC|DESC, response-unit selectors, start, and limit. Restricted GET /tracking/7/shipments/event/date searches events in an interval where from is inclusive and to is exclusive.

SearchResponseDto has independent freightShipments and parcelShipments arrays. Quantity query selectors use long unit names, while response objects use abbreviated units.

Restricted GET /tracking/7/reservations/status requires delivery-window from/to, destination country, and a postcode array. Array examples are comma-separated strings even though the schemas do not declare custom serialization; verify serialization when bypassing a generated client.

Review checklist

• Verify the provider, API family, base host, credential profile, and content type before comparing request fields.
• For Matkahuolto, keep pickup-point defaults, shipment XML conventions, and tracking response selection explicit.
• For Posti merchant APIs, reject undeclared JSON properties and preserve required error fields even when details is null.
• For Posti Tracking API v7, tolerate absent response fields and review generated handling of keys, success responses, array serialization, and pagination.
• Consult the topic references for complete field values, nested limits, statuses, event codes, and error-code mappings.