Channel API · v1
Connect your channel to Native Travel App.
A plain REST API for OTAs and channel managers. Read a destination’s published inventory and per-day availability, push sold reservations, move and cancel them. JSON in, JSON out — no SDK and no schema package required.
- Base URL
https://nativetravel.app/api/channels/v1- Live tenant
- Visit Almaty (nativetravel.app/en/almaty) — every city on Native Travel App serves the same API on its own domain.
- Format
- JSON over HTTPS, UTF-8. Dates are ISO 8601; calendar days are UTC.
Authentication
Send a partner key as a bearer token on every request. Each tenant issues its own keys; a key is bound to that tenant and can only see that tenant’s data. Keys start with nt_pk_.
GET /api/channels/v1/listings
Authorization: Bearer nt_pk_xxxxxxxxxxxxxxxxxxxxxxxx
The secret is shown once, when the key is issued; we store only its SHA-256 hash, so a lost key cannot be recovered — ask for a new one. A missing, wrong or revoked key always answers 401 with the same body, so a probe cannot tell the cases apart. A revoked key stops working immediately.
Scopes
Each key carries a list of scopes; a call outside them answers 403 FORBIDDEN.
| Scope | Grants |
|---|---|
listings:read | List and read published listings. |
availability:read | Per-day availability and price of an offering. |
availability:write | Create, move and cancel reservations. |
partners:read | Referral report for the one listing a key is bound to. |
verification:read | Tourist ID attestation status (granted per contract). |
A channel key is tenant-wide and carries the first three by default. A key bound to a single listing (partner network) carries only partners:read.
Listings
GET /listings
Published listings of the tenant, newest first, cursor-paginated. Scope: listings:read.
| Query | Type | Default | Notes |
|---|---|---|---|
limit | int | 50 | 1–200. |
cursor | string | — | nextCursor from the previous page. |
{
"items": [
{
"id": "ckl…",
"slug": "demo-cottage",
"type": "STAY",
"title": "Demo Cottage",
"tagline": "Mountain retreat",
"description": "…",
"address": "…",
"latitude": 43.222,
"longitude": 76.851,
"currency": "KZT",
"coverImageUrl": "https://…",
"offerings": [
{
"id": "cko…",
"kind": "ROOM",
"bookingMode": "DATE_RANGE",
"title": { "en": "Double", "ru": "…", "kk": "…" },
"basePrice": "32000.00",
"currency": "KZT",
"capacityPerSlot": 3
}
]
}
],
"nextCursor": "ckl…"
}
type is one of the 14 catalogue sections: STAY, DINING, NIGHTLIFE, CULTURE, ENTERTAINMENT, NATURE, ACTIVITIES, SPORT, WELLNESS, SHOPPING, SERVICES, TRANSPORT, EVENTS, JOBS. Older integrations may have stored ATTRACTIONS and TOURS — they are now CULTURE and ACTIVITIES.
Places imported from open city data are published before an owner claims them: they come with coverImageUrl: null, an empty gallery and no offerings. Treat image and offering fields as optional.
GET /listings/:slug
One published listing: the same fields plus its gallery (in display order) and offerings with descriptions. 404 when the slug is not a published listing of this tenant.
Availability
GET /availability/:offeringId?from=YYYY-MM-DD&to=YYYY-MM-DD
Per-day capacity and price for one offering. Scope: availability:read. Both dates are required; a window is capped at 90 days — walk longer calendars in 90-day pages. Prices are in minor units (priceCents) with the offering’s currency.
{
"offeringId": "cko…",
"kind": "TOUR_SLOT",
"bookingMode": "TIME_SLOT",
"from": "2026-11-01",
"to": "2027-01-29",
"slots": [
{
"date": "2026-11-01",
"capacity": 10,
"used": 3,
"remaining": 7,
"closed": false,
"priceCents": 1500000,
"currency": "KZT"
}
]
}
Days apply the same rules as a direct booking: a closed day reads capacity: 0, closed: true; per-day overrides and weekday rules replace the offering’s capacity; used counts confirmed and checked-in bookings plus holds that have not expired.
Reservations
POST /reservations
Commit a reservation you have already sold and collected payment for. It lands CONFIRMED immediately and a unit is assigned on the spot. Scope: availability:write.
{
"offeringId": "cko…",
"externalRef": "EXP-1234567",
"startAt": "2026-11-15T00:00:00Z",
"endAt": "2026-11-18T00:00:00Z",
"quantity": 2,
"guestName": "Alice Marsh",
"guestEmail": "[email protected]",
"note": "Late arrival"
}
offeringId, externalRef (≤ 200 chars), startAt, endAt and guestName are required; quantity is 1–100 (default 1). 201 Created for a new booking, 200 OK for a retry of the same externalRef:
{
"booking": {
"id": "ckb…",
"bookingRef": "CH-XYZ",
"status": "CONFIRMED",
"startAt": "2026-11-15T00:00:00.000Z",
"endAt": "2026-11-18T00:00:00.000Z",
"quantity": 2,
"totalAmount": "96000",
"currency": "KZT",
"externalRef": "EXP-1234567"
},
"idempotent": false
}
The reservation goes through the same booking core as a direct guest, under the offering’s lock: 409 when a day is closed or full, 400 when the property has paused bookings or the request breaks the offering’s quantity or lead-time rules. An offering of another tenant answers 404, never 403.
PATCH /reservations/:externalRef
New dates and/or quantity for a confirmed reservation. Checked like a new one, but against capacity without itself — moving a stay by a night on a full property works. Repriced at the offering’s price; keeps its unit while it stays free.
{ "startAt": "2026-11-16T00:00:00Z", "endAt": "2026-11-19T00:00:00Z", "quantity": 1 }
200 OK with { "booking": … }; 409 when the new dates do not fit or the reservation is no longer confirmed.
POST /reservations/:externalRef/cancel
The guest cancelled on your side. No body. 200 OK with the reservation in CANCELLED; a repeat answers the same with "idempotent": true. A checked-in guest cannot be cancelled from outside (409); an unknown reference is 404.
Idempotency
Your externalRef is the idempotency key: the pair (your key’s partner, externalRef) is unique. Retrying POST /reservations after a timeout returns the original booking — same id, same bookingRef, "idempotent": true — and never touches capacity twice. Cancel is idempotent the same way. Retry on network errors and 5xx freely; do not retry 4xx unchanged.
Referral report
GET /partners/report?days=30
Who the bound listing sent guests to, who sent guests to it, and how many reached payment. Needs partners:read and a key bound to a listing — a tenant-wide key is refused with 403. days is 1–365 (default 30). The figures are the ones the owner sees in their cabinet.
{
"listing": { "id": "ckl…", "title": "Demo Cottage", "slug": "demo-cottage" },
"since": "2026-09-15T00:00:00.000Z",
"sent": { "clicks": 12, "paidOrders": 3 },
"received": { "clicks": 41, "paidOrders": 9, "vouchersRedeemed": 4 },
"byPartner": [
{ "listing": { "id": "cko…", "title": "Mountain Cafe", "slug": "mountain-cafe" }, "clicks": 27 }
]
}
Tourist ID attestation
Operators that accept a traveller’s Tourist ID verify a signed attestation token.
GET /verification/jwks
Public keys for checking the signature. No key needed; cache for up to an hour.
GET /verification/status/:jti
Is this token still good? Needs verification:read. Answers only the status — never who the token belongs to.
{ "jti": "…", "active": true, "expiresAt": "2027-04-09T00:00:00.000Z", "revokedAt": null }
Errors
Every error has the same shape, and the HTTP status mirrors the code:
{ "error": { "code": "NOT_FOUND", "message": "Listing not found" } }
| Status | code | When |
|---|---|---|
| 400 | BAD_REQUEST | Malformed query or body, invalid range or quantity, bookings paused. |
| 401 | UNAUTHORIZED | Missing, invalid or revoked key. |
| 403 | FORBIDDEN | The key lacks the scope. |
| 404 | NOT_FOUND | Unknown listing, offering or reservation for this tenant. |
| 409 | CONFLICT | No room for these dates, a closed day, or a reservation that can no longer change. |
| 429 | TOO_MANY_REQUESTS | Throttled — back off and retry. The per-IP backstop (see below) answers 429 in its own shape (statusCode, error, message); treat any 429 the same way. |
| 500 | INTERNAL | Unexpected; we log it — retry with backoff. |
Rate limits
There is no per-key quota yet. A per-IP backstop protects the whole API (by default 300 requests a minute); past it you get 429 — wait and retry with exponential backoff. Page through /listings and walk availability in 90-day windows rather than polling day by day. If you expect sustained high volume, tell us before you go live.
Getting keys
Keys are issued by the destination’s team. Write to [email protected] with your company, the destination you want to connect and the scopes you need. Never send a key by e-mail back to us — if one leaks, ask us to revoke it and issue a new one.