Integrate external resellers sales by file

Introduction

S-360 has a BATCH feature which allows you to import sales from another system directly into the S-360 system. Below we specify the file format used to integrate in S-360 sales from external resellers.

Only sales and refunds for single entries (a ticket for an event / for a pass / for a service) are handled.

Duplicates and reprints are also covered.

This interface does not cover integration for reservation nor for options, nor packages, vouchers or season tickets.

Quick reference

API Latest version Examples
Resellers sales file integration 1.4 exemple.csv
exemple.xml
exemple-pass-non-daté.csv

File format

Transmittted files must be encoded in UTF-8 without BOM.

Either in CSV
  • with headers (or without headers : in that case the implicit headers are the list CSV header names listed in the table below)
  • tab as seperator
  • no fixed size filelds
  • EOL Unix style \n
  • Order of the fields does not matter : header position is relevant
  • Empty fields can either left empty (emptry string value), or, if the file is always empty and field is mandatory, the header can be removed (no column containing this field)
Or in XML

(see example attached)
with header : <?xml version="1.0" encoding="UTF-8"?>

Additional Information regarding File format

Process used for GroupOn and Wowcher sales import

There are some important steps to follow when generating this file:

  • The easiest way to generate this file is to start from a working EXCEL file (IMPORT_TEMPLATE_S.xlsx)
  • Populate the data you need
  • And then simply save as "Text (Tab delimited) (*.txt)" in excel.

The resulting .txt file can then be imported into S-360 to generate the sales

There is some other important information for this process:

  • After saving the file as a .txt file, you need to take out the header line. You can do this in Notepad or Notepad++
  • You need to ensure the event is on sale for the sales channel used by the batch
  • You need to ensure there are seats available in the contingent used by the batch
  • You do not need to specify row and seat number. If you specify the area and block, the system will automatically allocate the seats
  • The Seat Category and Tariff (Audience Sub Category) codes need to match what is available in S-360
  • The TaxNumber needs to be unique (no duplicate values)
  • All dates in the file need to be a specific format (As described in the IMPORT TEMPLATE file)
  • The unit price and quantity can never be blank

About the contact fields

If you want to import contacts (using the contact_* fields), you need to have an external_contact_reference. If you don't have one, use anything unique, like the first 20 characters of the email address.

Then, if your contact_email is defined and such an address exists in the contacts of the institution, it will be used, and it will not be modified by the import. It means that the sale is associated to this contact, but the payment contact is still the one defined in the interface.

If no contact is found in the institution to match the provided email address, then a new contact is created, using all the contact_* fields in the import file.

Data description

Each movement (sale or refund or duplicate) can be described by the following values

CSV header name Field name(XML) Type Explanation Mandatory
external_order_id externalOrderId String(20) External order id Yes
product_code productCode String(8) Product code Yes
service_item_code serviceItemCode String(8) Item or service code For services
performance_date performanceDate Date Performance or timeslot date For single entries
logical_seatcategory_code logSeatCategoryCode String(8) Logical seat category code For single entries
audience_sub_category_code audienceSubCatCode String(8) Tariff code Yes
physical_area_code physicalAreaCode String(8) Physical area code For single entries
physical_block_code physicalBlockCode String(8) Physical block code For numbered areas, block, rank or number must be defined in order to identity the seat
seat_row seatRow String(60) Seat rank
seat_number seatNb String(60) Seat number
line_type lineType Enum Line type (SALE, CANCEL, DUPLICATE) Yes
sale_date_time saleDateTime DateTime Sale date Yes
quantity quantity Integer Quantity Yes
unit_price unitAmount String Unit amount Yes
tax_number taxNumber String(20) Ticket tax number Yes
duplicate_tax_number duplicateTaxNumber String(20) Duplicated ticket's tax number For a duplicate
barcode barCode String(128) Ticket barcode Yes
duplicate_barcode duplicateBarCode String(128) Duplicated ticket's barcode For a duplicate
ticket_support ticketSupport Enum Ticket support (THERMAL, ETICKET, MOBILE, RFID) No
external_contact_reference externalContactId String(20) Contact external reference No
beneficiary_firstname beneficiaryFirstname String(100) Beneficiary first name For nominative tickets
beneficiary_lastname beneficiaryLastname String(100) Beneficiary last name For nominative tickets
contact_address_line1 contactFirstAddressLine String Contact address (line 1) No
contact_address_line2 contactSecondAddressLine String (line 2) No
contact_address_line3 contactThirdAddressLine String (line 3) No
contact_zip_code contactAddressZipCode String(20) Zip code No
contact_country_code contactAddressCountryCode String(2) Contact country code No
contact_email contactEmail String(200) Email No
contact_city contactCity String(200) Town No
contact_phone_number contactFixNumber String(200) Fixed number No
contact_mobile_number contactMobileNumber String(200) Mobile number No
contact_type contactType String Contact type : INDIVIDUAL ou STRUCTURE No. Default: INDIVIDUAL
contact_title contactTitle String MR, MRS, MR_AND_MRS, MISS, UNDEFINED No. Default: UNDEFINED
contact_firstname contactFirstName String(100) First name or structure postal name No
contact_lastname contactLastName String(100) Last name or structure official name No
remark Remark String(2000) Remark on order No
container_identifier containerIdentifier String(100) The tag on the ticket (to regroup tickets belonging to the same season ticket, for example) No
season_code seasonCode String(8) The code of the season to which the product is belonging No

Other relevant information:

  • Granularity is ticket, identified by the tax number, making the process idempotent.
  • If the a ticket is presented twice with the same tax number, the second import will be ignored and markes with a warning.
  • Order reference is indicative and will be stored in S-360 as an order remark.
  • Product codes, service codes are supplied by S-360.
  • Dates are in format ISO 8601 with the following format : yyyy-MM-dd HH:mm:ss.
  • Quantity is always 1
  • Amounts must follow the following format : xxx.xx
  • Country codes follow format : ISO 3166-1 alpha-2.
  • File is read line by line. Order of the lines matters.

Integration from SFTP server

S-360 can access files from an SFTP server. That server is not managed by S-360.

S-360 can access the file on a regular basis

File naming:
yyyymmdd_hhmmss_XXXXX.xml or yyyymmdd_hhmmss_XXXXX.csv

S-360 handles the file by alphabetical order.
Once the files have been processed, they are renamed as <name>.processed