shipfunk_python package

Submodules

shipfunk_python.shipfunk module

Main module.

class shipfunk_python.shipfunk.Shipfunk(apikey, orderid='', language='FI', currency='EUR')

Bases: object

Class for Shipfunk logistics API.

Following packages need to be installed:

• requests

Parameters:

• apikey – API key, string
• orderid – order id, string
• language – default language is FI, in two letter ‘ISO 639-1’-format
• currency – default currency is EUR, with three letters

Return type:

object

add_address(**kwargs)

Method saves customer’s address data. If data is saved then that data is used when getting data from Shipfunk if parameters are not defined in method calls.

Parameters:

• first_name – first name, string, optional
• last_name – last name, string, optional
• street_address – street, string, optional
• postal_code – postal code, string, optional
• city – city, string, optional
• country – country code, string, optional
• postal_box – postal box, string, optional
• company – company, string, optional
• phone – phone, string, optional
• email – email, string, optional

Returns:

None

add_product(productno, weight, amount=1, name='', weightunit='kg', dimensions=None, add_services=None)

Method saves product data. If data is saved then that data is used when getting data from Shipfunk if parameters are not defined in method calls.

Parameters:

• productno – product number, string
• weight – the weight of the product, float
• amount – the amount of the product, default is 1, float
• name – the name of the product, default is product number, string
• weightunit – used weight unit, default is kg, string
• dimensions – dimensions, dictionary - used keys are: unit, width, depth and height
• add_services –

  used additional services, dictionary

  • used keys are:

    • code
    • packing_group
    • quantity
    • quantity_unit
    • shipping_name
    • tunnel_restriction_code
    • un_code
    • warning_label_numbers

Returns:

added product, ShipfunkProduct

apikey

Return api key.

Returns:api key, string

static check_card_direction(direction)

Method to check that card direction is valid value. Value can be ‘send’, ‘return’ or ‘both’.

Parameters:direction – card direction, string Returns:1 if value is valid, boolean

check_currency(currency)

Method checks that currency is a valid currency code. If not then default currency code is used.

Parameters:currency – new currency code, with three letters Returns:currency code, with three letters

check_language(language)

Method checks that language is a valid language code. If not then default language code is used.

Parameters:language – new language code, in two letter ‘ISO 639-1’-format Returns:language code, in two letter ‘ISO 639-1’-format

create_new_package_cards(params)

Method creates the package cards and tracking codes for the order previously given in the methods get_delivery_options and send_selected_delivery.

Parameters:params –

send values for request, dictionary

• order: order information

  • return_cards: if value is 1 then return the tracking codes and package cards in the return message, (optional, default is 0)
  • sendmail: if value is 1: Shipfunk will send an notification email to the customer

  (optional, default is 0)

  • send_edi: if value is 1, the service will send the EDI-message (optional, default is 1)

  • package_card: (optional)

    • direction: direction of the card. Value can be ‘send’, ‘return’ or ‘both’ (optional, default is ‘both’)
    • format: format of the card. Example: “zpl”, “pdf” or “html” (optional, default is ‘pdf’)
    • dpi: Dpi of the package card, only for zpl format
    • size: size of the package card (optional, defaults is ‘A5’ for pdf and html and ‘4x6’ for zpl)
    • reversed: turn the package card upside down for printing, only for zpl-format (optional, default is 0)

  • additional_services: additional services for the order (optional)
  • parcels: you may give all the parcel information in this element or you can give only the product codes for each parcel.

    • for example: product_codes, tracking_codes, warehouse

• customer: customer information (optional)

  • first_name, last_name, street_address, postal_code, city, country, postal_box, company, phone, email

Returns:parcels info if return_cards is 1; otherwise ok message, dictionary

create_new_tracking_codes(params)

Method creates new tracking codes for the parcels. Then you can assign created tracking codes to the parcels with method create_new_package_cards. Shipfunk creates tracking codes also automatically so this method is not necessary to use. It is not recommended to create tracking codes unless you really need them.

Parameters:params –

send values for request, dictionary

• code_amount: amount of the tracking codes (optional, default is 1),
• carriercode: Shipfunk’s id for the transport company and it’s delivery option (optional)

Returns:tracking codes, dictionary

currency

Method returns currency code.

Returns:currency, with three letters

delete_parcels(params)

Method removes the defined parcels from the order. Removing a parcel also removes the package card and the tracking code.

You can remove parcels by giving the parcel codes or the tracking codes of the parcels.

Parameters:params –

send values for request, dictionary

• return_parcels: if value is 1 then all parcels for the order are returned (optional, defauls is 0)
• remove_all_parcels: if value is 1 then all parcels are deleted (optional, default is 0)

• parcels: parcel data

  • id: identifying code of the parcel. Shipfunk generated the id and it can not be edited (optional)
  • parcel_code: identifying code of the parcel generated by you (optional)
  • tracking_code: tracking code for the parcel (optional)

Returns:parcels info if return_parcels is 1; otherwise ok message, dictionary

edit_parcels(params)

Method edits the parcels details.

If you want to empty a field, set value to be “NULL” if the field is a string field, and -1 if the field is a float or integer field.

Parameters:params –

send values for request, dictionary

• return_parcels: if value is 1 then all parcels for the order are returned (optional, defauls is 0)

• parcels: parcel data

  • id: identifying code of the parcel. Shipfunk generated the id and it can not be edited
  • code: identifying code of the parcel. This is the code generated by you. If you use this, it must be unique for the order (optional)
  • contents: contents of the parcel (optional)

  • weight: the weight of the product

    • unit, amount

  • dimensions: dimensions of the product (optional)

    • unit, width, depth, height

  • monetary_value: monetary value of the parcel (optional)
  • warehouse: the warehouse where this product resides (optional)
  • fragile: “Fragile/Handle with care” -additional service, 1 = true, 0 = false (optional)

Returns:parcels info if return_parcels is 1; otherwise ok message, dictionary

endpoint

Return endpoint.

Returns:endpoint, string

get_address_data(keyname)

Method returns data from address dictionary if it is saved to object.

Parameters:keyname –

the key name of the returned data, string - used keys are:

• first_name
• last_name
• street_address
• postal_code
• city
• country
• postal_box
• company
• phone
• email

Returns:one value from address dictionary, string

get_customer_address_data(address_keys, params=None)

Method returns customer’s address data. If params dictionary is defined then try first take data from it. If key is not in the params dictionary then try to get saved value from object.

Parameters:

• address_keys – which customer data fields are wanted to return, dictionary
• params –

  request params, dictionary, optional - used keys are:

  • first_name
  • last_name
  • street_address
  • postal_code
  • city
  • country
  • postal_box
  • company
  • phone
  • email

Returns:

customer data, dictionary

get_delivery_options(params=None)

Method gets and returns the suitable delivery options for the given shopping basket and customer info.

If params are not defined, uses saved data from object.

Parameters:params –

send values for request, dictionary, optional

• order: order information (optional)

  • language: language for the texts in the delivery options (optional, default is FI)

  • monetary: (optional)

    • currency: prices in the order are in this currency, default is EUR
    • value: total value of the order

  • discounts: (optional)

    • type: type of discounts, 0=percentage (default), 1=money
    • all: discount amount for every delivery option
    • home: discount amount for home deliveries only
    • normal: discount amount for normal deliveries only
    • express: discount amount for express deliveries only

  • additions: (optional)

    • delivery_prices, delivery_times, delivery_times_store_pickups, warehouse_leadtime

  • get_pickups: (optional)

    • store, store_only, transport_company

  • tags: (optional)

  • additional_services

    • code, bank_account, bic, monetary_value, reference

  • products
  • parcels

• customer: customer information (optional)

  • first_name, last_name, street_address, postal_code, city, country, postal_box, company, phone, email

• value: total value of the order, float (optional, not needed of order key is defined)

Returns:delivery options, dictionary

get_package_cards(params)

Method gets the created package cards from Shipfunk. This service doesn’t create any cards, but only returns already created cards. You can fetch the package cards using only the order id. Then all the package cards for the order will be returned. If you give the tracking code as a parameter, then only the cards of the defined tracking code will be returned.

Parameters:params –

send values for request, dictionary

• card_direction: direction of the card. Value can be ‘send’, ‘return’ or ‘both’.
• sendmail: value is 1: Shipfunk will send an notification email to the customer (optional, default is 0)
• tracking_code: tracking code associated with the parcel (optional)

Returns:package cards, dictionary

get_parcels()

Method gets all parcels which have been created in Shipfunk the given order.

Returns:parcels data, dictionary

get_pickups(params)

Method gets and returns the pickup points for the chosen delivery company and it’s delivery option. Shipfunk’s API will return 20 nearest pickup points by default, or as much as the transport company can give through their apis.

If all needed params are not defined, uses saved data from object.

Parameters:params –

send values for request, dictionary

• carriercode: Shipfunk’s id for the transport company and its delivery option
• postal_code: customers postal code (optional)
• country: customers country (optional)
• return_count: the amount of the pickup points that Shipfunk returns if possible (default is 20)

Returns:pick up points, dictionary

get_price(params=None)

Method returns the minimum and maximum prices of the delivery, but without the actual delivery options, only prices are returned.

If params are not defined, uses saved products and customers data.

Parameters:params –

send values for request, dictionary, optional

• postal_code: customer’s postal code (optional)
• country: customer’s country (optional)

• products: (optional)

  • weight: the weight of the product

    • amount, unit (default is kg)

  • dimensions: dimensions of the product (optional)

    • unit, width, depth, height

  • warehouse: the warehouse where this product resides (optional)

  • additional_services: used additional services (optional)

    • code, packing_group, quantity, quantity_unit, shipping_name, tunnel_restriction_code, un_code, warning_label_numbers

Returns:min and max prices, dictionary

get_product_data()

Method returns list from saved products

Returns:product data dictionaries, list

get_tracking_codes(params)

Method gets all created tracking codes of the order. The method doesn’t create any tracking codes,

only returns the tracking codes that are already created.

Parameters:params –

send values for request, dictionary

• direction: direction of the card. Value can be ‘send’, ‘return’ or ‘both’

Returns:package cards, dictionary

get_tracking_events(params)

Method gets the tracking events for the given tracking code and transport company.

Parameters:params –

send values for request, dictionary

• tracking_code: tracking code of the parcel
• transport_company: name of the transport company (optional)
• carriercode: carriercode of the transport company’s delivery option (option)

Returns:tracking events, dictionary

static get_urlvariables()

Method returns url variables: /real_http_code/request_type/return_type/

Returns:variables for url, string

language

Method returns language code.

Returns:language, in two letter ‘ISO 639-1’-format

orderid

Return order id.

Returns:order id, string

products

Method returns product objects.

Returns:product objects, list

send_request(apiname, content, call_params='', add_orderid=1)

Method sends request to rest server and returns response.

Parameters:

• apiname – name of the Shipfunk’s API, string
• content – content which is sent to Shipfunk, dictionary
• call_params – params for url if default type is not used, string (optional)
• add_orderid – if 1 then order id is added to url, boolean (optional, default is 1)

Returns:

response from rest server, dictionary

send_selected_delivery(params)

Method sends the selected delivery method to Shipfunk. They need this information in order to create the correct package cards.

Parameters:params –

send values for request, dictionary

• selected_option

  • orderid: order id
  • carriercode: Shipfunk’s id for the transport company and it’s delivery option
  • calculated_price: Shipfunk system’s calculated price of the delivery
  • customer_price: the discounted price of the delivery
  • pickupid: tranport company’s pickup points id (optional if no pickups)
  • return_prices: this will tell the service to return the calculated_price and the customers price as an answer. (optional)

Returns:prices for customer and for shop, if return_prices is 1; otherwise OK message, dictionary

set_customer_details(params)

Method sets and updates the customer details on a order. The customer details can be changed before creating the package card. When updating customer information only updated fields can be sent. If the field is empty or the field doesn’t exists at all in the request, field is not updated on Shipfunk’s system.

Only fields company and PL can be emptied by giving 0 as a value, all other fields are mandatory. If other fields are give a zero or an empty string, those fields will not be updated.

Parameters:params –

send values for request, dictionary

• return_cards: return the updated package cards or not

• customer: customer information

  • first_name
  • last_name
  • street_address
  • postal_code
  • city
  • country
  • postal_box
  • company
  • phone
  • email

Returns:card info if return_cards is 1; otherwise ok message, dictionary

set_order_status(params)

Method sets the orders status. Status can be ‘placed’ or ‘cancelled’. The order status should be set ‘placed’ always when the customer finished the order.

Parameters:params –

send values for request, dictionary

• status: status of the order. Value can be ‘placed’ or ‘cancelled’.
• final_orderid: if you has used temporary order id before the order has been paid, you need to give the real order id

Returns:code 1 and message ‘OK’, dictionary

test_orderid()

Method tests if the orderid is already in use by another of your orders in Shipfunk.

Returns:code and message, is order id already in use, dictionary

class shipfunk_python.shipfunk.ShipfunkProduct(productno, weight, amount=1, weightunit='kg', name='', dimensions=None)

Bases: object

Class for Shipfunk product

Parameters:

• productno – product number, string
• weight – weight, float
• amount – amount, default is 1, float
• weightunit – weight unit, default is kg, string
• name – name of the product, string
• dimensions – dimensions of the product, dictionary - used keys are: unit, width, depth and height

Return type:

object

add_additional_service(values)

Method saves a additional service to object.

Parameters:values –

data of the additional service, dictionary - used keys are:

• code
• packing_group
• quantity
• quantity_unit
• shipping_name
• tunnel_restriction_code
• un_code
• warning_label_numbers

Returns:None

additional_services

Method returns additional services.

Returns:additional services, dictionary

amount

Method returns amount.

Returns:amount, float

check_dimensions(dimensions)

Method checks that dimension values are valid. The value has to be bigger than 0 and a number

Parameters:dimensions –

dimensions, dictionary

• used keys are: unit, width, depth and height

Returns:None

static check_value(value)

Method checks that the value is valid. The value has to be bigger than 0 and a number

Parameters:value – value, type can be any Returns:None

dimensions

Method returns dimensions.

Returns:dimensions, dictionary

• used keys are: unit, width, depth and height

get_data()

Method returns saved data in dictionary.

Returns:saved product data, dictionary

productno

Method returns product number.

Returns:productno, string

warehouse

Method returns warehouse.

Returns:warehouse, string

weight

Method returns weight.

Returns:weight, float

class shipfunk_python.shipfunk.ShipfunkUser(apikey)

Bases: shipfunk_python.shipfunk.Shipfunk

Class for Shipfunk logistics API for handling user accounts.

Parameters:apikey – API key, string Return type:object

create_invitation(params)

Method sends an invitation to the user to attach itself under your account. This method can be used if you tried to create a new user when the user already existed.

Parameters:params –

send values for request, dictionary

• email: email of the user account

Returns:code and message, dictionary

create_user(params)

Method creates new user accounts into Shipfunk under your own account.

Parameters:params –

send values for request, dictionary

• user: user information

  • email: email of the new user account
  • locale: locale of the new user account in two letter ISO 639-1-format (optional, default is fi)
  • eshop_name: name of the shop
  • business_id: business id of the shop
  • customs_id: customs id of the shop (optional)
  • contact_person_name: contact persons name. This is needed by the transport companies
  • contact_person_phone: contact persons phone number. This is needed by the transport companies
  • contact_person_email: contact persons email. This is needed by the transport companies
  • web_address: web address of the shop (optional)
  • customer_contact_info: the customer contact info of the shop. This will be added to the emails which Shipfunk sends to customers concerning the delivery. This can contain html-marking (optional)

Returns:user account data, dictionary

detach_user(params)

Method detaches the user from your account.

Parameters:params – send values for request, dictionary - email: email of the user account Returns:code and message, dictionary

edit_user(params)

Method modifies the existing user.

Parameters:params –

send values for request, dictionary

• user: user information

  • email: email of the new user account
  • locale: locale of the new user account in two letter ISO 639-1-format (optional, default is fi)
  • eshop_name: name of the shop
  • business_id: business id of the shop
  • customs_id: customs id of the shop (optional)
  • contact_person_name: contact persons name. This is needed by the transport companies
  • contact_person_phone: contact persons phone number. This is needed by the transport companies
  • contact_person_email: contact persons email. This is needed by the transport companies
  • web_address: web address of the shop (optional)
  • customer_contact_info: the customer contact info of the shop. This will be added to the emails which Shipfunk sends to customers concerning the delivery. This can contain html-marking (optional)

Returns:user account data, dictionary

static get_urlvariables()

Method returns url variables: /real_http_code/request_type/return_type

Returns:variables for url, string

get_user(params)

Method gets the user that is attached to defined account.

Parameters:params – send values for request, dictionary - email: email of the user account Returns:user account data, dictionary

Module contents

Top-level package for Shipfunk.