Imports and exports

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

Technická reference je anglicky (stejně jako strojově čitelný dokument OpenAPI). Celou skupinu pro AI agenta načtete z /api/openapi.json?tag=Imports%20and%20exports.

Přihlášení: Authorization: Bearer pst_... nebo HTTP Basic (e-mail člena firmy a API klíč).

Operace

Metoda	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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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.

Odpovědi

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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ne
`idTo`	query	string	ne
`name`	query	string	ne
`page`	query	integer	ne	Page number, from 1. default `1`, min 1
`pageSize`	query	integer	ne	Items per page, 1 to 100. default `25`, min 1, max 100
`q`	query	string	ne	Search text (case and diacritics insensitive). max 200 chars
`sort`	query	string	ne	Sort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
`status`	query	string	ne	Status filter.

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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.

Tělo požadavku (application/json): Required by the server: name, selection.

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

Odpovědi

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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ano	Id of the export (string of digits).

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ano	Id of the export (string of digits).

Odpovědi

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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: list_imports

Imports with status and counts.

Poznámky kontraktu: 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í).

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ne
`idTo`	query	string	ne
`name`	query	string	ne
`page`	query	integer	ne	Page number, from 1. default `1`, min 1
`pageSize`	query	integer	ne	Items per page, 1 to 100. default `25`, min 1, max 100
`q`	query	string	ne	Search text (case and diacritics insensitive). max 200 chars
`sort`	query	string	ne	Sort fields separated by commas, "-" = descending, at most 3 (e.g. name,-id).
`status`	query	string	ne	Status filter.

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: start_import (přes MCP jen s náhledem a potvrzením)

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

Poznámky kontraktu: 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.

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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.

Tělo požadavku (application/json)

Pole	Typ	Povinné	Popis
`name`	string	ano
`source`	string	ano	Where the contacts come from (se-spec 01 §7.1), e.g. a trade fair.
`purposeId`	string	ne	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	ne	The user confirms a documented, valid purpose for every contact; must be true. Not required for OPT_OUT_MODES.
`runAutomations`	boolean	ne	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	ne	Autofill, start of the purpose consent and the double opt-in e-mail (SE wizard).
`draftId`	string	ne	The wizard's draft this import comes from (deleted when the import starts).
`fileId`	string	ano
`mapping`	ImportMapping	ano
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	ano
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	ne	Default csv.
`subscribersConfirmed`	boolean	ne	A Shoptet newsletter export without a consent column: the person confirmed that every row is an active subscriber (required, 400 subscribers otherwise).
`shopId`	string	ano	Main shop of new contacts; lists must belong to it or to the whole company.
`listIds`	array of string	ano

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

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

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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.

Tělo požadavku (application/json)

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

Odpovědi

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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ano	Id of the import (string of digits).

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ano	Id of the import (string of digits).

Tělo požadavku (application/json)

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

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem 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: 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.

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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.

Tělo požadavku (application/json)

object

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: preview_import

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

Poznámky kontraktu: 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).

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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.

Tělo požadavku (application/json)

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

Odpovědi

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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ano	Id of the import (string of digits).

Odpovědi

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ávnění: modul contacts, úroveň full; klíč s přístupem full

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

Parametry

Název	Kde	Typ	Povinné	Popis
`tenant`	path	string (uuid)	ano	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	ano	Id of the import (string of digits).

Odpovědi

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émata

Error

Pole	Typ	Povinné	Popis
`error`	object	ano

json

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

ExportField

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

ExportInput

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

ExportStatus

one of: queued, running, finished, failed

ExportSummary

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

ImportCounts

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

ImportDetail

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

ImportDraftInput

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

ImportDraftState

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

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

ImportEncoding

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

ImportFile

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

ImportMapping

ImportOptions

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

ImportPlan

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

ImportPreview

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

ImportPreviewRow

Pole	Typ	Povinné	Popis
`row`	number	ano	Line in the file, the header is line 1.
`email`	string	ano
`action`	one of: `invalid`, `unsubscribe`, `remove`, `blacklist`, `create`, `update`, `skip_suppressed`, `skip_missing`, `duplicate`	ano
`error`	one of: `email_missing`, `email_invalid`, `value_invalid`, `null`	ano
`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`	ano	The field with an invalid value.
`values`	object	ano	Normalized values that would be written.
`consent`	boolean or null	ano	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	ano
`merge`	object	ano
`dropped`	object	ano	Values of Shoptet files that did not fit and were left out, per field.

ImportRequest

Pole	Typ	Povinné	Popis
`name`	string	ano
`source`	string	ano	Where the contacts come from (se-spec 01 §7.1), e.g. a trade fair.
`purposeId`	string	ne	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	ne	The user confirms a documented, valid purpose for every contact; must be true. Not required for OPT_OUT_MODES.
`runAutomations`	boolean	ne	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	ne	Autofill, start of the purpose consent and the double opt-in e-mail (SE wizard).
`draftId`	string	ne	The wizard's draft this import comes from (deleted when the import starts).
`fileId`	string	ano
`mapping`	ImportMapping	ano
`mode`	one of: `upsert`, `update_only`, `unsubscribe`, `remove`, `blacklist`	ano
`kind`	one of: `csv`, `shoptet_customers`, `shoptet_newsletter`	ne	Default csv.
`subscribersConfirmed`	boolean	ne	A Shoptet newsletter export without a consent column: the person confirmed that every row is an active subscriber (required, 400 subscribers otherwise).
`shopId`	string	ano	Main shop of new contacts; lists must belong to it or to the whole company.
`listIds`	array of string	ano

ImportRowProblem

Pole	Typ	Povinné
`row`	number	ano
`error`	one of: `email_missing`, `email_invalid`, `value_invalid`	ano
`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`	ano

ImportSummary

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

Imports and exports

Operace#

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émata#

Error#

ExportField#

ExportInput#

ExportStatus#

ExportSummary#

ImportCounts#

ImportDetail#

ImportDraft#

ImportDraftInput#

ImportDraftState#

ImportEncoding#

ImportFile#

ImportMapping#

ImportOptions#

ImportPlan#

ImportPreview#

ImportPreviewRow#

ImportReport#

ImportRequest#

ImportRowProblem#

ImportSummary#

Operace

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émata

Error

ExportField

ExportInput

ExportStatus

ExportSummary

ImportCounts

ImportDetail

ImportDraft

ImportDraftInput

ImportDraftState

ImportEncoding

ImportFile

ImportMapping

ImportOptions

ImportPlan

ImportPreview

ImportPreviewRow

ImportReport

ImportRequest

ImportRowProblem

ImportSummary