CRM Data Ingest - API
Bufor importów danych klientów. Autoryzacja: Authorization: Bearer TOKEN z uprawnieniem automation_import (token można ograniczyć wyłącznie do tego uprawnienia). Throttle: 3000 requestów/min per konto - operacje masowe wysyłaj batchami.
Wysyłka
POST /automation/import_batches.json
{
"kind": "crm_clients",
"source_code": "moj_system",
"batch_id": "unikalny-id-batcha",
"clients": [
{
"external_id": "123",
"name": "Firma Przykładowa",
"email": "kontakt@firma.pl",
"tax_no": "5551112233",
"fields": { "plan": "premium", "saldo": 199.99 }
}
]
}
| Pole | Wymagane | Opis |
|---|---|---|
kind |
nie | obecnie tylko crm_clients (default) |
source_code |
tak | stała nazwa źródła [a-z][a-z0-9_]* - przestrzeń identyfikatorów external_id; nie zmieniać po starcie |
batch_id |
nie | klucz idempotencji retry (duplikat -> "duplicate": true); bez niego hash treści |
clients[].external_id |
tak | id klienta w systemie źródłowym |
clients[].fields |
nie | pola własne - zapisywane tylko klucze zdefiniowane w Automation::CustomField; nieznane pomijane i zliczane |
Limit: 5000 rekordów na request. Odpowiedź: 202 Accepted + { status, accepted, batch_id, duplicate }. Przetwarzanie asynchroniczne (flow z debouncem + godzinowy cron-backstop). Wysyłaj pełny aktualny stan klienta, nie delty - dedup po external_id w batchu, ostatni stan wygrywa.
Pola stałe klienta: name, shortcut, first_name, last_name, company, email, phone, mobile_phone, www, tax_no, register_number, street, post_code, city, province, country, note, description, kind.
Podgląd i konfiguracja
GET /automation/import_batches.json?processed=false&source_code=... # batche w buforze
GET /automation/import_batches/:id.json # pojedynczy batch
GET /automation/import_batches/settings.json # konfiguracja, pola własne, źródła, statystyki
PATCH /automation/import_batches/settings.json # { "settings": { "duplicate_policy": "match_tax_no|match_contacts|external_id_only", "update_existing": true, "batch_size": 2000 } }
Osoby przy kliencie
Rekord klienta może zawierać listę contacts. Każda osoba wymaga id albo external_id
(id to identyfikator w Twoim systemie, external_id trafia do kolumny kontaktu w CRM).
| Pole | Opis |
|---|---|
contacts[].role |
rola w TEJ firmie: owner, admin, accountant, user, viewer (inna wartość zapisze się bez zmian) |
contacts[].fields |
pola własne kontaktu - jak przy kliencie, zapisywane tylko zdefiniowane klucze |
clients[].contacts_complete |
true = lista to pełny stan, brak osoby kończy jej powiązanie z firmą. Bez flagi payload jest przyrostowy |
Pola stałe osoby: name, first_name, last_name, email, phone, mobile_phone, external_id,
position, note, description.
Osoba jest deduplikowana po id w przestrzeni source_code, a następnie po adresie e-mail,
więc ta sama osoba przysłana przy kilku firmach daje jeden kontakt z kilkoma powiązaniami.
Powiązania dopisane ręcznie w CRM (bez source_code) nie są usuwane przez contacts_complete.
Limity: do 5000 klientów na request i do 20 000 pozycji łącznie (klienci razem z osobami).