OmaPosti Pro API v2: Overview
OmaPosti Pro API v2 is a Posti order channel for letter, parcel, and freight products. It has a similar messaging format as the SmartShip API, when sending new shipment orders via integration.
OmaPosti Pro API saves the information directly to Posti’s shipment register and returns address labels for the sent shipments to the sending system in a PDF format.
The shipment information from other IT systems (usually an operative system, such as order processing, ERP, eCommerce solution) needed for printing address labels is transmitted to OmaPosti Pro API as a JSON message. The detailed data content and structure of the message is described in this instruction.
Breaking changes between V1 and V2
Please notice, that the return shipment logic has been changed in v2 to match with the SmartShip API logic. This means that when an individual return shipment, e.g. 2108 (PO2108 in SmartShip format), is created, the sender party is set as the same sender as in the original shipment and the receiver party is also the same as in the original shipment. OmaPosti Pro API v2 will then switch the sender and receiver in the actual shipment information, including the generated shipping label.
If this change is not taken into account when migrating from v1 to v2, the individual return shipments will be created with invalid sender and receiver parties.
Authentication
OmaPosti Pro API uses OAuth 2.0 client credentials. The access credentials can be created in the developer portal. See the page Creating API Credentials for OmaPosti Pro API v2.
Please notice, that the API role for OmaPosti Pro API v2 is shippingapi, when creating a new application credentials.
If migrating from SmartShip API, then notice that the authentication method has been changed. In SmartShip API the authentication method is a Basic auth with username/password passed in the Authorization header as base64 encoded string (“Authorization: Basic aaaabbb…”). The Basic auth and old credentials will not work with OmaPosti Pro API v2.
Versioning / General conventions
- (Older version 1 is accessed only via API key created in the OmaPosti Pro UI.)
- Version 2 is accessed only via Oauth token, fetched with access credentials created in this developer portal.
Major difference between the versions is how the return shipment parties behave. V1 keeps the parties as they are in the order, but V2 switches the sender and receiver like in SmartShip API.
The developer portal instructions are version 2 specific.
Environments
- Production
Rate limits
Production access to the API is limited per caller IP address to 50 requests per second.
Testing
Testing environment is not yet available. Production environment can be used for creating sample shipments, as they are not invoiced unless physically shipped.
Instructions for OmaPosti Pro API v2
Creating API credentials for OmaPosti Pro API v2
Comments
0 comments
Please sign in to leave a comment.