OAuth ile yazılım entegrasyonu

Birçok acente adına çalışan yazılımlar için: acente izin verir, siz API anahtarını hiç görmeden erişirsiniz.

Bir yazılım firmasıysanız her acentenin API anahtarını istemek yerine OAuth 2.0 kullanın. Acente bir onay sayfasında yazılımınıza izin verir; siz de yalnızca o acentenin onayladığı yetkilerle çalışan bir erişim belirteci alırsınız. Acente erişimi istediği an kaldırabilir.

1. Uygulamanızı kaydedin

Geliştirici sayfasında Uygulamalar sekmesinden yeni uygulama ekleyin: ad, yönlendirme adresleri (https, yerelde http://localhost) ve istemci türü. Sunucuda çalışan uygulamalar gizli istemcidir ve client_secret alır (bir kez gösterilir); mobil ve tarayıcı uygulamaları genel istemcidir. İkisi de PKCE kullanmak zorundadır.

2. Acenteyi yönlendirin

import crypto from 'node:crypto';

const verifier = crypto.randomBytes(32).toString('base64url');          // keep it with the user's session
const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');

const url = new URL('/en/app/oauth/authorize');
url.search = new URLSearchParams({
  client_id: process.env.BP_CLIENT_ID,
  redirect_uri: 'https://app.example.com/callback',
  scope: 'properties:read calendar:read rates:read reservations:write events:read',
  state: crypto.randomBytes(16).toString('hex'),                        // check it again on return
  code_challenge: challenge,
  code_challenge_method: 'S256',
  mode: 'live',                                                         // or 'test' for the sandbox
}).toString();
// redirect the browser to url.toString()

Acente giriş yapmamışsa önce giriş yapar. Onaylarsa redirect_uri adresinize code ve state ile döner; reddederse error=access_denied ile.

3. Kodu belirteçle değiştirin

bash

curl -s -X POST https://api.cesisync.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=$BP_CLIENT_ID -d client_secret=$BP_CLIENT_SECRET \
  -d code=$CODE -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=$VERIFIER

json

{
  "access_token": "bp_oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "bp_ort_…",
  "scope": "properties:read calendar:read rates:read reservations:write events:read"
}

Kod 10 dakika geçerlidir ve yalnızca bir kez kullanılır; ikinci kullanım denemesi o koddan üretilen tüm belirteçleri geçersiz kılar. Genel istemcilerde client_secret gönderilmez, PKCE yeterlidir.

4. API'yi çağırın

bash

curl -s https://api.cesisync.com/v1/me -H "Authorization: Bearer bp_oat_…"

Erişim belirteci, /v1 üzerinde bir API anahtarı gibi çalışır, ancak yalnızca acentenin onayladığı yetkilerle ve ortamla (canlı ya da sandbox) sınırlıdır. Aynı hız sınırı ve hata kodları geçerlidir; süresi dolunca 401 api_key_expired alırsınız.

5. Yenileyin

bash

curl -s -X POST https://api.cesisync.com/oauth/token \
  -d grant_type=refresh_token -d client_id=$BP_CLIENT_ID -d client_secret=$BP_CLIENT_SECRET \
  -d refresh_token=bp_ort_…

Her yenilemede yeni bir erişim ve yenileme belirteci verilir; eskisi geçersiz olur (döndürme). Yenileme belirteci 60 gün geçerlidir. Belirteçleri iptal etmek için POST /oauth/revoke (token, client_id, client_secret).

OAuth uçları RFC 6749 biçiminde hata verir: {"error":"invalid_grant","error_description":"…"}. Diğer tüm API hataları problem+json biçimindedir.