Bon de Commande Digital TRAXIO – Specs connecteurs API (EN)

Technical contact
[email protected]

Table of contents

1. Table of contents. 1
2. Connection & versioning. 2
3. Security. 2
   3.1       Security mechanism.. 2
   3.2       Token and Account ID.. 2

4. Limitations. 2
5. Flow logic/schema. 2
6. Error handling. 3
7. Operations. 3
   7.1       GetList 3
   7.2       GetCredits. 3
   7.3       GetCheckList 4
   7.4       InsertCar 4
   7.5       UpdateCar 5
   7.6       GetCar 6
   7.7       DeleteCar 6
   7.8       GetAllCars. 7
   7.9       GetAllAvailableCars. 7
   7.10      InsertOrder 8
   7.11      UpdateOrder 8
   7.12      SetOrderToSold. 9
   7.13      GetOpenOrders. 10
   7.14      GetConfirmedOrders. 10
   7.15      GetDeclinedOrders. 11
   7.16      GetOrder 11
   7.17      GetOrderPDF. 12
   7.18      DeleteOrder 12
   7.19      UpdateLogo. 13
   7.20      UpdateComplaintsData. 13

8. Appendix 1: Data objects. 15

2. Connection & versioning

Currently only the test environment is available, the url of this environment is:

https://traxio.yourdailydrive.com/api/v1.aspx

For future changes we will do our best to maintain maximum backward compatibility. For non-breaking changes old version will stay available, however we advise to upgrade as soon as possible to take advantage of new features.

For breaking changes, we will allow for a test period of 3 weeks after notice.

The api uses JSON format to communicate.

3. Security
   
   
   • Security mechanism

This api is protected with security tokens in the HTTP headers. They should be put in the HTTP header Authorization and Traxio-Account-ID, the security token should by in the form of: ‘Authorization: Bearer [TOKEN]’ and Traxio-Account-ID: [ACCOUNT ID]

• Token and Account ID

Your Token and Account ID are linked to your My Traxio account. The token and account ID can be found in the web application under the profile section. The token is a personal token. Unique for each user. The Traxio Account ID is the ID of the company you are working for. This company has to be linked to your user account.

4. Limitations

Only existing users of the My Traxio platform can use the Web application and this API. It is not possible to create new accounts with this API.

The Traxio Digital Order system is based on the use of tokens, each car and order require 1 token. If no more tokens are available in your company’s account you wil not be able to add cars or orders.

The actual purchase of credits is not available via the API. This should always be done using the web application.

Via the API you can also change your company settings that are used in this application. These are the logo and the contact data that should be used in case of complaints. Personal data or company data should be changed using My Traxio. For the logo there is a limitation of 5mb per image file. The logo will be resized to fit the document layout. If possible, use a landscape logo.

5. Flow logic/schema

Below is a visual representation of the components and flow of date in the Traxio Digital Order system.

6. Error handling

All errors will be reported back as HTTP errors with status and sub status codes. Including textual description.

7. Operations
    
   • GetList

This method will return the available reference values for the specified list.

Possible list: Make, Model, Fuel, Color, Kind, ContractDocument, DeliveryDocument and Countries

Only for the list of type Model a parent is required. This should be a value from the Make list.

• Parameters

• Returns

HTTP code 200 with list of Value objects.

• Error codes

• GetCredits

This method will return the current status of credits.

• Parameters

None

• Returns

HTTP code 200 with a credits object containing the Total, Used and Available credits.

• Error codes

• GetCheckList

This method will return the 103 questions and possible answers. Questions will be divided in groups as they are printed on the Order document.

• Parameters

• Returns

HTTP code 200 will return a Checklist object (see appendix 1).

• Error codes

• InsertCar

This method will add a new car to your account. It uses the Car object as an input parameter and will returned the same object with ID and traxio ID filled in. The ID should be stored in the client database because this will be required to create an order.

All fields in the Car object are required except for FirstRegistraion Date. ID and TraxioID are filled in by the API and cannot be set.

A credit will be deducted from the account only when a car is successfully entered in the system and a TraxioID has been assigned.

• Parameters

• Returns

HTTP code 200 with Car object.

• Error codes

• UpdateCar

This method will update a car. It uses the Car object as an input parameter and will returned the same object with ID and traxio ID filled in. The ID, TraxioID and VIN cannot be changed once a car is entered in the system.

All fields in the Car object are required except for FirstRegistraionDate and TraxioID

• Parameters

• Returns

HTTP code 200 with Car object.

• Error codes

• GetCar

This method will return a car object. It uses ID previously returned by the insert method.

• Parameters

• Returns

HTTP code 200 with Car object.

• Error codes

• DeleteCar

This method will remove a car from the linked account. A car can only be removed it is not linked to an existing order. To remove a linked car, please remove the order first using DeleteOrder.

IMPORTANT: removing a car will also remove all referenced data like checklist answers.

• Parameters

• Returns

HTTP code 200 with Boolean value true if successful.

• Error codes

• GetAllCars

This method will return all cars existing in the company account. It is important to know that this method will return all cars wether or not they are linked to an order.

• Parameters

• Returns

HTTP code 200 with a list of Car objects (see appendix 1).

• Error codes

• GetAllAvailableCars

This method will return all available cars existing in the company account. It is important to know that this method will only return cars that are not linked to an existing order.

• Parameters

• Returns

HTTP code 200 with a Boolean value if delete was successful.

• Error codes

• InsertOrder

This method will add a new order to your account. It uses the Oder object as an input parameter and will returned the same object with ID and traxio ID filled in. The ID should be stored in the client database because this will be required to update the order.

An order can only be created using an existing car.

• Parameters

• Returns

HTTP code 200 with Order object.

• Error codes

• UpdateOrder

This method will add a update an existing order all data can be modified except for the ID, traxioID and referenced car.

Updating an order will not deduct a credit..

• Parameters

• Returns

HTTP code 200 with Order object.

• Error codes

• SetOrderToSold

This method will set an existing order to sold or to unsold.

• Parameters

• Returns

HTTP code 200 with a Boolean value indicating the new sold status of the order.

• Error codes

• GetOpenOrders

This method will return open orders. Open orders are orders that have not been accepted nor declined.

• Parameters

• Returns

HTTP code 200 with a list of Order objects (see appendix 1).

• Error codes

• GetConfirmedOrders

This method will return all confirmed orders. Confirmed orders are orders that have been set as accepted using the SetOrderToSold method.

• Parameters

• Returns

HTTP code 200 with a list of Order objects (see appendix 1).

• Error codes

• GetDeclinedOrders

This method will return all declined orders. Declined orders are orders that have been set as declined using the SetOrderToSold method.

• Parameters

• Returns

HTTP code 200 with a list of Order objects (see appendix 1).

• Error codes

• GetOrder

This method will return an individual order.

• Parameters

• Returns

HTTP code 200 with an Order object (see appendix 1).

• Error codes

• GetOrderPDF

This method will return a byte array containing the actual Order PDF

• Parameters

• Returns

HTTP code 200 with a byte array.

• Error codes

• DeleteOrder

This method will remove an order from the linked account. Important to know is that deleting an order will not restore credits.

IMPORTANT: removing an order will also remove all referenced data like car, buyback car, checklist answers.

• Parameters

• Returns

HTTP code 200 with Boolean value true if successful.

• Error codes

• UpdateLogo

This method will update the logo of the linked company account. The image can be a JPG or PNG image file of no more than 5mb. Preferably use a landscape logo with transparent background.

• Parameters

• Returns

HTTP code 200.

• Error codes

• UpdateComplaintsData

This method will update the complaints data of the linked company account. This information will be used in the general conditions printed on the order document.

• Parameters

• Returns

HTTP code 200.

• Error codes

8. Appendix 1: Data objects

    public class Credits

    {

        public int Total { get; set; }

        public int Used { get; set; }

        public int Available { get; set; }

    }

    public class Value

    {

        public int ID { get; set; }

        public string Description { get; set; }

    }

    public class Checklist

    {

        public string Version { get; set; }

 public List<ChecklistGroup> Groups {get;set;}

    }

    public class ChecklistGroup

    {

        public string Code { get; set; }

        public string Name { get; set; }

 public List<ChecklistQuestion> Questions { get; set; }

    }

    public class ChecklistQuestion

    {

        public int ID { get; set; }

 public string Question { get; set; }

 public List<ChecklistAnswerType> PossibleAnswers { get; set; }

    }

    public class ChecklistAnswerType

    {

        public int ID { get; set; }

 public string Answer { get; set; }

 public string Rating { get; set; }

    }

    public class Car

    {

        public int Id { get; set; }

        public string TraxioId { get; set; }

        public string Reference { get; set; }

        public string VIN { get; set; }

        public int MakeId { get; set; }

        public string MakeDescription { get; set; }

        public int ModelId { get; set; }

        public string ModelDescription { get; set; }

        public int KindId { get; set; }

        public string KindDescription { get; set; }

        public int ColorId { get; set; }

        public string ColorDescription { get; set; }

        public int FuelId { get; set; }

        public string FuelDescription { get; set; }

        public int CC { get; set; }

        public int Mileage { get; set; }

        public int PowerKw { get; set; }

        public DateTime? FirstRegistrationDate { get; set; }

        public bool IsVatCar { get; set; }

        public decimal? Price { get; set; }

        public List<int> ContractDocuments { get; set; }

        public List<int> DeliveryDocuments { get; set; }

        public List<CheckListAnswer> ChecklistAnswers { get; set; }

    }

    public class Customer

    {

        public string Company { get; set; }

        public string VATNr { get; set; }

        public string Firstname { get; set; }

        public string Lastname { get; set; }

        public string Phone { get; set; }

        public string Email { get; set; }

        public string Street { get; set; }

        public string Zipcode { get; set; }

        public string City { get; set; }

        public int CountryID { get; set; }

    }

    public class Order

    {

        public int Id { get; set; }

        public int CarId { get; set; }

        public Car Car { get; set; }

        public string TraxioId { get; set; }

        public string InternalReference { get; set; }

        public DateTime? OrderDate { get; set; }

        public bool IsB2B { get; set; }

        public Customer Customer { get; set; }

        public bool HasSalesWarranty { get; set; }

        public bool HasConstructorWarranty { get; set; }

        public string WarrantyDescription { get; set; }

        public bool CheckListRepairsRequired { get; set; }

        public string Remarks { get; set; }

        public BuybackCar BuybackCar { get; set; }

        public DateTime? DeliveryDate { get; set; }

        public bool HasDeliveryExtras { get; set; }

        public string DeliveryExtras { get; set; }

        public bool HasFinancing { get; set; }

        public bool HasInsurance { get; set; }

        public bool HasMaintenanceContract { get; set; }

        public bool IsSoldLocal { get; set; }

        public string ExtraConditions { get; set; }

        public decimal Advance { get; set; }

        public bool? IsSold { get; set; }

    }

    public class BuybackCar

    {

        public string VIN { get; set; }

        public int MakeId { get; set; }

        public string MakeDescription { get; set; }

        public int ModelId { get; set; }

        public string ModelDescription { get; set; }

        public int KindId { get; set; }

        public string KindDescription { get; set; }

        public int ColorId { get; set; }

        public string ColorDescription { get; set; }

        public int FuelId { get; set; }

        public string FuelDescription { get; set; }

        public int CC { get; set; }

        public int Mileage { get; set; }

        public int PowerKw { get; set; }

        public DateTime? FirstRegistrationDate { get; set; }

        public decimal PriceExcl { get; set; }

        public decimal VATAmount { get; set; }

        public decimal PriceIncl { get; set; }

    }

    public class CheckListAnswer {

        public int Question { get; set; }

        public int Answer { get; set; }

    }

    public class ContactData

    {

        public string Firstname { get; set; }

        public string Lastname { get; set; }

        public string Phone { get; set; }

        public string Email { get; set; }

    }