POST/v1/users/import

Import użytkowników z CSV

users_import

Wyślij plik CSV w polu csv. Pierwszy wiersz to nagłówek. Separatorem jest , lub ; i jest on wykrywany na podstawie nagłówka. Kodowanie to UTF-8 (dozwolony jest BOM), do 1000 wierszy danych.
Kolumny: email (wymagana; aliasy e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; alias роль), groups (группы; kilka grup rozdziel znakiem | lub ;, według klucza lub nazwy zwykłej grupy), profile (data_profile, профиль; klucz profilu dostępu). Nieznane kolumny są pomijane i wymieniane w ignored_columns.

Z dry_run: true (domyślnie) zwraca podgląd bez zmian: działanie i błędy dla każdego wiersza. W przeciwnym razie wykonywane są wiersze bez błędów:
- invite: wysyła zaproszenie z rolą, profilem oraz imieniem i nazwiskiem z pliku. Jeśli poczta jest skonfigurowana, wysyłana jest wiadomość e-mail, a link jest zwracany w odpowiedzi.
- exists: użytkownik z tym adresem e-mail już istnieje. Użytkownik jest dodawany do grup z pliku; rola i profil się nie zmieniają.
- pending: zaproszenie na ten adres czeka już na przyjęcie. Grupy z pliku są do niego dodawane.

Wiersze z błędami są pomijane. Zaproszeni użytkownicy dołączają do swoich grup po przyjęciu zaproszenia. create_groups tworzy brakujące zwykłe grupy; bez niego nieznana grupa jest błędem wiersza. Limit użytkowników planu i licencje abonamentu są sprawdzane łącznie dla wszystkich nowych zaproszeń: jeśli nie wystarczają, nic nie jest wykonywane (402). Limit zaproszeń ręcznych (50 oczekujących) nie dotyczy importów. Wymaga uprawnienia ORG_MANAGE_USERS. Zapisuje w dzienniku audytu zdarzenie users.import, a dla każdego zaproszenia – invitation.create.

Uwierzytelnianie

Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.

Parametry nagłówka

Idempotency-Keystring
Klucz bezpiecznego ponowienia zapisu: od 1 do 255 drukowalnych znaków ASCII; zalecany jest UUID v4 na każdą operację logiczną. Ponowienie z tym samym kluczem w ciągu 24 godzin nie wykonuje operacji ponownie: zwraca zapisaną odpowiedź (status, nagłówki i treść) z nagłówkiem Idempotency-Replayed: true. Ten sam klucz z inną metodą, ścieżką, Content-Type lub treścią zwraca 409 api.idempotency_mismatch; dopóki pierwsze żądanie jest jeszcze wykonywane – 409 api.idempotency_in_progress z Retry-After: 1. Po odpowiedzi 5xx lub 429 klucz zostaje zwolniony, a ponowienie wykonuje operację jeszcze raz. Klucz obowiązuje w obrębie organizacji i wywołującego (klucz API, użytkownik lub klucz własnego źródła).
length ≥ 1, length ≤ 255

Treść żądania

application/json

Obiekt: UsersImportRequest

csvstringwymagane
Zawartość pliku CSV w UTF-8.
length ≥ 1, length ≤ 2000000
dry_runboolean
Tylko podgląd (domyślnie). false wykonuje wiersze bez błędów.
Domyślnie: true
default_rolestring
Rola dla wierszy bez kolumny role lub z pustą komórką.
Domyślnie: "viewer"
default_profilestring | null
Profil dostępu dla wierszy bez profilu. Jeśli pole jest puste, używany jest domyślny profil organizacji (administratorzy otrzymują pełny dostęp).
create_groupsboolean
Tworzy brakujące zwykłe grupy. Bez tej flagi nieznana grupa jest błędem wiersza.
Domyślnie: false
ttl_daysinteger
Ważność zaproszeń w dniach.
Domyślnie: 7≥ 1, ≤ 30

Odpowiedzi

200Podgląd lub wynik importu, wiersz po wierszu

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.
Idempotency-Replayed
true oznacza, że odpowiedź została odtworzona z odpowiedzi zapisanej dla tego Idempotency-Key: operacja nie została wykonana ponownie.

application/json

Obiekt: UsersImportResult

dry_runbooleanwymagane
totalintegerwymagane
Liczba wierszy danych w pliku.
countsUsersImportCountswymagane
delimiterstringwymagane
Separator wykryty na podstawie nagłówka.
columnsarray of stringwymagane
Rozpoznane kolumny w postaci kanonicznej (email, name, role, groups, profile).
ignored_columnsarray of stringwymagane
created_groupsarray of stringwymagane
Grupy utworzone podczas wykonania.
limitUsersImportLimitwymagane
rowsarray of UsersImportRowwymagane

400Żądanie jest nieprawidłowe: wartość parametru lub stan obiektu nie pozwala na to działanie (`detail` zawiera komunikat).

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

402Organizacja osiągnęła limit planu (karty, miejsce na dane lub użytkownicy). `error.details` zawiera `kind`, `limit` i `used`.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

403Działanie jest niedozwolone: rola jest niewystarczająca, brak dostępu do kolekcji lub karty, żądanie jest wykonywane w trybie „View as” albo organizacja jest zawieszona lub usunięta (`detail` to obiekt z `code: org_suspended | org_deleted`).

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

413Treść żądania przekracza dozwolony rozmiar.

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

422Błąd walidacji: treść lub parametry nie odpowiadają schematowi (`detail` to lista błędów walidacji) albo wartość parametru jest poza zakresem (`detail` zawiera komunikat).

Nagłówki odpowiedzi

RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

429Zbyt wiele żądań (`api.rate_limited`), wyczerpano przydział organizacji na minutę, dzień lub miesiąc (`api.quota_exceeded`; `error.details` zawiera `quota`, `limit` i `reset_at`), osiągnięto limit organizacji albo usługa odpowiedzi jest zajęta (`answers.engine_busy`). Odczekaj czas podany w nagłówku `Retry-After`.

Nagłówki odpowiedzi

Retry-After
Liczba sekund oczekiwania przed ponowieniem żądania.
RateLimit-Policy
Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.
RateLimit
Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).
X-RateLimit-Remaining
Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.
X-RateLimit-Reset
Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

Kody błędów

Kody, które ta operacja może zwrócić w error.code, oprócz ogólnych kodów każdego żądania.

Bezpieczne ponawianie

Wysyłaj nagłówek Idempotency-Key (na przykład UUID) z każdym żądaniem POST i PATCH. Ponowienie z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź, zamiast ponownie wykonywać żądanie.

Limity częstotliwości

Odpowiedzi zawierają nagłówki RateLimit i RateLimit-Policy oraz starsze X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź 429 ma nagłówek Retry-After w sekundach: odczekaj i ponów żądanie.

← users · Dokumentacja 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"

Wypróbuj

Klucz API

Klucz zostaje w pamięci tej karty przeglądarki i jest wysyłany tylko do https://api.sursa.com.

Żądania działają na prawdziwych danych Twojej organizacji.

Idempotency-Key header

Idempotency-Key

Gdy to pole jest puste, dla każdego żądania generowany jest nowy klucz.

Treść żądania (JSON)