Mobil numaralar

Mobil numaralar, Android telefonlardaki gerçek SIM kartlarıdır. SIM Bridge uygulamasını çalıştıran bir telefon, aldığı SMS’leri clearance.rest’e iletir; böylece bu mesajlar GET /sms/wait’i diğer numaralar gibi çözer. Sanal numaraları reddeden servisler için kullanın.

Bir numarayı projenize almak iki bağımsız adımdır:

Numarayı doğrulama: telefonu elinde tutan kişi yapar. Uygulamada numara, ona gönderilen bir kodla doğrulanır.
Projenize ekleme: uygulamada sizin QR kodunuzu okutarak yapılır.

Hangi numaranın ekleneceğini siz seçemezsiniz. Karar telefonu tutan kişidedir; görmediğiniz bir numarayı da adlandıramazsınız.

SIM Bridge uygulamasını telefona kurun.

Bu bağlantıyı telefonun tarayıcısında açın. API anahtarı gerekmez:
```
https://api.clearance.rest/numbers/providers/mobile/download_apk
```
Yalnızca en son sürüm sunulur.
Backend’inizde bir claim bileti oluşturun.
```
curl -X POST https://api.clearance.rest/numbers/providers/mobile/claim/ticket \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "label": "agency-1" }'
```
```
{ "success": true, "ticket": "cst_3f9a…", "expires_at": 1700000060000, "ttl_ms": 60000 }
```
Bilet tek kullanımlıktır ve 60 saniye geçerlidir. Var olma nedeni, tarayıcı WebSocket’inin header gönderememesi ve API anahtarınızın tarayıcıya asla ulaşmaması gerekmesidir. İsteğe bağlı label, oturumun ürettiği her QR’da tutulan kendi notunuzdur.

Tarayıcıda claim socket’ini açın.

Tarayıcıya yalnızca biletli URL’i verin. Socket bir QR kodu gösterir, onu taze tutar ve okutulduğunda size haber verir.

const socket = new WebSocket(
  `wss://api.clearance.rest/numbers/providers/mobile/claim/socket?ticket=${ticket}`,
);

socket.onmessage = ({ data }) => {
  const event = JSON.parse(data);
  switch (event.type) {
    case 'qr':       renderQr(event.qr_payload); break;   // her yenilemede yeniden çağrılır
    case 'scanned':  showScanned(event.phone_number); break;
    case 'assigned': showDone(event); break;
    case 'error':    showError(event.message); break;
  }
};

QR’ı uygulamada okutun.

Telefonu tutan kişi QR’ı SIM Bridge uygulamasında okutur. Numara eklenir ve GET /numbers/list içinde provider: "mobile" ile görünür.

Socket event’leri

Her mesaj, type alanı olan bir JSON text frame’idir:

`type`	Ne zaman	Alanlar
`session`	Bağlantıda bir kez.	`session_id`, `ttl_ms`
`qr`	Bağlantıda ve QR her yenilendiğinde.	`token`, `qr_payload`, `issued_at`, `expires_at`
`scanned`	Güncel QR okutuldu.	`at`, `number_id`, `phone_number`, `carrier_name`
`assigned`	`scanned`’ın hemen ardından, numara eklendiğinde.	`at`, `unchanged` ve numaranın alanları
`error`	`scanned`’ın hemen ardından, ekleme başarısız olursa.	`code`, `message`

qr_payload’ı QR kodu olarak çizin. QR süresi dolmadan yenilenir ve her qr event’i bir öncekinin yerini alır.

assigned’dan sonra sunucu yenilemeyi durdurur ve socket’i 1000 koduyla kapatır. Başka bir numara eklemek için yeni bir bilet alıp yeniden bağlanın. Socket’i atama olmadan kapatırsanız, o an geçerli olan QR hemen geçersiz olur.

Canlılık kontrolü isterseniz socket, ping text frame’ine pong ile yanıt verir.

Socket’siz tek seferlik QR

POST /numbers/providers/mobile/claim/rest, tek çağrıda bir token ve onun qr_payload’ını döndürür. Token tek kullanımlıktır ve 30 saniye sonra geçersiz olur; bu, bir insanın elle işlem yapması için çok kısadır, bu yüzden gerçek kullanımda socket’i tercih edin. Hızlı bir kontrol için işe yarar: QR’ı SVG resmi olarak almak için ?preview=true ekleyin.

curl -X POST "https://api.clearance.rest/numbers/providers/mobile/claim/rest?preview=true" \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" -o claim-qr.svg

Numara durumu

Mobil numaralar, telefona bağlı iki durum ekler:

OFFLINE: telefondan 30 dakika ya da daha uzun süredir sinyal yok. Teslimatı engellemez; gelen bir SMS’in kendisi telefonun canlı olduğunun işaretidir.
SIM_REMOVED: SIM telefonda değil. SMS’ler waiter’lara teslim edilmez.

Bir numara aynı anda yalnızca tek bir projeye eklenebilir. Başka bir projeye eklenmişse sizin projenizde MOVED görünür. Bkz. Numaraları yönetme.

Yanlış numara eklenirse

Sızmış bir token, birinin istemediğiniz bir numarayı eklemesine yol açabilir. Bu bir sızıntı değil, kirliliktir: numarayı görürsünüz ve POST /numbers/release ile kaldırabilirsiniz; mobil numarada bu yalnızca projenizin atamasını kaldırır.