HOWTO: Process Orders Using The API

Processing Ticket Evolution Orders via API

Helpful tools

Create a User for Your Order Processor

Creating a separate user allows you to accurately see who has done what in our system. This applies to humans as well, please make sure each employee who needs access to our system has their own user account.

Follow these simple instructions to make a new user.

Establish API Credentials for Your Order Processor

We’ve also got simple instructions for creating API Credentials. If you already have API credentials for your website, please create an additional set just for order processing and label them accordingly.

Use the API to Retrieve a List of Orders With a state of pending and a type of Order

You can retrieve all your orders from the API, but for the purpose of automatically processing orders you want to filter to only ones with a state of pending. Additionally, if the brokerage is using our API for their website you may wish to filter out those orders by also including direct_buyer_type=Office.

 

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: WGiennHhZLefDmeUyAfvamiGkjEK77PXjMyyNxkdVswf' \
-H 'Accept: application/json' \
--url 'https://api.ticketevolution.com/v9/orders?state=pending&type=Order'

The result of that all will be an array of orders, even if there is only one.

You will want to loop through that list of orders processing each one. Each order will also have an array named items (even if there is only one). Each item will be a set of tickets identified by the remote_id which you provided to us in your upload as the unique identifier for that set of tickets, usually in a column named TicketID.

NOTE: Ticket Evolution is unique in that a single order may contain multiple ticket groups. Do not accept the order if you cannot supply every ticket group requested.

Contact customer support if you can only accept a portion of the order.

Because of this you will also need to loop through the items array as well. For each item you need to confirm in your system the following:

  • You can supply the requested quantity for all of the ticket groups
  • The price supplied is acceptable to you
  • If we are expecting you to upload PDF(s) for this item the boolean eticket_delivery property will be true or (1).

A pseudo-code example of what you probably want to do

 

 

Differentiating Order Types

Differentiating based on buyer type

All orders have a buyer object and each buyer object has a property named type which can be used to identify if this is an order from a Ticket Evolution Partner or another broker or from one of your clients such as through your Ticket Evolution API-powered website (one you built using our API, one of our Carbon stores or even an ATBS provided site).

  • Partner/Broker orders will have a buyer->type of Office
  • Client orders either from your Ticket Evolution API-powered website or from the Core POS will have a buyer->type of Client

Differentiating based on payment type

All orders have a payments object detailing one or more payments associated with the order. Each payments object has a property named type which can be used to identify how that particular payment was made. Available types can be found in the Payments / Create documentation.

Differentiating orders for speculation tickets

All orders have a boolean spec property and if it is set to true that order contains one or more items that are speculation ticket groups.

Accepting an Order

When you accept an order you are obligating your company to provide all of the requested tickets. You cannot accept just a portion of an order that has multiple items.

In the example below be sure to replace :order_id in the URL with the id of the order (not the id of the item). Also, use the id of the user that you created earlier as the reviewer_id. This way you will know that this order was accepted by your super-cool order processing robot.

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: RFajHc97ooCUqQUAPPXVAmrapqVnunmcLFZP4a8ZVHJs' \
-H '
Accept: application/json' \
-d '{"reviewer_id":12345}' \
--url 'https://api.ticketevolution.com/v9/orders/{order_id}/accept'

Delivering Etickets via the API

If you have confirmed—either manually or via the API—an order where one or more of the items has a value of true for eticket_delivery then you can deliver those tickets via the API.

Note: Delivering etickets is done on a per-item basis, not on a per-order basis. If your order has multiple items you will need to make sure that you handle delivery for each item. An order with multiple items may also have some items that are set for edelivery and some that are FedEx or another type of delivery. Be sure to handle each item accordingly.

Two Ways to Deliver Electronic Tickets

With our API you can either deliver etickets either as one file per page or as one single file that includes all and only all of the requested tickets. > If you have a PDF file that has more tickets than you need to deliver you will need to split that file first or manually upload those tickets and choose the pages to deliver.

Delivering Separate Files for Each Page

Use the Items / Add Etickets endpoint to upload individual files for each ticket. You can send all the files in an array in a single POST or you may POST them one at a time, or a combination of the two.

In the example below the item_id is the property named id from the item within the order, not the order_item_id.

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: Lyu2RxCtxYNZvJJXwDQbquoCcHB3gchHJWpaKkB6KBjk' \
-H 'Accept: application/json' \
--url 'https://api.ticketevolution.com/v9/orders/{order_id}/items/{item_id}/add_etickets'
-d '{"files":["<base64-encoded file>","<another base64-encoded file>"]}'

Once you have added all of the files, simple let us know that you have completed it by POSTing to the Items / Finalize Etickets endpoint.

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: nMNnzD2zauXFNgNoDwWBKwUg2TbJKZKLEwRcsmigdjkA' \
     -H 'Accept: application/json' \
-url 'https://api.ticketevolution.com/v9/orders/{order_id}/items/{item_id}/finalize_etickets' \ -d '{"keep_pages":[1,2,3,4]}'

If you need to, you can “reset” and wipe out all uploaded files using Items / Remove Etickets any time before you Finalize.

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: 2QGKdX7No4HFzDEkApbZfHiLnkFsHbnTKYWGiennHhZL' \
-H 'Accept: application/json' \
--url 'https://api.ticketevolution.com/v9/orders/{order_id}/items/{item_id}/remove_etickets'

Delivering All Tickets in a Single File

Use the Orders / Deliver Etickets endpoint to upload a single base64 encoded PDF file that has all of the tickets.

In the example below the item_id value comes from the property named order_item_id from the item within the order, not the id.

curl -H 'X-Token: FsxRk6qxJgVn6qzsgPQznyvVNykPwd22' \
     -H 'X-Signature: 2QGKdX7No4HFzDEkApbZfHiLnkFsHbnTKYWGiennHhZL' \
-H 'Accept: application/json' \
--url 'https://api.ticketevolution.com/v9/orders/{order_id}/deliver_etickets' \ -d '{"etickets":["item_id":12345,"eticket":"<base64-encoded file>"]}'