Skip to content

Tickets ​

Every method throws SkapiError with a code and a message, and can throw NETWORK_ERROR when no answer comes back. See Tickets.

consumeTicket ​

swift
func consumeTicket(ticketId: String, method: String = "POST", data: JSON? = nil, auth: Bool = false) async throws -> JSON

Calls a ticket of the project, at https://<first 4 characters of the Project ID>.skapi.dev/.

argument
ticketIdLetters, digits, _ and -, up to 64 characters, starting with a letter or digit.
method"GET" or "POST", any case. GET sends data as the query string (/tg/ route); POST sends it as the JSON body (/tp/ route).
dataThe request data. Defaults to {}.
authtrue sends the call as the signed-in user (POST /tpa/ route, with the user's token). POST only.

Returns the receipt, or the body a Respond action of the ticket composed, as sent:

json
{
    "ticket_id": "unlock-guide",
    "consume_id": "UwdAhf6k3Qp",
    "user_id": "f2b6c9e1-...",
    "is_test": false,
    "timestamp": 1757721600000,
    "hash": "..."
}
key
consume_idbase62 of the time in milliseconds, then 4 random characters
user_idthe user with auth: true, else "<ip>(<user agent>)"
timestampmilliseconds, read from consume_id
hashproof string of the consumption
queuedtrue only when the call waits for a free slot; its actions run later
positionwith queued: place in the line, 1 = next

Errors ​

codemessage
INVALID_PARAMETERTicket ID is required.
INVALID_PARAMETERInvalid "ticket_id". Use letters, digits, "_" and "-" (up to 64 chars, starting with a letter or digit).
INVALID_PARAMETERMethod is required. Should be either "GET" or "POST"
INVALID_PARAMETERMethod should be either "GET" or "POST".
INVALID_PARAMETERSigned-in consumption is POST only.
INVALID_REQUESTUser login is required. (auth: true, signed out)
TICKET_BUSYevery slot of a ticket with a concurrency limit is taken. Nothing was consumed; try again later.
the ticket's codethe ticket's message. cause is the whole error body as JSON: {"code", "message", "stage", "action"?, "detail"?, "ticket_id"}. Thrown whether the ticket answered 400 or 200. See When a consumption fails.
swift
do {
    _ = try await skapi.consumeTicket(ticketId: "launch-coupon", method: "GET", data: ["code": "WRONG"])
} catch let err as SkapiError {
    let body = err.cause as? JSON
    print(err.code, body?["stage"]?.string ?? "")
}

getTickets ​

swift
func getTickets(_ params: JSON? = nil, fetchOptions: FetchOptions? = nil) async throws -> JSON

The project's tickets. Signed-in users only. Returns {"list", "startKey", "endOfList", "startKeyHistory"}, up to 100 a page; see Paging.

keytype
ticket_idstringOnly this ticket.

Each row:

key
ticket_id
description
countconsumptions left, when the ticket has a count
time_to_livewhen it expires, milliseconds, when it has one
timestampwhen it was registered, milliseconds

Errors ​

codemessage
INVALID_REQUESTUser login is required.
INVALID_REQUESTInvalid ticket id. (ticket_id contains # or @)

getConsumedTickets ​

swift
func getConsumedTickets(_ params: JSON? = nil, fetchOptions: FetchOptions? = nil) async throws -> JSON

The signed-in user's own consumptions, the ones made with auth: true, oldest first. Returns {"list", "startKey", "endOfList", "startKeyHistory"}.

keytype
ticket_idstringOnly tickets whose ID starts with this.

Each row:

key
ticket_id, consume_id, timestampas in the receipt
user_id, regthe user's ID
is_testfalse (dry runs are anonymous, so they never appear here)
descriptionthe consumption log as JSON text, with data, method, headers, ip, user_agent, timestamp and outcome (ok, actions, error, ...); read it with JSON.parse(_:)
hashproof string of the consumption

Errors ​

codemessage
INVALID_REQUESTUser login is required.

skapi-swift 2.4.0