API
티켓타코 API의 인증 방식, 응답 형식, 오류 코드와 API 목록입니다. API 연동 방법은 API 연동하기 가이드를 참고해주세요.
시작하기
요청 보내기
모든 요청은 https://api.ticketa.co/v1로 보냅니다. Authorization 헤더에 API 키를 담아주세요. API 키를 발급한 조직의 정보만 조회할 수 있습니다.
curl "https://api.ticketa.co/v1/events" \
-H "Authorization: Bearer ttsk_xxxxxxxxxxxxxxxx"
응답 형식
목록 조회는 아래 형식으로 응답합니다.
{
"data": [
// ...
],
"has_more": true,
"next_cursor": "WyIyMDI1LTA0LTA3VDE0OjMwOjAwLjAwMFoiLCIxMjMiXQ"
}
data object[]
조회한 객체 배열입니다.
has_more boolean
다음 페이지가 있는지 여부입니다.
next_cursor nullable string
다음 페이지를 조회할 때 cursor 파라미터로 보낼 값입니다. 다음 페이지가 없으면 null입니다.
페이지네이션
목록 조회는 커서 기반 페이지네이션을 사용합니다. 한 페이지에 조회할 개수는 limit 파라미터로 정하며, 기본값과 최댓값은 API마다 다릅니다. 첫 페이지는 cursor 없이 요청하고, 응답의 has_more가 true이면 next_cursor 값을 그대로 cursor 파라미터로 보내 다음 페이지를 요청하세요. has_more가 false가 될 때까지 반복하면 전체 목록을 조회할 수 있습니다.
curl "https://api.ticketa.co/v1/events/a1b2c3d4/tickets?limit=250&cursor=WyIyMDI1LTA0LTA3VDE0OjMwOjAwLjAwMFoiLCIxMjMiXQ" \
-H "Authorization: Bearer ttsk_xxxxxxxxxxxxxxxx"
자세한 사용 방법은 전체 목록 조회하기를 참고해주세요.
오류
요청이 실패하면 HTTP 상태 코드와 함께 아래 형식으로 응답합니다.
{
"error": {
"code": "INVALID_PARAMETER",
"message": "limit must be an integer between 1 and 250"
}
}
| 상태 코드 | 오류 코드 | 설명 |
|---|---|---|
| 400 | INVALID_PARAMETER |
요청 파라미터가 올바르지 않습니다. message에서 원인을 확인하세요. |
| 401 | UNAUTHORIZED |
API 키가 없거나 올바르지 않습니다. |
| 404 | NOT_FOUND |
요청한 경로나 이벤트를 찾을 수 없습니다. |
| 410 | PERSONAL_DATA_EXPIRED |
개인정보 보관 기간이 지나 조회할 수 없습니다. |
| 429 | RATE_LIMITED |
요청 제한을 초과했습니다. |
| 500 | INTERNAL_ERROR |
서버에서 오류가 발생했습니다. 잠시 후 다시 요청해주세요. |
요청 제한
- API 키마다 1분에 약 30회까지 요청할 수 있습니다.
- 요청 제한을 초과하면
429상태 코드와Retry-After헤더가 응답됩니다. 헤더에 담긴 시간(초)만큼 기다린 뒤 다시 요청해주세요. - 참가자 개인정보는 이벤트 종료 후 1년까지 보관됩니다. 보관 기간이 지난 이벤트의 주문, 티켓, 참가신청 목록을 조회하면
410오류가 응답됩니다. 필요한 데이터는 보관 기간 안에 저장해주세요.
API 목록
이벤트 목록 조회
GET /v1/events
조직의 이벤트 목록을 조회합니다. 이벤트 시작 시간이 늦은 순서로 정렬됩니다.
쿼리 파라미터
limit optional number
한 페이지에 조회할 개수입니다. 1부터 100까지 지정할 수 있으며, 기본값은 20입니다.
cursor optional string
다음 페이지를 조회할 커서입니다. 이전 응답의 next_cursor 값을 보내주세요.
요청 예시
curl "https://api.ticketa.co/v1/events" \
-H "Authorization: Bearer ttsk_xxxxxxxxxxxxxxxx"
응답 예시
data는 Event 객체 배열입니다.
{
"data": [
{
"id": "a1b2c3d4",
"title": "FEConf 2025",
"status": "public",
"start_at": "2025-08-23T01:00:00.000Z",
"end_at": "2025-08-23T09:00:00.000Z",
"created_at": "2025-04-01T05:00:00.000Z"
}
// ...
],
"has_more": false,
"next_cursor": null
}
주문 목록 조회
GET /v1/events/{event_id}/orders
이벤트의 주문 목록을 조회합니다. 결제 시간이 이른 순서로 정렬됩니다.
경로 파라미터
event_id string
조회할 이벤트의 고유 식별자입니다.
쿼리 파라미터
format optional string
응답 형식입니다. 기본값은 json입니다.
json: 페이지 단위로 JSON 형식으로 응답합니다.csv: 전체 목록을 CSV 파일 하나로 응답합니다.limit,cursor와 함께 사용할 수 없습니다. 주문에 포함된 티켓(tickets)은 응답하지 않으니, 티켓 정보는 티켓 목록 조회로 받아주세요.
limit optional number
한 페이지에 조회할 개수입니다. 1부터 250까지 지정할 수 있으며, 기본값은 50입니다.
cursor optional string
다음 페이지를 조회할 커서입니다. 이전 응답의 next_cursor 값을 보내주세요.
status optional string
조회할 주문 상태입니다. 쉼표(,)로 구분해 여러 상태를 지정할 수 있습니다. 지정하지 않으면 모든 상태를 조회합니다. 상태 값은 Order 객체의 status를 참고해주세요.
updated_since optional string
지정한 시간 이후에 변경된 주문만 조회합니다. yyyy-MM-dd'T'HH:mm:ss.SSSZ ISO 8601 형식으로 보내주세요. 취소, 환불처럼 주문 자체의 변경만 조회되며, 체크인, 양도처럼 주문에 포함된 티켓의 변경은 티켓 목록 조회로 확인해주세요. 자세한 사용 방법은 변경된 정보만 조회하기를 참고해주세요.
요청 예시
curl "https://api.ticketa.co/v1/events/a1b2c3d4/orders?status=paid" \
-H "Authorization: Bearer ttsk_xxxxxxxxxxxxxxxx"
응답 예시
data는 Order 객체 배열입니다.
{
"data": [
{
"order_number": "P0000000001",
"event_id": "a1b2c3d4",
"name": "FEConf 2025",
"quantity": 2,
"total_amount": 40000,
"refund_amount": 0,
"status": "paid"
// ...
}
// ...
],
"has_more": true,
"next_cursor": "WyIyMDI1LTA0LTA3VDE0OjMwOjAwLjAwMFoiLCIxMjMiXQ"
}
티켓 목록 조회
GET /v1/events/{event_id}/tickets
이벤트의 티켓 목록을 조회합니다. 결제 시간이 이른 순서로 정렬됩니다.
경로 파라미터
event_id string
조회할 이벤트의 고유 식별자입니다.
쿼리 파라미터
format optional string
응답 형식입니다. 기본값은 json입니다.
json: 페이지 단위로 JSON 형식으로 응답합니다.csv: 전체 목록을 CSV 파일 하나로 응답합니다.limit,cursor와 함께 사용할 수 없습니다.
limit optional number
한 페이지에 조회할 개수입니다. 1부터 250까지 지정할 수 있으며, 기본값은 50입니다.
cursor optional string
다음 페이지를 조회할 커서입니다. 이전 응답의 next_cursor 값을 보내주세요.
status optional string
조회할 티켓 상태입니다. 쉼표(,)로 구분해 여러 상태를 지정할 수 있습니다. 지정하지 않으면 모든 상태를 조회합니다. 상태 값은 Ticket 객체의 status를 참고해주세요.
updated_since optional string
지정한 시간 이후에 변경된 티켓만 조회합니다. yyyy-MM-dd'T'HH:mm:ss.SSSZ ISO 8601 형식으로 보내주세요. 참가자 정보, 참가 양식 답변 변경은 포함되지 않으니, 이 변경까지 반영하려면 웹훅의 ticket.updated를 함께 사용하거나 주기적으로 전체 목록을 다시 조회해주세요. 자세한 사용 방법은 변경된 정보만 조회하기를 참고해주세요.
요청 예시
curl "https://api.ticketa.co/v1/events/a1b2c3d4/tickets?status=paid,used" \
-H "Authorization: Bearer ttsk_xxxxxxxxxxxxxxxx"
응답 예시
data는 Ticket 객체 배열입니다.
{
"data": [
{
"ticket_number": "T0000000001",
"order_number": "P0000000001",
"ticket_type_name": "일반 참가권",
"status": "paid"
// ...
}
// ...
],
"has_more": true,
"next_cursor": "WyIyMDI1LTA0LTA3VDE0OjMwOjAwLjAwMFoiLCIxMjMiXQ"
}
참가신청 목록 조회
GET /v1/events/{event_id}/entries
추첨·승인 방식 티켓의 참가신청 목록을 조회합니다. 신청 시간이 이른 순서로 정렬됩니다.
경로 파라미터
event_id string
조회할 이벤트의 고유 식별자입니다.
쿼리 파라미터
format optional string
응답 형식입니다. 기본값은 json입니다.
json: 페이지 단위로 JSON 형식으로 응답합니다.csv: 전체 목록을 CSV 파일 하나로 응답합니다.limit,cursor와 함께 사용할 수 없습니다.
limit optional number
한 페이지에 조회할 개수입니다. 1부터 250까지 지정할 수 있으며, 기본값은 50입니다.
cursor optional string
다음 페이지를 조회할 커서입니다. 이전 응답의 next_cursor 값을 보내주세요.
status optional string
조회할 참가신청 상태입니다. 쉼표(,)로 구분해 여러 상태를 지정할 수 있습니다. 지정하지 않으면 모든 상태를 조회합니다. 상태 값은 Entry 객체의 status를 참고해주세요.
updated_since optional string
지정한 시간 이후에 변경된 참가신청만 조회합니다. yyyy-MM-dd'T'HH:mm:ss.SSSZ ISO 8601 형식으로 보내주세요. 참가자 정보, 참가 양식 답변 변경은 포함되지 않으니, 이 변경까지 반영하려면 웹훅의 entry.updated를 함께 사용하거나 주기적으로 전체 목록을 다시 조회해주세요. 자세한 사용 방법은 변경된 정보만 조회하기를 참고해주세요.
요청 예시
curl "https://api.ticketa.co/v1/events/a1b2c3d4/entries?status=awaiting_payment" \
-H "Authorization: Bearer ttsk_xxxxxxxxxxxxxxxx"
응답 예시
data는 Entry 객체 배열입니다.
{
"data": [
{
"entry_number": "E0000000001",
"event_id": "a1b2c3d4",
"name": "FEConf 2025",
"ticket_type_name": "추첨 참가권",
"status": "awaiting_payment"
// ...
}
// ...
],
"has_more": false,
"next_cursor": null
}