0   Read me !

1     Quick reference

This document describes the interface between the SecuTix 360º ticketing system and their customers' accounting systems. These systems are applications that are independent from the ticketing system.

This document provides examples of exported accounting files and explains the customers how to select the data to import into their accounting system.

2       Interface description  

2.1           Solution perimeter  

The accounting interface is a generation system of text files containing accounting data which are exported from SecuTix source data.

The following scheme illustrates the accounting interface principle:

Open

The process stages are:

1.    SecuTix generates exported files from ticketing system (orders, payments, etc...). The exports are scheduled for automatic exportation once a day. This is the solution perimeter.

2.    An accounting import tool, external from SecuTix, downloads these files via HTTPS and updates the data to a format supported by the accounting system (if necessary). This tool is not provided by SecuTix and must be specific for the accounting system and for its current settings for the client.  These items are not included in the SecuTix supplied perimeter.

3.    The accounting import tool submits the reformatted data to the accounting system. These items are not included in the SecuTix supplied perimeter.

SecuTix exports five different file types:

·         Sales file : This file contains the detailed list of all orders created, including the name of the products, for sales and refunds, regardless of the sales channel.

·         Cash flow file : This file lists the payments related to sales and refunds, with an association with the corresponding order lines. The system exports the payments associated with cashdesks with the "accounting closed" state. In order for the sales and cash flow files match, the cashdesks must all have the accounting closed status.

·         Invoices file : This file contains the detailed set of invoices. Each invoice has a record per every operation associated with it.

·         Structures file : This file contains a list of structures (companies, communities, etc.) known to the ticketing system.

·         Individuals file : This file contains a list of individuals known to the ticketing system.

2.2        Export principles  

2.2.1     Submission of detailed data  

The interface provides detailed information for each sales operation. The data provided in the interface is not the result of any aggregation. On the other hand, the interface provides the complete set of data valid for a given file, with no other selection criteria. For example, the interface does not offer to select data for a subset of products.

Under this principle, the client's accounting system has a maximum flexibility for generating the reports or making the desired analysis.

2.2.2     Only a single submission for a given information  

A given record for a given file is only submitted once. In this way, the risk of accounting a sales or payment operation twice is lower minimized .

Therefore, every submitted record contains a technical identifier fully generated by SecuTix that cannot be modified. This identifier may, for example, be related to an operation or a payment. 

Data exported in the files is data not yet sent by a previous successful export until the start time of current export.

2.2.3     Data Identification  

All identifiers, code, etc. mentioned in the interface are SecuTix identifiers. In order to make it easy for an operator to query the data in the interface, the corresponding SecuTix names are attached to the codes.

If needed, a separate adapter will make any necessary conversions using tables of correspondence.

2.2.4     Date processing  

The dates mentioned in the files always represent the calendar dates. For example, an operation dated on July, 25th at 1:30 am will be recorded under July, 25^th, even if it is related to the "evening" of July, 24^th.

2.2.5     Multiple organisations  

If the institution has multiple organisations, there will be a separate file of each type for every organisation.

2.2.6        Currency  

SecuTix supports multiple currencies. Therefore, the ISO code for the currency will be attached to every amount shown.

2.2.7     File format  

The generated files are encoded in UTF-8 without BOM (byte-order mark) format.

Data are tab-separated. The size of fields is not fixed and those that are not filled in must be left blank.

The line break character is \n.

The file contains a header line that only specifies the version number.

No column names are used.

2.2.8     File structure  

The order of the records in the file is important, especially for files containing different types of records. In such case, the “daughter” line always refers to the previous “mother” line.

Example: If a composite product is sold, the records of the sales file describing the content of the sold product will appear directly after the record describing the composite product itself.

2.2.9     Accounting codes  

With a view to allowing the accounting system to record a sale operation (or other) under the adequate account, accounting codes can be configured in the interface for the following entities:

§   Structure and type of structure

§   Simple charge

§   General/Delivery charges

§   Product family

§   Product

§   Performance

§   Method of payment

If no accounting code has been configured for a simple charge, a general or delivery charge, an item which different from simple items, or a method of payment, no accounting code will be specified in the accounting files for this entity.

If no account code has been set for a

If no account code has been set for a performance, the interface will provide the accounting code of the product (i.e., of the event) that this performance belongs to.

An "accounting code required" setting defines the interface behaviour in case no applicable accounting code could be found. If this parameter value is "false", the lack of an accounting code is not considered to be an error. If the value of this parameter is "true", an ERROR is recorded in the interface log (interface_log_line) and the affected entity is not considered as processed. Therefore, an operator will be able to add the missing accounting code and the entity in question will be exported correctly during the next accounting export operation.

Note: certain analytic compatibilities use several accounting lines, so to satisfy this need, we recommend taking several numbers, always from the same order (accounting line 1, accounting line 2...) separated by commas, in the field of the correspondence interface. Then, the accounting system importing the file will be able to easily parse this field and manage the lines as desired.

4       File access  

4.1        Access from the application  

The generated files can be downloaded manually from the result screen of a run (by using a filter criterion to quickly access it; for example: interface type = accounting) by clicking on the link provided in one of the first INFO lines.

Generated files are kept on SecuTix servers for at least 90 days.

4.2        Direct access from a URL address  

In order to access the accounting files created by SecuTix, the accounting import tool has to retrieve the files generated daily from the addresses below.

From the PRODUCTION environment, the access addresses are as follows:

·         Sales file :

o   https://instit.pos.secutix.com/tnai/FileReader?file_name= Ventes(_VER)_ YYYYMMDD (_S).txt

·         Cash flow file :

o   https://instit.pos.secutix.com/tnai/FileReader?file_name= Encaissements(_VER)_YYYYMMDD-(_S).txt

·         Invoices file :

o   https://instit.pos.secutix.com/tnai/FileReader?file_name=Factures(_VER)_YYYYMMDD(_S).txt

·         Individuals file :

o   https://instit.pos.secutix.com/tnai/FileReader?file_name=Individuels(_VER)_YYYYMMDD(_S).txt

·         Structures file:  

o   https://instit.pos.secutix.com/tnai/FileReader?file_name=Structures(_VER)_YYYYMMDD(_S).txt

Where:

·         instit is the institution code

·         YYYY is the year

·         MM is the month with 2 digits

·         DD is the day of month with 2 digits

·         The version (_VER) is optional (parenthesis must not be included in the URL). It indicates the format version of the exported file. V3_2 for the current status of the documentation.

·         S is a sequence number. This number is incremented at each new export of a given file at a given date. The first file of the day gets no sequence number, only the next ones get one, starting from 1.

Examples (e xports from 16/08/2013)

https://nihon.pos.secutix.com:80/tnai/FileReader?file_name=Individuels_20130816.txt  

https://nihon.pos.secutix.com:80/tnai/FileReader?file_name=Structures_20130816.txt  

https://nihon.pos.secutix.com:80/tnai/FileReader?file_name=Factures_20130816.txt  

https://nihon.pos.secutix.com:80/tnai/FileReader?file_name=Ventes_20130816.txt  

https://nihon.pos.secutix.com:80/tnai/FileReader?file_name=Encaissements_20130816.txt  

These access URL addresses need a SecuTix operator (either real or virtual) user name / password; the operator must have READ access to the "Contexte organisme > Module Outils > Ecran Exécutions" (Organisation context > Tools module > Runs screen).

The user name to be entered is the concatenation of the institution code and the operator user name: INSTIT#USER_LOGIN.

4.3        Direct access to the files  

Files may be delivered to a system not managed by SecuTix :

• plain FTP: this is not recommended because transfer is not secured!
   

• SFTP with login and password: configure url= sftp://hostname:22?proxyPort=NO&ftpDir=XX&otherParam=value, then Connection = yourLogin and password = yourPassword.

• SFTP with certificate: configure url= sftp://hostname:22?proxyPort=NO&ftpDir=XX&otherParam=value, then Connection = PUBLIC_KEY_AUTH/yourLogin and password = the certificate in openSSH format (=starts by -----BEGIN DSA PRIVATE KEY----- ....)

• AWS S3: configure url = s3://bucketName/region?ftpDir=XXX then Connection = AWSaccessKeyId and password = AWSsecretAccessKey

• HTTP POST with basic auth: configure url = https://hostname/path?param1=value then Connection = yourLogin and password= yourPassword

5       Exported file contents  

5.1        Sales file  

This file contains the set of information about completed sales.

If the accounting service so wishes, it allows you to edit the global recipe of all products, including composite products like season tickets and packages.

This file contains a record per order line (operation).

In the case of composite products (packages and season tickets), there is a record for the composite product itself and a record for each item that it comprises.

Each record concerning an item in a composite product will mention the composite product it refers to.

5.1.1     Record selection  

The exported order lines satisfy the following conditions:

§   They have not yet been sent after a previous submission of the sales file.

§   They refer to closed orders.

§   They refer to orders associated with the current organisation [1] .

§   They refer to a product within a sale or refund (requested by the client or by the organisation) [2]

§   The order line does not represent a commission. The sales file mentions the commission amounts for each operation it benefits from. Therefore, the accounting system may recalculate the commission for a given contract and order.

For the composite products, the sales file provides the lines matching the composite product itself as well as the lines matching the content of the composite product.

5.1.2        Product validity period  

The following table mentions the

SecuTix handles 3 types of passes:

·         Non dated passes are valid during a period of time. This period may correspond to the season in which they are defined, to a period freely defined in the product catalogue or to a number of days starting from the purchase date.

·         Dated pass are usually valid for a specific date chosen at the time of purchase. In that case, the validity start date and end date will be the same. However, they may be valid for several consecutive days.

·         Timeslot pass are valid during a timeslot chosen at the time of purchase. The timeslot is defined by a start date and time and a duration.

5.1.3        File structure  

The generated file name is:

·       Ventes_YYYYMMDD_S.txt

The file structure is as defined in the following tables:

·         1 line per operation