Imports and exports

CSV import of contacts (upload, preview, run) and CSV exports.

Technická referencia je v angličtine (rovnako ako strojovo čitateľný dokument OpenAPI). Celú skupinu pre AI agenta načítate z /api/openapi.json?tag=Imports%20and%20exports.

Prihlásenie: Authorization: Bearer pst_... alebo HTTP Basic (e-mail člena firmy a API kľúč).

Operácie

Metóda	Cesta	Popis
GET	`/api/v1/tenants/{tenant}/export-fields`	Fields an export can contain
GET	`/api/v1/tenants/{tenant}/exports`	List exports
POST	`/api/v1/tenants/{tenant}/exports`	Start a CSV export
GET	`/api/v1/tenants/{tenant}/exports/{export_id}`	Get an export
GET	`/api/v1/tenants/{tenant}/exports/{export_id}/download`	Download an export (CSV)
GET	`/api/v1/tenants/{tenant}/imports`	List imports
POST	`/api/v1/tenants/{tenant}/imports`	Start an import
POST	`/api/v1/tenants/{tenant}/imports/drafts`	Start an import draft (wizard)
GET	`/api/v1/tenants/{tenant}/imports/drafts/{import_id}`	Get an import draft
PUT	`/api/v1/tenants/{tenant}/imports/drafts/{import_id}`	Save an import draft
POST	`/api/v1/tenants/{tenant}/imports/files`	Upload a CSV file for import
POST	`/api/v1/tenants/{tenant}/imports/preview`	Preview an import: mapping, counts, problems
GET	`/api/v1/tenants/{tenant}/imports/{import_id}`	Get an import with its progress and result
DELETE	`/api/v1/tenants/{tenant}/imports/{import_id}`	Delete an import record

Fields an export can contain

GET /api/v1/tenants/{tenant}/export-fields

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Odpovede

200 OK: application/json object

Chyby

Stav	Kód	Hodnoty `message`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
429		429 rate_limited: wait Retry-After seconds.

List exports

GET /api/v1/tenants/{tenant}/exports

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`idFrom`	query	string	nie
`idTo`	query	string	nie
`name`	query	string	nie
`page`	query	integer	nie	Page number, from 1. default `1`, min 1
`pageSize`	query	integer	nie	Items per page, 1 to 100. default `25`, min 1, max 100
`q`	query	string	nie	Search text (case and diacritics insensitive). max 200 chars
`sort`	query	string	nie	Sort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
`status`	query	string	nie	Status filter.

Odpovede

200 OK: application/json object

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`	q, sort, status
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
429		429 rate_limited: wait Retry-After seconds.

Start a CSV export

POST /api/v1/tenants/{tenant}/exports

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json): Required by the server: name, selection.

Pole	Typ	Povinné
`name`	string	áno
`selection`	one of: `bounced`, `blacklisted`, `all`, `lists`	áno
`listIds`	array of string	nie
`fields`	array of string	áno
`purposeIds`	array of string	nie
`encoding`	one of: `utf-8`, `windows-1250`	áno

Odpovede

201 Created: application/json ExportSummary

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
429		429 rate_limited: wait Retry-After seconds.

Get an export

GET /api/v1/tenants/{tenant}/exports/{export_id}

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`export_id`	path	string	áno	Id of the export (string of digits).

Odpovede

200 OK: application/json ExportSummary

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Download an export (CSV)

GET /api/v1/tenants/{tenant}/exports/{export_id}/download

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`export_id`	path	string	áno	Id of the export (string of digits).

Odpovede

200 OK: text/csv string

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
409	`conflict`	status
410	`expired`	export
429		429 rate_limited: wait Retry-After seconds.

List imports

GET /api/v1/tenants/{tenant}/imports

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: list_imports

Imports with status and counts.

Poznámky kontraktu (cs): Seznam (nejnovější první, page, pageSize) položek ImportSummary: { "id", "name", "status", "kind", "fileName", "shopId", "mode", "listIds", "createdAt", "startedAt", "finishedAt", "progress": { "processed", "total" }, "counts" }. Grid SE „Všechny importy“ (audit IM-01): q (slova názvu), Filtry idFrom, idTo, name, status (draft, queued, running, finished, failed; jiný stav nebo nečíselné ID 400), řazení navíc lists (počet vybraných seznamů); položka seznamu nese listNames (názvy vybraných seznamů v jejich pořadí). Stejné Filtry (idFrom, idTo, name, status exportu) bere GET …/exports (EX-01). Detail ImportDetail navíc source, purposeId, addedToLists (nová členství), errors (prvních 50 chybných řádků { "row", "error", "field" }) a report (ImportReport, null do dokončení).

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`idFrom`	query	string	nie
`idTo`	query	string	nie
`name`	query	string	nie
`page`	query	integer	nie	Page number, from 1. default `1`, min 1
`pageSize`	query	integer	nie	Items per page, 1 to 100. default `25`, min 1, max 100
`q`	query	string	nie	Search text (case and diacritics insensitive). max 200 chars
`sort`	query	string	nie	Sort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
`status`	query	string	nie	Status filter.

Odpovede

200 OK: application/json object

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`	q, sort, status
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
429		429 rate_limited: wait Retry-After seconds.

Start an import

POST /api/v1/tenants/{tenant}/imports

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: start_import (cez MCP len s náhľadom a potvrdením)

Runs an import. upsert and update_only need purposeId and consentConfirmed true; unsubscribe, remove and blacklist leave both out.

Poznámky kontraktu (cs): Tělo ImportRequest = ImportPlan a navíc name (1 až 100 znaků), source (odkud kontakty jsou, 1 až 200), purposeId (účel tenanta), consentConfirmed (musí být true: uživatel potvrzuje doložený a platný účel u všech kontaktů), nepovinně runAutomations (boolean, výchozí false). Chyby 400 name, source, purpose, consent, runAutomations (není boolean) a chyby náhledu.

Import nespouští automatizace (migrace 0077): kontakty, členství v seznamech, změny stavu v seznamu, změny polí a potlačení, které import zapíše, nespustí žádný spouštěč (přidání do seznamu, změna stavu v seznamu, přihlášení, nový kontakt, změna kontaktu, blacklist), jinak by tisíce importovaných lidí dostaly e-mail najednou. Jen když uživatel výslovně zaškrtne runAutomations: true, chová se import jako běžný zápis a automatizace spustí. Stejně tak přechod ze SmartEmailingu a jeho hodinová synchronizace nespouští automatizace nikdy. ImportDetail vrací runAutomations.
Opt-out režimy (unsubscribe, remove, blacklist) nezapisují žádný profil ani souhlas, takže purposeId a consentConfirmed jsou u nich nepovinné: klíč musí v těle úplně chybět (prázdný řetězec je pořád neplatné id a vrátí 400 purpose), server si pro záznam dosadí první účel tenanta; consentConfirmed se u nich vůbec nekontroluje. U ostatních režimů platí povinnost jako dřív.
Výsledek se rozhoduje stejně jako v náhledu. Nový kontakt: stav subscribed (bez souhlasu customer), source = import (u druhů Shoptetu shoptet), consent_basis = imported (bez souhlasu none), jazyk podle e-shopu, když ho soubor nemá. Jeden e-mail = jeden kontakt bez ohledu na zdroj: aktualizace přepíše jen neprázdné hodnoty, které se liší, nikdy e-mail a nikdy pole, které upravil člověk v Poštárně (editedFields kontaktu). Přidání do seznamů jako confirmed (u pending unconfirmed), jen se souhlasem; kdo se ze seznamu odhlásil, zůstane odhlášený.
Server ke každému kontaktu se souhlasem zapíše souhlas (consents: účel, valid_from = datum souhlasu ze souboru, jinak teď, valid_until podle platnosti účelu) a záznam do consent_log se zdrojem importu (import nebo shoptet); opt-out režimy žádný souhlas nezapisují, jen consent_log (list_unsubscribed, suppressed). Každý kontakt, kterého se řádek týká, dostane záznam zdroje (sources v detailu kontaktu: zdroj, co říká o souhlasu, kdy byl vidět poprvé a naposledy; u Shoptetu jeden záznam na e-shop).
Odpověď ImportDetail (viz níže). Do 1 000 řádků server import provede hned (finished), větší zařadí jako úlohu (queued, running): worker ho zpracuje po dávkách 2 000 řádků, po každé dávce uloží průběh (progress) a po restartu pokračuje od posledního uloženého řádku. UI se ptá GET /imports/{id}, dokud není finished nebo failed. Po dokončení přijde notifikace import_finished. Mock import provede hned.

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json)

Pole	Typ	Povinné	Popis
`name`	string	áno
`source`	string	áno	Where the contacts come from (se-spec 01 §7.1), e.g. a trade fair.
`purposeId`	string	nie	Purpose of processing given to the imported contacts. Optional for OPT_OUT_MODES (the server stores the tenant's first purpose when omitted; those modes write no consent).
`consentConfirmed`	boolean	nie	The user confirms a documented, valid purpose for every contact; must be true. Not required for OPT_OUT_MODES.
`runAutomations`	boolean	nie	Explicit opt-in: what the import writes starts automations (added to a list, subscribed, contact created ...). Default false: an import is a bulk write that starts none.
`options`	ImportOptions	nie	Autofill, start of the purpose consent and the double opt-in e-mail (SE wizard).
`draftId`	string	nie	The wizard's draft this import comes from (deleted when the import starts).
`fileId`	string	áno
`mapping`	ImportMapping	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	nie	Default csv.
`subscribersConfirmed`	boolean	nie	A Shoptet newsletter export without a consent column: the person confirmed that every row is an active subscriber (required, 400 subscribers otherwise).
`shopId`	string	áno	Main shop of new contacts; lists must belong to it or to the whole company.
`listIds`	array of string	áno

Odpovede

201 Created: application/json ImportDetail

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`	consent, draftId, purpose, runAutomations
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Start an import draft (wizard)

POST /api/v1/tenants/{tenant}/imports/drafts

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

SE "Rozpracováno": the wizard saves itself after its first step. Body {name, source, step, state, fileId?, shopId?}; 201 ImportDraft.

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json)

Pole	Typ	Povinné
`name`	string	nie
`source`	string	nie
`step`	number	nie
`state`	ImportDraftState	nie
`fileId`	string or null	nie
`shopId`	string or null	nie

Odpovede

201 Created: application/json ImportDraft

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Get an import draft

GET /api/v1/tenants/{tenant}/imports/drafts/{import_id}

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`import_id`	path	string	áno	Id of the import (string of digits).

Odpovede

200 OK: application/json ImportDraft

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Save an import draft

PUT /api/v1/tenants/{tenant}/imports/drafts/{import_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`import_id`	path	string	áno	Id of the import (string of digits).

Telo požiadavky (application/json)

Pole	Typ	Povinné
`name`	string	nie
`source`	string	nie
`step`	number	nie
`state`	ImportDraftState	nie
`fileId`	string or null	nie
`shopId`	string or null	nie

Odpovede

200 OK: application/json ImportDraft

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Upload a CSV file for import

POST /api/v1/tenants/{tenant}/imports/files

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: upload_import_csv

Uploads CSV text for an import (header row, ; , or tab, up to 5 MB of text; larger files through the administration, up to 64 MB and 300 000 rows). Answers fileId, columns, sample rows, suggestedKind and suggestedMapping.

multipart/form-data with the field file (up to imports.MAX_BYTES; werkzeug spools it to a temporary file, it is read from there as a stream) or JSON {text} (pasted, up to imports.TEXT_MAX_BYTES). 201 with the stored file, its encoding and the suggested kind and mapping.

Poznámky kontraktu (cs): Soubor jako multipart/form-data v poli file (nejvýš 64 MB), nebo vložený text jako JSON { "text": "…" } (nejvýš 5 MB). Odpověď ImportFile: { "fileId", "fileName", "size", "delimiter", "encoding", "columns", "rowCount", "sample", "suggestedKind", "suggestedMapping" }.

Kódování pozná server sám: UTF-8 (i s BOM), UTF-16 s BOM (Excel „Text v kódování Unicode“), jinak windows-1250 (Shoptet, český Excel); encoding = utf-8, utf-16 nebo windows-1250. Oddělovač ;, , nebo tabulátor podle hlavičky, uvozovky podle RFC 4180 (zdvojené uvozovky, nové řádky v poli). První řádek je hlavička, prázdné řádky se přeskočí. sample = prvních 5 datových řádků. Soubor se čte proudem a ukládá po dávkách, celý v paměti nikdy není.
suggestedKind a suggestedMapping: návrh druhu souboru a mapování podle názvů sloupců (cs, sk, en a názvy Shoptetu, docs/imports.md); UI ho použije, uživatel ho může změnit.
Chyby 400: file (prázdný), size (nad 64 MB, u vloženého textu nad 5 MB; params.maxBytes), encoding (nejde přečíst ani jako windows-1250), header, rows (žádný datový řádek nebo nad 300 000; params.maxRows), format (buňka nad 128 000 znaků, typicky chybějící uzavírací uvozovky). Tělo nad limit odmítne už server před čtením: 413 validation size.

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json)

object

Odpovede

201 Created: application/json ImportFile

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`	file
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Preview an import: mapping, counts, problems

POST /api/v1/tenants/{tenant}/imports/preview

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: preview_import

What an import would do with the file: counts per action and the first rows.

Poznámky kontraktu (cs): Tělo ImportPlan: { "fileId", "mapping", "mode", "kind"?, "shopId", "listIds" }.

mapping: pro každý sloupec pole kontaktu nebo null (nenačítat). Pole: email, firstName, lastName, fullName (jméno a příjmení v jednom sloupci, doplní prázdné jméno a příjmení), titleBefore, titleAfter, phone, mobile, company, companyId (IČO), street, city, postalCode, country, language, gender, birthday, note, newsletterConsent (souhlas s newsletterem v řádku), newsletterConsentAt (jeho datum), registeredAt (datum registrace, uloží se ke zdroji kontaktu). Právě jeden sloupec email, žádné pole dvakrát (jinak 400 mapping).
kind (výchozí csv): odkud je souhlas řádku. csv = souhlas ke všem řádkům potvrzuje uživatel (consentConfirmed), ledaže soubor má namapovaný newsletterConsent; shoptet_customers = export zákazníků ze Shoptetu, souhlas rozhoduje sloupec newsletterConsent (povinný, jinak 400 consentColumn); shoptet_newsletter = export odběratelů newsletteru, každý řádek je odběratel; bez namapovaného newsletterConsent musí plán nést subscribersConfirmed: true (uživatel v kroku Sloupce potvrdil, že každý řádek je aktivní odběratel; sloupce tohoto exportu nejsou ověřené proti Shoptetu), jinak 400 subscribers. Řádek bez souhlasu se uloží jen jako zákazník (stav customer, consentBasis none, nikdy se mu neposílá, nepřidá se do listIds, žádný souhlas). U druhů Shoptetu se hodnota, která nejde přečíst (neznámá země, chybné datum), vynechá a započítá v report.dropped, řádek kvůli ní není chybný; neznámé slovo v souhlasu = bez souhlasu. Neznámý druh = 400 kind.
mode: upsert (přidat nové a aktualizovat stávající), update_only (jen stávající, nové přeskočit), nebo tři režimy SE, co kontakty jen vyřazují a nic nezapisují do profilu ani do souhlasu (OPT_OUT_MODES): unsubscribe (odhlásit z listIds), remove (odebrat z listIds) a blacklist (adresa na blacklist, i když ještě není kontakt). unsubscribe a remove potřebují aspoň jeden list (jinak 400 listIds, LIST_MODES); blacklist list nepotřebuje.
shopId = hlavní e-shop nových kontaktů; vypnutý e-shop (Nastavení › E-shopy) nový import nepřijme, 400 shop. listIds = seznamy, kam kontakty přidat (nebo u opt-out režimů odhlásit/odebrat): jen ruční a formulářové seznamy tohoto e-shopu nebo celé firmy (jinak 400 listIds); do seznamů napojení na e-shop se neimportuje.
Neznámý fileId (i soubor jiného tenanta) = 404.

Odpověď { "counts": { "rows", "create", "update", "skipSuppressed", "skipMissing", "invalid", "duplicate", "unsubscribe", "remove", "blacklist" }, "rows": [ … prvních 20 … ], "report": ImportReport }, řádek { "row", "email", "action", "error", "field", "values", "consent" } (consent true/false, null u chybného řádku a opt-out režimů). Náhled projde celý soubor po dávkách.

Hodnoty se ořežou a znormalizují: e-mail malými písmeny, bez neviditelných znaků, mezinárodní doména v ASCII podobě (IDNA), tečky v adrese zůstávají; gender f/m (také žena, muž), language cs/sk (cz = cs), country dvě písmena nebo běžný název země (Česká republika, Slovensko, Německo …), birthday YYYY-MM-DD nebo D. M. YYYY, telefon jen číslice, mezery a +()-./, companyId písmena a číslice bez mezer, newsletterConsent yes/no (ano, áno, 1, x, souhlas, přihlášen / ne, nie, 0, odhlášen), data newsletterConsentAt a registeredAt (D. M. YYYY nebo YYYY-MM-DD, případně s časem, místní čas firmy) jako ISO UTC, ostatní text do 200 znaků. Prázdná buňka nic nemění.
ImportReport (souhrn sloučení): consent { optIn, none, keptUnsubscribed } (řádky se souhlasem, bez souhlasu, odhlášené kontakty, které soubor uvádí se souhlasem a zůstaly odhlášené), merge { existing, fromSources, fieldsUpdated, fieldsKeptEdited } (řádky k existujícímu kontaktu, z nich kolik už přišlo z jiného zdroje podle zdroje csv, shoptet, smartemailing, api, form, manual, erp; počet přepsaných hodnot a hodnot ponechaných, protože pole upravil člověk v Poštárně; obojí jen u spuštění), dropped { pole: počet }.
action: invalid (error = email_missing, email_invalid, nebo value_invalid s field), duplicate (adresa už byla výš v souboru), skip_suppressed (kontakt je odhlášený, vrácený, se stížností nebo na seznamu potlačení: import ho nikdy znovu nepřihlásí a nic na něm nezmění; server navíc kontroluje tabulku suppressions i pro adresy bez kontaktu), update, skip_missing (update_only a adresa není kontakt), create, unsubscribe, remove, blacklist (poslední tři jen u odpovídajícího opt-out režimu).

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.

Telo požiadavky (application/json)

Pole	Typ	Povinné	Popis
`fileId`	string	áno
`mapping`	ImportMapping	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	nie	Default csv.
`subscribersConfirmed`	boolean	nie	A Shoptet newsletter export without a consent column: the person confirmed that every row is an active subscriber (required, 400 subscribers otherwise).
`shopId`	string	áno	Main shop of new contacts; lists must belong to it or to the whole company.
`listIds`	array of string	áno

Odpovede

200 OK: application/json ImportPreview

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Get an import with its progress and result

GET /api/v1/tenants/{tenant}/imports/{import_id}

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`import_id`	path	string	áno	Id of the import (string of digits).

Odpovede

200 OK: application/json ImportDetail

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
429		429 rate_limited: wait Retry-After seconds.

Delete an import record

DELETE /api/v1/tenants/{tenant}/imports/{import_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

SE "Odstranit import": only a draft (409 status for an import that started).

Parametre

Názov	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	áno	Public id of the company (tenant), a UUID: GET /api/v3/account-info answers it as data.guid; the app shows it on the API keys page.
`import_id`	path	string	áno	Id of the import (string of digits).

Odpovede

204 No content

Chyby

Stav	Kód	Hodnoty `message`
400	`validation`
401		401 unauthorized: missing, unknown, revoked, expired or idle API key.
403		403 forbidden: message tenant (another company), scope (read-only key), api_key (person only), or the module the key's roles lack.
404	`not_found`
409	`conflict`	status
429		429 rate_limited: wait Retry-After seconds.

Schémy

Error

Pole	Typ	Povinné	Popis
`error`	object	áno

json

{
  "error": {
    "code": "validation",
    "message": "email"
  }
}

ExportField

Pole	Typ	Povinné	Popis
`id`	string	áno	df_* system field or cf_<id> custom field.
`kind`	one of: `custom`, `contact`	áno
`name`	string	áno	Custom fields: their name (tenant data); system fields are named by the UI.
`type`	string	áno

ExportInput

Pole	Typ	Povinné
`name`	string	áno
`selection`	one of: `bounced`, `blacklisted`, `all`, `lists`	áno
`listIds`	array of string	nie
`fields`	array of string	áno
`purposeIds`	array of string	nie
`encoding`	one of: `utf-8`, `windows-1250`	áno

ExportStatus

one of: queued, running, finished, failed

ExportSummary

Pole	Typ	Povinné	Popis
`id`	string	áno
`name`	string	áno
`status`	ExportStatus	áno
`selection`	one of: `bounced`, `blacklisted`, `all`, `lists`	áno
`listIds`	array of string	áno
`fields`	array of string	áno
`purposeIds`	array of string	áno
`encoding`	one of: `utf-8`, `windows-1250`	áno
`rowCount`	number or null	áno
`fileName`	string or null	áno
`downloadable`	boolean	áno	The file exists and its link has not expired.
`downloads`	number	áno
`createdAt`	string	áno
`finishedAt`	string or null	áno
`expiresAt`	string or null	áno
`listNames`	array of string	nie	Names of the chosen lists in their order (SE's column Seznamy); older servers leave it out.

ImportCounts

Pole	Typ	Povinné	Popis
`rows`	number	áno
`create`	number	áno
`update`	number	áno
`skipSuppressed`	number	áno	Unsubscribed, bounced, complained or suppressed: never re-subscribed and not changed.
`skipMissing`	number	áno	update_only and the address is not a contact.
`invalid`	number	áno
`duplicate`	number	áno	Same address earlier in the file.
`unsubscribe`	number	áno	Opt-out modes: unsubscribed from the lists, removed from them, put on the blacklist.
`remove`	number	áno
`blacklist`	number	áno

ImportDetail

Pole	Typ	Povinné	Popis
`source`	string	áno
`purposeId`	string	áno
`addedToLists`	number	áno	New list memberships.
`errors`	array of ImportRowProblem	áno	First 50 invalid rows.
`report`	ImportReport or null	áno	null until finished.
`runAutomations`	boolean	nie	The import starts automations (ImportRequest.runAutomations); false by default.
`options`	ImportOptions	nie
`id`	string	áno
`name`	string	áno
`status`	one of: `queued`, `running`, `draft`, `finished`, `failed`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	áno
`fileName`	string	áno
`shopId`	string	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`listIds`	array of string	áno
`createdAt`	string	áno
`startedAt`	string or null	áno	When the run started (null while queued).
`finishedAt`	string or null	áno
`progress`	object	áno	Rows the run has processed so far (it commits batch by batch).
`counts`	ImportCounts or null	áno	null until finished.
`listNames`	array of string	nie	Names of the chosen lists in their order (SE's column Seznamy; the grid only).

ImportDraft

SE "Rozpracováno": the summary, the wizard's state and the stored file while it lasts (24 hours).

Pole	Typ	Povinné	Popis
`source`	string	áno
`state`	ImportDraftState	áno
`file`	ImportFile or null	áno
`updatedAt`	string or null	áno
`id`	string	áno
`name`	string	áno
`status`	one of: `queued`, `running`, `draft`, `finished`, `failed`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	áno
`fileName`	string	áno
`shopId`	string	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`listIds`	array of string	áno
`createdAt`	string	áno
`startedAt`	string or null	áno	When the run started (null while queued).
`finishedAt`	string or null	áno
`progress`	object	áno	Rows the run has processed so far (it commits batch by batch).
`counts`	ImportCounts or null	áno	null until finished.
`listNames`	array of string	nie	Names of the chosen lists in their order (SE's column Seznamy; the grid only).

ImportDraftInput

Pole	Typ	Povinné
`name`	string	nie
`source`	string	nie
`step`	number	nie
`state`	ImportDraftState	nie
`fileId`	string or null	nie
`shopId`	string or null	nie

ImportDraftState

The wizard's own state of a draft import (opaque to the server, with the step).

Pole	Typ	Povinné	Popis
`step`	number	nie
`*`	any	nie

ImportEncoding

one of: utf-8, windows-1250, utf-16

ImportFile

Pole	Typ	Povinné	Popis
`fileId`	string	áno
`fileName`	string	áno
`size`	number	áno	Bytes of the file as uploaded.
`delimiter`	string	áno	; , tab or the one character the person chose.
`quote`	string	nie	Field enclosure (default ").
`hasHeader`	boolean	nie	false = the first line is data and the columns have no names.
`encoding`	ImportEncoding	áno	What the server read the file as (detected).
`columns`	array of string	áno	Header row.
`rowCount`	number	áno	Data rows without the header.
`sample`	array of array of string	áno	First data rows as they are in the file.
`suggestedKind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	áno	The server's suggestion from the header names (Czech, Slovak, English, Shoptet).
`suggestedMapping`	ImportMapping	áno

ImportMapping

ImportOptions

Pole	Typ	Povinné	Popis
`autofill`	object	nie	Fill empty fields from the first name and the address (SE "Automatické doplnění údajů ke kontaktu").
`consentFrom`	object	nie	Start of the purpose consent: now, or one date for every row (a date column is the mapped newsletterConsentAt).
`doi`	object	nie	Double opt-in e-mail instead of an immediate subscription (upsert and update_only).

ImportPlan

Pole	Typ	Povinné	Popis
`fileId`	string	áno
`mapping`	ImportMapping	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	nie	Default csv.
`subscribersConfirmed`	boolean	nie	A Shoptet newsletter export without a consent column: the person confirmed that every row is an active subscriber (required, 400 subscribers otherwise).
`shopId`	string	áno	Main shop of new contacts; lists must belong to it or to the whole company.
`listIds`	array of string	áno

ImportPreview

Pole	Typ	Povinné	Popis
`counts`	ImportCounts	áno
`rows`	array of ImportPreviewRow	áno	First 20 rows.
`report`	ImportReport	áno

ImportPreviewRow

Pole	Typ	Povinné	Popis
`row`	number	áno	Line in the file, the header is line 1.
`email`	string	áno
`action`	one of: `invalid`, `unsubscribe`, `remove`, `blacklist`, `create`, `update`, `skip_suppressed`, `skip_missing`, `duplicate`	áno
`error`	one of: `email_missing`, `email_invalid`, `value_invalid`, `null`	áno
`field`	one of: `companyId`, `firstName`, `lastName`, `phone`, `country`, `street`, `city`, `language`, `note`, `email`, `company`, `mobile`, `postalCode`, `gender`, `fullName`, `titleBefore`, `titleAfter`, `birthday`, `newsletterConsent`, `newsletterConsentAt`, `registeredAt`, `null`	áno	The field with an invalid value.
`values`	object	áno	Normalized values that would be written.
`consent`	boolean or null	áno	Whether the row brings a newsletter consent (false = a customer only); null for invalid rows and opt-out modes.

ImportReport

Merge summary of an import: the consent of the rows, existing contacts and their other sources, values left out.

Pole	Typ	Povinné	Popis
`consent`	object	áno
`merge`	object	áno
`dropped`	object	áno	Values of Shoptet files that did not fit and were left out, per field.

ImportRequest

Pole	Typ	Povinné	Popis
`name`	string	áno
`source`	string	áno	Where the contacts come from (se-spec 01 §7.1), e.g. a trade fair.
`purposeId`	string	nie	Purpose of processing given to the imported contacts. Optional for OPT_OUT_MODES (the server stores the tenant's first purpose when omitted; those modes write no consent).
`consentConfirmed`	boolean	nie	The user confirms a documented, valid purpose for every contact; must be true. Not required for OPT_OUT_MODES.
`runAutomations`	boolean	nie	Explicit opt-in: what the import writes starts automations (added to a list, subscribed, contact created ...). Default false: an import is a bulk write that starts none.
`options`	ImportOptions	nie	Autofill, start of the purpose consent and the double opt-in e-mail (SE wizard).
`draftId`	string	nie	The wizard's draft this import comes from (deleted when the import starts).
`fileId`	string	áno
`mapping`	ImportMapping	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	nie	Default csv.
`subscribersConfirmed`	boolean	nie	A Shoptet newsletter export without a consent column: the person confirmed that every row is an active subscriber (required, 400 subscribers otherwise).
`shopId`	string	áno	Main shop of new contacts; lists must belong to it or to the whole company.
`listIds`	array of string	áno

ImportRowProblem

Pole	Typ	Povinné
`row`	number	áno
`error`	one of: `email_missing`, `email_invalid`, `value_invalid`	áno
`field`	one of: `companyId`, `firstName`, `lastName`, `phone`, `country`, `street`, `city`, `language`, `note`, `email`, `company`, `mobile`, `postalCode`, `gender`, `fullName`, `titleBefore`, `titleAfter`, `birthday`, `newsletterConsent`, `newsletterConsentAt`, `registeredAt`, `null`	áno

ImportSummary

Pole	Typ	Povinné	Popis
`id`	string	áno
`name`	string	áno
`status`	one of: `queued`, `running`, `draft`, `finished`, `failed`	áno
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	áno
`fileName`	string	áno
`shopId`	string	áno
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	áno
`listIds`	array of string	áno
`createdAt`	string	áno
`startedAt`	string or null	áno	When the run started (null while queued).
`finishedAt`	string or null	áno
`progress`	object	áno	Rows the run has processed so far (it commits batch by batch).
`counts`	ImportCounts or null	áno	null until finished.
`listNames`	array of string	nie	Names of the chosen lists in their order (SE's column Seznamy; the grid only).

Imports and exports

Operácie#

Fields an export can contain#

List exports#

Start a CSV export#

Get an export#

Download an export (CSV)#

List imports#

Start an import#

Start an import draft (wizard)#

Get an import draft#

Save an import draft#

Upload a CSV file for import#

Preview an import: mapping, counts, problems#

Get an import with its progress and result#

Delete an import record#

Schémy#

Error#

ExportField#

ExportInput#

ExportStatus#

ExportSummary#

ImportCounts#

ImportDetail#

ImportDraft#

ImportDraftInput#

ImportDraftState#

ImportEncoding#

ImportFile#

ImportMapping#

ImportOptions#

ImportPlan#

ImportPreview#

ImportPreviewRow#

ImportReport#

ImportRequest#

ImportRowProblem#

ImportSummary#

Operácie

Fields an export can contain

List exports

Start a CSV export

Get an export

Download an export (CSV)

List imports

Start an import

Start an import draft (wizard)

Get an import draft

Save an import draft

Upload a CSV file for import

Preview an import: mapping, counts, problems

Get an import with its progress and result

Delete an import record

Schémy

Error

ExportField

ExportInput

ExportStatus

ExportSummary

ImportCounts

ImportDetail

ImportDraft

ImportDraftInput

ImportDraftState

ImportEncoding

ImportFile

ImportMapping

ImportOptions

ImportPlan

ImportPreview

ImportPreviewRow

ImportReport

ImportRequest

ImportRowProblem

ImportSummary