POST/v1/cards/bulk

Utfør en massehandling på kort

bulk_cards

Utfører en massehandling på de valgte kortene. Tillatelsene kontrolleres for hvert kort: rollen i samlingen og dataprofilen (destruktive handlinger krever tilgang til alle deler av dokumentet). Kort du ikke kan utføre handlingen på, hoppes over med en begrunnelse. Hver endring skrives til kortets revisjonslogg, i tillegg til én cards.bulk-post med resultatet.

Handlinger for mapper:
- folder_move med params.folder_id (obligatorisk) legger kortet i mappen og fjerner det fra mappen params.from_folder_id hvis den sendes (flytting ut av den åpne mappen).
- folder_remove med params.folder_id fjerner kortet fra mappen; kortet blir værende i samlingen.

Mappene kontrolleres én gang per forespørsel: en mappe som mangler eller ikke er synlig, returnerer 404 folders.not_found, manglende tillatelse COLLECTION_EDIT_CARDS på mappen returnerer 403 authz.forbidden, og en manglende folder_id eller en from_folder_id fra en annen samling returnerer 400 cards.bulk_invalid. For hvert kort: uten CARD_EDIT hoppes kortet over som no_write; et kort fra en annen samling enn mappen hoppes over som collection_mismatch; et kort som allerede er på plass, rapporteres som unchanged.

Autentisering

Send en API-nøkkel i headeren Authorization: Authorization: Bearer <nøkkel>.

Headerparametere

Idempotency-Keystring
Nøkkel for et trygt nytt forsøk på en skriveoperasjon: 1 til 255 utskrivbare ASCII-tegn; en UUID v4 per logisk operasjon anbefales. Et nytt forsøk med samme nøkkel innen 24 timer kjører ikke operasjonen på nytt: det returnerer det lagrede svaret (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøkkel med en annen metode, bane, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første forespørselen fortsatt kjører, 409 api.idempotency_in_progress med Retry-After: 1. Etter et 5xx- eller 429-svar frigjøres nøkkelen, og et nytt forsøk kjører operasjonen på nytt. Nøkkelen gjelder per organisasjon og per kaller (API-nøkkel, bruker eller nøkkel for en egendefinert kilde).
length ≥ 1, length ≤ 255
X-View-Asstring
Bare for API-nøkler med rollen admin. Utfører forespørselen som dataprofilen <profile>[:viewer|verifier|editor], for eksempel employee:viewer. Installasjonsnøkkelen kan ikke bruke denne headeren (403).

Parametere i informasjonskapsler

kb_view_asstring
Informasjonskapsel for modusen «View as» (vis som) i en økt. POST /auth/view-as setter den, og DELETE /auth/view-as fjerner den.

Forespørselens brødtekst

application/json

Objekt: BulkRequest

idsarray of stringobligatorisk
items ≥ 1, items ≤ 500
actionBulkActionobligatorisk
paramsobject

Svar

200Vellykket svar

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.
Idempotency-Replayed
true betyr at svaret ble gjentatt fra det lagrede svaret for denne Idempotency-Key: operasjonen ble ikke kjørt på nytt.

application/json

Objekt: BulkResult

countsobjectobligatorisk
Felt
- doneintegerobligatorisk
- reasonsobjectobligatorisk
  Felt
  - admin_onlynumber
  - collection_mismatchinteger
  - connectornumber
  - failedinteger
  - needs_usernumber
  - no_verifynumber
  - no_writenumber
  - not_foundnumber
  - partial_accessnumber
  - processinginteger
  - same_collectionnumber
  - sensitive_lowernumber
  - target_needs_reindexnumber
  - unchangedinteger
- skippedintegerobligatorisk
donearray of stringobligatorisk
fileAttachment
jobsarray of integer
skippedarray of BulkSkippedobligatorisk

400Forespørselen er ugyldig: en parameterverdi eller objektets tilstand tillater ikke handlingen (`detail` er en melding).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

401Ingen påloggingsinformasjon ble sendt (verken øktinformasjonskapsel eller API-nøkkel), eller nøkkelen ble ikke funnet.

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

403Handlingen er ikke tillatt: rollen er utilstrekkelig, det finnes ingen tilgang til samlingen eller kortet, forespørselen kjører i modusen «View as», eller organisasjonen er suspendert eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

404Objektet finnes ikke eller er ikke tilgjengelig for deg. API-et bekrefter ikke at et objekt med begrenset tilgang finnes.

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

422Valideringsfeil: brødteksten eller parameterne samsvarer ikke med skjemaet (`detail` er en liste over valideringsfeil), eller en parameterverdi er utenfor tillatt område (`detail` er en melding).

Headere i svaret

RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

429For mange forespørsler (`api.rate_limited`), organisasjonens kvote for minuttet, døgnet eller måneden er brukt opp (`api.quota_exceeded`; `error.details` inneholder `quota`, `limit` og `reset_at`), organisasjonens grense er nådd, eller svartjenesten er opptatt (`answers.engine_busy`). Vent så lenge som headeren `Retry-After` angir.

Headere i svaret

Retry-After
Antall sekunder du skal vente før du prøver forespørselen på nytt.
RateLimit-Policy
Gjeldende grenser i formatet fra IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerte elementer "<name>";q=<quota>;w=<window in seconds>. key er forespørselsraten til API-nøkkelen (kvoten er burst, tidsvinduet er tiden det tar å fylle den helt opp igjen; for en økt er det user, uten påloggingsinformasjon ip); minute, day og month er organisasjonens kvoter for kalenderminuttet, kalenderdøgnet og kalendermåneden i UTC.
RateLimit
Hva som gjenstår av hver grense i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grensen for den strengeste oppføringen i RateLimit-Policy (den med færrest gjenværende forespørsler).
X-RateLimit-Remaining
Gjenværende forespørsler under den strengeste grensen.
X-RateLimit-Reset
Sekunder til den strengeste grensen nullstilles.

application/json

Objekt: Error

Feilkoder

Kodene denne operasjonen kan returnere i error.code, i tillegg til de generelle kodene for alle forespørsler.

Trygge nye forsøk

Send en Idempotency-Key-header (for eksempel en UUID) med hver POST og PATCH. Et nytt forsøk med samme nøkkel innen 24 timer returnerer det lagrede svaret i stedet for å kjøre forespørselen på nytt.

Hastighetsgrenser

Svarene har headerne RateLimit og RateLimit-Policy og de eldre X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og prøv på nytt.

← cards · API-referanse

curl -X POST 'https://api.sursa.com/v1/cards/bulk' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ids":["string"],"action":"verify"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prøv

API-nøkkel

Nøkkelen lagres bare i minnet til denne fanen og sendes bare til https://api.sursa.com.

Forespørslene utføres på de faktiske dataene i organisasjonen din.

Idempotency-Key header

X-View-As header

Idempotency-Key

Når feltet er tomt, genereres en ny nøkkel for hver forespørsel.

Forespørselens brødtekst (JSON)