Create Order

This endpoint can be useful when you want to issue gift vouchers in your e-commerce shop. Please read this documentation for more information.

POST https://api.e-guma.ch/v1/voucher_orders.json?apikey={api-key}

Parameters


api-key `required`

POST Data


customer	Customer, see customer object below for details. If you omit the customer, then a default customer (passer-by) will be set.
order_lines `required`	List of order lines, see order line object below for details
delivery `required`	Provide one of those values pdf\|codes\|mailing
language `required`	Language as a two-letter code (ISO 639-1). The pdf with the vouchers will be generated in the provided language. e-guma supports German, French, Italian, English, Spanish and Portuguese. However it is up to each client, which languages are used.
payment_id	Optionally, you can pass a payment ID. If this value is empty then a default payment will be used.
note	Optionally, you can add a note that will be displayed in the e-guma Backoffice.

Customer object


email `required`	Email address
title `required`	Provide one of those two values Mr\|Mrs
first_name `required`	First name
last_name `required`	Last name
company `required`	Company name
street `required`	Street
zip `required`	Zip code
city `required`	City
country `required`	Country as two-letter code (ISO 3166-1 alpha-2)
phone `required`	Phone number

Order line object


product_id `required`	ID of the voucher type. Only voucher types of type value_voucher, package or variants can be used. See here for more information on the different types.
unit_price_in_cents `required`	Depending on the type, the correct amount must be specified. value_voucher You can set any amount. package Use the same price as set in e-guma, otherwise the API will return an error. You can get the price from the List of Voucher Types API. variants Use the same price as set in e-guma, otherwise the API will return an error. You can use price_in_cents from the variant object.
variant_id	Only required for voucher types of type variants. You can get the ID of a variant from the List of Voucher Types API
quantity `required`	Quantity If you set delivery to codes, then it is required to set the quantity to 1.
message	Personal message for the receiver of the voucher. The message will be printed on the voucher. If you set delivery to codes, then this field is not relevant.
receiver	The name of the person for whom the voucher is intended can be provided. The name will be printed on the voucher. If you set delivery to codes, then this field is not relevant.
giver	The name of the person giving the voucher can be provided. The message will be printed on the voucher. If you set delivery to codes, then this field is not relevant.

Return


order_id	ID of the Order Store it for further actions (e.g deleting the order)
order_number	Order number
pdf_url	Url of the pdf which contains the vouchers. For pdf You can provide this url in the confirmation e-mail. For mailing (printing) You can provide this url at the order details so it can easily get printed and shipped. For mailing (using depot vouchers) This value will be empty. For codes This value will be empty.
vouchers	If delivery is set to codes, then a list of vouchers will be returned. Each voucher has the following properties: - code (e.g. QXKR2VRHPEG7): you can use this value for the barcode or the qr code - code_formatted (e.g. QXKR-2VRH-PEG7): you can use this value to print on the voucher - product_id: the same product_id as you passed in - amount_in_cents: the same amount (unit_price_in_cents) you passed in - expiry_date: After this date, the voucher will expire. The API returns this value in ISO 8601 format. The order of the vouchers is the same as the passed in order_lines.
manage_order_url	Url to open the ordered vouchers in e-guma Backoffice.

Example (delivery set to codes)

POST https://api.e-guma.ch/v1/voucher_orders.json?apikey=510e32c594d84816a4af9df1

{
  "customer": {
    "email": "[email protected]",
    "title": "Mr",
    "first_name": "John",
    "last_name": "Doe",
    "street": "Walchestrasse 15",
    "zip": "8006",
    "city": "Zürich",
    "country": "CH",
    "phone": "+41 44 500 54 00"
  },
  "order_lines": [
    {
      "product_id": "c333c464-8676-4489-ae97-360236d7c999",
      "unit_price_in_cents": 1000,
      "quantity": 1
    },
    {
      "product_id": "c333c464-8676-4489-ae97-360236d7c999",
      "unit_price_in_cents": 5000,
      "quantity": 1
    }
  ],
  "language": "de",
  "delivery": "codes"
}

{
  "order_id": "50b6d149-49c4-4d2d-a96d-59d251de1edb",
  "order_number": "G10015",
  "pdf_url": "",
  "manage_order_url": "http://www.e-guma.ch/Backend/Voucher/Voucher.aspx?search=param&tnr=GI1015&___mId=2",
  "vouchers": [
    {
      "code": "LSFR5D2C5A65",
      "code_formatted": "LSFR-5D2C-5A65",
      "product_id": "c333c464-8676-4489-ae97-360236d7c999",
      "amount_in_cents": 1000,
      "expiry_date": "2019-12-31T00:00:00.0000000"
    },
    {
      "code": "CR7MFKRVH665",
      "code_formatted": "CR7M-FKRV-H665",
      "product_id": "c333c464-8676-4489-ae97-360236d7c999",
      "amount_in_cents": 5000,
      "expiry_date": "2019-12-31T00:00:00.0000000"
    }
  ]
}