POST/v1/users/import

Kullanıcıları CSV’den içe aktarma

users_import

csv alanında bir CSV dosyası gönderin. İlk satır başlık satırıdır. Ayırıcı , ya da ; olur ve başlık satırından belirlenir. Kodlama UTF-8’dir (BOM kullanılabilir), en fazla 1000 veri satırı.
Sütunlar: email (zorunlu; diğer adları e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; diğer adı роль), groups (группы; birden çok grubu | ya da ; ile ayırın, normal bir grubun anahtarına ya da adına göre), profile (data_profile, профиль; veri profilinin anahtarı). Bilinmeyen sütunlar atlanır ve ignored_columns içinde listelenir.

dry_run: true ile (varsayılan) değişiklik yapmadan bir önizleme döndürür: her satır için eylem ve hatalar. Aksi hâlde hatasız satırlar yürütülür:
- invite: dosyadaki rol, profil ve adla bir davet gönderir. E-posta yapılandırılmışsa bir e-posta gönderilir ve bağlantı yanıtta döndürülür.
- exists: bu e-posta adresine sahip bir kullanıcı zaten var. Kullanıcı dosyadaki gruplara eklenir; rol ve profil değişmez.
- pending: bu adrese gönderilmiş bir davet zaten kabul edilmeyi bekliyor. Dosyadaki gruplar davete eklenir.

Hatalı satırlar atlanır. Davet edilen kullanıcılar daveti kabul ettiklerinde gruplarına katılır. create_groups eksik normal grupları oluşturur; bu parametre olmadan bilinmeyen bir grup satır hatasıdır. Planın kullanıcı limiti ve aboneliğin kullanıcı lisansları tüm yeni davetler için birlikte denetlenir: yetmezse hiçbir şey yürütülmez (402). Elle davet limiti (50 bekleyen) içe aktarmalar için geçerli değildir. ORG_MANAGE_USERS izni gerektirir. Denetim kaydına users.import olayını ve her davet için invitation.create olayını yazar.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Başlık parametreleri

Idempotency-Keystring
Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).
length ≥ 1, length ≤ 255

İstek gövdesi

application/json

Nesne: UsersImportRequest

csvstringzorunlu
UTF-8 biçiminde CSV dosyasının içeriği.
length ≥ 1, length ≤ 2000000
dry_runboolean
Yalnızca önizleme (varsayılan). false hatasız satırları yürütür.
Varsayılan: true
default_rolestring
role sütunu olmayan ya da hücresi boş satırlar için rol.
Varsayılan: "viewer"
default_profilestring | null
Profili olmayan satırlar için veri profili. Boşsa kuruluşun varsayılan profili kullanılır (yöneticiler tam erişim alır).
create_groupsboolean
Eksik normal grupları oluşturur. Bu bayrak olmadan bilinmeyen bir grup satır hatasıdır.
Varsayılan: false
ttl_daysinteger
Davetlerin gün cinsinden geçerlilik süresi.
Varsayılan: 7≥ 1, ≤ 30

Yanıtlar

200İçe aktarmanın satır satır önizlemesi ya da sonucu

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.
Idempotency-Replayed
true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: UsersImportResult

dry_runbooleanzorunlu
totalintegerzorunlu
Dosyadaki veri satırı sayısı.
countsUsersImportCountszorunlu
delimiterstringzorunlu
Başlık satırından algılanan ayırıcı.
columnsarray of stringzorunlu
Standart biçimde tanınan sütunlar (email, name, role, groups, profile).
ignored_columnsarray of stringzorunlu
created_groupsarray of stringzorunlu
Yürütme sırasında oluşturulan gruplar.
limitUsersImportLimitzorunlu
rowsarray of UsersImportRowzorunlu

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

402Kuruluş bir plan limitine ulaştı (kartlar, depolama ya da kullanıcılar). `error.details` alanında `kind`, `limit` ve `used` bulunur.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

413İstek gövdesi izin verilen en büyük boyutu aşıyor.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

Retry-After
İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.
RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← users · API başvurusu

curl -X POST 'https://api.sursa.com/v1/users/import' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"csv":"string"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Dene

API anahtarı

Anahtar bu sekmenin belleğinde kalır ve yalnızca https://api.sursa.com adresine gönderilir.

İstekler kuruluşunuzun gerçek verileri üzerinde çalışır.

Idempotency-Key header

Idempotency-Key

Bu alan boş bırakılırsa her istek için yeni bir anahtar oluşturulur.

İstek gövdesi (JSON)