Summary

This architecture leverages the optionality of barcodes that don't always get used, to reduce stress on our system, and doesn't create an order or ticket until the barcode is scanned. 

APIs

Assigning a collaborator to a venue will include creating an org and tenant user in the venue with the tenant user being assigned an api key.  The name of the org and tenant user will match the name of the collaborator.

Each API call will be for a specific tenant and include the api key assigned to that user.

List barcodes

Get v2/b2b/barcodes

Parameters

  • createdAfter   ISO8601 date that you want barcodes created after
  • createdBefore   ISO8601 date that you want barcodes created before
  • updatedAfter   ISO8601 date that you want barcodes updated after
  • updatedBefore   ISO8601 date that you want barcodes updated before
  • usedAfter   ISO8601 date that you want barcodes scanned after - USEAGE NOT YET WORKING
  • usedBefore   ISO8601 date that you want barcodes scanned before - USEAGE NOT YET WORKING
  • eventTemplateId   The id of the event template you want barcodes of
  • eventId   The id of the event you want barcodes of
  • ticketTypeId    The ticket type id you want barcodes of
  • status  The status that you want barcodes of (converted, new, voided, error) - USEAGE NOT YET WORKING
  • customerEmail   The email of the customer you want the barcodes for
  • customerId   The id of the customer you want the barcodes for
  • externalOrderNumber   The external id of the barcode you want
  • pageSize   The number of barcodes you want returned, default 100
  • page   The page you want the barcodes for
  • sortDirection   Either 'asc' or 'desc'
  • sortField   What to sort the barcodes on (createdOn, updatedOn, usedOn, barcode, externalOrderNumber, eventTemplateId).

Returns

A paginated list of Barcode JSON objects

Examples

  • get /v2/b2b/barcodes?createdAfter=2019-04-18T00:00:00Z&createdBefore=2019-04-19T00:00:00Z  -H "x-acme-api-key:[key]" 
    • returns a page of up to 100 barcodes for April 18th, 2019 for the specified tenant.
  • get /v2/b2b/barcodes?externalOrderNumber=123  -H "x-acme-api-key:[key]"
    • returns a page of 1 barcodes with the external order number 123

Get a barcode

Get v2/b2b/barcodes/{barcode}

Paramaters

  • barcode  (required)  The barcode that you want to retrieve

Returns

A Barcode JSON object

Examples

  • get /v2/b2b/barcodes/123  -H "x-acme-api-key:[key]"
    • returns a single barcode JSON object with the corresponding barcode.  Will return 404 if the barcode does not exist.

Add barcodes

Post v2/b2b/barcodes

Body

A list of Barcode JSON objects

Field
Notes
collaboratorIdRequired - Assigned by ACME
eventTemplateIdRequired if eventId is not provided
eventIdRequired if eventTemplateId is not provided
ticketTypeIdRequired
barcodeRequired
externalOrderNumberRequired
customerIdOptional
customerFirstNameOptional
customerLastNameOptional
customerEmailOptional

Returns

The resulting list of Barcode JSON objects with the id and created time filled in.

Examples

Add three barcodes

[
    {
        "collaboratorId"9,
        "eventTemplateId""1234-1234-12345",
        "eventId""678-678-6789",
        "ticketTypeId""567-567-5678",
        "email""pascal@acmeticketing.com",
        "firstName""Pascal",
        "lastName""Belleville",
        "barcode""567-1230-0001",
        "orderNumber""10001"
    }, {
        "collaboratorId"9,
        "eventTemplateId""1234-1234-12345",
        "eventId""678-678-6789",
        "ticketTypeId""567-567-5678",
        "barcode""567-1230-0002",
        "orderNumber""10001"
    }, {
        "collaboratorId"9,
        "eventTemplateId""1234-1234-12345",
        "eventId""678-678-6789",
        "ticketTypeId""567-567-5678",
        "barcode""567-1230-0003",
        "orderNumber""10001"      
    }
]

Deactivate barcodes

Put v2/b2b/barcodes/deactivations

Body

A list of barcodes to be removed

Field
Description
Notes
barcodeThe barcode to be deactivatedrequired
codeAny numeric value between 0 and 3000.required
messageA message about why the barcode is being deactivated which may be presented to the customer when they try to use the barcode.  If not provided then a general message will be presented.varchar(2048)

Returns

     The Barcode JSON objects that were deleted

Example

Delete three barcodes  

[
    {
        "barcode""567-1230-0001",
        "code"1,
        "message""Order was cancelled. Call 555-555-5555."
    },
    {
        "barcode""567-1230-0002",
        "code"2,
        "message""Barcode was used on 1-12-2019."
    },
    {
        "barcode""567-1230-0003",
        "code"999,
        "message""Something went wrong with this barcode. Call 555-555-5555 for more information."
    }
]

JSON Objects

Barcode Object

Field
Description
idUnique id for this barcode
tenantIdId of the tenant this barcode is good for
collaboratorIdId of the collaborator
eventTemplateIdid of the event template
eventIdid of the event
ticketTypeIdid of the ticket type
customerIdid of the customer this barcode is for
customerFirstNamefirst name of the customer
customerLastNamelast name of the customer
customerEmailemail of the customer
barcodeThe text of the barcode
externalOrderNumberExternal order id of the barcode for the collaborator's records
statusStatus of the barcode (converted, voided, new, error...)
activeTrue if the barcode is active, false otherwise.  Might be changed to deleted
orgIdThe id of the org for this collaborator
orderNumberThe order number
createdOnThe date that the barcode was created
createdByThe id of the tenant user that created the barcode
updatedOnThe date that the barcode was last updated
updatedByThe tenant id of the user that last updated the barcode
usedOnThe time and date that the barcode was used

Barcode List

Field
Description

Array of event and customer information, used to create the barcodes
[x].idId of the tenant
[x].eventTemplateIdEvent template that all of the barcodes will be assigned to
[x].eventIdEvent id that all of the barcodes will be assigned to
[x].ticketTypeIdThe ticket type associated with this barcode (Child, Adult...)
[x].emailEmail address associated with this barcode
[x].firstNameThe first name of the person this barcode is for
[x].lastNameThe last name of the person this barcode is for
[x].barcodeThe barcode
[x].orderNumberThe external order number associated with this barcode
[x].createdOnThe time that the barcode was created
[x].usedOnThe time that the barcode was used