Processing Ticket Evolution Orders via API
Helpful tools
- API Documentation: https://ticketevolution.atlassian.net/wiki/display/API/API+Documentation
- API Demo: http://api-demo.ticketevolution.com/
- PHP Library: https://github.com/ticketevolution/ticketevolution-php
- Ruby Library: https://github.com/ticketevolution/ticketevolution-ruby
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
.
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 betrue
or (1
).
A pseudo-code example of what you probably want to do
$orders = get_pending_orders_from_api(); foreach ($orders as $order) { $can_accept_order = true; foreach ($order->items as $item) { $tickets_are_available = check_our_inventory_for_availability($item->ticket_group->remote_id, $quantity); if (!$tickets_are_available) { $can_accept_order = false; } } if ($can_accept_order) { accept_order_with_tevo($order->id); } else { notify_someone_we_cannot_confirm_tevo_order(); } }
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
ofOffice
- 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 type
s 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 item
s.
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' \
Accept: application/json' \
-H '
-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 item
s 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 multipleitem
s may also have someitem
s that are set for edelivery and some that are FedEx or another type of delivery. Be sure to handle eachitem
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 POST
ing 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>"]}'
Related articles