POST/v1/users/import

Импорт на потребители от CSV

users_import

Изпратете CSV файл в полето csv. Първият ред е заглавният. Разделителят е , или ; и се определя от заглавния ред. Кодирането е UTF-8 (BOM е разрешен), с до 1000 реда с данни.
Колони: email (задължителна; псевдоними e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; псевдоним роль), groups (группы; разделяйте няколко групи с | или ;, по ключ или по име на обикновена група), profile (data_profile, профиль; ключът на профила за достъп). Непознатите колони се пропускат и се изброяват в ignored_columns.

С dry_run: true (по подразбиране) връща преглед без промени: действието и грешките за всеки ред. Иначе се изпълняват редовете без грешки:
- invite: изпраща покана с ролята, профила и името от файла. Ако пощата е настроена, се изпраща имейл, а връзката се връща в отговора.
- exists: вече съществува потребител с този имейл. Потребителят се добавя към групите от файла; ролята и профилът не се променят.
- pending: покана до този адрес вече чака да бъде приета. Групите от файла се добавят към нея.

Редовете с грешки се пропускат. Поканените потребители се присъединяват към групите си, когато приемат поканата. create_groups създава липсващите обикновени групи; без него непозната група е грешка в реда. Лимитът на плана за потребители и местата в абонамента се проверяват за всички нови покани наведнъж: ако не стигат, нищо не се изпълнява (402). Лимитът за ръчни покани (50 чакащи) не се прилага при импорт. Изисква правото ORG_MANAGE_USERS. Записва в одитния дневник събитието users.import, а за всяка покана – invitation.create.

Удостоверяване

Изпратете API ключ в заглавката Authorization: Authorization: Bearer <ключ>.

Параметри в заглавката

Idempotency-Keystring
Ключ за безопасен повторен опит при запис: от 1 до 255 печатаеми ASCII знака; препоръчва се UUID v4 за всяка логическа операция. Повторен опит със същия ключ в рамките на 24 часа не изпълнява операцията отново: връща записания отговор (статус, заглавки и тяло) със заглавката Idempotency-Replayed: true. Същият ключ с друг метод, път, Content-Type или тяло връща 409 api.idempotency_mismatch, а докато първата заявка още се изпълнява – 409 api.idempotency_in_progress с Retry-After: 1. След отговор 5xx или 429 ключът се освобождава и повторният опит изпълнява операцията отново. Ключът важи в рамките на организацията и извикващия (API ключ, потребител или ключ на собствен източник).
length ≥ 1, length ≤ 255

Тяло на заявката

application/json

Обект: UsersImportRequest

csvstringзадължително
Съдържание на CSV файла в UTF-8.
length ≥ 1, length ≤ 2000000
dry_runboolean
Само преглед (по подразбиране). false изпълнява редовете без грешки.
По подразбиране: true
default_rolestring
Роля за редовете без колона role или с празна клетка.
По подразбиране: "viewer"
default_profilestring | null
Профил за достъп за редовете без профил. Ако е празно, се използва профилът по подразбиране на организацията (администраторите получават пълен достъп).
create_groupsboolean
Създаване на липсващите обикновени групи. Без този флаг непозната група е грешка в реда.
По подразбиране: false
ttl_daysinteger
Срок на валидност на поканите в дни.
По подразбиране: 7≥ 1, ≤ 30

Отговори

200Преглед или резултат от импорта, ред по ред

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.
Idempotency-Replayed
true означава, че отговорът е възпроизведен от записания за този Idempotency-Key: операцията не е изпълнена отново.

application/json

Обект: UsersImportResult

dry_runbooleanзадължително
totalintegerзадължително
Брой редове с данни във файла.
countsUsersImportCountsзадължително
delimiterstringзадължително
Разделител, определен по заглавния ред.
columnsarray of stringзадължително
Разпознати колони в каноничен вид (email, name, role, groups, profile).
ignored_columnsarray of stringзадължително
created_groupsarray of stringзадължително
Групи, създадени по време на изпълнението.
limitUsersImportLimitзадължително
rowsarray of UsersImportRowзадължително

400Заявката е невалидна: стойност на параметър или състоянието на обекта не позволява действието (`detail` е съобщение).

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

401Не са изпратени идентификационни данни (нито бисквитка на сесията, нито API ключ) или ключът не е намерен.

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

402Организацията е достигнала лимит на плана (карти, хранилище или потребители). `error.details` съдържа `kind`, `limit` и `used`.

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

403Действието не е разрешено: ролята е недостатъчна, няма достъп до колекцията или картата, заявката се изпълнява в режим „View as“ или организацията е спряна или изтрита (`detail` е обект с `code: org_suspended | org_deleted`).

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

413Тялото на заявката надвишава допустимия размер.

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

422Грешка при валидиране: тялото или параметрите не съответстват на схемата (`detail` е списък с грешки при валидиране) или стойност на параметър е извън допустимия диапазон (`detail` е съобщение).

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

429Твърде много заявки (`api.rate_limited`), квотата на организацията за минутата, деня или месеца е изчерпана (`api.quota_exceeded`; `error.details` съдържа `quota`, `limit` и `reset_at`), достигнат е лимит на организацията или услугата за отговори е заета (`answers.engine_busy`). Изчакайте времето от заглавката `Retry-After`.

Заглавки на отговора

Retry-After
Брой секунди, които да изчакате, преди да повторите заявката.
RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

Кодове на грешки

Кодове, които тази операция може да върне в error.code, освен общите кодове на всяка заявка.

Безопасни повторни опити

Изпращайте заглавката Idempotency-Key (например UUID) с всяка заявка POST и PATCH. Повторен опит със същия ключ в рамките на 24 часа връща запазения отговор, вместо да изпълни заявката отново.

Лимити на честотата

Отговорите съдържат заглавките RateLimit и RateLimit-Policy, както и по-ранните X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Отговорът 429 съдържа Retry-After в секунди: изчакайте и опитайте отново.

← users · Справочник на API

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"

Изпробвайте

API ключ

Ключът остава само в паметта на този раздел на браузъра и се изпраща единствено до https://api.sursa.com.

Заявките работят с реалните данни на организацията ви.

Idempotency-Key header

Idempotency-Key

Ако полето е празно, за всяка заявка се генерира нов ключ.

Тяло на заявката (JSON)