POST/v1/users/import

Uvoz korisnika iz CSV-a

users_import

Pošaljite CSV datoteku u polju csv. Prvi redak je zaglavlje. Razdjelnik je , ili ; i određuje se iz zaglavlja. Kodiranje je UTF-8 (BOM je dopušten), s najviše 1000 redaka podataka.
Stupci: email (obavezno; alternativni nazivi e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; alternativni naziv роль), groups (группы; više grupa odvojite s | ili ;, prema ključu ili nazivu obične grupe), profile (data_profile, профиль; ključ podatkovnog profila). Nepoznati stupci preskaču se i navode u ignored_columns.

Sa dry_run: true (zadano) vraća pregled bez promjena: radnju i pogreške za svaki redak. Inače se izvršavaju retci bez pogrešaka:
- invite: šalje pozivnicu s ulogom, profilom i imenom iz datoteke. E-poruka se šalje ako je e-pošta konfigurirana, a poveznica se vraća u odgovoru.
- exists: korisnik s tom e-adresom već postoji. Korisnik se dodaje u grupe iz datoteke; uloga i profil se ne mijenjaju.
- pending: pozivnica na tu adresu već čeka prihvaćanje. Grupe iz datoteke dodaju joj se.

Retci s pogreškama preskaču se. Pozvani korisnici pridružuju se svojim grupama kad prihvate pozivnicu. create_groups stvara obične grupe koje nedostaju; bez njega nepoznata grupa je pogreška retka. Ograničenje korisnika plana i mjesta pretplate provjeravaju se za sve nove pozivnice odjednom: ako nisu dovoljni, ništa se ne izvršava (402). Ograničenje ručnih pozivnica (50 na čekanju) ne primjenjuje se na uvoz. Zahtijeva dopuštenje ORG_MANAGE_USERS. U revizijski zapisnik upisuje događaj users.import i invitation.create za svaku pozivnicu.

Autentifikacija

Pošaljite API ključ u zaglavlju Authorization: Authorization: Bearer <ključ>.

Parametri zaglavlja

Idempotency-Keystring
Ključ za siguran ponovni pokušaj upisa: od 1 do 255 ispisivih ASCII znakova; preporučuje se UUID v4 po logičkoj operaciji. Ponovni pokušaj s istim ključem unutar 24 sata ne izvodi operaciju ponovno: vraća spremljeni odgovor (status, zaglavlja i tijelo) sa zaglavljem Idempotency-Replayed: true. Isti ključ s drugom metodom, putanjom, Content-Type ili tijelom vraća 409 api.idempotency_mismatch; dok se prvi zahtjev još izvodi – 409 api.idempotency_in_progress s Retry-After: 1. Nakon odgovora 5xx ili 429 ključ se oslobađa i ponovni pokušaj ponovno izvodi operaciju. Ključ vrijedi u okviru organizacije i pozivatelja (API ključ, korisnik ili ključ vlastitog izvora).
length ≥ 1, length ≤ 255

Tijelo zahtjeva

application/json

Objekt: UsersImportRequest

csvstringobavezno
Sadržaj CSV datoteke u UTF-8.
length ≥ 1, length ≤ 2000000
dry_runboolean
Samo pregled (zadano). false izvršava retke bez pogrešaka.
Zadano: true
default_rolestring
Uloga za retke bez stupca role ili s praznom ćelijom.
Zadano: "viewer"
default_profilestring | null
Podatkovni profil za retke bez profila. Ako je prazno, koristi se zadani profil organizacije (administratori dobivaju puni pristup).
create_groupsboolean
Stvaranje nepostojećih običnih grupa. Bez ove oznake nepoznata grupa je pogreška retka.
Zadano: false
ttl_daysinteger
Valjanost pozivnica u danima.
Zadano: 7≥ 1, ≤ 30

Odgovori

200Pregled ili rezultat uvoza, redak po redak

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.
Idempotency-Replayed
true znači da je odgovor ponovljen iz spremljenog odgovora za ovaj Idempotency-Key: operacija se nije ponovno izvela.

application/json

Objekt: UsersImportResult

dry_runbooleanobavezno
totalintegerobavezno
Broj redaka s podacima u datoteci.
countsUsersImportCountsobavezno
delimiterstringobavezno
Razdjelnik utvrđen iz zaglavlja.
columnsarray of stringobavezno
Prepoznati stupci u kanonskom obliku (email, name, role, groups, profile).
ignored_columnsarray of stringobavezno
created_groupsarray of stringobavezno
Grupe stvorene tijekom izvršavanja.
limitUsersImportLimitobavezno
rowsarray of UsersImportRowobavezno

400Zahtjev nije valjan: vrijednost parametra ili stanje objekta ne dopušta radnju (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

401Vjerodajnice nisu poslane (ni kolačić sesije ni API ključ) ili ključ nije pronađen.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

402Organizacija je dosegla ograničenje plana (kartice, pohrana ili korisnici). `error.details` sadrži `kind`, `limit` i `used`.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

403Radnja nije dopuštena: uloga nije dovoljna, nema pristupa zbirci ili kartici, zahtjev se izvodi u načinu „View as” ili je organizacija suspendirana ili izbrisana (`detail` je objekt s `code: org_suspended | org_deleted`).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

413Tijelo zahtjeva premašuje dopuštenu veličinu.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

422Pogreška provjere valjanosti: tijelo ili parametri ne odgovaraju shemi (`detail` je popis pogrešaka provjere valjanosti) ili je vrijednost parametra izvan raspona (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

429Previše zahtjeva (`api.rate_limited`), kvota organizacije za minutu, dan ili mjesec je potrošena (`api.quota_exceeded`; `error.details` sadrži `quota`, `limit` i `reset_at`), dosegnuto je ograničenje organizacije ili je usluga odgovora zauzeta (`answers.engine_busy`). Pričekajte vrijeme navedeno u zaglavlju `Retry-After`.

Zaglavlja odgovora

Retry-After
Broj sekundi koje treba pričekati prije ponovnog pokušaja zahtjeva.
RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

Kodovi pogrešaka

Kodovi koje ova operacija može vratiti u error.code, uz opće kodove svakog zahtjeva.

Sigurni ponovni pokušaji

Uz svaki POST i PATCH pošaljite zaglavlje Idempotency-Key (na primjer UUID). Ponovni pokušaj s istim ključem unutar 24 sata vraća spremljeni odgovor umjesto da ponovno izvrši zahtjev.

Ograničenja učestalosti

Odgovori sadrže zaglavlja RateLimit i RateLimit-Policy te ranija zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odgovor 429 sadrži zaglavlje Retry-After u sekundama: pričekajte i pokušajte ponovno.

← users · Referenca API-ja

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"

Isprobajte

API ključ

Ključ ostaje u memoriji ove kartice preglednika i šalje se samo na https://api.sursa.com.

Zahtjevi djeluju na stvarne podatke vaše organizacije.

Idempotency-Key header

Idempotency-Key

Ako je polje prazno, za svaki se zahtjev stvara novi ključ.

Tijelo zahtjeva (JSON)