Organizasyon KYC/KYB/IDV entegrasyonu

Quickstart adım 5 canlı trafiğin iki zorlu kapısını neler: onaylanmış organizasyon KYC’si ve fonlanmış bakiye. Organizasyon KYC’si workspace başına tek seferlik bir incelemedir — işletme kendini doğrular, numaralarını değil (numara başına doküman demetleri ayrı bir konu; sonunda karşılaştırmaya bakın). Bu kılavuz tam döngüyü kapsar — gönderim, isteğe bağlı barındırılan kimlik doğrulama oturumu, sonuç sorgusu, reddedilirse yeniden gönderim — ardından kalan go-live kapıları.

1. Canlı trafiği neden engellenmiş

Canlı gönderiler, Devotel operasyon ekibinden birinin gerçek bir işletme profiline bakması kadar kısıtlı kalır. Onay gelene kadar:

Numara satın almak hâlâ mümkün, ancak hiçbir SMS, WhatsApp veya ses gönderi platformdan çıkmaz.
Kontrol paneli durumu bir banner’da gösterir; bu kılavuzun ördüğü sayfa Ayarlar → KYC altından ulaşılabılır.

İki durum incelemeyi ilerletir. not_started formun hiç gönderilmediğini, pending_review bir operatör kuyruğunun gönderimi tuttuğunu ifade eder (e-posta onay webhook’u bunu kayıt sırasında ön-stampeler; aşağıdaki form onu zengin detayla değiştirir). Karar sonrası approved veya rejected alırsınız.

2. Formu gönderin

/api/v1/organization/kyc/submit adlı uç noktaya POST ile işletme profili gönderin. API doğrular: şirket adı ve ülke zorunlu, web sitesi isteğe bağlı, amaç-yanlama on karakterden az olmamalı, yarar-lidar-kimler isteğe bağlı (maks. 20).

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Logistics Ltd.",
    "company_website": "https://acme-logistics.example",
    "country": "US",
    "industry": "Lojistik",
    "use_case": "Ödeme esnasında rıza vermiş müşterilere gönderi durumu bildirimleri.",
    "estimated_monthly_volume": 45000,
    "registration_number": "DE-554433",
    "beneficial_owners": [
      { "name": "Maria Alvarez", "ownership_percentage": 100 }
    ]
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const result = await orbit.organization.kyc.submit({
  company_name: 'Acme Logistics Ltd.',
  company_website: 'https://acme-logistics.example',
  country: 'US',
  industry: 'Lojistik',
  use_case: 'Rıza almış müşterilere durum bildirimi.',
  estimated_monthly_volume: 45000,
});
console.log(result.data.status); // "pending_review"

Başarılı bir çağrı organizasyonu pending_review olarak damgalar, kaydı ve işletme-screening sonucunu verir — inceleme operatör-elindedir, hiçbir şey otomatik onaylanmaz ya da reddedilmez. Yanıt (200):

{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Logistics Ltd.",
      "country": "US",
      "submitted_at": "2026-09-04T09:12:33Z"
    },
    "kyb": {
      "status": "review",
      "matches": [],
      "legal_name": "Acme Logistics Ltd.",
      "country": "US",
      "screened_at": "2026-09-04T09:12:33Z"
    },
    "message": "Your KYC submission has been received and is awaiting review."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-09-04T09:12:33Z" }
}

data.kyb işletme-screening sinyalidir (clear temizse, review bir yaptırımlı ülke veya yasaklı taraf eşleştiyse). Form ile birlikte gözden geçirilir — gönderimi asla bloklamaz ve review sonucu aynı insan onayını ister. Screening çalışamazsa alan hiç gelmez; o zaman manuel inceleme başlar.

3. Pazar promosyonları — hedefinizin gerçekten istediği

Yukarıdaki form organizasyon başına bir kez gönderilir, ancak gözden geçirenin en çok ağırlıkladıği alanlar hedefe bağlıdır. Gönderdiğiniz country pazarı bağlayar — fatura adresini değil hedef pazarı yazın; UK’ye gönderen biri country: "US" belirtirse sadece bir düzeltme döndürür. Ne pazarda olursa olsun iki grup her zaman gözden geçirene ulaşır: serbest-metin use_case ve KYB kimlik alanları (registration_number, beneficial_owners). Birçok kilitli pazara gönderen bir organizasyon belge modeli hedef başına bir kez tekrar eder — tek formu seyreltmek yerine belge kütüphanesinde hedefe göre gruplandırın. Aşağıdaki pazarlar ön-kayıt tamamlanana kadar gönderi tutar. Her birine: vurgulanacak profil alanları ve düzenleyicinin istediği belge rolleri. Yüklemeler Uyum → Dokümanlar altında yapılır ve kayıtlarda kimlikle atıfa girer; gözden geçirme-görünü roller business_doc, address_proof, id_proof, authorization. Sender-ID pazar matri canlı registration düzeyini ülke başına verir; dokümanlar kılavuzu yükleme akısını kapsar.

Almanya — BNetzA varlık kimliği

BNetzA her alfanümerler ve her ses-KYC kaydı arkasındaki kimliği doğrular. registration_number (yerel ticaret sicil kaydı) ve doğru şirket unvanını vurgulayın. İstenilen belgeler: business_doc (ticaret sicil örneği).

İspanya — CNMC sender-id kaydı

CNMC, alfanümer göndericilerde ön-kayıt tamamlanana kadar gönderi engeller. registration_number ve İspanya alıcısına kilitli bir use_case vurgulayın. Belgeler: business_doc (CIF/NIF).

Fransa — ARCEP gönderici kaydı

ARCEP ve taşıyıcılar alfanümer göndericiyi kaydeder; kayıt eksik olunca SMS route’ları reddeder. registration_number (RCS kaydı) ile kısıtlı use_case vurgulayın. Belgeler: business_doc (Kbis veya SIREN) artı acente adına ise authorization.

Türkiye — BTK gönderici adı

BTK gönderici isim kaydı yapar — sadece rota değil: müşterilerin göreceği ismi verin ve use_case’de belirtin. Belgeler: business_doc (ticaret odası belgeler).

Arap pazarları — örneğin BAE TDRA

Bazı Arap pazarları (ör. BAE, TDRA + e&/du taşıyıcıları) göndericide KYC-destekli bir marka kimliği bekler — ince bir gönderiyi en çok geri pınarlayan kaplam. company_name, company_website ve tam bir use_case vurgulayın. Belgeler: business_doc artı marka authorization. Her pazarda amaç aynı: company_name, use_case ve registration_number’a ne yazacağınızı send-gate 422 ile trafiği geri pınarlamadan önce karar verin. Send Gates required hedeflerin kayıtsız gönderileri nasıl blokladığını açıklar. İngiliz veya tarihsel İngilizce pazarları (UK, Suudi Arabistan, BAE, Brazilya, Hindistan DLT, US 10DLC) için İngilizce kılavuzu okuyun.

4. İsteğe bağlı: barındırılan IDV oturumu ekleme

Bazı operatörler imzadan önce devletli bir kimlik ve canlılık kontrolü isterler. POST /api/v1/organization/kyc/idv/session yapılandırılmış sağlayıcıyla bir barındırılan oturum açar; dönen URL’yi tarayıcıda açın veya imzalere iletin.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/idv/session \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://your-app.example/kyc/return" }'

Yanıt (200):

{
  "data": {
    "status": "pending",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:13:04Z"
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-09-04T09:13:04Z" }
}

Operatör tedarik sağlamadıkça uç nokta 503 yanıt verir:

{ "error": { "code": "IDV_NOT_CONFIGURED", "message": "Identity verification is not available for this account", "status": 503 } }

Sağlayıcı sonucu GET /api/v1/organization/kyc/idv/status ile kontrol edin. Kendi kendine senkronize olur: kayıtlı oturum pending olduğu sürece her GET sağlayıcıdan son durumu sorar ve terminale geçiş yazar. verified, declined veya expired terminal bir durum — sağlayıcı verirse bir reason ile — gözden geçiren sinyale katılır. Hiçbir şekilde kendi başına onaylamaz: verified kimlik KYC’yi ONAYLAMAZ, declined sonuç da reddetmez.

{
  "data": {
    "status": "verified",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:44:12Z",
    "configured": true
  }
}

5. Organizasyon sonucu sorgulama

GET /api/v1/organization/kyc/status polle edin. Olası durumlar not_started, pending (pre-gönderi transitory), pending_review, approved ve rejected; yanıt, karar verildiğinde gönderilen şirket alanlarını ve reviewed_at de echo alır.

cURL

curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "X-API-Key: $ORBIT_TEST_KEY"

Yanıt (200):

{
  "data": {
    "status": "pending_review",
    "company_name": "Acme Logistics Ltd.",
    "country": "US",
    "industry": "Lojistik",
    "submitted_at": "2026-09-04T09:12:33Z",
    "reviewed_at": null,
    "source": null
  },
  "meta": { "request_id": "req_ghi789", "timestamp": "2026-09-04T09:15:00Z" }
}

Eski SDK binaları ve el-yazılı entegrasyonlar bazen yol-explicit GET /api/v1/organization/kyc okur; aynı yanıt şekli verildiğinden /kyc/status hedeflemesi güvenli ve geriye uyumlu kalır. Uç nokta panelden veya bir sunucudan sorgulanabilir — veri tabanı anlık bir kesinti üzerinde 503 yerine nötr not_started okumasına döner ve sonraki sorgu kendini düzeltir.

6. Yeniden gönderim ve «zaten onaylanmış» tutumu

rejected bir organizasyonda formu yeniden POST etmek doğru hamledir: yazma pending_review’yi yeniden damgalar, form bloğunu geçersiz kılar ve düzeltilmiş yanıtlarla screening’i tekrar çalıştırır. Hâlâ pending_review olan bir yeniden gönderim da kabul edilir — uçan profili değiştirir. approved bir organizasyonu yeniden göndermeye çalışmak 409 verir:

{
  "error": {
    "code": "ALREADY_VERIFIED",
    "message": "KYC verification has already been approved",
    "status": 409
  }
}

Aynı guard idv oturumunda kimlik verified olduğunda geçerlidir — o zaman sesion uç noktasına POST 409 ALREADY_VERIFIED alır ve yeniden çekim ancak organizasyon reddedilmiş ve yeniden sürülmekteyse anlam kazanır.

7. Red ne demek ve ne yapmalı

Red bir insan kararıdır — operatör Devotel operasyon paneli’nde gezip form alanlarını artı screening ve IDV sinyallerini okur, approve veya reject’ya basar. Müşteri yüzeyi hiçbir mekanik rationale açıklamaz; karar e-postası boşluğu ve düzeltmeyi adlandırır. rejected durumunu action-ready sayın:

Gönderilen alanları doğruluk açısından yeniden okuyun (hatalı bir legal ad veya ince use-case en sık nedendir).
Her kyb eşleşmesi ve her declined IDV sonucu düzeltin.
Düzeltilmiş verilerle yeniden gönderin — uç nokta kabul eder, kuyruk yeniden sıralanır.

Red açıkça bir yanlışlık ise — örneğin verileriniz yerine operatör panelindeki bir yazım hatası — account id’si ve durum sorgusundan gelen req_* id’si ile destek üzerinden başvurun; inceleme kuyruğunun sahibi dosyayı yeniden açıp operatör tarafından onaylayabilir.

Bu kapı NE DEĞİLDIR: numara başı dokümanlar

Organizasyon KYC’si, taşıyıcıların sender başına istediği numara-başı doküman demetlerinin yanında durur — bunlar (işletme kaydı, adres kanıtı, kimlik) sahip olduğunuz belirli bir numarayı kapsar ve Uyum → Dokümanlar altında ayrı bir inceleme döngüsu izler. Organizasyon onayı bir numara-demetini çözmez, terside de öyle. O ayrı kayıt için numara-başı KYC dokümanlar kılavuzu bakın.

8. Onaylandıktan sonra — kalan go-live kapıları

Onay organizasyon sonucu basılı için GET /organization/kyc/status approved verir. Kalan iki kapıyı go-live checklist listesinden tamamlayın:

Canlı anahtarı cast. Ayarlar → API Keys altında dv_live_sk_ prefixi ile bir gizli anahtar oluştur ve sandbox dv_test_sk_ yerine koy — istek şekilleri aynedır, kod yeniden yazmak gerekmez.
Bakiyeyi doldur. Ayarlar → Billing altında fonlar ekleyin; SMS, WhatsApp ve ses bu cüzdandan düşer ve boş bakiyeli canlı gönderi bir faturation hatasıyla basarına uçar.
ABD SMS: 10DLC katman. Hedef ABD long-code’ları içeriyorsa, 10DLC marka + kampanya kaydı tamamlayın. KYC onayı taşıyıcı kaydı yerine geçmez; ABD SMS sandbox’tan çıkmadan önce iki kap da yeşil olmalı.

İki zorlu kapı ve kanal kayıtları tamamlandığında canlı gönderi sandbox gönderi ile aynı davranır — aynı uç nokta, aynı webhook envelope, başka onay döngüsuz.

İlgili referanslar

Go-live checklist — canlı trafiğin zorlu kapıları.
Sender-ID Registration — ülke başına doc_ kimlikleriyle desteklenen kayıtlar.
Numara başı KYC dokümanları — tenant-sahip doküman kütüphanesi.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Organizasyon KYC/KYB/IDV entegrasyonu

Organizasyon KYC/KYB/IDV entegrasyonu

1. Canlı trafiği neden engellenmiş

2. Formu gönderin

3. Pazar promosyonları — hedefinizin gerçekten istediği

Almanya — BNetzA varlık kimliği

İspanya — CNMC sender-id kaydı

Fransa — ARCEP gönderici kaydı

Türkiye — BTK gönderici adı

Arap pazarları — örneğin BAE TDRA

4. İsteğe bağlı: barındırılan IDV oturumu ekleme

5. Organizasyon sonucu sorgulama

6. Yeniden gönderim ve «zaten onaylanmış» tutumu

7. Red ne demek ve ne yapmalı

Bu kapı NE DEĞİLDIR: numara başı dokümanlar

8. Onaylandıktan sonra — kalan go-live kapıları

İlgili referanslar

​Organizasyon KYC/KYB/IDV entegrasyonu

​1. Canlı trafiği neden engellenmiş

​2. Formu gönderin

​3. Pazar promosyonları — hedefinizin gerçekten istediği

​Almanya — BNetzA varlık kimliği

​İspanya — CNMC sender-id kaydı

​Fransa — ARCEP gönderici kaydı

​Türkiye — BTK gönderici adı

​Arap pazarları — örneğin BAE TDRA

​4. İsteğe bağlı: barındırılan IDV oturumu ekleme

​5. Organizasyon sonucu sorgulama

​6. Yeniden gönderim ve «zaten onaylanmış» tutumu

​7. Red ne demek ve ne yapmalı

​Bu kapı NE DEĞİLDIR: numara başı dokümanlar

​8. Onaylandıktan sonra — kalan go-live kapıları

​İlgili referanslar

Organizasyon KYC/KYB/IDV entegrasyonu

1. Canlı trafiği neden engellenmiş

2. Formu gönderin

3. Pazar promosyonları — hedefinizin gerçekten istediği

Almanya — BNetzA varlık kimliği

İspanya — CNMC sender-id kaydı

Fransa — ARCEP gönderici kaydı

Türkiye — BTK gönderici adı

Arap pazarları — örneğin BAE TDRA

4. İsteğe bağlı: barındırılan IDV oturumu ekleme

5. Organizasyon sonucu sorgulama

6. Yeniden gönderim ve «zaten onaylanmış» tutumu

7. Red ne demek ve ne yapmalı

Bu kapı NE DEĞİLDIR: numara başı dokümanlar

8. Onaylandıktan sonra — kalan go-live kapıları

İlgili referanslar