Developers - REST API v1

Create Voucher 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.

URL

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.

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 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 template
unit_price_in_cents required Unit price

For value vouchers:
Normally, there is only one value voucher in E-GUMA. You can use the same product Id with different unit prices.

For package vouchers (e.g. Brunch for 2):
Use the same unit price as set in E-GUMA.
quantity required Quantity
If you set delivery to codes, then it is required to set 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 you don't need to pass the message.

Returns

order_id Order Id
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)

Request (POST)
https://api.e-guma.ch/v1/voucher_orders.json?apikey=510e32c594d84816a4af9df1
{
  "customer": {
    "email": "john.doe@e-guma.ch",
    "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"
}
Response
{
  "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"
    }
  ]
}

Kontakt

Idea Creation GmbH
Walchestrasse 15
8006 Zürich
Tel. +41 44 500 54 00
info@e-guma.ch

Support
support@e-guma.ch
TeamViewer herunterladen

Social Media