Shipfunk API documentation

Get started

These pages depict all the Shipfunks logistics related APIs that can be used by e-commerce platforms.

From the left you can find all the different information links, like the different APIs that will let you dive deeper into them. You may also just scroll down to the api or other information you want to see.

On the right there are the actual code examples and the query and response messages.

Common information

Urls

Usually the API’s combine normal and REST API’s. The interface urls have variables in them, which is depicted next.

For every api, there is an url you must send the request to. The urls look something like this:

https://shipfunkservices.com/api/1.2/get_delivery_options/{real_http_code}/{request_type}/{return_type}/{orderid}”

All of these urls have modifiable variables in them, and these variables are identified with square brackets. These variables have some limits and definitions, which are always explained in the section looking like this:

This section almost always has the same parameters, and the only thing changing is the actual API name(“get_delivery_options” in this case). As you can see, you may select the send and return format for the data. If for example “request_type” is json, service expects valid json-data. This is important to note, and the service will give you an error if parsing the data fails because of wrong setting. The “return_type” states the datatype of the returning data. You may choose whichever suits your needs better. Other kind of variables are also present, and the whole API may be just a REST-api which means that there is only the url and all the data is sent through it. Some APIs might have the orderid as an optional parameter, since the API doesn’t actually need it. This is explained in the associated documentations.

Authentication

This API version uses API-keys to identify you. There are two different keys, one for testing, and other for production. Always rememeber to change the API key when switching the environment! You can get the keys from our Extranet after you’ve created an account in there. Recommended way of sending the API key is in the HTTP headers “Authorization” -section, but if you cannot send it in there for some reason, for instance if you are using JSONP, you can put the API key into the xml/json request and we’ll get it from there. See the examples in the APIs for more clarification.

POST and GET -variable names

If the API is not fully a REST-API, you might need to provide variable name for the data to be sent. If the correct variable name is not provided, service will return an error. Variable names are shown in the corresponding API pages.

JSONP

All APIs support the use of ajax jsonp -call.

Data format

All the incoming and outgoing data must be in string format. You need to parse the returning data yourself, and the data you send to the service, must also be in string format in order the system to understand the data. There are different formats like json and xml that can be transmitted through the APIs. Note that there are limits to these formats themselves, like xml don’t generally like chars like ‘&’. Always remember to encode all the data into a html-compliant format. Otherwise our service will return error. Our service expects all the data to be in a UTF-8 format! If your data has some other encoding, please transform it into UTF-8 before sending it to us.

Query structure

Every querys root element is “query”. Under this element can be any number of other elements, that can also have any number of other elements. See examples for more info. Note that in the examples there are elements that have 0 -value in them, and at the same time it states that the element is optional if it’s a 0. Elements are left in the examples for clarity purposes, but they can really be omitted if the condition is fullfilled.

Response structure

Responses can vary a bit. Usually there is a “response” -element as a root, and after that there can be “Error”, “Info”, or some other data elements. This can be however be different between datatypes. JSON doesn’t have the “response”-element at all, but just an “Error” or “Info” -element as root. These are all shown in more detail in the examples.

Boolean variables

Some elements are boolean values of true and false, but in order to these variables to work expectedly in all circumstances, all the boolean values are changed to 1 and 0. 1=true, and 0=false. Datatype for these variables is of course Int. Usually these booleans default to 0 if omitted, but note that some variables default to 1! This is clearly stated in the each APIs section of “Data contents and formats”, in the depiction of the element that might have this kind of behavior.

Package cards

Some APIs create and return a brand new package card in a pdf, zpl or html format. Note that the interface doesn’t return an actual pdf, but a base64-encoded string -version of the pdf. zpl is pure zpl code and html pure html code. IMPORTANT NOTE: We send the EDI-messages at the same time as the package card is created! See the EDI-message -section for more information on what is EDI.

Units of measures and money

  • Monetary values must be in one of the following currencies:

    • EUR for Euro
    • USD for U.S. dollar
    • JPY for Japanese yen
    • BGN for Bulgarian lev
    • CZK for Czech koruna
    • DKK for Danish krone
    • GBP for British pound
    • HUF for Hungarian forint
    • PLN for Polish zloty
    • RON for Romanian lei
    • SEK for Swedish krona
    • CHF for Swiss franc
    • NOK for Norwegian krone
    • HRK for Croatian kuna
    • RUB for Russian ruble
    • TRY for Turkish lira
    • AUD for Australian dollar
    • BRL for Brazil real
    • CAD for Canadian dollar
    • CNY for Chinese yuan
    • HKD for Hong Kong dollar
    • IDR for Indonesian rupiah
    • ILS for Israeli shekel
    • INR for Indian rupee
    • KRW for South Korean won
    • MXN for Mexican peso
    • MYR for Malaysian ringgit
    • NZD for New Zealand dollar
    • PHP for Philippine peso
    • SGD for Singapore dollar
    • THB for Thai baht
    • ZAR for South African rand
  • Allowed units for weights are:

    • g for grams
    • kg for kilos
    • oz for ounces
    • lb or lbs for pounds
    • st or stones
  • Allowed units for dimensions are:

    • mm for millimeters
    • cm for centimeters
    • m for meters
    • in for inches
    • ft for feets

Packages dimensions should be given in the following format: depth, width, height, and delimiter between the values should be ‘x’. The values themselves can be double values with dot as delimiter. Example: “60.5x30x40”. IMPORTANT NOTE: Height must always be the last value! If the dimensions are set wrong, the service might return wrong delivery options and/or prices!

Units of time

ISO 8601 -format is used. This standard uses the 24-hour clock system. Usually the services need only the hour and minutes(hh:mm), but if the seconds are needed, this will be stated in the relative documentation. Examples of usage: “08:00”, or “19:00”.

Countrycodes

All countrycodes must be in two letter ISO 639-1 -format. Examples: “FI” or “US” or “SE”. Note that this is an ISO 639-1 country code, not ISO 639-1 language code!

Languages

All languages must be in two letter ISO 639-1 -format. Examples: “fi” or “en” or “sw”. Note that this is an ISO 639-1 language code, not ISO 639-1 country code!

Phone numbers

Phone numbers must be in one of these formats: “040 1234567” or “+358401234567”. If phone number has the “+”-sign, urlencode must be used on the variable to preserve the plus -sign.

“Dummy”-delivery options

If for some reason Shipfunks system could not generate any delivery options with the given parameters, it will return “dummy”-options. These option are “Delivery to nearest pickup point” and “Home delivery”. These delivery options will have fixed prices and approximated delivery times, and no pickup points for customer to choose. Shipfunk will as soon as possible manually select a suitable delivery option for the situation, and the process can continue normally after that. You may adjust some settings for the dummys, or disable dummy options in the Extranet alltogether.

Eshops own pickup points

If you have declared store pickup points in the extranet, those pickup points will be returned in the GetDeliveryOptions -api. These pickups are returned in a same way every other delivery options is returned. Because every delivery option has carriercodes, your pickup points will have ones as well. Your company will have the carriercode of “1xxxxxxxxxxx” (always starts with one(1)!), and the name of the “transport company” is the name of your eshop. Product name will be “Pickup from the store”, in the language of the customer. See the examples in the GetDeliveryOptions-api for clearer vision of how this works.

EDI-message

EDI-message is an electronic notification for the transport companies, which will tell the transport company which kind of delivery we are talking about. This message has all the necessary information of the deliverable goods like the addresses from and to, package sizes, additional services, etc. We will create this message for you automatically so you don’t need to worry about it.



Errors

Common information

There are two types of errors. The real errors that indicate that something really went wrong, and the info-responses. Info responses indicate that there was propably no real error here, the service works, but it couldn’t find something you requested. Usually this happens because you gave the service a wrong code or number etc. If you are sure that the given data is correct, contact our technical support in love@shipfunk.com.

Errors can be returned with a real HTTP-status codes, but you’ll have to provide the ‘true’ -parameter in the url for this to happen. Errors are returned with a 400-code, and infos with a 202-code. Infos still belong into the 2XX-group since they are not really errors, but more like notifications, infos.

Errors listed

Message type Message code Message text Additional Info
Error 00001 No data. Shipfunk system didn't receive data or there is not enough data.
Error 00002 Malformed xml or not xml at all. Cannot create xml-object. System cannot create an xml-object from the given string.
Error 00003 There is something wrong with the xml. Are the element names correct. System can create the xml-object, but it cannot find all the necessary items from it.
Error 00004 Malformed json or not json at all. Cannot create json-object. System cannot create json-object from the given string.
Error 00005 There is something wrong with the json. Are the element names correct. System can create the json-object, but it cannot find all the necessary items from it.
Error 00007 Some internal error happened. There might be something wrong with the Shipfunk system, or the message you sent caused something weird to happen. Contact the Shipfunk's technical support for more details.
Error 00012 Webshop id is not correct.
Error 00013 Could not update the customer info. Is the order id: 'X' correct?
Error 00015 Return type cannot be recognized. Currently only XML and JSON are supported. Maybe you misspelled it?
Error 00016 Route not found. System couldn't recognize the url you are using. Double check that it's a correct one.
Error 00020 Order status is required.
Error 00025 We couldn't find any products nor parcels. Please double check that the message is correct. At least one of them is required. Either "products" or "parcels", or even both.
Error 00027 Phone number: 'X' is not in valid format. Please double check the documentations for correct phone number formats.
Error 00028 We couldn't figure out what you just sent to us. The data should be in string format or an object, but neither was found.
Error 00030 Field 'pickupid' required.
Error 00032 We couldn't find enough information for the order: 'X'. Are you sure that the order exists and the customer has selected a delivery option? Are you calling the api with a correct username? If the customer has not yet selected a delivery option, some actions cannot be taken and this error will be shown. This could also indicate a problem in our service.
Error 00033 Something went wrong and we couldn't create any tracking codes for you at this time. This could indicate a problem in our service, or your request data was somehow invalid. Contact the Shipfunk's technical support for more details.
Error 00035 Could not find the 'selected_option' element.
Error 00036 Carriercode cannot be empty.
Error 00037 Productcode cannot be empty.
Error 00042 Could not find the 'webshop' element.
Error 00043 Webshop 'api_key' cannot be empty.
Error 00044 Could not find the 'order' element.
Error 00047 'serviceCode' cannot be empty.
Error 00050 'weight' cannot be empty.
Error 00051 First name cannot be empty.
Error 00052 Last name cannot be empty.
Error 00053 Street address cannot be empty.
Error 00054 Postcode cannot be empty.
Error 00055 City cannot be empty.
Error 00056 Country cannot be empty.
Error 00057 Phone number cannot be empty.
Error 00058 Email cannot be empty.
Error 00059 We couldn't find the order from our database. Is the order ID: 'X' correct? Double check that your api key is correct too. This could indicate that there is something wrong with our service, but first double check that the order id and your api key are correct ones.
Error 00060 Could not find the 'parcels' element.
Error 00062 Requested card format is not supported.
Error 00063 Dpi: 'X' is not allowed.
Error 00064 Size: 'X' is not allowed.
Error 00065 Reversed -value: 'X' is not allowed.
Error 00066 Bad credentials. Api key could not be recognized.
Error 00067 Could not find the 'product' element.
Error 00068 We couldn't find any parcel codes nor tracking codes. Please double check that the message is correct.
Error 00070 Cannot create package cards. Customer has chosen a dummy-option, and we have not yet prosessed it to a normal delivery. Dummy delivery options are the ones that are shown to the customer when nothing else couldn't be returned. These dummys are shown to the customer with a Shipfunk name. We need to process these Shipfunk -delivery options's into real ones by hand, and this might take some time. The system learns from this though, and in the future these Shipfunk options shouldn't appear again.
Error 00071 We couldn't find the warehouse or the contact person details. Are they set in the settings?
Error 00073 Card direction: 'X' is not a valid direction. Possible values are: "both", "send", and "return"
Error 00074 You did not provide a warehouse name in the product-element, and there is more than one warehouse defined in the settings. We cannot know which warehouse the product resides in. Please provide a warehouse name in the product element.
Error 00075 Customers countrycode: 'X' is not allowed.
Error 00078 --Here's an error message that we receive from a 3rd party, and it tells that something went wrong in the system.-- Package cards cannot be created at this time. This error occurs when there's an issue with the service itself. There's nothing wrong with your credit cards or balance etc.
Error 00079 --Here's an error message that we receive from a 3rd party, and it tells that you have insufficient funds or you have cancelled the service-- Package cards cannot be created at this time. This error occurs when your account balance has been reached or your card was refused or something else related to your financial situation.
Error 00080 Could not find the 'logist_carriercode' element.
Error 00084 We couldn't find the pickup point's details with the given pickupID. Is the id correct?
Error 00085 Email is not valid.
Error 00086 Request type 'X' is not allowed. See the docs for allowed request types.
Error 00087 The order 'X' doesn't have any selected delivery option in it. Are you sure that the customer has selected one?
Error 00088 Status 'X' is not allowed.
Error 00089 No parcels found. The package cards cannot be created.
Error 00090 Language code is required.
Error 00091 Tracking code is required.
Error 00092 Transport company's name is required.
Error 00093 You didn't provide the transport company's name, and we couldn't find it with order id: 'X'. Transport company's name is required.
Error 00094 'calculated_price' cannot be empty.
Error 00095 'customer_price' cannot be empty.
Error 00096 Dimensions are not valid. Please double check the documentations for the correct dimensions format.
Error 00097 Bank account is a required field for the given service code.
Error 00098 BIC is a required field for the given service code.
Error 00099 Monetary value is a required field for the given service code.
Error 00100 We couldn't find a transport company with the given carriercode, and you have not provided other information that could helps us determine the transport company. Please double-check the given carriercode: 'X', or give us the other information. See the docs for more details. Is the carriercode correct? If you don't have the carriercode, give us the transport company's name. Either one will do the trick.
Error 00101 Webshop 'api_key' cannot be empty.
Error 00102 You must send either the email alone, or email and ALL of the other required fields. Api key for production only activates when you send all the required information in one go. You cannot send partial information, like just email and countrycode.
Error 00103 Api key not found. Are you sure you have it in the HTTP headers or in the POST/GET -message?
Error 00104 Api key is in wrong format. Double check the key for typos.
Error 00105 One or more updates were unsuccesfull. Try again later or contact our technical support.
Error 00106 Request type not found. Double check that your request url is correct. Every request url must have the certain elements in it. See the corresponding API for the correct url format.
Error 00107 Return type not found. Double check that your request url is correct. Every request url must have the certain elements in it. See the corresponding API for the correct url format.
Error 00108 Malformed url. Double check that your request url is correct. Every request url must have the certain elements in it. See the corresponding API for the correct url format.
Error 00109 Postal code: 'XXXXX', is not a valid one. Change it and try again. We validate every postal code against a list of known postal codes. This is put in place to prevent the customer from accidentally giving faulty postal codes, and thus making the package card creating more difficult later on.
Error 00109 Users not found with email: XXXXXXXXXXXXXX.

Infos listed

Message type Message code Message text Additional Info
Info 10001 No delivery options found. We couldn't generate any delivery options with given variables. This should not happen, but if it still does, please contact the Shipfunk's technical support.
Info 10002 No pickups found. Postcode might be the kind of code that just doesn't have any pickup points around it(for the given transport company), or the transport companys details are wrong. It is recommended to use carrier codes received in the GetDeliveryOptions -api.
Info 10003 No prices found. We couldn't generate any prices with given variables. This should not happen, but if it still does, please contact the Sipfunk admin.
Info 10004 Cannot find package cards with orderid='X' Have you created any package cards successfully for the given order? If you're sure that you have, contact the Shipfunk admin.
Info 10005 Cannot find tracking codes with orderid='X', direction='X' Tracking codes are created along with the package cards. Have you created any package cards successfully for the given order? If you're sure that you have, contact the Shipfunk admin.
Info 10007 One or more deletes were unsuccesfull. Maybe the given package codes or tracking codes were wrong ones? List of failed codes: '[X, X, X]'. Some of the parcels could not be removed. List of non-removed parcels codes is attached.
Info 10008 We couldn't find any products belonging to this orderid: 'X', with this product code:'X'. Maybe you gave us the wrong order id or product code?
Info 10009 No orders found with id: 'X'. There was no orders found for the given eshopid.
Info 10010 No tracking events found with given parameters. Transport company didn't return any events. It could be that the events are not yet registered to their services.
Info 10011 No parcels found
Info 10014 Given user is already attached to your account. To send more information, use EditUser -API.
Info 10015 User with given email already exists. Send the user an invite using CreateInvite -API.
Info 10016 Invitation has already been sent.
Info 10017 User is already attached to you.


Additional services

Common information

Here you can find a list of additional services that can be used in the shipments. Note: Codes used in the following list are Shipfunk -generated, and are not directly codes of any of the transport companies. Always use these codes when you have additional services required in the shipment.

COD(Cash On Delivery) -service have some limits to it, which the eshop must take into account. Note1: The customer might pay the parcels in different times if the parcels arrive to him/her in different times. Note2: If there are more than one products/parcels coming to us through the api, the cod values will be taken from the products/parcels values if they are set.

Services listed

Some of the additional services require some more fields than others. E.g. the COD-service requires the monetary sum, account number etc. whereas MPS-service only requires the service code.

  • If the service doesn’t require any additional fields besides the actual code, then it’s always marked as required.

  • Installation service has it’s own code for each type of product. See the codes in the “Installation service codes” -section.

  • If there are both, the Item and the Order marked into the Scope, it means that the current service mainly affects the first mentioned, but might affect the latter as well. Consult the transport company you are using for more details.

Service code is always required!

Some of the additional services affect the whole order and some are product/parcel related only. See the xml/json examples in the APIs to see where the appropriate elements should go. In the table below, there is a column which indicates whether the service is order or parcel related.

Service name Service code Scope (Item=Affects product/parcel only, Order=Affects the whole order) Service fields Example value Additional info Required field for the service(Y/N)
COD/Cash on delivery 10001 Order monetary_value 25 Monetary sum of the whole delivery. Y
bank_account FI49 5000 9420 0287 30 Account number. Y
bic OKOYFIHH BIC-code of the bank. Y
reference 0021 Billing reference number. N
Multi-Parcel shipment (MPS) 10002 Order Y
Fragile/Handle with care 10004 Item Y
Saturday delivery 10006 Order Y
Delivery insurance 10009 Order monetary_value 36.90 Value of the insured products. Y
Recycling/Old removal service 10025 Item count 1 Amount of these services. Defaults to 1. N
add_fee 1 Calculate the fee for this service or not. Defaults to 1(true, calculate the fee). N
Installation Varies by the product. See the "Installation service codes" Item count 1 Amount of these services. Defaults to 1. N
add_fee 1 Calculate the fee for this service or not. Defaults to 1(true, calculate the fee). N
Transport of Dangerous Goods (TDG) 10028 Item/Order quantity 0.4 Quantity of the dangerous substance. N
quantity_unit kg Required if the quantity is given! Y/N
packing_group Y The UN assigns a packing group classifying the regulated material further by the amount of risk each material poses during transportation. The packing group also determines the degree of protective packaging required. N
tunnel_restriction_code C5000D Some types of goods should not be delivered through tunnels. This code will dictate the tunnels that are forbidden for the delivery. N
un_code UN 3355 N

Installation service codes

If you need to provide your customer installation services, you’ll need to provide the correct service code in the API. Here’s a list of the installation service codes and their meanings.

  • 59010 | Washing machine

  • 59011 | Dryer

  • 59012 | Refrigerator

  • 59013 | Freezer

  • 59014 | Microwave oven

  • 59015 | Television

  • 59016 | Dishwasher

  • 59017 | Oven

  • 59018 | Oven (integrated)

  • 59019 | Stove

  • 59020 | Sauna stove

  • 59021 | Drying cabinet

  • 59022 | Side-by-side refrigerator/freezer

Note that you have to provide the correct codes for the different types of installations.



Order Metadata

Common information

Orders can have user-defined metadata in them. You can set metadata in APIs that have this functionality marked. This metadata can be used to identify and/or group orders. Metadata is always a key-value pair, where you can define both values.

Example of the metadata key-value pair:

"metadata": [
    {
        "key": "additional-order-id",
        "value": "123456",
        "unique": true
    }
]

where "additional-order-id" is defined by you, and so is the value: "123456".

Metadata -pairs also have an attribute called “unique”. With this field you can tell the API that this metadata is unique, and no other order should have the same value. Basically it tells us that the key-value -pair can be used to identify the order.

If you provide metadata marked as unique and the same key-value -pair already exists on another order, we will return a message indicating that the metadata is not valid. The API call will fail.

Metadata key and value fields are validated with preg match: /^[A-Za-z0-9_%#.\-]+$/. If the metadata contains other characters, error message is returned. The max length for key is 150 characters, and for value 300 characters.

When you call APIs related to an order, we always check the metadata the order has, and match the unique metadata when searching for the order. As in: you can use unique metadata values to identify orders.

Example:

You set metadata in this API call like following (with the unique setting as true): "additional-order-id": "1234567"

The actual order id for the current call is: “XYZ0123”.

  • Now this current order line has order number of “XYZ0123” and metadata “additional-order-id”: “1234567”.

Then you call the CreateNewPackageCards -API with order id: “1234567”.

We will let you create the package cards, since we found an order with the given id by looking at the metadata marked as unique.



GetPrice API

Basic info

With GetPrice-API you can get the minimum and maximum prices of the deliveries, but without the actual delivery options. Only the prices. This is handy if you want to show the possible cost of the delivery on the page right away after the customer adds a product into the basket. This way the customer doesn’t have to go to the delivery options -page, but can see a real time min and max price of the delivery.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: "sf_get_price" when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
language Two digit language code for the texts in the delivery options. Defaults to FI if not declared. IMPORTANT NOTE: If this field is omitted, the returning data might have wrong language in it! String N
monetary Monetary element. Includes other elements. See examples. Element N
currency ISO 4217 Currency Code used in this order. For example: "EUR", or "USD". Every price in the order is in this currency. This also filters the delivery options, if some transport-company cannot give its prices with this currency. For allowed units, see "Get started" -section. Defaults to EUR if not declared. String N
products Products element. Includes other elements. Note that this element with its sub elements is optional if it's replaced with "parcels" element. See examples. Element Y
product Product element. One product. There can be multiple of these elements, one for each product. Includes other elements. See examples. Element Y
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the product. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
warehouse Name of the warehouse where this product resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
customer Customer element. Includes other elements. Note that if you don't give all the customer info at this point, you must give them later via the "SetCustomerDetails" -API. This must be done before requesting the package cards. Element N
postal_code Customers postal code. String Y
country Customers country. String Y

–Return data:

Field Description Dataformat Required (Y or N)
min_price Minimum delivery price for the given details. Double Y
max_price Maximum delivery price for the given details. Double Y

Request

POST https://shipfunkservices.com/api/1.2/get_price/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /get_price/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>

    <order>
        <language>EN</language>

        <monetary>
            <currency>EUR</currency>
            <value>4</value>
        </monetary>

        <products>
            <product>
                <weight>
                    <unit>kg</unit>
                    <amount>0.1</amount>
                </weight>

                <dimensions>
                    <unit>cm</unit>
                    <width>25</width>
                    <depth>15</depth>
                    <height>3</height>
                </dimensions>

                <warehouse>Warehouse1</warehouse>

                <additional_services>
                    <service>
                        <code>10028</code>
                        <packing_group />
                        <quantity>0.04</quantity>
                        <quantity_unit>kg</quantity_unit>
                        <shipping_name />
                        <tunnel_restriction_code />
                        <un_code />
                        <warning_label_numbers />
                    </service>
                </additional_services>
            </product>

            <product>
                <weight>
                    <unit>kg</unit>
                    <amount>0.1</amount>
                </weight>

                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>

                <warehouse>Warehouse1</warehouse>
            </product>
        </products>
    </order>

    <customer>
        <postal_code>70100</postal_code>
        <country>FI</country>
    </customer>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <min_price>6.90</min_price>
    <max_price>14.98</max_price>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10003</Code>
        <Message>No prices found</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /get_price/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "language": "EN",
      "monetary": {
        "currency": "EUR"
      },
      "products": [
        {
          "weight": {
            "unit": "kg",
            "amount": "0.1"
          },
          "dimensions": {
            "unit": "cm",
            "width": "25",
            "depth": "15",
            "height": "3"
          },
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.04,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        },
        {
          "weight": {
            "unit": "kg",
            "amount": "0.1"
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "warehouse": "Warehouse1"
        }
      ]
    },
    "customer": {
      "postal_code": "70100",
      "country": "FI"
    }
  }
}
Responses200202400
Body
{
  "response": {
    "min_price": "6.90",
    "max_price": "14.98"
  }
}
Body
{
  "Info": {
    "Code": "10003",
    "Message": "No prices found"
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_price/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS,"sf_get_price=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetPrice query
POST/get_price/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetDeliveryOptions API

Basic info

With GetDeliveryOptions-API you get the suitable delivery options for the given shopping basket and customer info. This service will filter the delivery options based on the given information, and calculate the prices and delivery times. With this api you can also provide the customer info, which will later be used in the order. This api requires one of two elements: “product” or “parcel”. If you use both, latter will be used for calculations. See the “Data contents and formats” and “Examples” for more information. Api can return pickup points in the response together with the delivery options. 20 nearest pickup points will be returned wherever possible, but some transport companies do not allow this and less might be returned.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Note: You can send additional “metadata” in this API. See Order Metadata for more information.

In the example data there are all the possible elements visible, and they can be contradicting. This is for the demonstration purposes only. The example request might not work in real life(Installation service for a deodorant? Not likely.).

Variable name

You must use the form-data variable name: "sf_get_delivery_options" when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
metadata Metadata element. Includes other elements. See examples. IMPORTANT NOTE: In the xml format, every metadata entry is under entry -element, which cannot be seen in this listing. See the examples. Element N
key Name of the metadata field. Required if the value exists. String N
value Value of the metadata field. Required if the name exists. String N
unique Marks the metadata key-value -pair to be unique. No other order can have the same pair. Required if the name and/or value exists. Int/Bool N
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N
language Two digit language code for the texts in the delivery options. Defaults to FI if not declared. IMPORTANT NOTE: If this field is omitted, the returning data might have wrong language in it! String N
update_created_date The order has a datetime set to the moment when this API is called. If you call this API multiple times, the latest datetime will be updated into the order details. With this field you can tell the service NOT to update the datetime. IMPORTANT NOTE: Do not set this to false(0) if you are calling this API the first time! Order must have a creation date! You should use this field only if you are implementing a possibility to change the delivery option. Defaults to true(1) when omitted. Int N
monetary Monetary element. Includes other elements. See examples. Element N
currency ISO 4217 Currency Code used in this order. For example: "EUR", or "USD". Every price in the order is in this currency. This also filters the delivery options, if some transport-company cannot give its prices with this currency. For allowed units, see "Get started" -section. Defaults to EUR if not declared. String N
value Total value of the order. Double N
discounts Discounts element. Includes other elements. See examples. Element N
type Type of discounts. 0=percentage, 1=money(double value). This will tell the system whether the given discounts are percentages or straight currency. Example: Discount is 50.0, and this is set to 0, result is 50% lower price. If this would be set to 1, result is 50.0(currency) lower price, which might result in negative prices. Defaults to 0(percentage). Int N
all Discount amount for every delivery option. Note the discount type! Double N
normal Discount amount for normal deliveries only(no home or express deliveries). Note the discount type! Double N
home Discount amount for home deliveries only. Note the discount type! Double N
express Discount amount for express deliveries only. Note the discount type! Double N
additions Additions element. Includes other elements. See examples. Element N
delivery_prices This much will be added to EVERY delivery option the api returns. This can be used for example if some product has it's own delivery method, and it's price is wanted in the final delivery price we are showing to the customer. Double N
delivery_times EVERY delivery option, excluding the store pickups, will be added this much days into the delivery times. This can be used for the case if you know your warehouse is under a heavy load, and you would like to let the customer know that the delivery times are day or two higher than normally. Int N
order_addtodeliverytimes_storepickups This works exactly the same as the "delivery_times", but only for the store pickups. Int N
warehouse_leadtime Indicates whether we need to calculate the warehouses lead-times to the delivery options delivery time. Example: Warehouses leadtime is one(1) day, and delivery options two(2) days. If this option is set to 1(true), three(3) days delivery time is returned. 1=true, 0=false. Int N
get_pickups Get pickups element. Includes other elements. See examples. Element N
store Indicates whether we want to show the eshops own pickup points or not. 1=show, 0=don't show. NOTE: Defaults to 1 if empty or omitted! Int N
store_only Indicates whether we want to show ONLY the eshops own pickup points and nothing else. 1=true, 0=false. Int N
transport_company Return the transport companies's pickup points or not. If you don't want to return the pickup points for every delivery option(if the option has pickup points in the first place), make this zero(0). This defaults to 1, which means that you can omit this element if you want the transport companies's pickup points in the return message. Note that if you don't want the pickups now, you must get them separately with GetPickups -api! 1=true, 0=false. Int N
tags Tags element. Includes other elements. Element N
tag Name of the tag. This can be anything, but it must be exactly the same of that you defined in the settings. We will get only those delivery options that are marked with the given tag. There can be multiple tags. IMPORTANT NOTE: In the json format, this element doesn't have a name, but instead it's just an array of values! See the examples. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
products Products element. Includes other elements. Note that this element with its sub elements is optional if it's replaced with "parcels" element. See examples. Element Y/N
product Product element. One product. There can be multiple of these elements, one for each product. Includes other elements. See examples. Element Y/N
amount Amount of the same kind of product. If you have 3 of the same type of products, you can just set this to 3. You can give us 3 individual "product" -elements with same details, but you can skip that by just giving a amount of the same kind of products. Defaults to 1 if omitted. Int N
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards -api. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String N
name Name of the product. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
category Category of the product. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the product. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the product. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Int N
warehouse Name of the warehouse where this product resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
parcels Parcels element. Includes other elements. Note that this element with its subelements is optional if it's replaced with "products"-element, but this is preferred way since it provides better delivery option filtering and more accurate estimations on the prices and delivery times. Note that one parcel may contain several products. Element Y/N
parcel Parcel element. Includes other elements. There can be multiple of these elements, one for each parcel. See examples. Element N
code Identifying code of the parcel. Must be unique for the order. String N
contents Contents of the parcel. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the parcel. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the parcel. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the parcel can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the parcel is sturdy enough to be stacked on other parcels of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
warehouse Name of the warehouse where this parcels contents resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country or even on same postal code area. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
customer Customer element. Includes other elements. Note that if you don't give all the customer info at this point, you must give them later via the "SetCustomerDetails" -API. This must be done before requesting the package cards. Element N
first_name Customers first name. String N
last_name Customers last name. String N
street_address Customers street address. String N
postal_code Customers postal code. String Y
city Customers city. String N
country Customers country. String Y
postal_box Customers post office box(eng. P.O.Box). String N
company Customers companys name. String N
phone Customers phone number. For allowed formats, see "Get started" -section. String N
email Customers email. String N

–Return data:

Field Description Dataformat Required (Y or N)
item Item element. Includes other elements. Important note: This in only applicable in the xml-format! Json-format is a bit different and doesn't include this element. Json has only the attribute of this element, which is the carriercode of the current element. One item is one delivery company. See examples. Element Y
key Attribute of the element "item". This is the carriercode of the current delivery company. This code is not needed in this API version, but is included as an option for future updates. Important note: This attribute is an actual element in the json-format! See examples. String Y
Carriercode Carriercode of the current delivery company. Note that this is not the code of some delivery option, but the whole transport company. This code is not needed in this api version, but is included as an option for future updates. String Y
Companyname Name of the current delivery company. String Y
Options Options element. Includes other elements. Note that this element is different in json/xml. In xml-format, this element has one single delivery option, and there can be many of these elements, whereas in json-format this element has an array of delivery options. Element Y
carriercode Carriercode of the current delivery option. Note that this is a little different from the "Carriercode" before. This one is a carriercode for the whole transport company, whereas this is the carriercode for the single delivery option within the transport company. This code is the one that is needed later when using GetPickups-api, and/or SelectedDelivery-api. String Y
productname This is the delivery options name. This is also the name that should be shown to the customer. String Y
calculated_price This is the calculated approximated price for the delivery. This is not the one you show to the customer as a delivery price. This information is needed later when using SelectedDelivery-api. Double Y
customer_price This is the price that is shown to the customer. It is the price that has all the discounts or additions you have requested for current delivery and/or defined in the Extranet settings. This information is needed later when using SelectedDelivery-api. Double Y
delivtime This is the calculated estimated TOTAL time of the delivery. This time already has everything taken into account, and should not be altered anymore. If you feel the need to alter this, please use the Shipfunk's extranet. This is either one digit: "2", or delivery time is an approximation and is returned like this: "1-3". String Y
info This element has the additional info that the current delivery option has. This info includes information valuable to the customer, and should be shown to the customer. For example this element might read something like this: "Package will be delivered to your nearest pickup point. You will be notified of this via email and/or phone. Please take your ID with you when you go collect the package.". String Y
green_delivery This element will state the greenliness of the delivery. If this option is set to 1, it means that this delivery is a green delivery, where nature is being taken into account. If the delivery option is not "green", this element will not exist. 1=green, 0=not green. Int N
category Category of the delivery option. You can set a category for the delivery options in the extranet. This functionality can be used for grouping the options the way you want them to be grouped. Setting a category is optional, and this element might be empty if you have not declared any categories to current delivery option. String N
normal_delivery If current delivery option can be categorized as a normal delivery, this will be as "1". Otherwise as "0". Int Y
home_delivery If current delivery option can be categorized as a home delivery, this will be as "1". Otherwise as "0". Int Y
express_oneday_delivery If current delivery option can be categorized as a express delivery that is delivered by tomorrow, this will be as "1". Otherwise as "0". Express in this context is defined by the delivery company, and not by Shipfunk. Int Y
express_sameday_delivery If current delivery option can be categorized as a express delivery that is delivered in the same day it's oredered, this will be as "1". Otherwise as "0". Express in this context is defined by the delivery company, and not by Shipfunk. Int Y
express_sameday_final_ordertime If the delivery option is same day express delivery, this option will tell the time window in which the order must be placed in order to get the delivery done. This should be shown to the customer so that the customer can decide whether to use this option or not. Format of this element is: "08:00-17:00". String N
announcement IMPORTANT! This element is Shipfunk's only direct channel to the customers. This elements contents should be shown to customers as an important note. We will convey important messages about the current delivery option, such as problems with the option, or even the company, like strikes or similar. We will not use this channel for anything else that extremely important notices about the current delivery option or transport company. Example of the contents of this element: "Posti's workers are currently in strike, and will have it's deliverys delayed indefinitely. Please take this into consideration when selecting the delivery options.". String N
country_code Country code for store pickups. IMPORTANT NOTE: This field only exists for the store pickup points! Normal delivery options do not have this element at all! String Y/N
product_code The product code defined by the shipping company itself. Note that this does not exist for store pickup points. String Y
haspickups Once again, this differs from the json a bit when compairing to the xml. In xml there can be multiple elements. One for each pickup point. In json this is an array of pickup points. If the delivery option doesn't have any pickup points, this field will be either 0 for XML or false for JSON. Please see the examples for clearer vision of how this one works. Element Y
pickup_name Name of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_addr Address of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_postal Postcode of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_city City of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_country Country of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_id Id of the pickup point. This information is needed later when using SelectedDelivery-api. String Y
pickup_distance_from_origin Distance from the customer in kilometers(km). Note that this might not be 100% accurate when using only the postal code! Double Y
pickup_is_parcel_automat This will indicate whether the pickup point is a parcel automat/package dispenser or not. (In XML: 1=true/0=false). Int/Boolean Y

Request

POST https://shipfunkservices.com/api/1.2/get_delivery_options/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /get_delivery_options/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>

    <order>
        <metadata>
            <entry>
                <key>master_order_id</ey>
                <value>213</value>
                <unique>0</unique>
            </entry>
            <entry>
                <key>any_type_of_string</key>
                <value>any_type_of_string</value>
                <unique>1</unique>
            </entry>
        </metadata>

        <external_resource_id>FOO123</external_resource_id>

        <language>EN</language>

        <monetary>
            <currency>EUR</currency>
            <value>4</value>
        </monetary>

        <discounts>
            <type>0</type>
            <all>0</all>
            <normal>0</normal>
            <home>0</home>
            <express>0</express>
        </discounts>

        <additions>
            <delivery_prices>0</delivery_prices>
            <delivery_times>0</delivery_times>
            <delivery_times_store_pickups>0</delivery_times_store_pickups>
            <warehouse_leadtime>1</warehouse_leadtime>
        </additions>

        <get_pickups>
            <store>1</store>
            <store_only>0</store_only>
            <transport_company>1</transport_company>
        </get_pickups>

        <tags>
            <tag>bicycle</tag>
            <tag>big_product</tag>
        </tags>

        <additional_services>
            <service>
                <code>10001</code>
                <bank_account>FI2350000110000238</bank_account>
                <bic>OKOYFIHH</bic>
                <monetary_value>8.90</monetary_value>
                <reference>1000342</reference>
            </service>
            <service>
                <code>10009</code>
                <monetary_value>8.90</monetary_value>
            </service>
        </additional_services>

        <products>
            <product>
                <amount>1</amount>
                <code>B53756b6174</code>
                <external_resource_id>FOO123</external_resource_id>
                <name>Deodorant</name>
                <category>Parfumes and cosmetics</category>

                <weight>
                    <unit>kg</unit>
                    <amount>0.2</amount>
                </weight>

                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>

                <monetary_value>8.90</monetary_value>

                <toppleable>1</toppleable>
                <stackable>1</stackable>
                <nestable>0</nestable>

                <warehouse>Warehouse1</warehouse>

                <additional_services>
                    <service>
                        <code>10004</code>
                    </service>

                    <service>
                        <code>10025</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>59010</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>10028</code>
                        <packing_group />
                        <quantity>0.04</quantity>
                        <quantity_unit>kg</quantity_unit>
                        <shipping_name />
                        <tunnel_restriction_code />
                        <un_code />
                        <warning_label_numbers />
                    </service>
                </additional_services>
            </product>
        </products>
        <parcels>
            <parcel>
                <code>0001</code>
                <contents>Parfumes and cosmetics</contents>

                <weight>
                    <unit>kg</unit>
                    <amount>0.2</amount>
                </weight>

                <monetary_value>8.90</monetary_value>

                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>

                <toppleable>1</toppleable>
                <stackable>1</stackable>

                <warehouse>Warehouse1</warehouse>

                <additional_services>
                    <service>
                        <code>10004</code>
                    </service>

                    <service>
                        <code>10025</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>59010</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>10028</code>
                        <packing_group />
                        <quantity>0.04</quantity>
                        <quantity_unit>kg</quantity_unit>
                        <shipping_name />
                        <tunnel_restriction_code />
                        <un_code />
                    </service>
                </additional_services>
            </parcel>
        </parcels>
    </order>
    <customer>
        <first_name>MrFirstname</first_name>
        <last_name>Lastname</last_name>
        <street_address>Teststreet 10 A 34</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <country>FI</country>
        <postal_box />
        <company />
        <phone>0401231234</phone>
        <email>example@example.com</email>
    </customer>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item key="10000000">
        <Carriercode>10000000</Carriercode>
        <Companyname>Example Eshop</Companyname>
        <Options>
            <carriercode>1xxxxxxxxxxx</carriercode>
            <productname>Nouto myymälästä</productname>
            <calculated_price>0</calculated_price>
            <customer_price>0</customer_price>
            <delivtime>1</delivtime>
            <info><![CDATA[<b>Testikatu 1, 70100, Kuopio, FI</b>.<br />]]></info>
            <green_delivery>0</green_delivery>
            <category />
            <normal_delivery>0</normal_delivery>
            <home_delivery>0</home_delivery>
            <express_oneday_delivery>0</express_oneday_delivery>
            <express_sameday_delivery>0</express_sameday_delivery>
            <express_sameday_final_ordertime>0</express_sameday_final_ordertime>
            <announcement />
            <country_code>0</country_code>
            <haspickups>0</haspickups>
        </Options>
    </item>
    <item key="00000100">
        <Carriercode>00000100</Carriercode>
        <Companyname>Matkahuolto</Companyname>
        <Options>
            <carriercode>02000101</carriercode>
            <productname>Bussipaketti</productname>
            <calculated_price>7.18</calculated_price>
            <customer_price>7.18</customer_price>
            <delivtime>1-2</delivtime>
            <info>Paketti noudetaan saapumisilmoituksessa ilmoitetusta toimipisteestä. Paketti luovutetaan henkilötodistusta vastaan. Henkilöllisyyden voi todistaa ajokortilla, passilla tai poliisin myöntämällä henkilökortilla. Jos paketin noutaja on muu kuin osoitekorttiin merkitty vastaanottaja, täytyy paketin noutajalla olla mukana henkilötodistuksensa lisäksi valtakirja.</info>
            <green_delivery>1</green_delivery>
            <category />
            <normal_delivery>1</normal_delivery>
            <home_delivery>0</home_delivery>
            <express_oneday_delivery>0</express_oneday_delivery>
            <express_sameday_delivery>0</express_sameday_delivery>
            <express_sameday_final_ordertime>0</express_sameday_final_ordertime>
            <announcement />
            <product_code>10</product_code>
            <haspickups>
                <pickup_name>KUOPIO</pickup_name>
                <pickup_addr>PUIJONKATU 45</pickup_addr>
                <pickup_postal>70300</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>27</pickup_id>
                <pickup_openinghours />
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.47303920884673</pickup_distance_from_origin>
                <pickup_is_parcel_automat>0</pickup_is_parcel_automat>
            </haspickups>
            <haspickups>
                <pickup_name>SIILINJÄRVI MH-ASIAMIES</pickup_name>
                <pickup_addr>TORITIE 7</pickup_addr>
                <pickup_postal>71800</pickup_postal>
                <pickup_city>SIILINJÄRVI</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>2423</pickup_id>
                <pickup_openinghours />
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>20.161233584201</pickup_distance_from_origin>
                <pickup_is_parcel_automat>0</pickup_is_parcel_automat>
            </haspickups>
        </Options>
        <Options>
            <carriercode>00000102</carriercode>
            <productname>Jakopaketti</productname>
            <calculated_price>11.21</calculated_price>
            <customer_price>11.21</customer_price>
            <delivtime>1-2</delivtime>
            <info>Vastaanottajalle ilmoitetaan saapuneesta paketista puhelimitse ja sovitaan jakeluaika.</info>
            <green_delivery>1</green_delivery>
            <category />
            <normal_delivery>0</normal_delivery>
            <home_delivery>1</home_delivery>
            <express_oneday_delivery>0</express_oneday_delivery>
            <express_sameday_delivery>0</express_sameday_delivery>
            <express_sameday_final_ordertime>0</express_sameday_final_ordertime>
            <announcement />
            <product_code>30</product_code>
            <haspickups>0</haspickups>
        </Options>
        <Options>
            <carriercode>01000104</carriercode>
            <productname>Lähellä-paketti</productname>
            <calculated_price>7.18</calculated_price>
            <customer_price>7.18</customer_price>
            <delivtime>1-3</delivtime>
            <info>Paketti noudetaan saapumisilmoituksessa ilmoitetusta toimipisteestä. Paketti luovutetaan henkilötodistusta vastaan. Henkilöllisyyden voi todistaa ajokortilla, passilla tai poliisin myöntämällä henkilökortilla. Jos paketin noutaja on muu kuin osoitekorttiin merkitty vastaanottaja, täytyy paketin noutajalla olla mukana henkilötodistuksensa lisäksi valtakirja.</info>
            <green_delivery>1</green_delivery>
            <category />
            <normal_delivery>1</normal_delivery>
            <home_delivery>0</home_delivery>
            <express_oneday_delivery>0</express_oneday_delivery>
            <express_sameday_delivery>0</express_sameday_delivery>
            <express_sameday_final_ordertime>0</express_sameday_final_ordertime>
            <announcement />
            <product_code>80</product_code>
            <haspickups>
                <pickup_name>K-MARKET PELIMIES KUOPIO</pickup_name>
                <pickup_addr>TULLIPORTINKATU 54</pickup_addr>
                <pickup_postal>70110</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>8799</pickup_id>
                <pickup_openinghours />
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.4222658953242</pickup_distance_from_origin>
                <pickup_is_parcel_automat>0</pickup_is_parcel_automat>
            </haspickups>
            <haspickups>
                <pickup_name>KUOPIO</pickup_name>
                <pickup_addr>PUIJONKATU 45</pickup_addr>
                <pickup_postal>70300</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>27</pickup_id>
                <pickup_openinghours />
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.47303920884673</pickup_distance_from_origin>
                <pickup_is_parcel_automat>0</pickup_is_parcel_automat>
            </haspickups>
        </Options>
    </item>
    <item key="00000200">
        <Carriercode>00000200</Carriercode>
        <Companyname>Posti</Companyname>
        <Options>
            <carriercode>02000201</carriercode>
            <productname>Postipaketti</productname>
            <calculated_price>6.98</calculated_price>
            <customer_price>6.98</customer_price>
            <delivtime>1-3</delivtime>
            <info>Nouda tilauksesi postin palvelupisteestä. Ota henkilöllisyystodistus mukaan. Pakettiautomaattitilauksissa sinulle lähetetään tekstiviestillä lokerokoodi kun paketti on noudettavissa.</info>
            <green_delivery>1</green_delivery>
            <category />
            <normal_delivery>1</normal_delivery>
            <home_delivery>0</home_delivery>
            <express_oneday_delivery>0</express_oneday_delivery>
            <express_sameday_delivery>0</express_sameday_delivery>
            <express_sameday_final_ordertime>0</express_sameday_final_ordertime>
            <announcement />
            <product_code>2103</product_code>
            <haspickups>
                <pickup_name>Pakettiautomaatti, Liikekeskus Puijonkatu</pickup_name>
                <pickup_addr>Puijonkatu 19</pickup_addr>
                <pickup_postal>70105</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>701053201</pickup_id>
                <pickup_openinghours>ma-pe 9.00 - 21.00, la 8.00 - 18.00, su 12.00 - 18.00</pickup_openinghours>
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.17440831200976</pickup_distance_from_origin>
                <pickup_is_parcel_automat>1</pickup_is_parcel_automat>
            </haspickups>
            <haspickups>
                <pickup_name>Pakettiautomaatti, Sokos Kuopio</pickup_name>
                <pickup_addr>Haapaniemenkatu 24</pickup_addr>
                <pickup_postal>70115</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>701153201</pickup_id>
                <pickup_openinghours>ma-la 8.00 - 21.00, su 10.00 - 21.00</pickup_openinghours>
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.20234510730396</pickup_distance_from_origin>
                <pickup_is_parcel_automat>1</pickup_is_parcel_automat>
            </haspickups>
            <haspickups>
                <pickup_name>Posti, Keskusta</pickup_name>
                <pickup_addr>Kauppakatu 40</pickup_addr>
                <pickup_postal>70100</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>701003200</pickup_id>
                <pickup_openinghours>ma-pe 8.00 - 20.00, la 10.00 - 16.00, su 12.00 - 16.00</pickup_openinghours>
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.398216552096</pickup_distance_from_origin>
                <pickup_is_parcel_automat>0</pickup_is_parcel_automat>
            </haspickups>
            <haspickups>
                <pickup_name>Noutopiste, R-kioski Niirala</pickup_name>
                <pickup_addr>Niiralankatu 11</pickup_addr>
                <pickup_postal>70600</pickup_postal>
                <pickup_city>KUOPIO</pickup_city>
                <pickup_country>FI</pickup_country>
                <pickup_id>706003200</pickup_id>
                <pickup_openinghours>ma-la 7.30 - 21.00, su 9.00 - 21.00</pickup_openinghours>
                <pickup_openinghours_excep />
                <pickup_distance_from_origin>0.92148081502286</pickup_distance_from_origin>
                <pickup_is_parcel_automat>0</pickup_is_parcel_automat>
            </haspickups>
        </Options>
        <Options>
            <carriercode>00000203</carriercode>
            <productname>Kotipaketti</productname>
            <calculated_price>11.01</calculated_price>
            <customer_price>11.01</customer_price>
            <delivtime>1-3</delivtime>
            <info>Posti tuo tilauksesi haluamaasi osoitteeseen ja sopii kanssasi toimitusajankohdan.</info>
            <green_delivery>1</green_delivery>
            <category />
            <normal_delivery>0</normal_delivery>
            <home_delivery>1</home_delivery>
            <express_oneday_delivery>1</express_oneday_delivery>
            <express_sameday_delivery>0</express_sameday_delivery>
            <express_sameday_final_ordertime>0</express_sameday_final_ordertime>
            <announcement />
            <product_code>2104</product_code>
            <haspickups>0</haspickups>
        </Options>
    </item>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10001</Code>
        <Message>No delivery options found</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00001</Code>
        <Message>No data.</Message>
    </Error>
</response>
Headers
Location: /get_delivery_options/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "metadata": [
        {
          "key": "master_order_id",
          "value": "213",
          "unique": false
        },
        {
          "key": "any_type_of_string",
          "value": "any_type_of_string",
          "unique": true
        }
      ],
      "external_resource_id": "FOO123",
      "language": "EN",
      "monetary": {
        "currency": "EUR",
        "value": 8.9
      },
      "discounts": {
        "type": "percentage",
        "all": 0,
        "home": 0,
        "normal": 0,
        "express": 0
      },
      "additions": {
        "delivery_prices": 0,
        "delivery_times": 0,
        "delivery_times_store_pickups": 0,
        "warehouse_leadtime": 1
      },
      "get_pickups": {
        "store": 1,
        "store_only": 0,
        "transport_company": 1
      },
      "tags": [
        "bicycle",
        "big_product"
      ],
      "additional_services": [
        {
          "code": "10001",
          "bank_account": "FI2350000110000238",
          "bic": "OKOYFIHH",
          "monetary_value": 8.9,
          "reference": "1000342"
        },
        {
          "code": "10009",
          "monetary_value": 8.9
        }
      ],
      "products": [
        {
          "amount": 1,
          "code": "B53756b6174",
          "external_resource_id": "FOO123",
          "name": "Deodorant",
          "category": "Parfumes and cosmetics",
          "weight": {
            "unit": "kg",
            "amount": 0.2
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "monetary_value": 8.9,
          "toppleable": 1,
          "stackable": 1,
          "nestable": 0,
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10004"
            },
            {
              "code": "10025",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "59010",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.2,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        }
      ],
      "parcels": [
        {
          "code": 0,
          "contents": "Parfumes and cosmetics",
          "weight": {
            "unit": "kg",
            "amount": 0.2
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "monetary_value": 8.9,
          "toppleable": 1,
          "stackable": 1,
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10004"
            },
            {
              "code": "10025",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "59010",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.2,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        }
      ]
    },
    "customer": {
      "first_name": "MrFirstname",
      "last_name": "Lastname",
      "street_address": "Teststreet 10 A 34",
      "postal_code": "70100",
      "city": "Kuopio",
      "country": "FI",
      "postal_box": "",
      "company": "",
      "phone": "040 1231234",
      "email": "example@example.com"
    }
  }
}
Responses200202400
Body
{
  "response": {
    "10000000": {
      "Carriercode": "10000000",
      "Companyname": "Example Eshop",
      "Options": [
        {
          "carriercode": "1xxxxxxxxxxx",
          "productname": "Nouto myymälästä",
          "calculated_price": 0,
          "customer_price": 0,
          "delivtime": "1",
          "info": "<b>Testikatu 1, 70100, Kuopio, FI</b>.<br />",
          "green_delivery": false,
          "category": "",
          "normal_delivery": false,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": "",
          "country_code": "FI",
          "haspickups": false
        }
      ]
    },
    "00000100": {
      "Carriercode": "00000100",
      "Companyname": "Matkahuolto",
      "Options": [
        {
          "carriercode": "02000101",
          "productname": "Bussipaketti",
          "calculated_price": "7.18",
          "customer_price": "7.18",
          "delivtime": "1-2",
          "info": "Paketti noudetaan saapumisilmoituksessa ilmoitetusta toimipisteestä. Paketti luovutetaan henkilötodistusta vastaan. Henkilöllisyyden voi todistaa ajokortilla, passilla tai poliisin myöntämällä henkilökortilla. Jos paketin noutaja on muu kuin osoitekorttiin merkitty vastaanottaja, täytyy paketin noutajalla olla mukana henkilötodistuksensa lisäksi valtakirja.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": true,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 10,
          "haspickups": [
            {
              "pickup_name": "KUOPIO",
              "pickup_addr": "PUIJONKATU 45",
              "pickup_postal": "70300",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "27",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.4730392,
              "pickup_is_parcel_automat": false
            },
            {
              "pickup_name": "SIILINJÄRVI MH-ASIAMIES",
              "pickup_addr": "TORITIE 7",
              "pickup_postal": "71800",
              "pickup_city": "SIILINJÄRVI",
              "pickup_country": "FI",
              "pickup_id": "2423",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 20.161234,
              "pickup_is_parcel_automat": false
            }
          ]
        },
        {
          "carriercode": "00000102",
          "productname": "Jakopaketti",
          "calculated_price": "11.21",
          "customer_price": "11.21",
          "delivtime": "1-2",
          "info": "Vastaanottajalle ilmoitetaan saapuneesta paketista puhelimitse ja sovitaan jakeluaika.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": false,
          "home_delivery": true,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 30,
          "haspickups": false
        },
        {
          "carriercode": "01000104",
          "productname": "Lähellä-paketti",
          "calculated_price": "7.18",
          "customer_price": "7.18",
          "delivtime": "1-3",
          "info": "Paketti noudetaan saapumisilmoituksessa ilmoitetusta toimipisteestä. Paketti luovutetaan henkilötodistusta vastaan. Henkilöllisyyden voi todistaa ajokortilla, passilla tai poliisin myöntämällä henkilökortilla. Jos paketin noutaja on muu kuin osoitekorttiin merkitty vastaanottaja, täytyy paketin noutajalla olla mukana henkilötodistuksensa lisäksi valtakirja.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": true,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 80,
          "haspickups": [
            {
              "pickup_name": "K-MARKET PELIMIES KUOPIO",
              "pickup_addr": "TULLIPORTINKATU 54",
              "pickup_postal": "70110",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "8799",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.4222659,
              "pickup_is_parcel_automat": false
            },
            {
              "pickup_name": "KUOPIO",
              "pickup_addr": "PUIJONKATU 45",
              "pickup_postal": "70300",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "27",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.4730392,
              "pickup_is_parcel_automat": false
            }
          ]
        }
      ]
    },
    "00000200": {
      "Carriercode": "00000200",
      "Companyname": "Posti",
      "Options": [
        {
          "carriercode": "02000201",
          "productname": "Postipaketti",
          "calculated_price": "6.98",
          "customer_price": "6.98",
          "delivtime": "1-3",
          "info": "Nouda tilauksesi postin palvelupisteestä. Ota henkilöllisyystodistus mukaan. Pakettiautomaattitilauksissa sinulle lähetetään tekstiviestillä lokerokoodi kun paketti on noudettavissa.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": true,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 2103,
          "haspickups": [
            {
              "pickup_name": "Pakettiautomaatti, Liikekeskus Puijonkatu",
              "pickup_addr": "Puijonkatu 19",
              "pickup_postal": "70105",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "701053201",
              "pickup_openinghours": "ma-pe 9.00 - 21.00, la 8.00 - 18.00, su 12.00 - 18.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.17440832,
              "pickup_is_parcel_automat": true
            },
            {
              "pickup_name": "Pakettiautomaatti, Sokos Kuopio",
              "pickup_addr": "Haapaniemenkatu 24",
              "pickup_postal": "70115",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "701153201",
              "pickup_openinghours": "ma-la 8.00 - 21.00, su 10.00 - 21.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.2023451,
              "pickup_is_parcel_automat": true
            },
            {
              "pickup_name": "Posti, Keskusta",
              "pickup_addr": "Kauppakatu 40",
              "pickup_postal": "70100",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "701003200",
              "pickup_openinghours": "ma-pe 8.00 - 20.00, la 10.00 - 16.00, su 12.00 - 16.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.39821655,
              "pickup_is_parcel_automat": false
            },
            {
              "pickup_name": "Noutopiste, R-kioski Niirala",
              "pickup_addr": "Niiralankatu 11",
              "pickup_postal": "70600",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "706003200",
              "pickup_openinghours": "ma-la 7.30 - 21.00, su 9.00 - 21.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.92148083,
              "pickup_is_parcel_automat": false
            }
          ]
        },
        {
          "carriercode": "00000203",
          "productname": "Kotipaketti",
          "calculated_price": "11.01",
          "customer_price": "11.01",
          "delivtime": "1-3",
          "info": "Posti tuo tilauksesi haluamaasi osoitteeseen ja sopii kanssasi toimitusajankohdan.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": false,
          "home_delivery": true,
          "express_oneday_delivery": true,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 2104,
          "haspickups": false
        }
      ]
    }
  }
}
Body
{
  "Info": {
    "Code": "10001",
    "Message": "No delivery options found"
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "No data."
  }
}
Body
$real_http_code = 'false';
$query_format = 'xml';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_delivery_options/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS,"sf_get_delivery_options=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetDeliveryOptions query
POST/get_delivery_options/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetShippingOptions API

Basic info

With GetShippingOptions-API you get the suitable delivery options for the given shopping basket and customer info. This service will filter the delivery options based on the given information, and calculate the prices and delivery times. This api requires one of two elements: “product” or “parcel”. If you use both, latter will be used for calculations. See the “Data contents and formats” and “Examples” for more information. Api can return pickup points in the response together with the delivery options. 20 nearest pickup points will be returned wherever possible, but some transport companies do not allow this and less might be returned.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

This api is essentially the same as GetDeliveryOptions, but with one very important difference: this doesn’t save any temporary orders into the database. This causes two things to happen:

  1. This is much faster.
  2. You cannot use api endpoints that require the temporary order that was created in the GetDeliveryOptions. These include api’s like GetPickups, SelectedDelivery and SetOrderStatus(this one works if you create the order with CreateOrder first). You have to use CreateOrder api to actually create the order into the service.

In the example data there are all the possible elements visible, and they can be contradicting. This is for the demonstration purposes only. The example request might not work in real life (e.g. installation service for a deodorant? Not likely.).

Variable name

You can use the form-data variable name: "sf_get_delivery_options" when sending the data. Service doesn’t accept any other variable name. See examples.

You don’t have to use the form data key (Variable name) if you send the data as raw body with GET http method. We would recommend not using the form data at all. POST method with form data has been left for easier transition from the GetDeliveryOptions api.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
order Order element. Includes other elements. See examples. Element Y
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N
language Two digit language code for the texts in the delivery options. Defaults to FI if not declared. IMPORTANT NOTE: If this field is omitted, the returning data might have wrong language in it! String N
monetary Monetary element. Includes other elements. See examples. Element N
currency ISO 4217 Currency Code used in this order. For example: "EUR", or "USD". Every price in the order is in this currency. This also filters the delivery options, if some transport-company cannot give its prices with this currency. For allowed units, see "Get started" -section. Defaults to EUR if not declared. String N
value Total value of the order. Double N
discounts Discounts element. Includes other elements. See examples. Element N
type Type of discounts. 0=percentage, 1=money(double value). This will tell the system whether the given discounts are percentages or straight currency. Example: Discount is 50.0, and this is set to 0, result is 50% lower price. If this would be set to 1, result is 50.0(currency) lower price, which might result in negative prices. Defaults to 0(percentage). Int N
all Discount amount for every delivery option. Note the discount type! Double N
normal Discount amount for normal deliveries only(no home or express deliveries). Note the discount type! Double N
home Discount amount for home deliveries only. Note the discount type! Double N
express Discount amount for express deliveries only. Note the discount type! Double N
additions Additions element. Includes other elements. See examples. Element N
delivery_prices This much will be added to EVERY delivery option the api returns. This can be used for example if some product has it's own delivery method, and it's price is wanted in the final delivery price we are showing to the customer. Double N
delivery_times EVERY delivery option, excluding the store pickups, will be added this much days into the delivery times. This can be used for the case if you know your warehouse is under a heavy load, and you would like to let the customer know that the delivery times are day or two higher than normally. Int N
order_addtodeliverytimes_storepickups This works exactly the same as the "delivery_times", but only for the store pickups. Int N
warehouse_leadtime Indicates whether we need to calculate the warehouses lead-times to the delivery options delivery time. Example: Warehouses leadtime is one(1) day, and delivery options two(2) days. If this option is set to 1(true), three(3) days delivery time is returned. 1=true, 0=false. Int N
get_pickups Get pickups element. Includes other elements. See examples. Element N
store Indicates whether we want to show the eshops own pickup points or not. 1=show, 0=don't show. NOTE: Defaults to 1 if empty or omitted! Int N
store_only Indicates whether we want to show ONLY the eshops own pickup points and nothing else. 1=true, 0=false. Int N
transport_company Return the transport companies's pickup points or not. If you don't want to return the pickup points for every delivery option(if the option has pickup points in the first place), make this zero(0). This defaults to 1, which means that you can omit this element if you want the transport companies's pickup points in the return message. Note that if you don't want the pickups now, you must get them separately with GetPickups -api! 1=true, 0=false. Int N
tags Tags element. Includes other elements. Element N
tag Name of the tag. This can be anything, but it must be exactly the same of that you defined in the settings. We will get only those delivery options that are marked with the given tag. There can be multiple tags. IMPORTANT NOTE: In the json format, this element doesn't have a name, but instead it's just an array of values! See the examples. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
products Products element. Includes other elements. Note that this element with its sub elements is optional if it's replaced with "parcels" element. See examples. Element Y/N
product Product element. One product. There can be multiple of these elements, one for each product. Includes other elements. See examples. Element Y/N
amount Amount of the same kind of product. If you have 3 of the same type of products, you can just set this to 3. You can give us 3 individual "product" -elements with same details, but you can skip that by just giving a amount of the same kind of products. Defaults to 1 if omitted. Int N
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards -api. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String N
name Name of the product. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
category Category of the product. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the product. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the product. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Int N
warehouse Name of the warehouse where this product resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
parcels Parcels element. Includes other elements. Note that this element with its subelements is optional if it's replaced with "products"-element, but this is preferred way since it provides better delivery option filtering and more accurate estimations on the prices and delivery times. Note that one parcel may contain several products. Element Y/N
parcel Parcel element. Includes other elements. There can be multiple of these elements, one for each parcel. See examples. Element N
code Identifying code of the parcel. Must be unique for the order. String N
contents Contents of the parcel. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the parcel. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the parcel. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the parcel can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the parcel is sturdy enough to be stacked on other parcels of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
warehouse Name of the warehouse where this parcels contents resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country or even on same postal code area. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
customer Customer element. Includes other elements. Note that if you don't give all the customer info at this point, you must give them later via the "SetCustomerDetails" -API. This must be done before requesting the package cards. Element N
first_name Customers first name. String N
last_name Customers last name. String N
street_address Customers street address. String N
postal_code Customers postal code. String Y
city Customers city. String N
country Customers country. String Y
postal_box Customers post office box(eng. P.O.Box). String N
company Customers companys name. String N
phone Customers phone number. For allowed formats, see "Get started" -section. String N
email Customers email. String N

–Return data:

Field Description Dataformat Required (Y or N)
item Item element. Includes other elements. Important note: This in only applicable in the xml-format! Json-format is a bit different and doesn't include this element. Json has only the attribute of this element, which is the carriercode of the current element. One item is one delivery company. See examples. Element Y
key Attribute of the element "item". This is the carriercode of the current delivery company. This code is not needed in this API version, but is included as an option for future updates. Important note: This attribute is an actual element in the json-format! See examples. String Y
Carriercode Carriercode of the current delivery company. Note that this is not the code of some delivery option, but the whole transport company. This code is not needed in this api version, but is included as an option for future updates. String Y
Companyname Name of the current delivery company. String Y
Options Options element. Includes other elements. Note that this element is different in json/xml. In xml-format, this element has one single delivery option, and there can be many of these elements, whereas in json-format this element has an array of delivery options. Element Y
carriercode Carriercode of the current delivery option. Note that this is a little different from the "Carriercode" before. This one is a carriercode for the whole transport company, whereas this is the carriercode for the single delivery option within the transport company. This code is the one that is needed later when using GetPickups-api, and/or SelectedDelivery-api. String Y
productname This is the delivery options name. This is also the name that should be shown to the customer. String Y
calculated_price This is the calculated approximated price for the delivery. This is not the one you show to the customer as a delivery price. This information is needed later when using SelectedDelivery-api. Double Y
customer_price This is the price that is shown to the customer. It is the price that has all the discounts or additions you have requested for current delivery and/or defined in the Extranet settings. This information is needed later when using SelectedDelivery-api. Double Y
delivtime This is the calculated estimated TOTAL time of the delivery. This time already has everything taken into account, and should not be altered anymore. If you feel the need to alter this, please use the Shipfunk's extranet. This is either one digit: "2", or delivery time is an approximation and is returned like this: "1-3". String Y
info This element has the additional info that the current delivery option has. This info includes information valuable to the customer, and should be shown to the customer. For example this element might read something like this: "Package will be delivered to your nearest pickup point. You will be notified of this via email and/or phone. Please take your ID with you when you go collect the package.". String Y
green_delivery This element will state the greenliness of the delivery. If this option is set to 1, it means that this delivery is a green delivery, where nature is being taken into account. If the delivery option is not "green", this element will not exist. 1=green, 0=not green. Int N
category Category of the delivery option. You can set a category for the delivery options in the extranet. This functionality can be used for grouping the options the way you want them to be grouped. Setting a category is optional, and this element might be empty if you have not declared any categories to current delivery option. String N
normal_delivery If current delivery option can be categorized as a normal delivery, this will be as "1". Otherwise as "0". Int Y
home_delivery If current delivery option can be categorized as a home delivery, this will be as "1". Otherwise as "0". Int Y
express_oneday_delivery If current delivery option can be categorized as a express delivery that is delivered by tomorrow, this will be as "1". Otherwise as "0". Express in this context is defined by the delivery company, and not by Shipfunk. Int Y
express_sameday_delivery If current delivery option can be categorized as a express delivery that is delivered in the same day it's oredered, this will be as "1". Otherwise as "0". Express in this context is defined by the delivery company, and not by Shipfunk. Int Y
express_sameday_final_ordertime If the delivery option is same day express delivery, this option will tell the time window in which the order must be placed in order to get the delivery done. This should be shown to the customer so that the customer can decide whether to use this option or not. Format of this element is: "08:00-17:00". String N
announcement IMPORTANT! This element is Shipfunk's only direct channel to the customers. This elements contents should be shown to customers as an important note. We will convey important messages about the current delivery option, such as problems with the option, or even the company, like strikes or similar. We will not use this channel for anything else that extremely important notices about the current delivery option or transport company. Example of the contents of this element: "Posti's workers are currently in strike, and will have it's deliverys delayed indefinitely. Please take this into consideration when selecting the delivery options.". String N
country_code Country code for store pickups. IMPORTANT NOTE: This field only exists for the store pickup points! Normal delivery options do not have this element at all! String Y/N
product_code The product code defined by the shipping company itself. Note that this does not exist for store pickup points. String Y
haspickups Once again, this differs from the json a bit when compairing to the xml. In xml there can be multiple elements. One for each pickup point. In json this is an array of pickup points. If the delivery option doesn't have any pickup points, this field will be either 0 for XML or false for JSON. Please see the examples for clearer vision of how this one works. Element Y
pickup_name Name of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_addr Address of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_postal Postcode of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_city City of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_country Country of the pickup point. This should be shown to the customer. This information is needed later when using SelectedDelivery-api. String Y
pickup_id Id of the pickup point. This information is needed later when using SelectedDelivery-api. String Y
pickup_distance_from_origin Distance from the customer in kilometers(km). Note that this might not be 100% accurate when using only the postal code! Double Y
pickup_is_parcel_automat This will indicate whether the pickup point is a parcel automat/package dispenser or not. (In XML: 1=true/0=false). Int/Boolean Y

Request

GET https://shipfunkservices.com/api/1.2/shipping_options/true/json/json/orderid
Requestsjson
Headers
Location: /shipping_options/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "order": {
      "external_resource_id": "FOO123",
      "language": "EN",
      "monetary": {
        "currency": "EUR",
        "value": 8.9
      },
      "discounts": {
        "type": "percentage",
        "all": 0,
        "home": 0,
        "normal": 0,
        "express": 0
      },
      "additions": {
        "delivery_prices": 0,
        "delivery_times": 0,
        "delivery_times_store_pickups": 0,
        "warehouse_leadtime": 1
      },
      "get_pickups": {
        "store": 1,
        "store_only": 0,
        "transport_company": 1
      },
      "tags": [
        "bicycle",
        "big_product"
      ],
      "additional_services": [
        {
          "code": "10001",
          "bank_account": "FI2350000110000238",
          "bic": "OKOYFIHH",
          "monetary_value": 8.9,
          "reference": "1000342"
        },
        {
          "code": "10009",
          "monetary_value": 8.9
        }
      ],
      "products": [
        {
          "amount": 1,
          "code": "B53756b6174",
          "external_resource_id": "FOO123",
          "name": "Deodorant",
          "category": "Parfumes and cosmetics",
          "weight": {
            "unit": "kg",
            "amount": 0.2
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "monetary_value": 8.9,
          "toppleable": 1,
          "stackable": 1,
          "nestable": 0,
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10004"
            },
            {
              "code": "10025",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "59010",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.2,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        }
      ],
      "parcels": [
        {
          "code": 0,
          "contents": "Parfumes and cosmetics",
          "weight": {
            "unit": "kg",
            "amount": 0.2
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "monetary_value": 8.9,
          "toppleable": 1,
          "stackable": 1,
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10004"
            },
            {
              "code": "10025",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "59010",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.2,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        }
      ]
    },
    "customer": {
      "first_name": "MrFirstname",
      "last_name": "Lastname",
      "street_address": "Teststreet 10 A 34",
      "postal_code": "70100",
      "city": "Kuopio",
      "country": "FI",
      "postal_box": "",
      "company": "",
      "phone": "040 1231234",
      "email": "example@example.com"
    }
  }
}
Responses200202400
Body
{
  "response": {
    "10000000": {
      "Carriercode": "10000000",
      "Companyname": "Example Eshop",
      "Options": [
        {
          "carriercode": "1xxxxxxxxxxx",
          "productname": "Nouto myymälästä",
          "calculated_price": 0,
          "customer_price": 0,
          "delivtime": "1",
          "info": "<b>Testikatu 1, 70100, Kuopio, FI</b>.<br />",
          "green_delivery": false,
          "category": "",
          "normal_delivery": false,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": "",
          "country_code": "FI",
          "haspickups": false
        }
      ]
    },
    "00000100": {
      "Carriercode": "00000100",
      "Companyname": "Matkahuolto",
      "Options": [
        {
          "carriercode": "02000101",
          "productname": "Bussipaketti",
          "calculated_price": "7.18",
          "customer_price": "7.18",
          "delivtime": "1-2",
          "info": "Paketti noudetaan saapumisilmoituksessa ilmoitetusta toimipisteestä. Paketti luovutetaan henkilötodistusta vastaan. Henkilöllisyyden voi todistaa ajokortilla, passilla tai poliisin myöntämällä henkilökortilla. Jos paketin noutaja on muu kuin osoitekorttiin merkitty vastaanottaja, täytyy paketin noutajalla olla mukana henkilötodistuksensa lisäksi valtakirja.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": true,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 10,
          "haspickups": [
            {
              "pickup_name": "KUOPIO",
              "pickup_addr": "PUIJONKATU 45",
              "pickup_postal": "70300",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "27",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.4730392,
              "pickup_is_parcel_automat": false
            },
            {
              "pickup_name": "SIILINJÄRVI MH-ASIAMIES",
              "pickup_addr": "TORITIE 7",
              "pickup_postal": "71800",
              "pickup_city": "SIILINJÄRVI",
              "pickup_country": "FI",
              "pickup_id": "2423",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 20.161234,
              "pickup_is_parcel_automat": false
            }
          ]
        },
        {
          "carriercode": "00000102",
          "productname": "Jakopaketti",
          "calculated_price": "11.21",
          "customer_price": "11.21",
          "delivtime": "1-2",
          "info": "Vastaanottajalle ilmoitetaan saapuneesta paketista puhelimitse ja sovitaan jakeluaika.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": false,
          "home_delivery": true,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 30,
          "haspickups": false
        },
        {
          "carriercode": "01000104",
          "productname": "Lähellä-paketti",
          "calculated_price": "7.18",
          "customer_price": "7.18",
          "delivtime": "1-3",
          "info": "Paketti noudetaan saapumisilmoituksessa ilmoitetusta toimipisteestä. Paketti luovutetaan henkilötodistusta vastaan. Henkilöllisyyden voi todistaa ajokortilla, passilla tai poliisin myöntämällä henkilökortilla. Jos paketin noutaja on muu kuin osoitekorttiin merkitty vastaanottaja, täytyy paketin noutajalla olla mukana henkilötodistuksensa lisäksi valtakirja.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": true,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 80,
          "haspickups": [
            {
              "pickup_name": "K-MARKET PELIMIES KUOPIO",
              "pickup_addr": "TULLIPORTINKATU 54",
              "pickup_postal": "70110",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "8799",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.4222659,
              "pickup_is_parcel_automat": false
            },
            {
              "pickup_name": "KUOPIO",
              "pickup_addr": "PUIJONKATU 45",
              "pickup_postal": "70300",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "27",
              "pickup_openinghours": null,
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.4730392,
              "pickup_is_parcel_automat": false
            }
          ]
        }
      ]
    },
    "00000200": {
      "Carriercode": "00000200",
      "Companyname": "Posti",
      "Options": [
        {
          "carriercode": "02000201",
          "productname": "Postipaketti",
          "calculated_price": "6.98",
          "customer_price": "6.98",
          "delivtime": "1-3",
          "info": "Nouda tilauksesi postin palvelupisteestä. Ota henkilöllisyystodistus mukaan. Pakettiautomaattitilauksissa sinulle lähetetään tekstiviestillä lokerokoodi kun paketti on noudettavissa.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": true,
          "home_delivery": false,
          "express_oneday_delivery": false,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 2103,
          "haspickups": [
            {
              "pickup_name": "Pakettiautomaatti, Liikekeskus Puijonkatu",
              "pickup_addr": "Puijonkatu 19",
              "pickup_postal": "70105",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "701053201",
              "pickup_openinghours": "ma-pe 9.00 - 21.00, la 8.00 - 18.00, su 12.00 - 18.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.17440832,
              "pickup_is_parcel_automat": true
            },
            {
              "pickup_name": "Pakettiautomaatti, Sokos Kuopio",
              "pickup_addr": "Haapaniemenkatu 24",
              "pickup_postal": "70115",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "701153201",
              "pickup_openinghours": "ma-la 8.00 - 21.00, su 10.00 - 21.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.2023451,
              "pickup_is_parcel_automat": true
            },
            {
              "pickup_name": "Posti, Keskusta",
              "pickup_addr": "Kauppakatu 40",
              "pickup_postal": "70100",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "701003200",
              "pickup_openinghours": "ma-pe 8.00 - 20.00, la 10.00 - 16.00, su 12.00 - 16.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.39821655,
              "pickup_is_parcel_automat": false
            },
            {
              "pickup_name": "Noutopiste, R-kioski Niirala",
              "pickup_addr": "Niiralankatu 11",
              "pickup_postal": "70600",
              "pickup_city": "KUOPIO",
              "pickup_country": "FI",
              "pickup_id": "706003200",
              "pickup_openinghours": "ma-la 7.30 - 21.00, su 9.00 - 21.00",
              "pickup_openinghours_excep": "",
              "pickup_distance_from_origin": 0.92148083,
              "pickup_is_parcel_automat": false
            }
          ]
        },
        {
          "carriercode": "00000203",
          "productname": "Kotipaketti",
          "calculated_price": "11.01",
          "customer_price": "11.01",
          "delivtime": "1-3",
          "info": "Posti tuo tilauksesi haluamaasi osoitteeseen ja sopii kanssasi toimitusajankohdan.",
          "green_delivery": true,
          "category": null,
          "normal_delivery": false,
          "home_delivery": true,
          "express_oneday_delivery": true,
          "express_sameday_delivery": false,
          "express_sameday_final_ordertime": false,
          "announcement": null,
          "product_code": 2104,
          "haspickups": false
        }
      ]
    }
  }
}
Body
{
  "Info": {
    "Code": "10001",
    "Message": "No delivery options found"
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "No data."
  }
}

GetShippingOptions query
GET/shipping_options/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetPickups API

Basic info

With GetPickups-API you can get the pickup points for the chosen delivery company and it’s delivery option.

Api will return 20 nearest pickup points by default. You can also define the amount of pickups you want the get.

If you give this API a Finnish postal code that ends to 4 or 5, the service will try to see if there are pickup points that point directly to that postal code. These pickup points are parcel automats, and if the service finds them directly with the given postal code, it will return only them. If no parcel automats are found, normal process will be run and the closest ones returned.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: "sf_get_pickups." when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
carriercode Shipfunk's own id for the transport company and its delivery option. String Y
language Two digit language code for the texts in the delivery options. Defaults to FI if not declared. IMPORTANT NOTE: If this field is omitted, the returning data might have wrong language in it! String N
return_count This is the amount of the pickup points that our service should return if possible. Don't go overboard with this number. Remember that there are rarely more than a handful of pickup points in one postal area. If you define this number to be very high, pickup points from neighbouring cities are also being returned. Defaults to 20 if omitted. Int N
customer Customer element. Includes other elements. See examples. Element N
postal_code Customers postal code. String Y
country Customers country. String Y
street_address Customers street address. This is optional, but will result in more accurate distance calculations when we calculate the distances to the nearest pickup points. String N

–Return data:

Field Description Dataformat Required (Y or N)
item Item element. Includes other elements. IMPORTANT NOTE: This element is only present in the xml-response. Json doesn't have this. Json has arrays of elements, but since xml doesn't cope well with arrays, it must have these item-elements as the parent of the pickup points details. See the examples. Element Y
pickup_id Id of the pickup point. This information is needed later when using SelectedDelivery-api. String Y
pickup_name Name of the pickup point. This should be shown to the customer. String Y
pickup_addr Address of the pickup point. This should be shown to the customer. String Y
pickup_postal Postal code of the pickup point. This should be shown to the customer. String Y
pickup_city City of the pickup point. This should be shown to the customer. String Y
pickup_country Country of the pickup point. This should be shown to the customer. String Y
pickup_openinghours Opening hours of the pickup point. This is defined by the transport company and might be an empty string. This field has not pre-defined format, since every transport company has their own way of defining it. String Y
pickup_openinghours_excep Exceptions on the opening hours. This is defined by the transport company and might be an empty string. This field has not pre-defined format, since every transport company has their own way of defining it. String Y
pickup_distance_from_origin Distance from the customer in kilometers(km). Note that this might not be 100% accurate when using only the postal code! Double Y
pickup_is_parcel_automat This will indicate whether the pickup point is a parcel automat/package dispenser or not. (In XML: 1=true/0=false). Int/Boolean Y

Request

POST https://shipfunkservices.com/api/1.2/get_pickups/true/json/json/orderid
RequestsxmljsonJavaScript/Ajax example
Headers
Location: /get_pickups/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <carriercode>02000201</carriercode>
        <language>FI</language>
        <return_count>10</return_count>
    </order>
    <customer>
        <postal_code>70100</postal_code>
        <country>FI</country>
        <street_address>Puijonkatu 20</street_address>
    </customer>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item key="0">
        <pickup_name>Posti, Keskusta</pickup_name>
        <pickup_addr>Kauppakatu 40-42</pickup_addr>
        <pickup_postal>70100</pickup_postal>
        <pickup_city>KUOPIO</pickup_city>
        <pickup_country>FI</pickup_country>
        <pickup_id>701003200</pickup_id>
        <pickup_openinghours>ma-pe 8.00 - 19.00, la 10.00 - 15.00</pickup_openinghours>
        <pickup_openinghours_excep />
        <pickup_distance_from_origin>0.1023</pickup_distance_from_origin>
        <pickup_is_parcel_automat>false</pickup_is_parcel_automat>
    </item>
    <item key="1">
        <pickup_name>Noutopiste, R-kioski Niirala</pickup_name>
        <pickup_addr>Niiralankatu 11</pickup_addr>
        <pickup_postal>70600</pickup_postal>
        <pickup_city>KUOPIO</pickup_city>
        <pickup_country>FI</pickup_country>
        <pickup_id>706003200</pickup_id>
        <pickup_openinghours>ma-la 7.30 - 21.00, su 9.00 - 21.00</pickup_openinghours>
        <pickup_openinghours_excep />
        <pickup_distance_from_origin>0.3334</pickup_distance_from_origin>
        <pickup_is_parcel_automat>false</pickup_is_parcel_automat>
    </item>
    <item key="2">
        <pickup_name>Posti, K-market Puijon Pähkinä</pickup_name>
        <pickup_addr>Sammakkolammentie 6</pickup_addr>
        <pickup_postal>70200</pickup_postal>
        <pickup_city>KUOPIO</pickup_city>
        <pickup_country>FI</pickup_country>
        <pickup_id>702003200</pickup_id>
        <pickup_openinghours>ma-la 7.00 - 21.00, su 11.00 - 19.00</pickup_openinghours>
        <pickup_openinghours_excep />
        <pickup_distance_from_origin>1.3004</pickup_distance_from_origin>
        <pickup_is_parcel_automat>false</pickup_is_parcel_automat>
    </item>
    <item key="3">
        <pickup_name>Posti, R-kioski Männistö</pickup_name>
        <pickup_addr>Lönnrotinkatu 27</pickup_addr>
        <pickup_postal>70500</pickup_postal>
        <pickup_city>KUOPIO</pickup_city>
        <pickup_country>FI</pickup_country>
        <pickup_id>705003200</pickup_id>
        <pickup_openinghours>ma-pe 8.00-21.00, la-su 8.30-21.00</pickup_openinghours>
        <pickup_openinghours_excep />
        <pickup_distance_from_origin>1.64</pickup_distance_from_origin>
        <pickup_is_parcel_automat>false</pickup_is_parcel_automat>
    </item>
    <item key="4">
        <pickup_name>Noutopiste, K-market Neulamuikku</pickup_name>
        <pickup_addr>Neulamäentie 28</pickup_addr>
        <pickup_postal>70150</pickup_postal>
        <pickup_city>KUOPIO</pickup_city>
        <pickup_country>FI</pickup_country>
        <pickup_id>701503201</pickup_id>
        <pickup_openinghours>ma-la 7.00 - 21.00, su 10.00 - 20.00</pickup_openinghours>
        <pickup_openinghours_excep />
        <pickup_distance_from_origin>4.234</pickup_distance_from_origin>
        <pickup_is_parcel_automat>false</pickup_is_parcel_automat>
    </item>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10002</Code>
        <Message>No pickups found.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00002</Code>
        <Message>Malformed xml or not xml at all. Cannot create xml-object.</Message>
    </Error>
</response>
Headers
Location: /get_pickups/true/xml/xml/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "carriercode": "02000201",
      "language": "FI",
      "return_count": 10
    },
    "customer": {
      "postal_code": "70100",
      "country": "FI",
      "street_address": "Puijonkatu 20"
    }
  }
}
Responses200202400
Body
{
  "response": [
    {
      "pickup_name": "Posti, Keskusta",
      "pickup_addr": "Kauppakatu 40-42",
      "pickup_postal": "70100",
      "pickup_city": "KUOPIO",
      "pickup_country": "FI",
      "pickup_id": "701003200",
      "pickup_openinghours": "ma-pe 8.00 - 19.00, la 10.00 - 15.00",
      "pickup_openinghours_excep": "",
      "pickup_distance_from_origin": 0.1023,
      "pickup_is_parcel_automat": false
    },
    {
      "pickup_name": "Noutopiste, R-kioski Niirala",
      "pickup_addr": "Niiralankatu 11",
      "pickup_postal": "70600",
      "pickup_city": "KUOPIO",
      "pickup_country": "FI",
      "pickup_id": "706003200",
      "pickup_openinghours": "ma-la 7.30 - 21.00, su 9.00 - 21.00",
      "pickup_openinghours_excep": "",
      "pickup_distance_from_origin": 0.3334,
      "pickup_is_parcel_automat": false
    },
    {
      "pickup_name": "Posti, K-market Puijon Pähkinä",
      "pickup_addr": "Sammakkolammentie 6",
      "pickup_postal": "70200",
      "pickup_city": "KUOPIO",
      "pickup_country": "FI",
      "pickup_id": "702003200",
      "pickup_openinghours": "ma-la 7.00 - 21.00, su 11.00 - 19.00",
      "pickup_openinghours_excep": "",
      "pickup_distance_from_origin": 1.3004,
      "pickup_is_parcel_automat": false
    },
    {
      "pickup_name": "Posti, R-kioski Männistö",
      "pickup_addr": "Lönnrotinkatu 27",
      "pickup_postal": "70500",
      "pickup_city": "KUOPIO",
      "pickup_country": "FI",
      "pickup_id": "705003200",
      "pickup_openinghours": "ma-pe 8.00-21.00, la-su 8.30-21.00",
      "pickup_openinghours_excep": "",
      "pickup_distance_from_origin": 1.64,
      "pickup_is_parcel_automat": false
    },
    {
      "pickup_name": "Noutopiste, K-market Neulamuikku",
      "pickup_addr": "Neulamäentie 28",
      "pickup_postal": "70150",
      "pickup_city": "KUOPIO",
      "pickup_country": "FI",
      "pickup_id": "701503201",
      "pickup_openinghours": "ma-la 7.00 - 21.00, su 10.00 - 20.00",
      "pickup_openinghours_excep": "",
      "pickup_distance_from_origin": 4.234,
      "pickup_is_parcel_automat": false
    }
  ]
}
Body
{
  "Info": {
    "Code": "10002",
    "Message": "No pickups found."
  }
}
Body
{
  "Error": {
    "Code": "00036",
    "Message": "'Carriercode' cannot be empty."
  }
}
Body
var sf_real_http_code = 'true';
var sf_querytype = 'json';
var sf_returntype = 'json';
var sf_orderid = 'AB0012345'

$.ajax(
{
    type: "GET",
    url: "https://shipfunkservices.com/api/1.2/get_pickups/"+sf_real_http_code+"/"+sf_querytype+"/"+sf_returntype+"/"+sf_orderid,
    timeout: 5000, // 5 second timeout in millis!
    data:{ 'sf_get_pickups' :  sf_sendable_string }, // Notice the variable name! It's kinda important.
    dataType: "jsonp",
    success: function( data, textStatus, jqXHR ) {
        // Parse to json:
        var data = $.parseJSON(data);

        // Get the data if present:
        var response = data.response;
        var error = data.Error;
        var info = data.Info;
    }
});
Responses200
Body
{see the other Requests for responses}

GetPickups query
POST/get_pickups/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


SelectedDelivery API

Basic info

With SelectedDelivery-API you can send the user chosen delivery method to Shipfunk. We will need this information in order to create the correct package cards later in the process.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_selected_delivery when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
selected_option selected_option element. Includes other elements. See examples. Element Y
carriercode Shipfunk's own id for the transport company and its delivery option. String Y
pickupid Tranport companys pickup points id. This is the same as the GetDeliveryOptions-API's or GetPickups-API's "pickup_id". If the delivery option doesn't have pickups, this will be left empty. If the delivery option does have a pickup, this is absolutely necessary to have! String Y/N
orderid Id of the order, given by the ecommerce platform. This is important because the service identifies the orders by this id. String Y
calculated_price Shipfunk systems calculated price of the delivery. This what the delivery is calculated to cost for the sender, without any eshop induced discounts. This is given to you in the GetDeliveryOptions-API, and it should be given here as well for data-analysis. Double Y
customer_price This is the discounted price of the delivery, and is the one that is usually shown to the customer. This is given to you in the GetDeliveryOptions-API, and it should be given here as well for data-analysis. Double Y
return_prices This will tell the service to return the calculated_price and the customers price as an answer. These are the exact same things that are given above. This field is optional. 1=true, 0=false. Int N

–Return data:

Field Description Dataformat Required (Y or N)
customers_price This is the selected options price for the customer. Double N
calculated_price This is the selected options price for the eshop. Double N

Request

GET https://shipfunkservices.com/api/1.2/selected_delivery/true/json/json/orderid
RequestsxmljsonJavaScript/Ajax example
Headers
Location: /selected_delivery/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <selected_option>
            <carriercode>02000201</carriercode>
            <pickupid>701003200</pickupid>
            <calculated_price>5.55</calculated_price>
            <customer_price>6.90</customer_price>
            <return_prices>0</return_prices>
        </selected_option>
    </order>
</query>
Responses200400
Body
// Success:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>

// Success, return_prices=1:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <calculated_price>5.55</calculated_price>
    <customers_price>6.90</customers_price>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /selected_delivery/true/xml/xml/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "selected_option": {
        "carriercode": "02000201",
        "pickupid": "701003200",
        "calculated_price": "5.55",
        "customer_price": "6.90",
        "return_prices": "0"
      }
    }
  }
}
Responses200400
Body
// Success:
{
    "Response": {
        "Code": "1",
        "Message": "OK"
    }
}

// Success, return_prices=1:
{
    "response": {
        "calculated_price": "5.55"
        "customers_price": "6.90",
    }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened"
  }
}
Body
var sf_real_http_code = 'true';
var sf_querytype = 'json';
var sf_returntype = 'json';
var sf_orderid = 'AB0012345'

$.ajax(
{
    type: "GET",
    url: "https://shipfunkservices.com/api/1.2/selected_delivery/"+sf_real_http_code+"/"+sf_querytype+"/"+sf_returntype+"/"+sf_orderid",
    timeout: 5000, // 5 second timeout in millis!
    data:{ 'sf_selected_delivery' :  sf_sendable_string }, // Notice the variable name! It's kinda important.
    dataType: "jsonp",
    success: function( data, textStatus, jqXHR ) {
        console.debug("selected: "+data);
    },
});
Responses200
Body
{see the other Requests for responses}

SelectedDelivery query
GET/selected_delivery/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


SetOrderStatus API

Basic info

With SetOrderStatus-API you can set the orders status. There are two statuses which you can set the order to be via this api, and these statuses are “placed” and “cancelled”. You can leave out all the xml/json -data, and use this API as a fully RESTFUL API. The status of the order will be shown in the Extranet.

If you leave out the POST/GET data, set the “request_type” to be “rest”! This way you can only set the order status to be “placed”, without having to send any actual data. RESTFUL message will be enough.

IMPORTANT NOTE: Always set the order status to be “placed” when the customer finished the order, i.e. when the customer selected the payment method and really placed the order in the web store. This information is important for our inner process, and makes things difficult later if we don’t have this information.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_set_order_status when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
status Status of the order. This can be "placed" or "cancelled". Double check the spelling! Defaults to "placed" if omitted. String N
final_orderid If your estore uses temporary order id before the order has been paid, you need to give the real and final order id here. We will update it into the place of the "orderid" you have given above and in the APIs before. Note that the old "orderid" is discarded after that and our system will not recognize it anymore! String N
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N

Request

POST https://shipfunkservices.com/api/1.2/set_order_status/true/json/json/orderid
RequestsREST | xmljsonxmlPHP example
Headers
Location: /set_order_status/true/rest/xml/AB0012345
Authorization: my_apikey
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /set_order_status/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "status": "placed",
      "final_orderid": "000012345",
      "external_resource_id": "FOO123"
    }
  }
}
Responses200400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "No data."
  }
}
Headers
Location: /set_order_status/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <status>placed</status>
        <final_orderid>000012345</final_orderid>
        <external_resource_id>FOO123</external_resource_id>
    </order>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/set_order_status/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_set_order_status=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

SetOrderStatus query
POST/set_order_status/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in. If you don’t send any POST/GET data, set this to “rest”.

Choices: xml json rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


SetCustomerDetails API

Basic info

With this API you can set and modify the customers details on a order. This API can be used to set the customer data at any point of the order process(but always before creating the package cards!), and can also be useful if the customer has given a wrong address, email, phone number, or even the name has a typo in it.

If you want to update customer information, you can send only the updatable field like the address, and only it will be updated. Every field you send will be updated, unless the field is empty or the element doesn’t exist at all. Note that you cannot empty the fields but only update, since customer info generally cannot be empty, excluding two exceptions: Company and PL. These fields can be emptied by giving a zero(0) as a value. If other fields are give a zero or an empty string, those fields will not be updated.

When you change the customer details, the package cards must be updated if they exist! If the cards are not updated, they will have the wrong customer information on them. Cards will not be updated by default, but you can create and get the updated package cards by giving the return_cards -parameter in the message.

Package cards cannot be created if we don’t have the customer details. You can give the customer details anywhere in the process via this api, but if you don’t use this API, you must give them in the CreateNewPackageCards -API in order to get the cards!

Variable name

You must use the form-data variable name: sf_set_customer_details when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
return_cards Return the updated package cards or not. 1=true, 0=false. Defaults to 0(don't return the cards) if omitted. Int N
customer Customer element. Includes other elements. Note that if you don't give all the customer info at this point, you must give them later via the "SetCustomerDetails" -API. This must be done before requesting the package cards. Element N
first_name Customers first name. String N
last_name Customers last name. String N
street_address Customers street address. String N
postal_code Customers postal code. String Y
city Customers city. String N
country Customers country. String Y
postal_box Customers post office box(eng. P.O.Box). String N
company Customers companys name. String N
phone Customers phone number. For allowed formats, see "Get started" -section. String N
email Customers email. String N

–Return data (If “return_cards” is set to 1!):

Field Description Dataformat Required (Y or N)
orderid Id of the order you gave in the query. String Y
parcel parcel element. Contains other elements. If the order has more than one parcel, there will be one parcel element for each of them. Each parcel includes it's own tracking codes and package cards. Element Y
parcelcode Identifying code of the parcel. String Y
send_trcode Tracking code for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_trcode Tracking code for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y
send_card Package card for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_card Package card for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y

Request

POST https://shipfunkservices.com/api/1.2/set_customer_details/true/json/json/orderid
RequestsjsonxmlPHP example
Headers
Location: /set_customer_details/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "return_cards": "1"
    },
    "customer": {
      "first_name": "MrFirstname",
      "last_name": "Lastname",
      "street_address": "Teststreet 10 A 35",
      "postal_code": "70100",
      "city": "Kuopio",
      "country": "FI",
      "phone": "040 1231234",
      "email": "example@example.com",
      "PL": "0",
      "company": ""
    }
  }
}
Responses200400
Body
// return_cards = 0:
{
    "response": {
        "Code": "1",
        "Message": "OK"
    }
}

// return_cards = 1:
{
    "response": {
        "orderid": "AB0012345",
        "parcels": [
            {
                "parcelcode": "",
                "send_trcode": "JJFIXXXXX999943896642",
                "return_trcode": "JJFIXXXXX999932744725",
                "send_card": "package card in the requested format",
                "return_card": "package card in the requested format"
            },
            {
                "parcelcode": "",
                "send_trcode": "JJFIXXXXX999943896643",
                "return_trcode": "JJFIXXXXX999932744726",
                "send_card": "package card in the requested format",
                "return_card": "package card in the requested format"
            }
        ]
    }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Headers
Location: /set_customer_details/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <return_cards>1</return_cards>
    </order>
    <customer>
        <first_name>MrFirstname</first_name>
        <last_name>Lastname</last_name>
        <street_address>Teststreet 10 A 35</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <country>FI</country>
        <postal_box>0</postal_box>
        <company />
        <phone>040 1231234</phone>
        <email>example@example.com</email>
    </customer>
</query>
Responses200400
Body
// return_cards = 0:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>

// return_cards = 1:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <orderid>AB0012345</orderid>
    <parcels>
        <parcel>
            <parcel_code />
            <send_trcode>JJFIXXXXX999943896642</send_trcode>
            <return_trcode>JJFIXXXXX999932744725</return_trcode>
            <send_card>package card in the requested format</send_card>
            <return_card>package card in the requested format</return_card>
        </parcel>
        <parcel>
            <parcel_code />
            <send_trcode>JJFIXXXXX999943896643</send_trcode>
            <return_trcode>JJFIXXXXX999932744726</return_trcode>
            <send_card>package card in the requested format</send_card>
            <return_card>package card in the requested format</return_card>
        </parcel>
    </parcels>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/set_customer_details/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_set_customer_details=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

SetCustomerDetails query
POST/set_customer_details/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


CreateOrder API

Basic info

With CreateOrder-API you can create a new order into the service. This order resembles the order you have in your store, and is created after the customer has selected payment method.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Note: You can send additional “metadata” in this API. See Order Metadata for more information.

In the example data there are all the possible elements visible, and they can be contradicting. This is for the demonstration purposes only. The example request might not work in real life(Installation service for a deodorant? Not likely.).

Variable name

You must use the form-data variable name: "sf_create_order" when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
metadata Metadata element. Includes other elements. See examples. IMPORTANT NOTE: In the xml format, every metadata entry is under entry -element, which cannot be seen in this listing. See the examples. Element N
key Name of the metadata field. Required if the value exists. String N
value Value of the metadata field. Required if the name exists. String N
unique Marks the metadata key-value -pair to be unique. No other order can have the same pair. Required if the name and/or value exists. Int/Bool N
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N
language Two digit language code for the texts in the delivery options. Defaults to FI if not declared. IMPORTANT NOTE: If this field is omitted, the returning data might have wrong language in it! String N
status Status of the order. This can be "placed" or "cancelled". Double check the spelling! Defaults to "placed" if omitted. String Y
monetary Monetary element. Includes other elements. See examples. Element N
currency ISO 4217 Currency Code used in this order. For example: "EUR", or "USD". Every price in the order is in this currency. This also filters the delivery options, if some transport-company cannot give its prices with this currency. For allowed units, see "Get started" -section. Defaults to EUR if not declared. String N
value Total value of the order. Double N
temporary_orderid If your estore used a temporary order id before the order has been paid, you need to give the it here. With this we can identify the GetDeliveryOptions -API call, and connect it to the actual order. String N
selected_option selected_option element. Includes other elements. See examples. Element Y
carriercode Shipfunk's own id for the transport company and its delivery option. You got this via GetDeliveryOptions API. String Y
pickupid Transport companys pickup points id. This is the same as the GetDeliveryOptions-API's or GetPickups-API's "pickup_id". If the delivery option doesn't have pickups, this will be left empty. If the delivery option does have a pickup, this is absolutely necessary to have! String Y/N
calculated_price Shipfunk systems calculated price of the delivery. This what the delivery is calculated to cost for the sender, without any eshop induced discounts. This is given to you in the GetDeliveryOptions-API, and it should be given here as well for data-analysis. Double Y
customer_price This is the discounted price of the delivery, and is the one that is usually shown to the customer. This is given to you in the GetDeliveryOptions-API, and it should be given here as well for data-analysis. Double Y
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
products Products element. Includes other elements. Note that this element with its sub elements is optional if it's replaced with "parcels" element. See examples. Element Y/N
product Product element. One product. There can be multiple of these elements, one for each product. Includes other elements. See examples. Element Y/N
amount Amount of the same kind of product. If you have 3 of the same type of products, you can just set this to 3. You can give us 3 individual "product" -elements with same details, but you can skip that by just giving a amount of the same kind of products. Defaults to 1 if omitted. Int N
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. String N
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards -api. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String N
name Name of the product. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
category Category of the product. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the product. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the product. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Int N
warehouse Name of the warehouse where this product resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
parcels Parcels element. Includes other elements. Note that this element with its subelements is optional if it's replaced with "products"-element, but this is preferred way since it provides better delivery option filtering and more accurate estimations on the prices and delivery times. Note that one parcel may contain several products. Element Y/N
parcel Parcel element. Includes other elements. There can be multiple of these elements, one for each parcel. See examples. Element N
code Identifying code of the parcel. Must be unique for the order. String N
contents Contents of the parcel. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the parcel. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the parcel. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the parcel can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the parcel is sturdy enough to be stacked on other parcels of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
warehouse Name of the warehouse where this parcels contents resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country or even on same postal code area. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
customer Customer element. Includes other elements. Note that if you don't give all the customer info at this point, you must give them later via the "SetCustomerDetails" -API. This must be done before requesting the package cards. Element N
first_name Customers first name. String N
last_name Customers last name. String N
street_address Customers street address. String N
postal_code Customers postal code. String Y
city Customers city. String N
country Customers country. String Y
postal_box Customers post office box(eng. P.O.Box). String N
company Customers companys name. String N
phone Customers phone number. For allowed formats, see "Get started" -section. String N
email Customers email. String N

–Return data:

Only return OK -message or an error.

Request

POST https://shipfunkservices.com/api/1.2/create_order/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /create_order/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>

    <order>
        <metadata>
            <entry>
                <key>master_order_id</key>
                <value>213</value>
                <unique>0</unique>
            </entry>
            <entry>
                <key>any_type_of_string</key>
                <value>any_type_of_string</value>
                <unique>1</unique>
            </entry>
        </metadata>

        <external_resource_id>FOO123</external_resource_id>

        <language>EN</language>

        <monetary>
            <currency>EUR</currency>
            <value>4</value>
        </monetary>

        <status>placed</status>

        <selected_option>
            <carriercode>02000201</carriercode>
            <pickupid>701003200</pickupid>
            <calculated_price>5.55</calculated_price>
            <customer_price>6.90</customer_price>
        </selected_option>

        <additional_services>
            <service>
                <code>10001</code>
                <bank_account>FI2350000110000238</bank_account>
                <bic>OKOYFIHH</bic>
                <monetary_value>8.90</monetary_value>
                <reference>1000342</reference>
            </service>
            <service>
                <code>10009</code>
                <monetary_value>8.90</monetary_value>
            </service>
        </additional_services>

        <products>
            <product>
                <amount>1</amount>
                <code>B53756b6174</code>
                <external_resource_id>FOO123</external_resource_id>
                <name>Deodorant</name>
                <category>Parfumes and cosmetics</category>

                <weight>
                    <unit>kg</unit>
                    <amount>0.2</amount>
                </weight>

                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>

                <monetary_value>8.90</monetary_value>

                <toppleable>1</toppleable>
                <stackable>1</stackable>
                <nestable>0</nestable>

                <warehouse>Warehouse1</warehouse>

                <additional_services>
                    <service>
                        <code>10004</code>
                    </service>

                    <service>
                        <code>10025</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>59010</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>10028</code>
                        <packing_group />
                        <quantity>0.04</quantity>
                        <quantity_unit>kg</quantity_unit>
                        <shipping_name />
                        <tunnel_restriction_code />
                        <un_code />
                        <warning_label_numbers />
                    </service>
                </additional_services>
            </product>
        </products>
        <parcels>
            <parcel>
                <code>0001</code>
                <contents>Parfumes and cosmetics</contents>

                <weight>
                    <unit>kg</unit>
                    <amount>0.2</amount>
                </weight>

                <monetary_value>8.90</monetary_value>

                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>

                <toppleable>1</toppleable>
                <stackable>1</stackable>

                <warehouse>Warehouse1</warehouse>

                <additional_services>
                    <service>
                        <code>10004</code>
                    </service>

                    <service>
                        <code>10025</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>59010</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>10028</code>
                        <packing_group />
                        <quantity>0.04</quantity>
                        <quantity_unit>kg</quantity_unit>
                        <shipping_name />
                        <tunnel_restriction_code />
                        <un_code />
                    </service>
                </additional_services>
            </parcel>
        </parcels>
    </order>
    <customer>
        <first_name>MrFirstname</first_name>
        <last_name>Lastname</last_name>
        <street_address>Teststreet 10 A 34</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <country>FI</country>
        <postal_box />
        <company />
        <phone>0401231234</phone>
        <email>example@example.com</email>
    </customer>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_order/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "metadata": [
        {
          "key": "master_order_id",
          "value": "213",
          "unique": false
        },
        {
          "key": "any_type_of_string",
          "value": "any_type_of_string",
          "unique": true
        }
      ],
      "external_resource_id": "FOO123",
      "language": "EN",
      "monetary": {
        "currency": "EUR",
        "value": 8.9
      },
      "status": "placed",
      "selected_option": {
        "carriercode": "02000201",
        "pickupid": "701003200",
        "calculated_price": "5.55",
        "customer_price": "6.90"
      },
      "additional_services": [
        {
          "code": "10001",
          "bank_account": "FI2350000110000238",
          "bic": "OKOYFIHH",
          "monetary_value": 8.9,
          "reference": "1000342"
        },
        {
          "code": "10009",
          "monetary_value": 8.9
        }
      ],
      "products": [
        {
          "amount": 1,
          "code": "B53756b6174",
          "external_resource_id": "FOO123",
          "name": "Deodorant",
          "category": "Parfumes and cosmetics",
          "weight": {
            "unit": "kg",
            "amount": 0.2
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "monetary_value": 8.9,
          "toppleable": 1,
          "stackable": 1,
          "nestable": 0,
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10004"
            },
            {
              "code": "10025",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "59010",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.2,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        }
      ],
      "parcels": [
        {
          "code": 0,
          "contents": "Parfumes and cosmetics",
          "weight": {
            "unit": "kg",
            "amount": 0.2
          },
          "dimensions": {
            "unit": "cm",
            "width": "15",
            "depth": "10",
            "height": "3"
          },
          "monetary_value": 8.9,
          "toppleable": 1,
          "stackable": 1,
          "warehouse": "Warehouse1",
          "additional_services": [
            {
              "code": "10004"
            },
            {
              "code": "10025",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "59010",
              "count": 1,
              "add_fee": 1
            },
            {
              "code": "10028",
              "packing_group": "",
              "quantity": 0.2,
              "quantity_unit": "kg",
              "shipping_name": "",
              "tunnel_restriction_code": "",
              "un_code": "",
              "warning_label_numbers": ""
            }
          ]
        }
      ]
    },
    "customer": {
      "first_name": "MrFirstname",
      "last_name": "Lastname",
      "street_address": "Teststreet 10 A 34",
      "postal_code": "70100",
      "city": "Kuopio",
      "country": "FI",
      "postal_box": "",
      "company": "",
      "phone": "040 1231234",
      "email": "example@example.com"
    }
  }
}
Responses200400
Body
{
  "Response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'xml';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/create_order/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS,"sf_create_order=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateOrder query
POST/create_order/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


CreateNewPackageCards API

Basic info

With CreateNewPackageCards-API you can create the package cards and tracking codes for the order previously given in the GetDeliveryOptions-API and SelectedDelivery-API. Note that despite of the the name this service also creates the tracking codes if they are not given in the query.

You can create package cards for the products given in the GetDeliveryOptions -api. All you have to do is to give the same product codes you gave there, and we’ll form parcels out of them. Notice that you do have to show us in which parcels the products belong to.

Note that you cannot create any package cards or tracking codes for store pickups. The API will just return OK -message to state that the request was received and processed. Response will be the same as if the return_cards -flag is set to zero(0).

If you have not given the customers information before this step, you must give that info in this API. We cannot create the package cards without the customer details.

If you have created package cards earlier, this api will not return the already created cards, but only the new ones that are requested!

If you give same parcel code or tracking code twice, the service will update the parcel information and package card. In other words, if you call this api twice with same parcel code or tracking code, the first will be overwritten. If you want to create new cards, you need to provide a different parcel code or tracking code, or leave them both out.

We will send the EDI-message at the same time with the creation of the package card! See the Get started -section for more information.

You cannot give two products in one parcel if those products have a different warehouse! The products’s warehouses can be overwritten if you give a warehouses name in the parcel element.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_new_package_cards when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
return_cards Indicates the need for returning the tracking codes and package cards in the return message. 1=true, 0=false. Defaults to 0(false) if omitted. Int N
sendmail If this is 1(true), we will send an email to the customer telling that the order has been processed and is ready to be delivered. This email will include the tracking codes for the order, and other details about the delivery. 1=true, 0=false. Defaults to 0(false) if omitted. Int N
send_edi If this is 1(true), the service WILL send the EDI-message. If this is 0(false), the service WON'T send the EDI-message. This is a helpful flag if you want to test the system in production mode, but don't want to send the edi-messages(the transport companies are not generally happy about receiving EDI-messages that are not real.). 1=true, 0=false. Defaults to 1(true) if omitted. Int N
package_card Package card element. Includes other elements. See examples. Element N
direction Direction of the card. 'send', 'return', or 'both'. This dictates the direction of the package cards. If you want to have only the send-cards, set this to be 'send'. Defaults to 'both' if omitted. String N
format Format of the card. Example: "zpl", "pdf" or "html". Defaults to 'pdf' if omitted. String N
dpi Dpi of the desired package card. Example: "300". Defaults to 300dpi if omitted. NOTE: this is only applicable to zpl-format! String N
size Size of the desired package card. ZPL size is in inches and the format looks like this: "4x6", which means 4 inches wide and 6 inches long. 'x' is used as a delimiter. PDF size is in default paper sizes like "A5" or "A4". Defaults to 'A5' for pdf and html, and '4x6' for zpl. String N
reversed Some printers wants to print the label upside-down. If the stickers you are using have some pre-printed pictures or text in them, like logos, this might be an issue. This is an option to turn the package card upside down for printing. NOTE: this is only applicable to zpl-format! 1=turn the card, 0=don't turn the card. Defaults to 0 if omitted. Int N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
parcels Parcels element. Includes other elements. Note that one parcel may contain several products. Element Y
parcel Parcel element. Includes other elements. There can be multiple of these elements, one for each parcel. Note that one parcel may contain several products. You may give all the parcel information here, or you can give only the product codes for each parcel. In order to use the product codes alone, you must give them in the GetDeliveryOptions -api! See examples for more details on how to use product codes alone. Element Y
Full parcel details described next:
code Identifying code of the parcel. Must be unique for the order. String N
contents Contents of the parcel. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the parcel. This element is not required but without it the calculation of prices and filtering the delivery options will not be as accurate. Some of the delivery options will be filtered away right away if this element is not present with valid data. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
value Monetary value of the parcel. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. IMPORTANT NOTE: If the additional service "COD" is selected, this field must have a value! Double N
toppleable Tells if the parcel can be rotated in any way needed. 1=true, 0=false. Int N
stackable Tells if the parcel is sturdy enough to be stacked on other parcels of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Int N
warehouse Name of the warehouse where this parcels contents resides. This is a filtering option, since some delivery services might not be available, unless the packages departure and destination places are on the same city or country or even on same postal code area. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
tracking_codes Tracking codes element. Includes other elements. Element N
send You can also give the parcel a tracking code for the send direction. You can get the tracking codes from the CreateNewTrackingCodes -api. Our service will attach the given tracking code into the current parcel, and this code will also be printed onto the package card. Only one of these elements can be in one parcel. String N
return You can also give the parcel a tracking code for the return direction. You can get the tracking codes from the CreateNewTrackingCodes -api. Our service will attach the given tracking code into the current parcel, and this code will also be printed onto the package card. Only one of these elements can be in one parcel. String N
additional_services Additional services element. Includes other elements. Element N
service Service element. Includes other elements. You can have multiple of these elements. Under this element there is always the "code" -element, and there could be others as well. See the "Additional services" -section and examples. Element Y
code Unique identifier for the additional service. For the codes refer to "Additional services" -section. String Y
If only the product codes are used:
product_codes product_codes element. Includes other elements. Contains all the product_code -elements. If you are not using full details of the parcel, this is required element. Element Y/N
product_code Product code of the product. This must be the same as declared in the GetDeliveryOptions -api! At least one product code for each parcel must be present. If you are using the full parcel details, this can be omitted. Note that json format doesn't have this element! See the examples. String Y/N
Optional customer details:
customer Customer element. Includes other elements. Element N
first_name Customers first name. String N
last_name Customers last name. String N
street_address Customers street address. String N
postal_code Customers postal code. String Y
city Customers city. String N
country Customers country. String Y
postal_box Customers post office box(eng. P.O.Box). String N
company Customers companys name. String N
phone Customers phone number. For allowed formats, see "Get started" -section. String N
email Customers email. String N

–Return data:

Field Description Dataformat Required (Y or N)
orderid Id of the order you gave in the query. String Y
parcels Parcels element. Includes other elements. Element Y
parcel Parcel element. Includes other elements. If the order has more than one parcel, there will be one parcel element for each of them. Each parcel includes it's own tracking codes and package cards. Note that json format doesn't have this element. In json response the parcels are an array but since xml is not happy about arrays, this element exists for each parcel. Element Y/N
parcel_code Identifying code of the parcel. String Y
send_trcode Tracking code for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_trcode Tracking code for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y
send_card Package card for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_card Package card for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y

Request

POST https://shipfunkservices.com/api/1.2/create_new_package_cards/true/json/json/orderid
Requestsxmlxml, product codesjsonjson, product codesPHP example
Headers
Location: /create_new_package_cards/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <return_cards>1</return_cards>
        <sendmail>0</sendmail>
        <send_edi>0</send_edi>

        <package_card>
            <direction>both</direction>
            <dpi>300</dpi>
            <size>4x6</size>
            <reversed>0</reversed>
            <format>zpl</format>
        </package_card>

        <additional_services>
            <service>
                <code>10001</code>
                <bank_account>FI2350000110000238</bank_account>
                <bic>OKOYFIHH</bic>
                <monetary_value>400</monetary_value>
                <reference>1000342</reference>
            </service>
            <service>
                <code>10009</code>
                <monetary_value>400</monetary_value>
            </service>
        </additional_services>

        <parcels>
            <parcel>
                <code>00001</code>
                <contents>Clothing</contents>

                <weight>
                    <unit>kg</unit>
                    <amount>5</amount>
                </weight>

                <monetary_value>4</monetary_value>

                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>

                <toppleable>1</toppleable>
                <stackable>1</stackable>

                <warehouse>Warehouse1</warehouse>

                <tracking_codes>
                    <send>JJFI12340000000000004</send>
                    <return>JJFI12340000000000005</return>
                </tracking_codes>

                <additional_services>
                    <service>
                        <code>10004</code>
                    </service>

                    <service>
                        <code>10025</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>59010</code>
                        <count>1</count>
                        <add_fee>1</add_fee>
                    </service>

                    <service>
                        <code>10028</code>
                        <packing_group />
                        <quantity>0.01</quantity>
                        <quantity_unit>kg</quantity_unit>
                        <shipping_name />
                        <tunnel_restriction_code />
                        <un_code />
                    </service>
                </additional_services>
            </parcel>
            <parcel>
                <code>00002</code>
                <contents>Apparatus</contents>

                <weight>
                    <unit>kg</unit>
                    <amount>15</amount>
                </weight>

                <monetary_value>400</monetary_value>

                <dimensions>
                    <unit>cm</unit>
                    <width>40</width>
                    <depth>40</depth>
                    <height>30</height>
                </dimensions>

                <toppleable>1</toppleable>
                <stackable>1</stackable>

                <warehouse>Warehouse1</warehouse>

                <tracking_codes>
                    <send>JJFI12340000000000006</send>
                    <return>JJFI12340000000000007</return>
                </tracking_codes>
            </parcel>
        </parcels>
    </order>

    <customer>
        <first_name>MrFirstname</first_name>
        <last_name>Lastname</last_name>
        <street_address>Teststreet 10 A 34</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <country>FI</country>
        <postal_box />
        <company />
        <phone>040 1231234</phone>
        <email>example@example.com</email>
    </customer>
</query>
Responses200400
Body
// Success, return_cards=1:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <orderid>AB0012345</orderid>
    <parcel>
        <parcelcode>00001</parcelcode>
        <send_trcode>JJFI12340000000000004</send_trcode>
        <return_trcode>JJFI12340000000000005</return_trcode>
        <send_card>Package card in the requested format</send_card>
        <return_card>Package card in the requested format</return_card>
    </parcel>
    <parcel>
        <parcelcode>00002</parcelcode>
        <send_trcode>JJFI12340000000000006</send_trcode>
        <return_trcode>JJFI12340000000000007</return_trcode>
        <send_card>Package card in the requested format</send_card>
        <return_card>Package card in the requested format</return_card>
    </parcel>
</response>

// Success, return_cards=0:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_new_package_cards/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <return_cards>1</return_cards>
        <sendmail>0</sendmail>
        <send_edi>0</send_edi>

        <package_card>
            <direction>both</direction>
            <dpi>300</dpi>
            <size>4x6</size>
            <reversed>0</reversed>
            <format>zpl</format>
        </package_card>

        <additional_services>
            <service>
                <code>10001</code>
                <bank_account>FI2350000110000238</bank_account>
                <bic>OKOYFIHH</bic>
                <monetary_value>400</monetary_value>
                <reference>1000342</reference>
            </service>
            <service>
                <code>10009</code>
                <monetary_value>400</monetary_value>
            </service>
        </additional_services>

        <parcels>
            <parcel>
                <product_codes>
                    <product_code>B53756b6174</product_code>
                    <product_code>B53756b6175</product_code>
                    <product_code>B53756b6176</product_code>
                </product_codes>

                <tracking_codes>
                    <send>JJFI12340000000000004</send>
                    <return>JJFI12340000000000005</return>
                </tracking_codes>
            </parcel>
            <parcel>
                <product_codes>
                    <product_code>A1234gg7115</product_code>
                </product_codes>

                <warehouse>Warehouse1</warehouse>

                <tracking_codes>
                    <send>JJFI12340000000000006</send>
                    <return>JJFI12340000000000007</return>
                </tracking_codes>
            </parcel>
        </parcels>
    </order>
</query>
Responses200400
Body
// Success, return_cards=1:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <orderid>AB0012345</orderid>
    <parcel>
        <parcelcode>00001</parcelcode>
        <send_trcode>JJFI12340000000000004</send_trcode>
        <return_trcode>JJFI12340000000000005</return_trcode>
        <send_card>Package card in the requested format</send_card>
        <return_card>Package card in the requested format</return_card>
    </parcel>
    <parcel>
        <parcelcode>00002</parcelcode>
        <send_trcode>JJFI12340000000000006</send_trcode>
        <return_trcode>JJFI12340000000000007</return_trcode>
        <send_card>Package card in the requested format</send_card>
        <return_card>Package card in the requested format</return_card>
    </parcel>
</response>

// Success, return_cards=0:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_new_package_cards/true/json/json/AB0012345
Authorization: my_apikey
Body
{
    "query": {
        "webshop": {
            "api_key": "my_apikey"
        },
        "order": {
            "return_cards": 1,
            "sendmail": 0,
            "send_edi": 0,
            "package_card": {
                "direction": "both",
                "format": "zpl",
                "dpi": "300",
                "size": "4x6",
                "reversed": 0
            },
            "additional_services": [
                {
                    "code": "10001",
                    "bank_account": "FI2350000110000238",
                    "bic": "OKOYFIHH",
                    "monetary_value": 4,
                    "reference": "1000342"
                },
                {
                    "code": "10009",
                    "monetary_value": 4
                }
            ],
            "parcels": [
                {
                    "code": 0,
                    "contents": "Clothing",
                    "weight": {
                        "unit": "kg",
                        "amount": 0.1
                    },
                    "dimensions": {
                        "unit": "cm",
                        "width": "15",
                        "depth": "10",
                        "height": "3"
                    },
                    "monetary_value": 4,
                    "toppleable": 1,
                    "stackable": 1,
                    "warehouse": "Warehouse1",
                    "additional_services": [
                        {
                            "code": "10004"
                        },
                        {
                            "code": "10025",
                            "count": 1,
                            "add_fee": 1
                        },
                        {
                            "code": "59010",
                            "count": 1,
                            "add_fee": 1
                        },
                        {
                            "code": "10028",
                            "packing_group": "",
                            "quantity": 0.1,
                            "quantity_unit": "kg",
                            "shipping_name": "",
                            "tunnel_restriction_code": "",
                            "un_code": "",
                            "warning_label_numbers": ""
                        }
                    ]
                    "tracking_codes": {
                        "send": "JJFI12340000000000004",
                        "return": "JJFI12340000000000005"
                    }
                }
            ]
        },
        "customer": {
            "first_name": "MrFirstname",
            "last_name": "Lastname",
            "street_address": "Teststreet 10 A 34",
            "postal_code": "70100",
            "city": "Kuopio",
            "country": "FI",
            "postal_box": "",
            "company": "",
            "phone": "040 1231234",
            "email": "example@example.com"
        }
    }
}
Responses200400
Body
// Success, return_cards=1:
{
    "response": {
        "orderid": "AB0012345",
        "parcels": [
            {
                "parcel_code": "",
                "send_trcode": "JJFI12340000000000004",
                "return_trcode": "JJFI12340000000000005",
                "send_card": "package card in the requested format",
                "return_card": "package card in the requested format"
            }
        ]
    }
}

// Success, return_cards=0:
{
    "Response": {
        "Code": "1",
        "Message": "OK"
    }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Headers
Location: /create_new_package_cards/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "return_cards": 1,
      "sendmail": 0,
      "send_edi": 0,
      "package_card": {
        "direction": "both",
        "format": "zpl",
        "dpi": "300",
        "size": "4x6",
        "reversed": 0
      },
      "additional_services": [
        {
          "code": "10001",
          "bank_account": "FI2350000110000238",
          "bic": "OKOYFIHH",
          "monetary_value": 4,
          "reference": "1000342"
        },
        {
          "code": "10009",
          "monetary_value": 4
        }
      ],
      "parcels": [
        {
          "product_codes": [
            "B53756b6174"
          ],
          "tracking_codes": {
            "send": "JJFI12340000000000004",
            "return": "JJFI12340000000000005"
          },
          "warehouse": "Warehouse1"
        }
      ]
    },
    "customer": {
      "first_name": "MrFirstname",
      "last_name": "Lastname",
      "street_address": "Teststreet 10 A 34",
      "postal_code": "70100",
      "city": "Kuopio",
      "country": "FI",
      "postal_box": "",
      "company": "",
      "phone": "040 1231234",
      "email": "example@example.com"
    }
  }
}
Responses200400
Body
// Success, return_cards=1:
{
    "response": {
        "orderid": "AB0012345",
        "parcels": [
            {
                "parcel_code": "",
                "send_trcode": "JJFI12340000000000004",
                "return_trcode": "JJFI12340000000000005",
                "send_card": "package card in the requested format",
                "return_card": "package card in the requested format"
            }
        ]
    }
}

// Success, return_cards=0:
{
    "Response": {
        "Code": "1",
        "Message": "OK"
    }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/create_new_package_cards/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_new_package_cards=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateNewPackageCards query
POST/create_new_package_cards/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


CreateNewTrackingCodes API

Basic info

With CreateNewTrackingCodes-API you can create new tracking codes for the parcels. In CreateNewPackageCards -api you can assign these tracking codes to the parcels of your choice.

Note that we will create the tracking codes for you in the CreateNewPackageCards, so this api is not necessary to use. If this api suits your needs better, you are free to use it.

We will automatically search for the correct transport company attached to the order, and create the tracking codes for that company. You can also add the carriercode which you want to have the codes for. In case you just want one tracking code for the given order, you can use this API as a fully RESTFUL API, which means that you can leave out the xml/json message for good. Just remember to set the request_type to “rest”.

If the order doesn’t have a delivery method selected and you don’t provide a carriercode in the message, we cannot create any tracking codes.

It is not recommended to create tracking codes unless you really need them.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_new_tracking_codes when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
code_amount Amount of the tracking codes you want us to return. Defaults to 1 if omitted. Int N
carriercode Shipfunk's own id for the transport company and its delivery option. String N

–Return data:

Field Description Dataformat Required (Y or N)
tracking_codes tracking_codes element. Includes other elements. See examples. Note that in json this element is an array holding all the tracking codes! Element Y
tr_code (XML only!)The tracking code. There might be multiple of these elements, depending of the amount of codes you requested. All of these elements are named the same. Note that in json this element doesn't exist! String Y/N

Request

GET https://shipfunkservices.com/api/1.2/create_new_tracking_codes/true/json/json/orderid
RequestsREST | xmlxmljsonPHP example
Headers
Location: /create_new_tracking_codes/true/rest/xml/AB0012345
Authorization: my_apikey
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <tracking_codes>
        <tr_code>JJFI12345999990000004</tr_code>
    </tracking_codes>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_new_tracking_codes/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <code_amount>2</code_amount>
        <carriercode>02000201</carriercode>
    </order>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <tracking_codes>
        <tr_code>JJFI12345999990000004</tr_code>
        <tr_code>JJFI12345999990000005</tr_code>
    </tracking_codes>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_new_tracking_codes/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "code_amount": "2",
      "carriercode": "02000201"
    }
  }
}
Responses200400
Body
{
  "response": {
    "tracking_codes": [
      "JJFI12345999990000004",
      "JJFI12345999990000005"
    ]
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/create_new_tracking_codes/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_new_tracking_codes=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateNewTrackingCodes query
GET/create_new_tracking_codes/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in. If you don’t send any data besides the ones in the url, set this to “rest”.

Choices: xml json rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetPackageCards API

Basic info

With GetPackageCards-API you can fetch the previously created package cards. This service doesn’t create the cards, but only returns the ones that are already created.

You can fetch the package cards using only the order id, and all the package cards for the order will be returned. You have the option to use the tracking code as a parameter, and only the cards associated with the tracking code will be returned.

Important note: If you are requesting the cards with a tracking code, you might get multiple ones, depending on the transport companys’ practises. Sometimes there can be multiple parcels under a one single tracking code.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_get_package_cards when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
sendmail If this is 1(true), we will send an email to the customer telling that the order has been processed and is ready to be delivered. This email will include the tracking codes for the order, and other details about the delivery. 1=true, 0=false. Defaults to 0(false) if omitted. Int N
tracking_code Tracking code associated with the parcel. String N
package_card Package card element. Includes other elements. See examples. Element N
direction Direction of the card. 'send', 'return', or 'both'. This dictates the direction of the package cards. If you want to have only the send-cards, set this to be 'send'. Defaults to 'both' if omitted. String N

–Return data:

Field Description Dataformat Required (Y or N)
orderid Id of the order you gave in the query. String Y
parcels Parcels element. Includes other elements. Element Y
parcel Parcel element. Includes other elements. If the order has more than one parcel, there will be one parcel element for each of them. Each parcel includes it's own tracking codes and package cards. Note that json format doesn't have this element. In json response the parcels are an array but since xml is not happy about arrays, this element exists for each parcel. Element Y
parcel_code Identifying code of the parcel. String Y
send_trcode Tracking code for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_trcode Tracking code for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y
send_card Package card for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_card Package card for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y

Request

POST https://shipfunkservices.com/api/1.2/get_package_cards/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /get_package_cards/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <sendmail>0</sendmail>
        <tracking_code>JJFI12340000000000004</tracking_code>
        <package_card>
            <direction>both</direction>
        </package_card>
    </order>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <orderid>AB0012345</orderid>
    <parcel>
        <parcelcode>00001</parcelcode>
        <send_trcode>JJFI12340000000000004</send_trcode>
        <return_trcode>JJFI12340000000000005</return_trcode>
        <send_card>Package card in the requested format</send_card>
        <return_card>Package card in the requested format</return_card>
    </parcel>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /get_package_cards/true/xml/xml/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "package_card": {
        "card_direction": "both"
      },
      "sendmail": "0",
      "tracking_code": "JJFI12340000000000004"
    }
  }
}
Responses200400
Body
{
  "response": {
    "orderid": "AB0012345",
    "parcels": [
      {
        "parcel_code": "",
        "send_trcode": "JJFI12340000000000004",
        "return_trcode": "JJFI12340000000000005",
        "send_card": "package card in the requested format",
        "return_card": "package card in the requested format"
      }
    ]
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_package_cards/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_package_cards=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetPackageCards query
POST/get_package_cards/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetTrackingCodes API

Basic info

With GetTrackingCodes-API you can fetch all of the previously created tracking codes for the specific order. This service doesn’t create the tracking codes, but only returns the ones that are already created.

GetTrackingCodes-API can be used as a REST-API, which means that you don’t have to send any files via POST or GET. All the necessary data is transferred within the url. If you use this API as a REST-API, you’ll get both of the tracking codes, the outgoing and incoming.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_get_tracking_codes when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
package_card Package card element. Includes other elements. See examples. Element N
direction Direction of the parcel. 'send', 'return', or 'both'. This dictates the direction of the tracking codes. If you want to have only the outgoing parcels tracking codes, set this to be 'send'. Defaults to 'both' if omitted. If you want both of the codes, the send and return, don't send any data in the POST/GET, and set the query_type as "rest". String N

–Return data:

Field Description Dataformat Required (Y or N)
orderid Id of the order you gave in the query. String Y
parcel parcel element. Contains other elements. If the order has more than one parcel, there will be one parcel element for each of them. Each parcel includes it's own tracking codes and package cards. Element Y
parcel_code Identifying code of the parcel. String Y
send_link Link to the tracking service for the outgoing parcel. This link will take the customer directly to the tracking service for this current parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_link Link to the tracking service for the inbound parcel. This link will take the customer directly to the tracking service for this current parcel. This is for the package coming back to the webstore from the customer. String Y
send_trcode Tracking code for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return_trcode Tracking code for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y

Request

GET https://shipfunkservices.com/api/1.2/get_tracking_codes/true/json/json/orderid
RequestsREST | xmlxmljsonPHP example
Headers
Location: /get_tracking_codes/true/rest/xml/AB0012345
Authorization: my_apikey
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <orderid>AB0012345</orderid>
    <parcel>
        <parcelcode>000001</parcelcode>
        <send_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000004&company=Posti</send_link>
        <return_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000005&company=Posti</return_link>
        <send_code>JJFI12340000000000004</send_code>
        <return_code>JJFI12340000000000005</return_code>
    </parcel>
    <parcel>
        <parcelcode>000002</parcelcode>
        <send_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000006&company=Posti</send_link>
        <return_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000007&company=Posti</return_link>
        <send_code>JJFI12340000000000006</send_code>
        <return_code>JJFI12340000000000007</return_code>
    </parcel>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10005</Code>
        <Message>Cannot find tracking codes with orderid='AB0012345', direction='both'</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /get_tracking_codes/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <package_card>
            <direction>both</direction>
        </package_card>
    </order>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <orderid>AB0012345</orderid>
    <parcel>
        <parcelcode>000001</parcelcode>
        <send_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000004&company=Posti</send_link>
        <return_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000005&company=Posti</return_link>
        <send_code>JJFI12340000000000004</send_code>
        <return_code>JJFI12340000000000005</return_code>
    </parcel>
    <parcel>
        <parcelcode>000002</parcelcode>
        <send_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000006&company=Posti</send_link>
        <return_link>https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000007&company=Posti</return_link>
        <send_code>JJFI12340000000000006</send_code>
        <return_code>JJFI12340000000000007</return_code>
    </parcel>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10005</Code>
        <Message>Cannot find tracking codes with orderid='AB0012345', direction='both'</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /get_tracking_codes/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "package_card": {
        "card_direction": "both"
      }
    }
  }
}
Responses200202400
Body
{
  "response": {
    "orderid": "dummyorder",
    "parcel": [
      {
        "parcel_code": "000001",
        "send_link": "https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000004&company=Posti",
        "return_link": "https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000005&company=Posti",
        "send_code": "JJFI12340000000000004",
        "return_code": "JJFI12340000000000005"
      },
      {
        "parcel_code": "000002",
        "send_link": "https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000006&company=Posti",
        "return_link": "https://shipfunkservices.com/tracking/tracked?tracking_code=JJFI12340000000000007&company=Posti",
        "send_code": "JJFI12340000000000006",
        "return_code": "JJFI12340000000000007"
      }
    ]
  }
}
Body
{
  "Info": {
    "Code": "10005",
    "Message": "Cannot find tracking codes with orderid='AB0012345', direction='both'."
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_tracking_codes/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_tracking_codes=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetTrackingCodes query
GET/get_tracking_codes/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in. If you don’t send any data in the POST/GET, set this to “rest”.

Choices: xml json rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetTrackingEvents API

Basic info

With GetTrackingEvents-API you can get the tracking events for the given tracking code and transport company. Note that the transport company is mandatory since we house many different transport companies in our system, and some of the tracking codes are quite similar in different companies. You can define the transport company by name, carriercode, or you can give us the orderid which the tracking events should belong to, and we can get the correct transport company from our database.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Tracking statuses

Our service can return the following statuscodes for the events:

  • 0 = No tracking statuses

  • ‘RECE’ = Received for delivery from the eshop / Collected from the warehouse

  • ‘DELP’ = Delivered to pickup point / Ready to be picked by customer

  • ‘NOTI’ = Notice of arrival sent

  • ‘DELC’ = Delivered to customer

  • ‘RETA’ = Not collected by customer --> returned to eshop automatically

  • ‘RETU’ = Returned by customer

  • ‘RETD’ = Returned to eshop, parcel damaged

Variable name

You must use the form-data variable name: sf_get_tracking_events when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
tracking_code Tracking code of the parcel to be tracked. String Y
language Two digit language code for the texts in the tracking events. Defaults to FI if not declared. IMPORTANT NOTE: If this field is omitted, the returning data might have wrong language in it! Tracking events come directly from the transport company, and we do not have control over the translations. If the language you defined is not supported, it will default to en_US or the transport companys default language. String Y
carrier Carrier card element. Includes other elements. See examples. Element N
transport_company Name of the transport company. If you don't define the carriercode or the orderid(in the url), this must exist. String Y/N
carriercode Carriercode of the transport companys delivery option. If you don't define the transport_company or the orderid(in the url), this must exist. String Y/N

–Return data:

Field Description Dataformat Required (Y or N)
tracked tracked element. Includes other elements. See examples. Element Y
DeliveryStatus This is the main indicator of the situation of the order. The latest bigger status can be seen here. See the "Tracking statuses" above to see what statuses are possible. Int Y
ShipmentIdentifier Tracking code of the order. String Y
ServiceName Name of the delivery option. String Y
Weight Weight of the order. In kilos. Double Y
Volume Volume of the order. This is in cubic meters. Double Y
DestinationPostalCode This is the postcode of the customer for the outgoing parcels, and the postcode of the webstore for the incoming parcels. String Y
DestinationPostOffice This is the city of the customer for the outgoing parcels, and the city of the webstore for the incoming parcels. String Y
DestinationCountryCode This is the country of the customer for the outgoing parcels, and the country of the webstore for the incoming parcels. String Y
Events Events element. Includes other elements. See examples. One Events-element has one tracking event. I.e. "Order has been packed." Element Y
TrackingStatus This is the statuscode for the current tracking event. Note that not all the events have a code! See the "Tracking statuses" above to see what statuses are possible. String Y
TrackingDescription Written description of the event. I.e. "Order has been packed." String Y
TrackingDate Date of the event. Date format is: dd.MM.yyyy Date Y
TrackingTime Time of the event. Time format is: hh:mm:ss Time Y
TrackingPlace Place for the event. This might have just the name of the place, i.e. SmartPost CM Kuopio 70700, or this might only have the address of the place. Contents of this element depends on the transport company, and what it wants to convey through this information. String Y

Request

GET https://shipfunkservices.com/api/1.2/get_tracking_events/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /get_tracking_events/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <language>FI</language>
        <tracking_code>JJFI12340000000000004</tracking_code>
        <carrier>
            <transport_company>Posti</transport_company>
            <carriercode>02000201</carriercode>
        </carrier>
    </order>
</query>
Responses200202400
Body
// Success:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <tracked>
        <DeliveryStatus>DELC</DeliveryStatus>
        <ShipmentIdentifier>JJFI12340000000000004</ShipmentIdentifier>
        <ServiceName>Posti Home Parcel</ServiceName>
        <Weight>0.45</Weight>
        <Volume>0.0143</Volume>
        <DestinationPostalCode>02340</DestinationPostalCode>
        <DestinationPostOffice>ESPOO</DestinationPostOffice>
        <DestinationCountryCode>FI</DestinationCountryCode>
        <Events>
            <TrackingStatus>DELC</TrackingStatus>
            <TrackingDescription>Item delivered to the recipient.</TrackingDescription>
            <TrackingDate>20.10.2016</TrackingDate>
            <TrackingTime>19:10:06</TrackingTime>
            <TrackingPlace>Posti kuljetus 02610</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>Item is in delivery transportation.</TrackingDescription>
            <TrackingDate>20.10.2016</TrackingDate>
            <TrackingTime>17:05:34</TrackingTime>
            <TrackingPlace>Posti kuljetus 02610</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>Item has been registered.</TrackingDescription>
            <TrackingDate>20.10.2016</TrackingDate>
            <TrackingTime>16:10:56</TrackingTime>
            <TrackingPlace>ESPOO 02610</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>A delivery time has been scheduled with the recipient.</TrackingDescription>
            <TrackingDate>19.10.2016</TrackingDate>
            <TrackingTime>11:12:00</TrackingTime>
            <TrackingPlace>VANTAA Kuljetus Loke 01300</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>An attempt has been made to contact the recipient in order to schedule the delivery time. The recipient will be contacted again.</TrackingDescription>
            <TrackingDate>4.10.2016</TrackingDate>
            <TrackingTime>11:19:07</TrackingTime>
            <TrackingPlace>VANTAA Kuljetus Loke 01300</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>Item has been registered.</TrackingDescription>
            <TrackingDate>4.10.2016</TrackingDate>
            <TrackingTime>08:22:09</TrackingTime>
            <TrackingPlace>VANTAA Kuljetus Loke 01300</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>An attempt has been made to contact the recipient in order to schedule the delivery time. The recipient will be contacted again.</TrackingDescription>
            <TrackingDate>4.10.2016</TrackingDate>
            <TrackingTime>07:32:47</TrackingTime>
            <TrackingPlace>Posti Flex Tekstiviestipalvelu 02610</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus>RECE</TrackingStatus>
            <TrackingDescription>Item in sorting.</TrackingDescription>
            <TrackingDate>3.10.2016</TrackingDate>
            <TrackingTime>19:43:39</TrackingTime>
            <TrackingPlace>Posti Logistiikkakeskus 01010</TrackingPlace>
        </Events>
        <Events>
            <TrackingStatus />
            <TrackingDescription>The item is not yet in Posti.</TrackingDescription>
            <TrackingDate>30.9.2016</TrackingDate>
            <TrackingTime>11:09:08</TrackingTime>
            <TrackingPlace>TUUSULA 04360</TrackingPlace>
        </Events>
    </tracked>
</response>

// Error:
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00020</Code>
        <Message>No tracking events found with given parameters.</Message>
    </Error>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10010</Code>
        <Message>No tracking events found with given parameters.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /get_tracking_events/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "tracking_code": "JJFI12340000000000004",
      "language": "FI",
      "carrier": {
        "transport_company": "Posti",
        "carriercode": "02000201"
      }
    }
  }
}
Responses200202400
Body
{
    "response": {
        "tracked": [
            {
                "DeliveryStatus": "DELC",
                "ShipmentIdentifier": "JJFI12340000000000004",
                "ServiceName": "Posti Home Parcel",
                "Weight": "0.45",
                "Volume": "0.0143",
                "DestinationPostalCode": "02340",
                "DestinationPostOffice": "ESPOO",
                "DestinationCountryCode": "FI",
                "Events": [
                    {
                        "TrackingStatus": "DELC",
                        "TrackingDescription": "Item delivered to the recipient.",
                        "TrackingDate": "20.10.2016",
                        "TrackingTime": "19:10:06",
                        "TrackingPlace": "Posti kuljetus 02610"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "Item is in delivery transportation.",
                        "TrackingDate": "20.10.2016",
                        "TrackingTime": "17:05:34",
                        "TrackingPlace": "Posti kuljetus 02610"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "Item has been registered.",
                        "TrackingDate": "20.10.2016",
                        "TrackingTime": "16:10:56",
                        "TrackingPlace": "ESPOO 02610"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "A delivery time has been scheduled with the recipient.",
                        "TrackingDate": "19.10.2016",
                        "TrackingTime": "11:12:00",
                        "TrackingPlace": "VANTAA Kuljetus Loke 01300"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "An attempt has been made to contact the recipient in order to schedule the delivery time. The recipient will be contacted again.",
                        "TrackingDate": "4.10.2016",
                        "TrackingTime": "11:19:07",
                        "TrackingPlace": "VANTAA Kuljetus Loke 01300"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "Item has been registered.",
                        "TrackingDate": "4.10.2016",
                        "TrackingTime": "08:22:09",
                        "TrackingPlace": "VANTAA Kuljetus Loke 01300"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "An attempt has been made to contact the recipient in order to schedule the delivery time. The recipient will be contacted again.",
                        "TrackingDate": "4.10.2016",
                        "TrackingTime": "07:32:47",
                        "TrackingPlace": "Posti Flex Tekstiviestipalvelu 02610"
                    },
                    {
                        "TrackingStatus": "RECE",
                        "TrackingDescription": "Item in sorting.",
                        "TrackingDate": "3.10.2016",
                        "TrackingTime": "19:43:39",
                        "TrackingPlace": "Posti Logistiikkakeskus 01010"
                    },
                    {
                        "TrackingStatus": "",
                        "TrackingDescription": "The item is not yet in Posti.",
                        "TrackingDate": "30.9.2016",
                        "TrackingTime": "11:09:08",
                        "TrackingPlace": "TUUSULA 04360"
                    }
                ]
            }
        ]
    }
}

// Error:
{
    "Error": {
        "Code": "00020",
        "Message": "No tracking events found with given parameters."
    }
}
Body
{
  "Info": {
    "Code": "10010",
    "Message": "No tracking events found with given parameters."
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_tracking_events/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_tracking_events=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetTrackingEvents query
GET/get_tracking_events/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (optional) 

This is the id given for the order by the eshop. Note that this can be empty.


GetParcels API

Basic info

With GetParcels-API you can get all the parcels that have been created in our service, but obviously only for the given order. This API can be used as a REST API, which means that you don’t have to send anything in the POST/GET. If you cannot send HTTP headers with the auth-section, you must send the api key within the POST/GET -message.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters. Note that even if the element is returned, it might still be empty.

Variable name

You must use the form-data variable name: sf_get_parcels when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N

–Return data:

Field Description Dataformat Required (Y or N)
parcels Parcels element. Includes other elements. Note that one parcel may contain several products. Element Y
parcel Parcel element. Includes other elements. There can be multiple of these elements, one for each parcel. Note that one parcel may contain several products. Element Y
code Identifying code of the parcel. String Y
contents Contents of the parcel. String Y
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. String Y
amount The actual weight of the product. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the parcel. Element Y
unit Dictates the used unit for dimensions. String Y
width Width of the item. Double Y
depth Depth of the item. Double Y
height Height of the item. Double Y
value Monetary value of the parcel. Unit has been given in the order details but is not stated here anymore. Double Y
warehouse Name of the warehouse where this parcels contents resides. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String Y
fragile If the parcel has the fragile -additional service, it will be stated here. 1=true, 0=false. Int Y
tracking_codes Tracking codes element. Includes other elements. Element Y
send Tracking code for outgoing direction, i.e. for sending. Only one of these elements can be in one parcel. String Y
return Tracking code for incoming direction, i.e. for returning. Only one of these elements can be in one parcel. String Y
package_cards Package cards element. Includes other elements. Element Y
send Package card for the outgoing parcel. This is for the package leaving the webstores warehouse to the customer. String Y
return Package card for the inbound parcel. This is for the package coming back to the webstore from the customer. String Y

Request

GET https://shipfunkservices.com/api/1.2/get_parcels/true/rest/json/orderid
RequestsxmljsonPHP example
Headers
Location: /get_parcels/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <parcels>
        <parcel>
            <code />
            <contents>Clothing</contents>
            <weight>
                <unit>kg</unit>
                <amount>0.1</amount>
            </weight>
            <dimensions>
                <unit>cm</unit>
                <width>15</width>
                <depth>10</depth>
                <height>3</height>
            </dimensions>
            <value>4</value>
            <warehouse>Warehouse1</warehouse>
            <fragile>0</fragile>
            <tracking_codes>
                <send>JJFI12345999990000004</send>
                <return>JJFI12345999990000005</return>
            </tracking_codes>
            <package_cards>
                <send><![CDATA[--package card in requested format--]]></send>
                <return><![CDATA[--package card in requested format--]]></return>
            </package_cards>
            <parcel_creation_date>2017-04-07 13:18:24</parcel_creation_date>
        </parcel>
        <parcel>
            <code>010001554</code>
            <contents>Parfumes</contents>
            <weight>
                <unit>kg</unit>
                <amount>0.5</amount>
            </weight>
            <dimensions>
                <unit>cm</unit>
                <width>10</width>
                <depth>10</depth>
                <height>15</height>
            </dimensions>
            <value>45</value>
            <warehouse>Warehouse1</warehouse>
            <fragile>1</fragile>
            <tracking_codes>
                <send />
                <return />
            </tracking_codes>
            <package_cards>
                <send />
                <return />
            </package_cards>
            <parcel_creation_date>2017-04-12 14:53:18</parcel_creation_date>
        </parcel>
    </parcels>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10011</Code>
        <Message>No parcels found.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /get_parcels/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    }
  }
}
Responses200202400
Body
{
  "response": {
    "parcels": [
      {
        "code": "",
        "contents": "Clothing",
        "weight": {
          "unit": "kg",
          "amount": "0.1"
        },
        "dimensions": {
          "unit": "cm",
          "width": "15",
          "depth": "10",
          "height": "3"
        },
        "value": "4",
        "warehouse": "Warehouse1",
        "fragile": "0",
        "tracking_codes": {
          "send": "JJFI12345999990000004",
          "return": "JJFI12345999990000005"
        },
        "package_cards": {
          "send": "--package card in requested format--",
          "return": "--package card in requested format--"
        },
        "parcel_creation_date": "2017-04-07 13:18:24"
      },
      {
        "code": "010001554",
        "contents": "Parfumes",
        "weight": {
          "unit": "kg",
          "amount": "0.5"
        },
        "dimensions": {
          "unit": "cm",
          "width": "10",
          "depth": "10",
          "height": "15"
        },
        "value": "45",
        "warehouse": "Warehouse1",
        "fragile": "1",
        "tracking_codes": {
          "send": null,
          "return": null
        },
        "package_cards": {
          "send": null,
          "return": null
        },
        "parcel_creation_date": "2017-04-12 14:53:18"
      }
    ]
  }
}
Body
{
  "Info": {
    "Code": "10011",
    "Message": "No parcels found."
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_parcels/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_parcels=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetParcels
GET/get_parcels/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: rest

This is the format you are sending the data in. If you are not sending anything via POST/GET, set this to rest.

Choices: rest xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


EditParcels API

Basic info

With EditParcels-API you can edit the parcels details. You can for example change the weight or the dimensions of the parcels.

If you want to empty a field, set it to be NULL, as in a text “NULL” if the field is a String field, and a minus one(-1) if the field is a Double or Int field. If you just empty the value or omit the field altogether, it won’t be updated. “NULL” and -1 tells the API to empty the value in that field. If the field has a default value, it will be reset to that, like in the fragile field, which will default to zero(0).

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_edit_parcels when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
return_parcels If this is set to 1(true), the api will return all the parcels for the order, after some of them have been modified deleted. Defaults to 0(false) if omitted. Note that there can be an Info-response stating that no parcels were found if this is set to 1. Int N
parcels Parcels element. Includes other elements. Element Y
parcel Parcel element. Includes other elements. If the order has more than one parcel, there will be one parcel element for each of them. Each parcel includes it's own tracking codes and package cards. Note that json format doesn't have this element. In json request the parcels are an array but since xml is not happy about arrays, this element exists for each parcel. Element Y/N
id Identifying code of the parcel. This is a Shipfunk generated code, and each parcel always has one. This cannot be edited. You can get this id via GetParcels -API. String Y
code Another identifying code of the parcel. This is the code generated by your eshop, and Shipfunk has nothing to do with this. If you provide this, it must be unique for the order. String N
contents Contents of the parcel. Important notice: If you use PHP's curl to send the data, please use urlencode on this field. Otherwise the system might give an error depending on the text, and won't send the data! String N
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the parcel. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
monetary_value Monetary value of the parcel. Unit is told in the "currency"-element earlier. For allowed units, see "Get started" -section. Double N
warehouse Name of the warehouse where this parcels contents resides. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. This element can be omitted if you have declared only one warehouse in your extranet settings. IMPORTANT NOTE: You can also use the warehouse id in place of the name. You can get the id via GetWarehouse -API. String N
fragile "Fragile/Handle with care" -additional service. This service usually requires a service code, but in this API you can just tell it to be true or false. 1=true, 0=false. Int N

–Return data:

If the “return_parcels” is set to 1, the api will return the same data as in the GetParcels-API, or “OK”-response if the “return_parcels” is set to 0 or omitted. API can also return an Info -response. See the GetParcels -API for response examples if the “return_parcels” is set to 1. See examples for more details.

Request

POST https://shipfunkservices.com/api/1.2/edit_parcels/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /edit_parcels/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <return_parcels>1</return_parcels>
        <parcels>
            <parcel>
                <id>314834944</id>
                <code />
                <contents>Clothing</contents>
                <weight>
                    <unit>kg</unit>
                    <amount>0.1</amount>
                </weight>
                <dimensions>
                    <unit>cm</unit>
                    <width>15</width>
                    <depth>10</depth>
                    <height>3</height>
                </dimensions>
                <monetary_value>0</monetary_value>
                <warehouse>Warehouse1</warehouse>
                <fragile>0</fragile>
            </parcel>
            <parcel>
                <id>314900480</id>
                <code>010001554</code>
                <contents>Parfumes</contents>
                <weight>
                    <unit>kg</unit>
                    <amount>0.5</amount>
                </weight>
                <dimensions>
                    <unit>cm</unit>
                    <width>10</width>
                    <depth>10</depth>
                    <height>15</height>
                </dimensions>
                <monetary_value>40</monetary_value>
                <warehouse>Warehouse1</warehouse>
                <fragile>1</fragile>
            </parcel>
        </parcels>
    </order>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10011</Code>
        <Message>No parcels found.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00001</Code>
        <Message>No data.</Message>
    </Error>
</response>
Headers
Location: /edit_parcels/true/json/json/AB0012345
Authorization: my_apikey
Body
{
    "query": {
        "webshop": {
            "api_key": "my_apikey",
        },
        "order": {
            "return_parcels": "1",
            "parcels": [
                {
                    "id": "314834944",
                    "code": "",
                    "contents": "Clothing",
                    "weight": {
                        "unit": "kg",
                        "amount": "0.1"
                    },
                    "dimensions": {
                        "unit": "cm",
                        "width": "15",
                        "depth": "10",
                        "height": "3"
                    },
                    "monetary_value": "0",
                    "warehouse": "Warehouse1",
                    "fragile": "0"
                },
                {
                    "id": "314900480",
                    "code": "010001554",
                    "contents": "Parfumes",
                    "weight": {
                        "unit": "kg",
                        "amount": "0.5"
                    },
                    "dimensions": {
                        "unit": "cm",
                        "width": "10",
                        "depth": "10",
                        "height": "15"
                    },
                    "monetary_value": "40",
                    "warehouse": "Warehouse1",
                    "fragile": "1"
                }
            ]
        }
    }
}
Responses200202400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Info": {
    "Code": "10011",
    "Message": "No parcels found."
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "No data."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/edit_parcels/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_edit_parcels=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

EditParcels
POST/edit_parcels/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


DeleteParcels API

Basic info

With DeleteParcels-API you can remove the parcels you no longer wish to see in the order. Removing a parcel also removes the package card and the tracking code associated with it.

IMPORTANT NOTE: Deleting something is a final action, and the removed parcels cannot be returned in any way.

You can remove parcels by giving the parcel codes or the tracking codes of the parcels. Either one will do, you don’t need to give both of them.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_delete_parcels when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. See examples. Element Y
return_parcels If this is set to 1(true), the api will return all the parcels for the order, after some of them have been modified deleted. Defaults to 0(false) if omitted. Note that there can be an Info-response stating that no parcels were found if this is set to 1. Int N
remove_all_parcels This will tell our service to delete ALL the parcels associated with the given order. All the package cards and tracking codes will be removed along with the parcels. Note that removed parcels cannot be retrieved by any means after calling this api with this flag turned on. If this flag is on, the "parcels" -element is not needed. 1=true, 0=false. Defaults to 0 if omitted. Int N
parcels Parcels element. Includes other elements. Element Y/N
parcel Parcel element. Includes other elements. If the order has more than one parcel, there will be one parcel element for each of them. Each parcel includes it's own tracking codes and package cards. Note that json format doesn't have this element. In json request the parcels are an array but since xml is not happy about arrays, this element exists for each parcel. This element with it's child elements is not needed if the "remove_all_parcels" is set to 1(true). Element Y/N
id Identifying code of the parcel. This is a Shipfunk generated code, and each parcel always has one. You can get this id via GetParcels -API. Not needed if a valid tracking_code or parcel_code is present. String Y/N
parcel_code Identifying code of the parcel, created by your eshop. This is not a Shipfunk generated code! Not needed if a valid tracking_code or id is present. String Y/N
tracking_code Tracking code for the parcel. Not needed if a valid parcel_code or id is present. String Y/N

–Return data:

If the “return_parcels” is set to 1, the api will return the same data as in the GetParcels-API, or “OK”-response if the “return_parcels” is set to 0 or omitted. API can also return an Info -response. See the GetParcels -API for response examples if the “return_parcels” is set to 1. See examples for more details.

Request

POST https://shipfunkservices.com/api/1.2/delete_parcels/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /delete_parcels/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <return_parcels>1</return_parcels>
        <remove_all_parcels>0</remove_all_parcels>
        <parcels>
            <parcel>
                <id />
                <parcel_code />
                <tracking_code>JJFI12345999990000004</tracking_code>
            </parcel>
        </parcels>
    </order>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>00007</Code>
        <Message>One or more deletes were unsuccesfull. Maybe the given package codes or tracking codes were wrong ones? List of failed codes: '[JJFI12345999990000004]'.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00001</Code>
        <Message>No data.</Message>
    </Error>
</response>
Headers
Location: /delete_parcels/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "return_parcels": "1",
      "remove_all_parcels": "0",
      "parcels": [
        {
          "id": "",
          "parcel_code": "",
          "tracking_code": "JJFI12345999990000004"
        }
      ]
    }
  }
}
Responses200202400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Info": {
    "Code": "10007",
    "Message": "One or more deletes were unsuccesfull. Maybe the given package codes or tracking codes were wrong ones? List of failed codes: '[JJFI12345999990000004]'."
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "No data."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/delete_parcels/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_delete_parcels=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

DeleteParcels
POST/delete_parcels/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


TestOrderID API

Basic info

With TestOrderID-API you can test if the orderid is already in use by another of your orders in our system. This will come in handy for example if your ecommerce platform uses temporary order id’s, and you want to test if some order already has the id and if it’s necessary to generate a new id for the order.

TestOrderID-API is a REST-API, which means that you don’t have to send any files via POST or GET. All the necessary data is transferred within the url.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

No variables used.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Return data:

This api will return only an error or info response. See examples for more details.

Request

GET https://shipfunkservices.com/api/1.2/test_order_id/true/rest/json/orderid
RequestsREST | xmlREST | jsonPHP example
Headers
Location: /test_order_id/true/rest/xml/AB0012345
Authorization: my_apikey
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>20010</Code>
    <Message>Order found with id: 'AB0012345'.</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10009</Code>
        <Message>No orders found with id: 'AB0012345'.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /test_order_id/true/rest/json/AB0012345
Authorization: my_apikey
Responses200202400
Body
{
  "response": {
    "Code": "20010",
    "Message": "Order found with id: 'AB0012345'."
  }
}
Body
{
  "Info": {
    "Code": "10009",
    "Message": "No orders found with id: 'AB0012345'."
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'true';
$query_format = 'rest';
$return_format = 'json';
$orderid = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/test_order_id/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

TestOrderID query
GET/test_order_id/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: rest

This is the format you are sending the data in.

Choices: rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


CreateUser API

Basic info

With CreateUser-API you can create new users into our service, and attach them under your own account. Attaching the new user to your host -account will be done automatically after the new user is created, and you don’t have to send any additional API calls or parameters. Send us at least the new users email, and we’ll send you the newly created user and its API keys. Note that you’ll receive the so-called onboarding api-keys, which will attach you to the eshop when the eshop makes apicalls with these keys.

We will send the newly created user an email which has a link for the user to “activate” the account. This activation means that the account becomes usable, and the API keys start to work.

To use this API, you must have a specific host-account. If you need one, contact us via email or phone. Contact details can be found from www.shipfunk.com.

For security purposes, we will not send or return the newly created users credentials to you, but they will be sent directly to the given emails.

User created in test mode with test API key, cannot be activated into production! Those users are and always will be just test users. Use your live API key when creating real users!

If the user already exists in our service, you cannot attach it directly to you, but you must send an invitation to the user via CreateInvitation -API.

The eshop will still have his own api keys that he can use if he wants to. If he uses his own api keys, you won’t see the statistics from those orders, and if you are in our partner program, you won’t get any comissions from those orders.

Note that you or the newly created user won’t receive the live api keys unless you provide all the information needed for activation, and you are using your own live api key to call this api! To activate the users account for production, you need to provide the fields described in the “Send data” -section. If the element is required for production, it will be told in the elements description. If you don’t yet have all the necessary information required for activation, you can send that information later in the EditUser -API.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_user when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
user User element. Includes other elements. Required if the child elements are present! See examples. Element Y
email Email of the new user account. String Y
locale Locale of the new user account. Must be in the standard two letter ISO 639-1 -format. See Common information->Languages. Defaults to fi. String N
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y/N
business_id Business id of the new eshop. Required when activating the given email to production! String Y/N
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String N
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String N
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String N

–Return data:

Field Description Dataformat Required (Y or N)
user User element. Contains other elements. See examples. Element Y
email The email you gave to us. String Y
locale Locale of the new user account. Is in the standard two letter ISO 639-1 -format. See Common information->Languages. String Y
enabled If the new user has not yet clicked the link in the email, or the user is temporarily suspended (for unpaid bills for example), this value will be false. Boolean/Int Y
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y
business_id Business id of the new eshop. Required when activating the given email to production! String Y
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String Y
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String Y
contract_currency Eshops contract currency. Cannot be changed via API or Extranet. Contact Shipfunk if you must change this. String Y
activated Is the user activated or not. If we have gotten all the user data required for activation, user gets activated for production automatically. Boolean/Int Y
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String Y
api_key_test Api key for testing. String Y
api_key_live Api key for production. Note that you won't receive this if you called this api with your own testing api key, or you didn't provide all the required information. String Y

Request

POST https://shipfunkservices.com/api/1.2/create_user/true/json/json
RequestsxmljsonPHP example
Headers
Location: /create_user/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <user>
        <email>example@example.com</email>
        <eshop_name>Example Store</eshop_name>
        <locale>EN</locale>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <web_address>real_deal.example.com</web_address>
        <customer_contact_info><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contact_info>
    </user>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <user>
        <email>example@example.com</email>
        <eshop_name>Example Store</eshop_name>
        <locale>EN</locale>
        <enabled>0</enabled>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <customer_contactinfo><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contactinfo>
        <web_address>real_deal.example.com</web_address>
        <contract_currency>EUR</contract_currency>
        <activated>1</activated>
        <api_key_test>sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx</api_key_test>
        <api_key_live>sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx</api_key_live>
    </user>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10015</Code>
        <Message>User with given email already exists. Send the user an invite using CreateInvitation -API or create a new account for the user by using CreateAccount -API.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_user/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "user": {
      "email": "example@example.com",
      "locale": "EN",
      "eshop_name": "Example Store",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "web_address": "real_deal.example.com",
      "customer_contact_info": "<b>Contact us:</b> service@example.com"
    }
  }
}
Responses200202400
Body
{
  "response": {
    "user": {
      "email": "example@example.com",
      "locale": "EN",
      "enabled": false,
      "eshop_name": "Example Store",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "customer_contactinfo": "<b>Contact us:</b> service@example.com",
      "web_address": "real_deal.example.com",
      "contract_currency": "EUR",
      "activated": true,
      "api_key_test": "sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx",
      "api_key_live": "sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Body
{
  "Info": {
    "Code": "10015",
    "Message": "User with given email already exists. Send the user an invite using CreateInvitation -API or create a new account for the user by using CreateAccount -API."
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/create_user/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_user=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateUser query
POST/create_user/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


GetUser API

Basic info

With GetUser-API you can get the user that’s attached to your host -account.

To use this API, you must have a specific host-account. If you need one, contact us via email or phone. Contact details can be found from www.shipfunk.com.

You can only get the users that are attached to your account.

This API returns information that cannot be edited via any API. See the EditUser API for the fields that can be edited.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_get_user when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
user User element. Includes other elements. Required if the child elements are present! See examples. Element Y
email Email of the new user account. String Y

–Return data:

Field Description Dataformat Required (Y or N)
user User element. Contains other elements. See examples. Element Y
email The email you gave to us. String Y
locale Locale of the user account. Is in the standard two letter ISO 639-1 -format. See Common information->Languages. String Y
enabled If the new user has not yet clicked the link in the email, or the user is temporarily suspended (for unpaid bills for example), this value will be false. Boolean/Int Y
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y
business_id Business id of the new eshop. Required when activating the given email to production! String Y
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String Y
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String Y
contract_currency Eshops contract currency. Cannot be changed via API or Extranet. Contact Shipfunk if you must change this. String Y
activated Is the user activated or not. If we have gotten all the user data required for activation, user gets activated for production automatically. Boolean/Int Y
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String Y
api_key_test Api key for testing. String Y
api_key_live Api key for production. Note that you won't receive this if you called this api with your own testing api key, or you didn't provide all the required information. String Y

Request

POST https://shipfunkservices.com/api/1.2/get_user/true/json/json
RequestsxmljsonPHP example
Headers
Location: /get_user/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <user>
        <email>example@example.com</email>
    </user>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <user>
        <email>example@example.com</email>
        <locale>EN</locale>
        <enabled>0</enabled>
        <eshop_name>Example Store</eshop_name>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <customer_contactinfo><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contactinfo>
        <web_address>real_deal.example.com</web_address>
        <contract_currency>EUR</contract_currency>
        <activated>1</activated>
        <api_key_test>sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx</api_key_test>
        <api_key_live>sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx</api_key_live>
    </user>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00110</Code>
        <Message>Users not found with email: example@example.com.</Message>
    </Error>
</response>
Headers
Location: /get_user/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "user": {
      "email": "example@example.com"
    }
  }
}
Responses200400
Body
{
  "response": {
    "user": {
      "email": "example@example.com",
      "locale": "EN",
      "enabled": false,
      "eshop_name": "Example Store",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "customer_contactinfo": "<b>Contact us:</b> service@example.com",
      "web_address": "real_deal.example.com",
      "contract_currency": "EUR",
      "activated": true,
      "api_key_test": "sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx",
      "api_key_live": "sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Body
{
  "Error": {
    "Code": "00110",
    "Message": "Users not found with email: example@example.com."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/get_user/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_user=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetUser query
POST/get_user/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


EditUser API

Basic info

With EditUser-API you can modify the existing user. You can give more information, or edit the data already given. You can also use this API to activate the user into production readiness, by giving all the prod-required data.

To use this API, you must have a specific host-account. If you need one, contact us via email or phone. Contact details can be found from www.shipfunk.com.

Note that you or the edited user won’t receive the live api keys unless you provide all the information needed for activation, and you used your own live api keys when you called the CreateUser -API! To activate the users account for production, you need to provide the fields described in the “Send data” -section. If the element is required for production, it will be told in the elements description.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_edit_user when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
user User element. Includes other elements. Required if the child elements are present! See examples. Element Y
email Email of the new user account. String Y
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y/N
business_id Business id of the new eshop. Required when activating the given email to production! String Y/N
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String N
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String N
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String N

–Return data:

Field Description Dataformat Required (Y or N)
user User element. Contains other elements. See examples. Element Y
email The email you gave to us. String Y
locale Locale of the user account. Is in the standard two letter ISO 639-1 -format. See Common information->Languages. String Y
enabled If the new user has not yet clicked the link in the email, or the user is temporarily suspended (for unpaid bills for example), this value will be false. Boolean/Int Y
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y
business_id Business id of the new eshop. Required when activating the given email to production! String Y
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String Y
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String Y
contract_currency Eshops contract currency. Cannot be changed via API or Extranet. Contact Shipfunk if you must change this. String Y
activated Is the user activated or not. If we have gotten all the user data required for activation, user gets activated for production automatically. Boolean/Int Y
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String Y
api_key_test Api key for testing. String Y
api_key_live Api key for production. Note that you won't receive this if you called this api with your own testing api key, or you didn't provide all the required information. String Y

Request

POST https://shipfunkservices.com/api/1.2/edit_user/true/json/json
RequestsxmljsonPHP example
Headers
Location: /edit_user/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <user>
        <email>example@example.com</email>
        <eshop_name>True Deal Example Store</eshop_name>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <web_address>true_deal.example.com</web_address>
        <customer_contact_info><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contact_info>
    </user>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <user>
        <email>example@example.com</email>
        <locale>EN</locale>
        <enabled>0</enabled>
        <eshop_name>True Deal Example Store</eshop_name>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <customer_contactinfo><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contactinfo>
        <web_address>true_deal.example.com</web_address>
        <contract_currency>EUR</contract_currency>
        <activated>1</activated>
        <api_key_test>sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx</api_key_test>
        <api_key_live>sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx</api_key_live>
    </user>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00110</Code>
        <Message>Users not found with email: example@example.com.</Message>
    </Error>
</response>
Headers
Location: /edit_user/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "user": {
      "email": "example@example.com",
      "eshop_name": "True Deal Example Store",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "web_address": "true_deal.example.com",
      "customer_contact_info": "<b>Contact us:</b> service@example.com"
    }
  }
}
Responses200400
Body
{
  "response": {
    "user": {
      "email": "example@example.com",
      "locale": "EN",
      "enabled": false,
      "eshop_name": "True Deal Example Store",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "customer_contactinfo": "<b>Contact us:</b> service@example.com",
      "web_address": "true_deal.example.com",
      "contract_currency": "EUR",
      "activated": true,
      "api_key_test": "sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx",
      "api_key_live": "sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Body
{
  "Error": {
    "Code": "00110",
    "Message": "Users not found with email: example@example.com."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/edit_user/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_edit_user=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

EditUser query
POST/edit_user/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


DeleteUser API

Basic info

With DeleteUser-API you can detach the user from your account. The name of the API suggests that the user account is deleted, but this is not the case, but the user is just detached from you.

To use this API, you must have a specific host-account. If you need one, contact us via email or phone. Contact details can be found from www.shipfunk.com.

You can only delete users that are attached to your account.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_delete_user when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
user User element. Includes other elements. Required if the child elements are present! See examples. Element Y
email Email of the new user account. String Y

–Return data:

Only returns an OK -response or error.

Request

POST https://shipfunkservices.com/api/1.2/delete_user/true/json/json
RequestsxmljsonPHP example
Headers
Location: /delete_user/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <user>
        <email>example@example.com</email>
    </user>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00110</Code>
        <Message>Users not found with email: example@example.com.</Message>
    </Error>
</response>
Headers
Location: /delete_user/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "user": {
      "email": "example@example.com"
    }
  }
}
Responses200400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Error": {
    "Code": "00110",
    "Message": "Users not found with email: example@example.com."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/delete_user/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_delete_user=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetUser query
POST/delete_user/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


CreateInvitation API

Basic info

With CreateInvitation-API you can send an invitation to the user to attach itself under your account. This API becomes relevant if you tried to create a new user with CreateUser -API, but the API returned an error stating that the user already existed. We cannot attach existing users to you unless they give their consent.

To use this API, you must have a specific host-account. If you need one, contact us via email or phone. Contact details can be found from www.shipfunk.com.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_invitation when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
user User element. Includes other elements. Required if the child elements are present! See examples. Element Y
email Email of the new user account. String Y

–Return data:

Only returns an OK -response or error.

Request

POST https://shipfunkservices.com/api/1.2/create_invitation/true/json/json
RequestsxmljsonPHP example
Headers
Location: /create_invitation/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <user>
        <email>example@example.com</email>
    </user>
</query>
Responses200202400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Info>
        <Code>10016</Code>
        <Message>Invitation has already been sent.</Message>
    </Info>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00110</Code>
        <Message>Users not found with email: example@example.com.</Message>
    </Error>
</response>
Headers
Location: /create_invitation/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "user": {
      "email": "example@example.com"
    }
  }
}
Responses200400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Error": {
    "Code": "00110",
    "Message": "Users not found with email: example@example.com."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/create_invitation/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_invitation=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateInvitation query
POST/create_invitation/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


CreateAccount API

Basic info

With CreateAccount-API you can create new user accounts into our service, and attach them under your own account. This API does NOT create the user. You must use the CreateUser API for that, and if the user already exists, create a new account under that user with this API.

To use this API, you must have a specific host-account. If you need one, contact us via email or phone. Contact details can be found from www.shipfunk.com.

For security purposes, we will not send or return the newly created users credentials to you, but they will be sent directly to the given emails.

User created in test mode with test API key, cannot be activated into production! Those users are and always will be just test users. Use your live API key when creating real users!

The eshop will still have his own api keys that he can use if he wants to. If he uses his own api keys, you won’t see the statistics from those orders, and if you are in our partner program, you won’t get any comissions from those orders.

Note that you or the newly created user won’t receive the live api keys unless you provide all the information needed for activation, and you are using your own live api key to call this api! To activate the users account for production, you need to provide the fields described in the “Send data” -section. If the element is required for production, it will be told in the elements description. If you don’t yet have all the necessary information required for activation, you can send that information later in the EditUser -API.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_account when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
user User element. Includes other elements. Required if the child elements are present! See examples. Element Y
email Email of the new user account. String Y
locale Locale of the new user account. Must be in the standard two letter ISO 639-1 -format. See Common information->Languages. Defaults to fi. String N
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y/N
business_id Business id of the new eshop. Required when activating the given email to production! String Y/N
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String N
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y/N
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String N
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String N
display_name This will be the account name that the user can see in our Extranet. It is recommended to name the new account so that the user instantly knows what this account is about. String N

–Return data:

Field Description Dataformat Required (Y or N)
user User element. Contains other elements. See examples. Element Y
email The email you gave to us. String Y
locale Locale of the new user account. Is in the standard two letter ISO 639-1 -format. See Common information->Languages. String Y
enabled If the new user has not yet clicked the link in the email, or the user is temporarily suspended (for unpaid bills for example), this value will be false. Boolean/Int Y
account_id Shipfunk defined if of the newly created account. You'll need this with the other onboarding APIs. String Y
eshop_name Name of the new eshop. This name will go into the emails we send to the customers(end users) and will be shown to customers if there are store pickups defined. Required when activating the given email to production! String Y
display_name This will be the account name that the user can see in our Extranet. It is recommended to name the new account so that the user instantly knows what this account is about. String Y
business_id Business id of the new eshop. Required when activating the given email to production! String Y
customs_id Customs id of the new eshop. This is needed when shipping goods outside of origin country. String Y
contact_person_name Eshops contact persons name. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_phone Eshops contact persons phone number. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
contact_person_email Eshops contact persons email. This is needed by the transport companies. If there is something wrong with the deliveries, parcels etc. the transport companies will contact this person. Required when activating the given email to production! String Y
web_address Eshops web address. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. String Y
contract_currency Eshops contract currency. Cannot be changed via API or Extranet. Contact Shipfunk if you must change this. String Y
activated Is the user activated or not. If we have gotten all the user data required for activation, user gets activated for production automatically. Boolean/Int Y
customer_contact_info Eshops customer contact info. E.g. email, phone numbers, web site, etc., where the customer can contact the store. This will be added to the emails we might send to the shops customers concerning the delivery, i.e. the tracking codes etc. Can contain html -marking, but if you use xml to send the data, put this field in a CDATA element. String Y
api_key_test Api key for testing. String Y
api_key_live Api key for production. Note that you won't receive this if you called this api with your own testing api key, or you didn't provide all the required information. String Y

Request

POST https://shipfunkservices.com/api/1.2/create_account/true/json/json
RequestsxmljsonPHP example
Headers
Location: /create_account/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <user>
        <email>example@example.com</email>
        <eshop_name>Example Store</eshop_name>
        <locale>en</locale>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <web_address>real_deal.example.com</web_address>
        <customer_contact_info><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contact_info>
        <display_name>Partner X connected account</display_name>
    </user>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <user>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <email>example@example.com</email>
        <eshop_name>Example Store</eshop_name>
        <display_name>Partner X connected account</display_name>
        <locale>en</locale>
        <enabled>0</enabled>
        <account_id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</account_id>
        <business_id>12312345</business_id>
        <customs_id>6543210</customs_id>
        <contact_person_name>Head Honcho</contact_person_name>
        <contact_person_phone>040 1231234</contact_person_phone>
        <contact_person_email>head_honcho@example.com</contact_person_email>
        <customer_contactinfo><![CDATA[<b>Contact us:</b> service@example.com]]></customer_contactinfo>
        <web_address>real_deal.example.com</web_address>
        <contract_currency>EUR</contract_currency>
        <activated>1</activated>
        <api_key_test>sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx</api_key_test>
        <api_key_live>sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx</api_key_live>
    </user>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /create_account/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "user": {
      "email": "example@example.com",
      "locale": "en",
      "eshop_name": "Example Store",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "web_address": "real_deal.example.com",
      "customer_contact_info": "<b>Contact us:</b> service@example.com",
      "display_name": "Partner X connected account"
    }
  }
}
Responses200400
Body
{
  "response": {
    "user": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "email": "example@example.com",
      "locale": "en",
      "enabled": false,
      "account_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "eshop_name": "Example Store",
      "display_name": "Partner X connected account",
      "business_id": "12312345",
      "customs_id": "6543210",
      "contact_person_name": "Head Honcho",
      "contact_person_phone": "040 1231234",
      "contact_person_email": "head_honcho@example.com",
      "customer_contactinfo": "<b>Contact us:</b> service@example.com",
      "web_address": "real_deal.example.com",
      "contract_currency": "EUR",
      "activated": true,
      "api_key_test": "sk_onboarding_test_xxxxxxxxxxxxxxxxxxxxxx",
      "api_key_live": "sk_onboarding_live_xxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/create_account/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_account=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateAccount query
POST/create_account/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


CreateWarehouse API

Basic info

With CreateWarehouse-API you can create a new warehouse. You’ll need warehouses when you want delivery options and package cards. If you don’t have a warehouse defined, we don’t know where you are sending the stuff from, and thus cannot generate any delivery options nor package cards. Note: Warehouse address information will be printed onto package cards.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_warehouse when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
warehouse Warehouse element. Includes other elements. See examples. Element Y
user_defined_id Warehouse id that you can define. Can be used to identify the warehouse in other APIs, and works similarly to the warehouse name below. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
name Name of the warehouse in a human readable form. You can use this to make it easier for you to distinguish warehouses in the Extranet, and within the APIs as well. Note that you can also use this as an identifier in APIs where the warehouse information is needed, like the GetDeliveryOptions. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
country_code ISO 639-1 country code of the warehouse. String Y
street_address Street address of the warehouse. String Y
postal_code Postal code of the warehouse. String Y
city City of the warehouse. String Y
lead_time Lead time element. Includes other elements. See examples. Element Y
min Minimum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
max Maximum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
working_hours Working hours element. Includes other elements. See examples. Element N
(weekday) For every day of the week there is an opening and closing time. This will tell us when the warehouse starts to operate and ends its operations, and we can use this information to calculate shipping times for the customers. If your warehouse is not open for that day, you can omit this element. See the examples. String N
start Warehouse operations start time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N
end Warehouse operations end time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N

–Return data:

Field Description Dataformat Required (Y or N)
warehouse Warehouse element. Includes other elements. See examples. Element Y
id Id of the warehouse. This will be used to identify the warehouse when you call other APIs like EditWarehouse or GetDeliveryOptions. String Y
user_defined_id Warehouse id that you can define. Can be used to identify the warehouse in other APIs, and works similarly to the warehouse name below. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
name Name of the warehouse in a human readable form. You can use this to make it easier for you to distinguish warehouses in the Extranet, and within the APIs as well. Note that you can also use this as an identifier in APIs where the warehouse information is needed, like the GetDeliveryOptions. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String Y
country_code ISO 639-1 country code of the warehouse. String Y
street_address Street address of the warehouse. String Y
postal_code Postal code of the warehouse. String Y
city City of the warehouse. String Y
lead_time Lead time element. Includes other elements. See examples. Element Y
min Minimum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
max Maximum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
working_hours Working hours element. Includes other elements. See examples. Element N
(weekday) For every day of the week there is an opening and closing time. This will tell us when the warehouse starts to operate and ends its operations, and we can use this information to calculate shipping times for the customers. If your warehouse is not open for that day, you can omit this element. See the examples. String N
start Warehouse operations start time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N
end Warehouse operations end time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N

Request

POST https://shipfunkservices.com/api/1.2/create_warehouse/true/json/json
RequestsxmljsonPHP example
Headers
Location: /create_warehouse/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <warehouse>
        <user_defined_id>123456789</user_defined_id>
        <name>TestWareHouse1</name>
        <country_code>FI</country_code>
        <street_address>TestStreet 1</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <lead_time>
            <min>1</min>
            <max>2</max>
        </lead_time>
        <working_hours>
            <monday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </monday>
            <tuesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </tuesday>
            <wednesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </wednesday>
            <thursday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </thursday>
            <friday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </friday>
            <saturday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </saturday>
            <sunday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </sunday>
        </working_hours>
    </warehouse>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <user_defined_id>123456789</user_defined_id>
        <name>TestWareHouse1</name>
        <country_code>FI</country_code>
        <street_address>TestStreet 1</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <lead_time>
            <min>1</min>
            <max>2</max>
        </lead_time>
        <working_hours>
            <monday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </monday>
            <tuesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </tuesday>
            <wednesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </wednesday>
            <thursday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </thursday>
            <friday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </friday>
            <saturday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </saturday>
            <sunday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </sunday>
        </working_hours>
    </warehouse>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Element "country_code" is not valid.</Message>
</Error>
Headers
Location: /create_warehouse/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "warehouse": {
      "user_defined_id": "123456789",
      "name": "TestWareHouse1",
      "country_code": "FI",
      "street_address": "TestStreet 1",
      "postal_code": "70100",
      "city": "Kuopio",
      "lead_time": {
        "min": "0",
        "max": "2"
      },
      "working_hours": {
        "monday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "tuesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "wednesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "thursday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "friday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "saturday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "sunday": {
          "start": "08:00:00",
          "end": "16:00:00"
        }
      }
    }
  }
}
Responses200400
Body
{
  "response": {
    "warehouse": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_defined_id": "123456789",
      "name": "TestWareHouse1",
      "country_code": "FI",
      "street_address": "TestStreet 1",
      "postal_code": "70100",
      "city": "Kuopio",
      "lead_time": {
        "min": "0",
        "max": "2"
      },
      "working_hours": {
        "monday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "tuesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "wednesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "thursday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "friday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "saturday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "sunday": {
          "start": "08:00:00",
          "end": "16:00:00"
        }
      }
    }
  }
}
Body
{
    "Error": {
        "Code": "00422",
        "Message": "Element "country_code" is not valid."
    }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/create_warehouse/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_warehouse=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateWarehouse query
POST/create_warehouse/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


GetWarehouse API

Basic info

With GetWarehouse-API you can fetch a warehouse created earlier. If you leave out the warehouse id, the API will return all your warehouses.

You must use request type “rest” if you leave out the id and the form data!

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_get_warehouse when sending the data. Service doesn’t accept any other variable name. If you want all the warehouses, you can omit the form data. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
warehouse Warehouse element. Includes other elements. See examples. Element N
id Id of the warehouse. This will be used to identify the warehouse when you call other APIs like EditWarehouse or GetDeliveryOptions. String N

–Return data:

Field Description Dataformat Required (Y or N)
warehouse/warehouses Warehouse element. Includes other elements. If you omitted the warehouse id and return type is json, this element will be named "warehouses". See examples. Element Y
id Id of the warehouse. This will be used to identify the warehouse when you call other APIs like EditWarehouse or GetDeliveryOptions. String Y
user_defined_id Warehouse id that you can define. Can be used to identify the warehouse in other APIs, and works similarly to the warehouse name below. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
name Name of the warehouse in a human readable form. You can use this to make it easier for you to distinguish warehouses in the Extranet, and within the APIs as well. Note that you can also use this as an identifier in APIs where the warehouse information is needed, like the GetDeliveryOptions. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String Y
country_code ISO 639-1 country code of the warehouse. String Y
street_address Street address of the warehouse. String Y
postal_code Postal code of the warehouse. String Y
city City of the warehouse. String Y
lead_time Lead time element. Includes other elements. See examples. Element Y
min Minimum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
max Maximum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
working_hours Working hours element. Includes other elements. See examples. Element N
(weekday) For every day of the week there is an opening and closing time. This will tell us when the warehouse starts to operate and ends its operations, and we can use this information to calculate shipping times for the customers. If your warehouse is not open for that day, you can omit this element. See the examples. String N
start Warehouse operations start time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N
end Warehouse operations end time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N

Request

POST https://shipfunkservices.com/api/1.2/get_warehouse/true/json/json
Requestsxmljsonrest/jsonrest/xmlPHP example
Headers
Location: /get_warehouse/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
    </warehouse>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <user_defined_id>123456789</user_defined_id>
        <name>TestWareHouse1</name>
        <country_code>FI</country_code>
        <street_address>TestStreet 1</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <lead_time>
            <min>1</min>
            <max>2</max>
        </lead_time>
        <working_hours>
            <monday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </monday>
            <tuesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </tuesday>
            <wednesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </wednesday>
            <thursday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </thursday>
            <friday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </friday>
            <saturday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </saturday>
            <sunday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </sunday>
        </working_hours>
    </warehouse>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Element "id" is not valid.</Message>
</Error>
Headers
Location: /get_warehouse/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "warehouse": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Responses200400
Body
{
  "response": {
    "warehouse": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_defined_id": "123456789",
      "name": "TestWareHouse1",
      "country_code": "FI",
      "street_address": "TestStreet 1",
      "postal_code": "70100",
      "city": "Kuopio",
      "lead_time": {
        "min": "0",
        "max": "2"
      },
      "working_hours": {
        "monday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "tuesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "wednesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "thursday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "friday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "saturday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "sunday": {
          "start": "08:00:00",
          "end": "16:00:00"
        }
      }
    }
  }
}
Body
{
    "Error": {
        "Code": "00422",
        "Message": "Element "country_code" is not valid."
    }
}
Headers
Location: /get_warehouse/true/rest/json
Authorization: my_apikey
Body
(no body)
Responses200400
Body
{
  "response": {
    "warehouses": [
      {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "user_defined_id": "123456789",
        "name": "TestWareHouse1",
        "country_code": "FI",
        "street_address": "TestStreet 1",
        "postal_code": "70100",
        "city": "Kuopio",
        "lead_time": {
          "min": "1",
          "max": "2"
        },
        "working_hours": {
          "monday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "tuesday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "wednesday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "thursday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "friday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "saturday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "sunday": {
            "start": "08:00:00",
            "end": "16:00:00"
          }
        }
      },
      {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "user_defined_id": null,
        "name": "TestWareHouse2",
        "country_code": "FI",
        "street_address": "TestStreet 1",
        "postal_code": "70100",
        "city": "Kuopio",
        "lead_time": {
          "min": "0",
          "max": "2"
        },
        "working_hours": {
          "monday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "tuesday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "wednesday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "thursday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "friday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "saturday": {
            "start": "08:00:00",
            "end": "16:00:00"
          },
          "sunday": {
            "start": "08:00:00",
            "end": "16:00:00"
          }
        }
      }
    ]
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "Some internal error happened."
  }
}
Headers
Location: /get_warehouse/true/rest/xml
Authorization: my_apikey
Body
(no body)
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <user_defined_id>123456789</user_defined_id>
        <name>TestWareHouse1</name>
        <country_code>FI</country_code>
        <street_address>TestStreet 1</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <lead_time>
            <min>1</min>
            <max>2</max>
        </lead_time>
        <working_hours>
            <monday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </monday>
            <tuesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </tuesday>
            <wednesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </wednesday>
            <thursday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </thursday>
            <friday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </friday>
            <saturday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </saturday>
            <sunday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </sunday>
        </working_hours>
    </warehouse>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <user_defined_id />
        <name>TestWareHouse2</name>
        <country_code>FI</country_code>
        <street_address>TestStreet 1</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <lead_time>
            <min>0</min>
            <max>2</max>
        </lead_time>
        <working_hours>
            <monday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </monday>
            <tuesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </tuesday>
            <wednesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </wednesday>
            <thursday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </thursday>
            <friday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </friday>
            <saturday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </saturday>
            <sunday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </sunday>
        </working_hours>
    </warehouse>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/get_warehouse/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_warehouse=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetWarehouse query
POST/get_warehouse/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


EditWarehouse API

Basic info

With EditWarehouse-API you can edit an existing warehouse. Give one field and we’ll update it. Give two fields and we’ll update them. Give three… You get the drill.

If you give only the id of a warehouse, we won’t update anything and the API just returns the warehouse resource unchanged.

Warehouse id cannot be changed.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_edit_warehouse when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
warehouse Warehouse element. Includes other elements. See examples. Element Y
id Id of the warehouse. This will be used to identify the warehouse when you call other APIs like EditWarehouse or GetDeliveryOptions. String Y
user_defined_id Warehouse id that you can define. Can be used to identify the warehouse in other APIs, and works similarly to the warehouse name below. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
name Name of the warehouse in a human readable form. You can use this to make it easier for you to distinguish warehouses in the Extranet, and within the APIs as well. Note that you can also use this as an identifier in APIs where the warehouse information is needed, like the GetDeliveryOptions. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
country_code ISO 639-1 country code of the warehouse. String N
street_address Street address of the warehouse. String N
postal_code Postal code of the warehouse. String N
city City of the warehouse. String N
lead_time Lead time element. Includes other elements. See examples. Element Y
min Minimum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
max Maximum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
working_hours Working hours element. Includes other elements. See examples. Element N
(weekday) For every day of the week there is an opening and closing time. This will tell us when the warehouse starts to operate and ends its operations, and we can use this information to calculate shipping times for the customers. If your warehouse is not open for that day, you can omit this element. See the examples. String N
start Warehouse operations start time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N
end Warehouse operations end time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N

–Return data:

Field Description Dataformat Required (Y or N)
warehouse Warehouse element. Includes other elements. See examples. Element Y
id Id of the warehouse. This will be used to identify the warehouse when you call other APIs like EditWarehouse or GetDeliveryOptions. String Y
user_defined_id Warehouse id that you can define. Can be used to identify the warehouse in other APIs, and works similarly to the warehouse name below. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String N
name Name of the warehouse in a human readable form. You can use this to make it easier for you to distinguish warehouses in the Extranet, and within the APIs as well. Note that you can also use this as an identifier in APIs where the warehouse information is needed, like the GetDeliveryOptions. Alphanumeric and these characters are allowed: '-', '_', '.', ' ' String Y
country_code ISO 639-1 country code of the warehouse. String Y
street_address Street address of the warehouse. String Y
postal_code Postal code of the warehouse. String Y
city City of the warehouse. String Y
lead_time Lead time element. Includes other elements. See examples. Element Y
min Minimum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
max Maximum leadtime of the warehouse. How long does it take your warehouse to get the packages ready to be shipped? In hours. Int N
working_hours Working hours element. Includes other elements. See examples. Element N
(weekday) For every day of the week there is an opening and closing time. This will tell us when the warehouse starts to operate and ends its operations, and we can use this information to calculate shipping times for the customers. If your warehouse is not open for that day, you can omit this element. See the examples. String N
start Warehouse operations start time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N
end Warehouse operations end time. Format is "H:i:s" (00:00:00) as a string. 24 hour format is used. String N

Request

POST https://shipfunkservices.com/api/1.2/edit_warehouse/true/json/json
RequestsxmljsonPHP example
Headers
Location: /edit_warehouse/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <user_defined_id>987654321</user_defined_id>
        <name>New-name-for-warehouse1</name>
    </warehouse>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <user_defined_id>987654321</user_defined_id>
        <name>New-name-for-warehouse1</name>
        <country_code>FI</country_code>
        <street_address>TestStreet 1</street_address>
        <postal_code>70100</postal_code>
        <city>Kuopio</city>
        <lead_time>
            <min>1</min>
            <max>2</max>
        </lead_time>
        <working_hours>
            <monday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </monday>
            <tuesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </tuesday>
            <wednesday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </wednesday>
            <thursday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </thursday>
            <friday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </friday>
            <saturday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </saturday>
            <sunday>
                <start>08:00:00</start>
                <end>16:00:00</end>
            </sunday>
        </working_hours>
    </warehouse>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Element "name" is not valid.</Message>
</Error>
Headers
Location: /edit_warehouse/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "warehouse": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_defined_id": "987654321",
      "name": "New-name-for-warehouse1"
    }
  }
}
Responses200400
Body
{
  "response": {
    "warehouse": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_defined_id": "987654321",
      "name": "New-name-for-warehouse1",
      "country_code": "FI",
      "street_address": "TestStreet 1",
      "postal_code": "70100",
      "city": "Kuopio",
      "lead_time": {
        "min": "0",
        "max": "2"
      },
      "working_hours": {
        "monday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "tuesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "wednesday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "thursday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "friday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "saturday": {
          "start": "08:00:00",
          "end": "16:00:00"
        },
        "sunday": {
          "start": "08:00:00",
          "end": "16:00:00"
        }
      }
    }
  }
}
Body
{
    "Error": {
        "Code": "00422",
        "Message": "Element "name" is not valid."
    }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/edit_warehouse/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_edit_warehouse=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

EditWarehouse query
POST/edit_warehouse/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


DeleteWarehouse API

Basic info

With DeleteWarehouse-API you can remove an existing warehouse.

This operation cannot be undone! Deleted warehouses stay deleted, and cannot be recovered in any way!

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_delete_warehouse when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
warehouse Warehouse element. Includes other elements. See examples. Element Y
id Id of the warehouse. This will be used to identify the warehouse when you call other APIs like EditWarehouse or GetDeliveryOptions. String Y

–Return data:

Only returns an error or “OK” -response.

Request

POST https://shipfunkservices.com/api/1.2/delete_warehouse/true/json/json
RequestsxmljsonPHP example
Headers
Location: /delete_warehouse/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <warehouse>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
    </warehouse>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Element "id" is not valid.</Message>
</Error>
Headers
Location: /delete_warehouse/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "warehouse": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Responses200400
Body
{
  "Response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
    "Error": {
        "Code": "00422",
        "Message": "Element "id" is not valid."
    }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/delete_warehouse/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_delete_warehouse=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

DeleteWarehouse query
POST/delete_warehouse/{real_http_code}/{request_type}/{return_type}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json


SetTrackingCode API

Basic info

With SetTrackingCode-API you can give the order some new tracking codes to be tracked.

The tracking codes must be for the shipping company that the order has! If you provide codes for GLS and the selected company is Posti, tracking will fail.

For each of the new code-pairs a new parcel will be created into the order.

Codes are provided as a send-return -pairs. If we already have one of those codes in our db, both of the given codes will be discarded. I.e. You give us: send=code1, return=code2, and we already have the code1 in our db, the code2 will be discarded as well.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_set_tracking_code when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
tracking_codes Tracking codes element. Includes other elements. Note that this differs a little from xml to json. See examples. Element Y
send Tracking code for sending. String Y
return Tracking code for returning. String N

–Return data:

This api will return only an error or info response. See examples for more details.

Request

POST https://shipfunkservices.com/api/1.2/set_tracking_code/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /set_tracking_code/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <tracking_codes>
        <send>JJFIXXXXX999943896642</send>
        <return>JJFIXXXXX999943896643</return>
    </tracking_codes>
    <tracking_codes>
        <send>JJFIXXXXX999943896644</send>
        <return>JJFIXXXXX999943896645</return>
    </tracking_codes>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00404</Code>
        <Message>Required element "tracking_codes" not found.</Message>
    </Error>
</response>
Headers
Location: /set_tracking_code/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "tracking_codes": [
      {
        "send": "JJFIXXXXX999943896642",
        "return": "JJFIXXXXX999943896643"
      },
      {
        "send": "JJFIXXXXX999943896644",
        "return": "JJFIXXXXX999943896645"
      }
    ]
  }
}
Responses200400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
    "Error": {
        "Code": "00404",
        "Message": "Required element "tracking_codes" not found."
    }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/set_tracking_code/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_set_tracking_code=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

SetTrackingCode query
POST/set_tracking_code/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: json xml

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


SetNewOrderId API

Basic info

With SetNewOrderId-API you can change the order id of the order. Process goes like this:

  • GetDeliveryOptions/CreateOrder -> order id = 12345

  • SetNewOrderId -> you call this with the id 12345, and give a new id of: XXYYZZ.

  • CreateNewPackageCards/CreateNewTrackingCodes/etc. -> you can now call other APIs with either id, and they work just like before.

  • Extranet -> You can now find the order with the id XXYYZZ. The id: 12345 is still in the orders metadata, and it can be identified through the APIs, but not in the Extranet.

You can call this API only once with the same order id! The id will be changed to the given one, and if you want to change it again, this API needs to be called with the new id!

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_set_new_order_id when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements!

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Eshops api key. This is given to the eshop by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
order Order element. Includes other elements. Required if the child elements are present! See examples. Element Y/N
new_order_id New id for the order. The order will be identified with this one after this call. String Y

Request

POST https://shipfunkservices.com/api/1.2/set_new_order_id/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /set_new_order_id/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <order>
        <new_order_id>XXYYZZ</new_order_id>
    </order>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00007</Code>
        <Message>Some internal error happened.</Message>
    </Error>
</response>
Headers
Location: /set_new_order_id/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "order": {
      "new_order_id": "XXYYZZ"
    }
  }
}
Responses200400
Body
{
  "response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
  "Error": {
    "Code": "00001",
    "Message": "No data."
  }
}
Body
$real_http_code = 'false';
$query_format = 'json';
$return_format = 'json';
$orderid = 'AB0012345';
$url = 'https://shipfunkservices.com/api/1.2/set_new_order_id/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$orderid;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_set_new_order_id=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

SetNewOrderId query
POST/set_new_order_id/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in. If you don’t send any POST/GET data, set this to “rest”.

Choices: xml json rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


GetOrderStatusEvents API

Basic info

With GetOrderStatusEvents-API you can get all the orders tracking statuses. This differs from the GetTrackingEvents API in these ways:

  • This API must be called with an order id. We fetch all that orders tracking codes and fetch their statuses.

  • This API returns only the recognized events, and not all the shipping companys steps.

  • This API returns more than just the shipping companys’ events. In this API you can get steps before the actual shipment too.

  • This API returns main events as well. You can easily extract the main situation where the order is. These main events are just boolean values, and indicate whether the order has reached a certain point. These main events are: ‘processed’, ‘sent’, ‘delivered’, ‘returned’.

  • If you’re our partner, you can call this api with a non-unique metadata order id, and receive statuses for every order that is found with it. But only for the eshops that are under your account.

Possible status codes and descriptions:

  • CREA => ‘Shipping label created by sender’

  • RECE => ‘Received for delivery / Collected from the sender’

  • NOTI => ‘Notice of arrival sent’

  • DELP => ‘Delivered to pickup point / Ready to be picked by recipient’

  • DELC => ‘Delivered to recipient’

  • RETA => ‘Not collected by recipient’

  • RETD => ‘Returned to sender, parcel damaged’

  • RETU => ‘Returned by recipient’

You can give this API tracking codes as well. These codes must be codes found within the given order. If we cannot find the given codes from the order, the events in the response will be empty. If you don’t want to get the statuses for specific codes, use the request type ‘rest’.

Note that even if the events element is empty, the main events always exist and if the order has reached some of those points, there will be values too. This means that the API will always return the order id and the main events, even if there was no actual events found. Only errors trigger a different response.

This API can return multiple orders and their statuses. When you implement this, remember that the ‘orders’ -element is in fact an array and can return multiple different orders. This can occur if the given order id is some sort of master id for multiple orders. In xml return format each of the orders are within their own ‘orders’ element.

All the events are ordered from newest to oldest.

In the return -codes events, the RECE -status means that the parcel has been received from the customer, and the DELC means that the parcel has been delivered back to the eshop.

IMPORTANT NOTE: The send code might start to return as well! This means that in the send -code, there can be events after it has been delivered to recipient or to pickup point, and these events indicate that the parcel has been returned by the customer or the customer didn’t retrieve the parcel within the given time. In this case, the final DELC -status indicates that the parcel has been received by the eshop again.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_get_order_status_events when sending the data. Service doesn’t accept any other variable name. See examples.

JSONP

You may use ajax jsonp -call if needed.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Hosts api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
tracking_codes Tracking codes element. Includes other elements. Note that this differs a little from xml to json. See examples. Element N
send Tracking code for sending. String N
return Tracking code for returning. String N

–Return data:

Field Description Dataformat Required (Y or N)
orders Orders element. Includes other elements. See examples. Element Y
id Order id that you sent to us. String Y
eshop_public_name Name of the eshop. String Y
placed_time Date time when the order was placed. Format: "Y-m-d H:i:s". String Y
processed One of the main statuses. This one means that at least one package card has been created for this order. Boolean Y
sent One of the main statuses. At least one of the parcels have received at least one tracking event from the shipping company. Boolean Y
delivered One of the main statuses. At least one of the parcels have been delivered to the receiver. Boolean Y
returned One of the main statuses. At least one of the parcels have been returned by the customer. This triggers when we see an indicator of a return tracking event, not when the parcel has reached the eshop again. Boolean Y
shipments Shipments element. Includes other elements. See examples. Element Y
carrier_code Shipfunk defined carrier code for the shipping option. String Y
shipping_company Name of the shipping company. I.e. "DB Schenker" String Y
shipping_option Name of the shipping option. I.e. "Express". Note that we might not have this information. This element will always return, but it might be empty. String Y
code The tracking code. String Y
type Direction of the tracking code. There can be tracking codes meant only for returning shipments, and this tells whether the 'code' is for sending or returning. Values: 'send' or 'return'. String Y
events Events element. Includes other elements. See examples. Element Y
status_code Status defined by our service. See this APIs 'Basic info' for all the possible statuses. String Y
description Human readabe status description for the 'status_code'. See this APIs 'Basic info' for all the possible descriptions. String Y
creator Indicates the origin of this event. This is usually 'Shipping-company' or 'Shipfunk', but it can be something else too. String Y
time Time of the event. Date format is: Y-m-d H:i:s String Y

Request

POST https://shipfunkservices.com/api/1.2/get_order_status_events/true/rest/json/orderid
Requestsxmljsonrest/jsonPHP example
Headers
Location: /get_order_status_events/true/xml/xml/AB0012345
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <tracking_codes>
        <send>JJFIXXXXX999943896642</send>
        <return>JJFIXXXXX999943896643</return>
    </tracking_codes>
    <tracking_codes>
        <send>JJFIXXXXX999943896644</send>
        <return>JJFIXXXXX999943896645</return>
    </tracking_codes>
</query>
Responses200400
Body
<?xml version="1.0"?>
<response>
    <orders>
        <id>AB0012345</id>
        <eshop_public_name>Example Eshop</eshop_public_name>
        <placed_time>2018-08-30 15:12:41</placed_time>
        <processed>1</processed>
        <sent>1</sent>
        <delivered>1</delivered>
        <returned>1</returned>
        <shipments>
            <carrier_code>00000203</carrier_code>
            <shipping_company>Posti</shipping_company>
            <shipping_option>Kotipaketti</shipping_option>
            <code>JJFIXXXXX999943896642</code>
            <type>send</type>
            <events>
                <status_code>DELC</status_code>
                <description>Delivered to recipient</description>
                <creator>Shipping-company</creator>
                <time>2018-09-04 14:56:50</time>
            </events>
            <events>
                <status_code>NOTI</status_code>
                <description>Notice of arrival sent</description>
                <creator>Shipping-company</creator>
                <time>2018-09-04 09:05:38</time>
            </events>
            <events>
                <status_code>NOTI</status_code>
                <description>Notice of arrival sent</description>
                <creator>Shipping-company</creator>
                <time>2018-09-04 09:05:35</time>
            </events>
            <events>
                <status_code>DELP</status_code>
                <description>Delivered to pickup point / Ready to be picked by recipient</description>
                <creator>Shipping-company</creator>
                <time>2018-09-04 09:02:41</time>
            </events>
            <events>
                <status_code>RECE</status_code>
                <description>Received for delivery / Collected from the sender</description>
                <creator>Shipping-company</creator>
                <time>2018-09-03 16:23:11</time>
            </events>
            <events>
                <status_code>CREA</status_code>
                <description>Shipping label created by sender</description>
                <creator>Shipfunk</creator>
                <time>2018-09-03 13:00:58</time>
            </events>
        </shipments>
        <shipments>
            <carrier_code>00000203</carrier_code>
            <shipping_company>Posti</shipping_company>
            <shipping_option>Kotipaketti</shipping_option>
            <code>JJFIXXXXX999943896643</code>
            <type>return</type>
            <events>
                <status_code>DELC</status_code>
                <description>Delivered to recipient</description>
                <creator>Shipping-company</creator>
                <time>2018-09-06 11:19:56</time>
            </events>
            <events>
                <status_code>RECE</status_code>
                <description>Received for delivery / Collected from the sender</description>
                <creator>Shipping-company</creator>
                <time>2018-09-04 16:23:57</time>
            </events>
            <events>
                <status_code>CREA</status_code>
                <description>Shipping label created by sender</description>
                <creator>Shipfunk</creator>
                <time>2018-09-03 13:00:58</time>
            </events>
        </shipments>
    </orders>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Error>
        <Code>00404</Code>
        <Message>No tracking codes found.</Message>
    </Error>
</response>
Headers
Location: /get_order_status_events/true/json/json/AB0012345
Authorization: my_apikey
Body
{
  "query": {
    "tracking_codes": [
      {
        "send": "JJFIXXXXX999943896642",
        "return": "JJFIXXXXX999943896643"
      }
    ]
  }
}
Responses200400
Body
{
  "response": {
    "orders": [
      {
        "id": "AB0012345",
        "eshop_public_name": "Example Eshop",
        "placed_time": "2018-08-30 15:12:41",
        "processed": true,
        "sent": true,
        "delivered": true,
        "returned": true,
        "shipments": [
          {
            "carrier_code": "00000203",
            "shipping_company": "Posti",
            "shipping_option": "Kotipaketti",
            "code": "JJFIXXXXX999943896642",
            "type": "send",
            "events": [
              {
                "status_code": "DELC",
                "description": "Delivered to recipient",
                "creator": "Shipping-company",
                "time": "2018-09-04 14:56:50"
              },
              {
                "status_code": "NOTI",
                "description": "Notice of arrival sent",
                "creator": "Shipping-company",
                "time": "2018-09-04 09:05:38"
              },
              {
                "status_code": "NOTI",
                "description": "Notice of arrival sent",
                "creator": "Shipping-company",
                "time": "2018-09-04 09:05:35"
              },
              {
                "status_code": "DELP",
                "description": "Delivered to pickup point / Ready to be picked by recipient",
                "creator": "Shipping-company",
                "time": "2018-09-04 09:02:41"
              },
              {
                "status_code": "RECE",
                "description": "Received for delivery / Collected from the sender",
                "creator": "Shipping-company",
                "time": "2018-09-03 16:23:11"
              },
              {
                "status_code": "CREA",
                "description": "Shipping label created by sender",
                "creator": "Shipfunk",
                "time": "2018-09-03 13:00:58"
              }
            ]
          },
          {
            "carrier_code": "00000203",
            "shipping_company": "Posti",
            "shipping_option": "Kotipaketti",
            "code": "JJFIXXXXX999943896643",
            "type": "return",
            "events": [
              {
                "status_code": "DELC",
                "description": "Delivered to recipient",
                "creator": "Shipping-company",
                "time": "2018-09-06 11:19:56"
              },
              {
                "status_code": "RECE",
                "description": "Received for delivery / Collected from the sender",
                "creator": "Shipping-company",
                "time": "2018-09-04 16:23:57"
              },
              {
                "status_code": "CREA",
                "description": "Shipping label created by sender",
                "creator": "Shipfunk",
                "time": "2018-09-03 13:00:58"
              }
            ]
          }
        ]
      }
    ]
  }
}
Body
{
  "Error": {
    "Code": "00404",
    "Message": "No tracking codes found."
  }
}
Headers
Location: /get_order_status_events/true/rest/json/AB0012345
Authorization: my_apikey
Body
(no body)
Responses200400
Body
{
  "response": {
    "orders": [
      {
        "id": "AB0012345",
        "eshop_public_name": "Example Eshop",
        "placed_time": "2018-08-30 15:12:41",
        "processed": true,
        "sent": true,
        "delivered": true,
        "returned": true,
        "shipments": [
          {
            "carrier_code": "00000203",
            "shipping_company": "Posti",
            "shipping_option": "Kotipaketti",
            "code": "JJFIXXXXX999943896642",
            "type": "send",
            "events": [
              {
                "status_code": "DELC",
                "description": "Delivered to recipient",
                "creator": "Shipping-company",
                "time": "2018-09-04 14:56:50"
              },
              {
                "status_code": "NOTI",
                "description": "Notice of arrival sent",
                "creator": "Shipping-company",
                "time": "2018-09-04 09:05:38"
              },
              {
                "status_code": "NOTI",
                "description": "Notice of arrival sent",
                "creator": "Shipping-company",
                "time": "2018-09-04 09:05:35"
              },
              {
                "status_code": "DELP",
                "description": "Delivered to pickup point / Ready to be picked by recipient",
                "creator": "Shipping-company",
                "time": "2018-09-04 09:02:41"
              },
              {
                "status_code": "RECE",
                "description": "Received for delivery / Collected from the sender",
                "creator": "Shipping-company",
                "time": "2018-09-03 16:23:11"
              },
              {
                "status_code": "CREA",
                "description": "Shipping label created by sender",
                "creator": "Shipfunk",
                "time": "2018-09-03 13:00:58"
              }
            ]
          },
          {
            "carrier_code": "00000203",
            "shipping_company": "Posti",
            "shipping_option": "Kotipaketti",
            "code": "JJFIXXXXX999943896643",
            "type": "return",
            "events": [
              {
                "status_code": "DELC",
                "description": "Delivered to recipient",
                "creator": "Shipping-company",
                "time": "2018-09-06 11:19:56"
              },
              {
                "status_code": "RECE",
                "description": "Received for delivery / Collected from the sender",
                "creator": "Shipping-company",
                "time": "2018-09-04 16:23:57"
              },
              {
                "status_code": "CREA",
                "description": "Shipping label created by sender",
                "creator": "Shipfunk",
                "time": "2018-09-03 13:00:58"
              }
            ]
          }
        ]
      }
    ]
  }
}
Body
{
  "Error": {
    "Code": "00007",
    "Message": "Some internal error happened."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';
$order_id = 'AB0012345';

$url = 'https://shipfunkservices.com/api/1.2/get_order_status_events/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$order_id;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_get_order_status_events=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetOrderStatusEvents query
POST/get_order_status_events/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: rest

This is the format you are sending the data in.

Choices: json xml rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk system identifies orders by this key.


CreateProduct API

Basic info

With CreateProductAPI you can create a new product into the order. Note that you cannot create products without an existing order.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_create_product when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
product Product element. Includes other elements. See examples. Element Y
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. You can also use this to identify the product in other product APIs like EditProduct. String N
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards API. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String N
category Category of the product. Important notice: Use url_encode() on this field. Otherwise the sending might fail, since the interface is expecting form-data, and some special characters might break the message. String N
weight Weight element. Includes other elements. See examples. Weight cannot be empty! Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Dimensions of the product. This element is not required but it helps us do more precise calculations for package card creation etc. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
name Name of the product. Important notice: Use url_encode() on this field. Otherwise the sending might fail, since the interface is expecting form-data, and some special characters might break the message. String N
value Monetary value of the product. Currency is dictated by the currency of the order. This must be in the smallest unit of the currency. I.e. cents for euros. 400 = 4€. Double N
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Boolean value for JSON format. Int/bool N
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Boolean value for JSON format. Int/bool N
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Boolean value for JSON format. Int/bool N
warehouse_name Name of the warehouse where this product resides. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. String N
quantity Quantity of the same kind of product. Int N

–Return data:

Field Description Dataformat Required (Y or N)
product Product element. Includes other elements. See examples. Element Y
id Id of the product. This will be used to identify the product when you call other APIs like EditProduct. String Y
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. You can also use this to identify the product in other product APIs like EditProduct. String Y
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards API. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String Y
category Category of the product. String Y
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String Y
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Element Y
unit Dictates the used unit for dimensions. String Y
width Width of the item. Double Y
depth Depth of the item. Double Y
height Height of the item. Double Y
name Name of the product. String Y
value Monetary value of the product. Currency is dictated by the currency of the order. This is in the smallest unit of the currency. I.e. cents for euros. 400 = 4€. Double Y
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Boolean value for JSON format. Int/bool Y
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Boolean value for JSON format. Int/bool Y
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Boolean value for JSON format. Int/bool Y
warehouse_name Name of the warehouse where this product resides. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. String Y
quantity Quantity of the same kind of product. Int Y

Request

POST https://shipfunkservices.com/api/1.2/create_product/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /create_product/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <product>
        <external_resource_id>FOO123abc</external_resource_id>
        <code>SKU-1234</code>
        <category>Clothing</category>
        <weight>
            <unit>kg</unit>
            <amount>0.1</amount>
        </weight>
        <dimensions>
            <unit>cm</unit>
            <width>8.9</width>
            <depth>8.9</depth>
            <height>8.9</height>
        </dimensions>
        <name>Socks</name>
        <value>400</value>
        <toppleable>1</toppleable>
        <stackable>1</stackable>
        <nesting>0</nesting>
        <warehouse_name>Test-warehouse-1</warehouse_name>
        <quantity>2</quantity>
    </product>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abc</external_resource_id>
        <code>SKU-1234</code>
        <category>Clothing</category>
        <weight>
            <unit>kg</unit>
            <amount>0.1</amount>
        </weight>
        <dimensions>
            <unit>cm</unit>
            <width>8.9</width>
            <depth>8.9</depth>
            <height>8.9</height>
        </dimensions>
        <name>Socks</name>
        <value>400</value>
        <toppleable>1</toppleable>
        <stackable>1</stackable>
        <nesting>0</nesting>
        <warehouse_name>Test-warehouse-1</warehouse_name>
        <quantity>2</quantity>
    </product>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Weight cannot be empty.</Message>
</Error>
Headers
Location: /create_product/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "product": {
      "external_resource_id": "FOO123abc",
      "code": "SKU-1234",
      "category": "Clothing",
      "weight": {
        "unit": "kg",
        "amount": 0.1
      },
      "dimensions": {
        "unit": "cm",
        "width": 8.9,
        "depth": 8.9,
        "height": 8.9
      },
      "name": "Socks",
      "value": 400,
      "toppleable": true,
      "stackable": true,
      "nesting": false,
      "warehouse_name": "Test-warehouse-1",
      "quantity": 2
    }
  }
}
Responses200400
Body
{
  "response": {
    "product": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "external_resource_id": "FOO123abc",
      "code": "SKU-1234",
      "category": "Clothing",
      "weight": {
        "unit": "kg",
        "amount": 0.1
      },
      "dimensions": {
        "unit": "cm",
        "width": 8.9,
        "depth": 8.9,
        "height": 8.9
      },
      "name": "Socks",
      "value": 400,
      "toppleable": true,
      "stackable": true,
      "nesting": false,
      "warehouse_name": "Test-warehouse-1",
      "quantity": 2
    }
  }
}
Body
{
  "Error": {
    "Code": "00422",
    "Message": "Weight cannot be empty."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';
$order_id = "123456";

$url = 'https://shipfunkservices.com/api/1.2/create_product/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$order_id;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_create_product=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

CreateProduct query
POST/create_product/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk identifies orders by this key.


GetProduct API

Basic info

With GetProductAPI you can fetch products that have been created earlier. You can fetch all the products be leaving out the form data variable name, and setting the query type as “rest”.

You must use request type “rest” if you leave out the id and the form data!

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_get_product when sending the data. Service doesn’t accept any other variable name. If you want all the products, you can omit the form data. See examples.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
product Product element. Includes other elements. See examples. Element Y
id Id of the product. This is optional if you are using the external_resource_id. String Y/N
external_resource_id Resource id in the ecommerce platform, ERP, etc. You can use this as the product identifier, if the product has it. This is optional if you are using the product id. String Y/N

–Return data:

Field Description Dataformat Required (Y or N)
product Product element. Includes other elements. See examples. Element Y
id Id of the product. This will be used to identify the product when you call other APIs like EditProduct. String Y
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. You can also use this to identify the product in other product APIs like EditProduct. String Y
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards API. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String Y
category Category of the product. String Y
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String Y
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Element Y
unit Dictates the used unit for dimensions. String Y
width Width of the item. Double Y
depth Depth of the item. Double Y
height Height of the item. Double Y
name Name of the product. String Y
value Monetary value of the product. Currency is dictated by the currency of the order. This is in the smallest unit of the currency. I.e. cents for euros. 400 = 4€. Double Y
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Boolean value for JSON format. Int/bool Y
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Boolean value for JSON format. Int/bool Y
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Boolean value for JSON format. Int/bool Y
warehouse_name Name of the warehouse where this product resides. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. String Y
quantity Quantity of the same kind of product. Int Y

Request

POST https://shipfunkservices.com/api/1.2/get_product/true/json/json/orderid
Requestsxmljsonrest/jsonrest/xmlPHP example
Headers
Location: /get_product/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abc</external_resource_id>
    </product>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abc</external_resource_id>
        <code>SKU-1234</code>
        <category>Clothing</category>
        <weight>
            <unit>kg</unit>
            <amount>0.1</amount>
        </weight>
        <dimensions>
            <unit>cm</unit>
            <width>8.9</width>
            <depth>8.9</depth>
            <height>8.9</height>
        </dimensions>
        <name>Socks</name>
        <value>400</value>
        <toppleable>1</toppleable>
        <stackable>1</stackable>
        <nesting>0</nesting>
        <warehouse_name>Test-warehouse-1</warehouse_name>
        <quantity>2</quantity>
    </product>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Element "id" is not valid.</Message>
</Error>
Headers
Location: /get_product/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "product": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "external_resource_id": "FOO123abc"
    }
  }
}
Responses200400
Body
{
  "response": {
    "products": [
      {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "external_resource_id": "FOO123abc",
        "code": "SKU-1234",
        "category": "Clothing",
        "weight": {
          "unit": "kg",
          "amount": 0.1
        },
        "dimensions": {
          "unit": "cm",
          "width": 8.9,
          "depth": 8.9,
          "height": 8.9
        },
        "name": "Socks",
        "value": 400,
        "toppleable": true,
        "stackable": true,
        "nesting": false,
        "warehouse_name": "Test-warehouse-1",
        "quantity": 2
      }
    ]
  }
}
Body
{
    "Error": {
        "Code": "00422",
        "Message": "Element "id" is not valid."
    }
}
Headers
Location: /get_product/true/rest/json
Authorization: my_apikey
Body
(no body)
Responses200400
Body
{
  "response": {
    "products": [
      {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "external_resource_id": "FOO123abc",
        "code": "SKU-1234",
        "category": "Clothing",
        "weight": {
          "unit": "kg",
          "amount": 0.1
        },
        "dimensions": {
          "unit": "cm",
          "width": 8.9,
          "depth": 8.9,
          "height": 8.9
        },
        "name": "Socks",
        "value": 400,
        "toppleable": true,
        "stackable": true,
        "nesting": false,
        "warehouse_name": "Test-warehouse-1",
        "quantity": 2
      },
      {
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "external_resource_id": "BAR123def",
        "code": "SKU-5678",
        "category": "Kitchen appliances",
        "weight": {
          "unit": "kg",
          "amount": 1
        },
        "dimensions": {
          "unit": "cm",
          "width": 10,
          "depth": 10,
          "height": 15
        },
        "name": "Coffee maker",
        "value": 4000,
        "toppleable": false,
        "stackable": true,
        "nesting": false,
        "warehouse_name": "Test-warehouse-1",
        "quantity": 1
      }
    ]
  }
}
Body
{
  "Error": {
    "Code": "00404",
    "Message": "No products found."
  }
}
Headers
Location: /get_product/true/rest/xml
Authorization: my_apikey
Body
(no body)
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abc</external_resource_id>
        <code>SKU-1234</code>
        <category>Clothing</category>
        <weight>
            <unit>kg</unit>
            <amount>0.1</amount>
        </weight>
        <dimensions>
            <unit>cm</unit>
            <width>8.9</width>
            <depth>8.9</depth>
            <height>8.9</height>
        </dimensions>
        <name>Socks</name>
        <value>400</value>
        <toppleable>1</toppleable>
        <stackable>1</stackable>
        <nesting>0</nesting>
        <warehouse_name>Test-warehouse-1</warehouse_name>
        <quantity>2</quantity>
    </product>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>BAR123def</external_resource_id>
        <code>SKU-5678</code>
        <category>Kitchen appliances</category>
        <weight>
            <unit>kg</unit>
            <amount>1.0</amount>
        </weight>
        <dimensions>
            <unit>cm</unit>
            <width>10.0</width>
            <depth>10.0</depth>
            <height>15.0</height>
        </dimensions>
        <name>Coffee maker</name>
        <value>4000</value>
        <toppleable>0</toppleable>
        <stackable>1</stackable>
        <nesting>0</nesting>
        <warehouse_name>Test-warehouse-1</warehouse_name>
        <quantity>1</quantity>
    </product>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00404</Code>
    <Message>No products found.</Message>
</Error>
Body
$real_http_code = 'true';
$query_format = 'rest';
$return_format = 'json';
$order_id = "123456";

$url = 'https://shipfunkservices.com/api/1.2/get_product/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$order_id;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

GetProduct query
POST/get_product/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json rest

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk identifies orders by this key.


EditProduct API

Basic info

With EditProductAPI you can edit an existing product. Give one field and we’ll update it. Give two fields and we’ll update them. Give three… You get the drill.

If you give only the id of a product, we won’t update anything and the API just returns the product resource unchanged.

Product id cannot be changed.

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_edit_product when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
product Product element. Includes other elements. See examples. Element Y
id Id of the product. This is optional if you are using the external_resource_id. String Y/N
external_resource_id Resource id in the ecommerce platform, ERP, etc. You can use this as the product identifier, if the product has it. This is optional if you are using the product id. Note that you can change this id if you give the actual product id in this api, along with this one. String Y/N
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards API. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String N
category Category of the product. Important notice: Use url_encode() on this field. Otherwise the sending might fail, since the interface is expecting form-data, and some special characters might break the message. String N
weight Weight element. Includes other elements. See examples. Note that if you provide this field, it cannot be empty, or have an empty value in the "amount"! Element N
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String N
amount The actual weight of the product. For allowed units, see "Get started" -section. Double N
dimensions Dimensions element. Includes other elements. Dimensions of the product. This element is not required but it helps us do more precise calculations for package card creation etc. See examples. Element N
unit Dictates the used unit for dimensions. If not specified, centimeters(cm) will be used. For allowed units, see "Get started" -section. String N
width Width of the item. See the "Units of measures and money" -section. Double N
depth Depth of the item. See the "Units of measures and money" -section. Double N
height Height of the item. See the "Units of measures and money" -section. Double N
name Name of the product. Important notice: Use url_encode() on this field. Otherwise the sending might fail, since the interface is expecting form-data, and some special characters might break the message. String N
value Monetary value of the product. Currency is dictated by the currency of the order. This must be in the smallest unit of the currency. I.e. cents for euros. 400 = 4€. Double N
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Boolean value for JSON format. Int/bool N
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Boolean value for JSON format. Int/bool N
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Boolean value for JSON format. Int/bool N
warehouse_name Name of the warehouse where this product resides. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. String N
quantity Quantity of the same kind of product. Int N

–Return data:

Field Description Dataformat Required (Y or N)
product Product element. Includes other elements. See examples. Element Y
id Id of the product. This will be used to identify the product when you call other APIs like EditProduct. String Y
external_resource_id Resource id in the ecommerce platform, ERP, etc. This is used when we call the store's own APIs to create shipments, orders, etc. You can also use this to identify the product in other product APIs like EditProduct. String Y
code Product code of the product. If you provide this in here, you can use this code in the CreateNewPackageCards API. We will save the product information you give here, and when you want to create the package cards, you don't have to give the full "parcel"-detals, but only the codes given here. String Y
category Category of the product. String Y
weight Weight element. Includes other elements. See examples. Element Y
unit Dictates the used unit for weight. If not specified, kilos(kg) will be used. For allowed units, see "Get started" -section. String Y
amount The actual weight of the product. For allowed units, see "Get started" -section. Double Y
dimensions Dimensions element. Includes other elements. Element Y
unit Dictates the used unit for dimensions. String Y
width Width of the item. Double Y
depth Depth of the item. Double Y
height Height of the item. Double Y
name Name of the product. String Y
value Monetary value of the product. Currency is dictated by the currency of the order. This is in the smallest unit of the currency. I.e. cents for euros. 400 = 4€. Double Y
toppleable Tells if the item can be rotated in any way needed. 1=true, 0=false. Boolean value for JSON format. Int/bool Y
stackable Tells if the item is sturdy enough to be stacked on other items of roughly the same size and weight. This element does NOT indicate that the item is fragile! There is a "fragile" -element for that. Note that this will default to 1! 1=true, 0=false. Boolean value for JSON format. Int/bool Y
nestable Tells if the items of this type can be nested within each other, like buckets. Note that with this the product_codes must match. Different products cannot be stacked. 1=true, 0=false. Boolean value for JSON format. Int/bool Y
warehouse_name Name of the warehouse where this product resides. This warehouse name is the same you have given in the Extranet's settings. Name can be arbitrarily chosen, but must be exactly the same as the one in the settings. String Y
quantity Quantity of the same kind of product. Int Y

Request

POST https://shipfunkservices.com/api/1.2/edit_product/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /edit_product/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abcd</external_resource_id>
        <warehouse_name>Test-warehouse-2</warehouse_name>
        <quantity>1</quantity>
    </product>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abcd</external_resource_id>
        <code>SKU-1234</code>
        <category>Clothing</category>
        <weight>
            <unit>kg</unit>
            <amount>0.1</amount>
        </weight>
        <dimensions>
            <unit>cm</unit>
            <width>8.9</width>
            <depth>8.9</depth>
            <height>8.9</height>
        </dimensions>
        <name>Socks</name>
        <value>400</value>
        <toppleable>1</toppleable>
        <stackable>1</stackable>
        <nesting>0</nesting>
        <warehouse_name>Test-warehouse-2</warehouse_name>
        <quantity>1</quantity>
    </product>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Weight cannot be empty.</Message>
</Error>
Headers
Location: /edit_product/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "product": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "external_resource_id": "FOO123abcd",
      "warehouse_name": "Test-warehouse-2",
      "quantity": 1
    }
  }
}
Responses200400
Body
{
  "response": {
    "product": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "external_resource_id": "FOO123abcd",
      "code": "SKU-1234",
      "category": "Clothing",
      "weight": {
        "unit": "kg",
        "amount": 0.1
      },
      "dimensions": {
        "unit": "cm",
        "width": 8.9,
        "depth": 8.9,
        "height": 8.9
      },
      "name": "Socks",
      "value": 400,
      "toppleable": true,
      "stackable": true,
      "nesting": false,
      "warehouse_name": "Test-warehouse-2",
      "quantity": 1
    }
  }
}
Body
{
  "Error": {
    "Code": "00422",
    "Message": "Weight cannot be empty."
  }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';
$order_id = "123456";

$url = 'https://shipfunkservices.com/api/1.2/edit_product/'.$real_http_code.'/'.$query_format.'/'.$return_format.'/'.$order_id;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_edit_product=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

EditProduct query
POST/edit_product/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk identifies orders by this key.


DeleteProduct API

Basic info

With DeleteProductAPI you can remove an existing product.

This operation cannot be undone! Deleted products stay deleted, and cannot be recovered in any way!

Note that when something is marked to be “Required” in the “Return-data” table, it means that the api will always return the marked element. If it’s not “Required”, returning the element with actual data might depend on the given parameters.

Variable name

You must use the form-data variable name: sf_delete_product when sending the data. Service doesn’t accept any other variable name. See examples.

Data contents and formats

Fields with their name in bold are elements

–Send data:

Field Description Dataformat Required (Y or N)
webshop Webshop element. Includes other elements. If the api_key element exists, this must too. See examples. Element Y/N
api_key Your api key. This is given to the you by Shipfunk. If you're implementing this service to your ecommerce platform, you'll need this key. Contact Shipfunk to obtain it. If you are using jsonp or cannot send HTTP Authorization header, this must be set. Otherwise this is optional. String Y/N
product Product element. Includes other elements. See examples. Element Y
id Id of the product. This is optional if you are using the external_resource_id. String Y/N
external_resource_id Resource id in the ecommerce platform, ERP, etc. You can use this as the product identifier, if the product has it. This is optional if you are using the product id. String Y/N

–Return data:

Only returns an error or “OK” -response.

Request

POST https://shipfunkservices.com/api/1.2/delete_product/true/json/json/orderid
RequestsxmljsonPHP example
Headers
Location: /delete_product/true/xml/xml
Authorization: my_apikey
Body
<?xml version="1.0" encoding="UTF-8"?>
<query>
    <webshop>
        <api_key>my_apikey</api_key>
    </webshop>
    <product>
        <id>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</id>
        <external_resource_id>FOO123abcd</external_resource_id>
    </product>
</query>
Responses200400
Body
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <Code>1</Code>
    <Message>OK</Message>
</response>
Body
<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>00422</Code>
    <Message>Element "id" is not valid.</Message>
</Error>
Headers
Location: /delete_product/true/json/json
Authorization: my_apikey
Body
{
  "query": {
    "webshop": {
      "api_key": "my_apikey"
    },
    "product": {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "external_resource_id": "FOO123abcd"
    }
  }
}
Responses200400
Body
{
  "Response": {
    "Code": "1",
    "Message": "OK"
  }
}
Body
{
    "Error": {
        "Code": "00422",
        "Message": "Element "id" is not valid."
    }
}
Body
$real_http_code = 'true';
$query_format = 'json';
$return_format = 'json';

$url = 'https://shipfunkservices.com/api/1.2/delete_product/'.$real_http_code.'/'.$query_format.'/'.$return_format;
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_HTTPHEADER, ["Authorization: my_apikey"]);
curl_setopt( $ch, CURLOPT_POST, true );  // Tell cURL you want to post something
curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT, 5 ); // Try to connect for 5s before giving up.
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true ); // Return the output in string format
curl_setopt( $ch, CURLOPT_POSTFIELDS, "sf_delete_product=$sendable_str"); // Notice the variable name! It's kinda important.
$curl_result = curl_exec($ch);
Responses200
Body
{see the other Requests for responses}

DeleteProduct query
POST/delete_product/{real_http_code}/{request_type}/{return_type}/{orderid}

URI Parameters
HideShow
real_http_code
string (required) Example: true

If you want us to return the real HTTP-status codes, this must be “true”. Otherwise set it to “false”. Real HTTP-status codes means that if something went wrong in our service, it will return the response as 4XX error etc. and not as 2XX OK -message. If this is set to “false”, every response is a 200OK -response, and you have to check the response data to determine if it was an error or not.

Choices: true false

request_type
string (required) Example: json

This is the format you are sending the data in.

Choices: xml json

return_type
string (required) Example: json

This is the return format you want our response to be.

Choices: xml json

orderid
string (required) 

This is the id given for the order by the eshop. This is very important information, because Shipfunk identifies orders by this key.


Generated by aglio on 28 Oct 2021