POST/v1/push/sources/{source_id}/documents/batch

Slanje paketa dokumenata

push_upsert_documents

Šalje do 500 JSON dokumenata (najviše 50 MiB po zahtjevu; od verzije 1.62.0, prije 100 i 20 MB) i do 1000 brisanja prema external_id (deletes, od verzije 1.62.0) u jednom zahtjevu. Svaki dokument je kao u push_upsert_document; datoteke se šalju samo kao učitavanja u dijelovima (upload_id, attachments). Rezultat se navodi po dokumentu: created, updated, unchanged, deleted, not_found ili error s razlogom, a od verzije 1.62.0 i rezultat dokumenta: status (pending, processing, indexed, failed, removed), card_id i neutralni kod reason. Bez atomic pogreška u jednom dokumentu ne otkazuje ostale. S atomic: true paket se primjenjuje u cijelosti ili nikako: prvo odbijanje vraća 422 sources.push_batch_rejected s rezultatom svakog dokumenta u error.details.results (dokumenti bez pogrešaka su skipped). Ponavljanje paketa s istim Idempotency-Key vraća prethodni odgovor; ponavljanje bez ključa ne stvara druge kartice, jer je isti dokument unchanged.

Autentifikacija

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

Parametri putanje

source_idintegerobavezno

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: PushDocumentBatch

sync_numberinteger
Broj otvorene sinkronizacije. Bez njega dokumenti se zapisuju kao izravno stvaranje ili zamjena.
documentsarray of PushDocument
items ≤ 500
deletesarray of string
external_id dokumenata za brisanje (od verzije 1.62.0). Unutar sinkronizacije brisanje se pojavljuje u rezultatima dokumenata sinkronizacije. external_id ne može biti istodobno u documents i u deletes.
items ≤ 1000
atomicboolean
Sve ili ništa (od verzije 1.62.0): ako je bilo koji dokument odbijen, odgovor je 422 sources.push_batch_rejected i ništa se ne zapisuje.
Zadano: false

Odgovori

200Rezultati po dokumentima

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: PushDocumentBatchResult

resultsarray of PushDocumentResultobavezno
Rezultati redoslijedom paketa: najprije dokumenti, zatim brisanja.

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

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

404Objekt ne postoji ili vam nije dostupan. API ne potvrđuje postojanje ograničenog objekta.

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

409Stanje objekta ne dopušta radnju, na primjer duplikat, indeksiranje u tijeku ili posao koji je već obrađ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

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.

← sources · Referenca API-ja

curl -X POST 'https://api.sursa.com/v1/push/sources/1/documents/batch' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sync_number":1,"documents":[{"external_id":"crm-1042","title":"Refund policy"}],"deletes":["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

source_id path *

Idempotency-Key

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

Tijelo zahtjeva (JSON)