Skip to content

Tickets ​

A ticket is an endpoint of your project that runs actions when it is called: post a record, change a user's access group, send an e-mail, call another API. Each call is a consumption. Tickets, their conditions and their actions are set up on skapi.com.

Calling a ticket ​

consumeTicket calls a ticket with data:

kotlin
import com.skapi.Skapi
import com.skapi.SkapiException
import com.skapi.jsonOf

val skapi = Skapi("<Project ID>")

// anonymous GET: data becomes the query string
val coupon = skapi.consumeTicket("launch-coupon", "GET", jsonOf("code" to "LAUNCH24"))

// anonymous POST: data is the JSON body
skapi.consumeTicket("order-note", "POST", jsonOf("order" to "A-1001"))

// signed in: the consumer is the user
skapi.login("user@example.com", "password")
val unlocked = skapi.consumeTicket("unlock-guide", "POST", auth = true)
java
import com.skapi.java.SkapiJava;
import com.skapi.java.SkapiJson;

SkapiJava skapi = new SkapiJava("<Project ID>");

// anonymous GET: data becomes the query string
Object coupon = skapi.consumeTicket("launch-coupon", "GET", SkapiJson.obj("code", "LAUNCH24")).get();

// anonymous POST: data is the JSON body
skapi.consumeTicket("order-note", "POST", SkapiJson.obj("order", "A-1001")).get();

// signed in: the consumer is the user
skapi.login("user@example.com", "password").get();
Object unlocked = skapi.consumeTicket("unlock-guide", "POST", null, true).get();

The route depends on method and auth:

callrouteconsumer
method = "GET"GET /tg/<project id>/<ticket_id>IP address and User-Agent
method = "POST" (default)POST /tp/<project id>/<ticket_id>IP address and User-Agent
auth = truePOST /tpa/<project id>/<ticket_id>, with the user's tokenthe signed-in user

A GET sends data as the query string (values that are not strings go in as compact JSON); a POST sends it as the JSON body. auth = true is POST only, and it is the only call that carries a user: a ticket's per-user limit, its user conditions and its record access condition see only this.

The request also carries Accept, Content-Type: application/json, the SDK's Content-Meta header and OkHttp's own User-Agent (okhttp/<version>), which is what a ticket's header conditions can read.

The receipt ​

A successful consumption returns its receipt as a JsonElement:

json
{
    "ticket_id": "unlock-guide",
    "consume_id": "UwdAhf6k3Qp",
    "user_id": "f2b6c9e1-...",
    "is_test": false,
    "timestamp": 1757721600000,
    "hash": "..."
}
  • consume_id: base62 of the time in milliseconds, then 4 random characters.
  • user_id: the user with auth = true, else "<ip>(<user agent>)".
  • timestamp: milliseconds, read from consume_id.

A ticket with a Respond action returns what that action composed instead, as it was sent. A ticket that limits how many runs go at once, with every slot taken, returns the receipt with "queued": true and "position" (1 = next); its actions run when its turn comes.

When a consumption fails ​

A refused consumption throws a SkapiException whose code is the ticket's error code and whose details is the whole error body:

kotlin
try {
    skapi.consumeTicket("launch-coupon", "GET", jsonOf("code" to "WRONG"))
} catch (err: SkapiException) {
    val body = err.details?.jsonObject
    println(err.code)          // CONDITION_FAILED
    println(err.message)       // one sentence
    println(body?.get("stage"))   // "ticket", "condition" or "action"
    println(body?.get("detail"))  // {"field":"params","keys":["code"]}
    println(body?.get("action"))  // {"act":"req","path":"actions[2]"} on an action failure
}
java
import com.skapi.SkapiException;
import java.util.concurrent.ExecutionException;

try {
    skapi.consumeTicket("launch-coupon", "GET", SkapiJson.obj("code", "WRONG")).get();
} catch (ExecutionException e) {
    SkapiException err = (SkapiException) e.getCause();
    Map<String, Object> body = (Map<String, Object>) SkapiJson.toJava(err.getDetails());
    System.out.println(err.getCode());     // CONDITION_FAILED
    System.out.println(err.getMessage());  // one sentence
    if (body != null) {
        System.out.println(body.get("stage"));                         // "ticket", "condition" or "action"
        System.out.println(SkapiJson.stringify(body.get("detail")));  // {"field":"params","keys":["code"]}
        System.out.println(SkapiJson.stringify(body.get("action")));  // {"act":"req","path":"actions[2]"} on an action failure
    }
}

This is the same whether the ticket answered 400 or, with Always answer 200 on, 200. Mistakes caught before sending (a bad ticketId, auth = true with GET) are plain INVALID_PARAMETER errors with no details.

codestagewhen
INVALID_SERVICE, SERVICE_DISABLEDticketthe project is not found or is switched off
TICKET_NOT_FOUND, TICKET_DISABLED, TICKET_EXPIRED, TICKET_EXHAUSTEDticketno such ticket, switched off, past its time to live, or no count left
USER_LIMIT_REACHEDticketthe per-user limit is used up
ISSUER_CANNOT_CONSUMEticketthe caller is the ticket's issuer
AUTH_REQUIREDanythe ticket needs a user and the call has none (auth = true is missing), or the token is from another project
METHOD_NOT_ALLOWED, CONDITION_FAILEDconditionthe request does not match the ticket's condition
PATH_NOT_FOUND, PLACEHOLDER_MISSINGactionan action read a value the request does not carry
REQUEST_FAILED, ACTION_FAILED, ACTION_FORBIDDEN, TIMEOUT, QUOTA_EXCEEDED, ALREADY_RESPONDEDactionan action could not be done
INTERNAL_ERRORanyan unexpected failure

There is no rollback: actions that ran before a failure stay done.

Listing tickets ​

getTickets lists the project's tickets for a signed-in user. Each row is the public part of a ticket:

kotlin
val tickets = skapi.getTickets()
// {"list":[{"ticket_id":"launch-coupon","description":"Launch coupon","count":87,"timestamp":1757721600000}, ...], ...}

val one = skapi.getTickets(jsonOf("ticket_id" to "launch-coupon"))
java
Map<String, Object> tickets = skapi.getTickets().get();
// {"list":[{"ticket_id":"launch-coupon","description":"Launch coupon","count":87,"timestamp":1757721600000}, ...], ...}

Map<String, Object> one = skapi.getTickets(SkapiJson.obj("ticket_id", "launch-coupon")).get();

count (consumptions left) and time_to_live (when it expires, in milliseconds) are there only when the ticket has them.

Your own consumptions ​

getConsumedTickets lists the signed-in user's consumptions, oldest first. Only calls made with auth = true belong to a user, so anonymous ones never appear. ticket_id narrows the list to tickets whose ID starts with it.

kotlin
import kotlinx.serialization.json.*

val consumed = skapi.getConsumedTickets(jsonOf("ticket_id" to "unlock-guide"))

for (r in consumed["list"]!!.jsonArray) {
    val row = r.jsonObject
    val log = Json.parseToJsonElement(row["description"]!!.jsonPrimitive.content).jsonObject
    val ok = log["outcome"]!!.jsonObject["ok"]
    println("${row["ticket_id"]} ${row["consume_id"]} ${row["timestamp"]} $ok")
}
java
import java.util.List;
import java.util.Map;

Map<String, Object> consumed = skapi.getConsumedTickets(SkapiJson.obj("ticket_id", "unlock-guide")).get();

for (Object r : (List<Object>) consumed.get("list")) {
    Map<String, Object> row = (Map<String, Object>) r;
    Map<String, Object> log = (Map<String, Object>) SkapiJson.parse((String) row.get("description"));
    Object ok = ((Map<String, Object>) log.get("outcome")).get("ok");
    System.out.println(row.get("ticket_id") + " " + row.get("consume_id") + " " + row.get("timestamp") + " " + ok);
}
field
ticket_id, consume_id, timestampas in the receipt
user_id, regyour user ID
is_testalways false here: only dry runs are true, and they are anonymous
descriptionthe consumption log as JSON text: the request as received (data, method, headers, ip, user_agent, timestamp) and its outcome (ok, actions, error, ...)
hashproof string of the consumption

Both listings page like getRecords.

skapi-kotlin 2.4.1