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: 2000 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 id; nie zmieniać po starcie |
batch_id |
nie | klucz idempotencji retry (duplikat -> "duplicate": true); bez niego hash treści |
clients[].id |
tak* | id klienta w systemie źródłowym - klucz tożsamości w przestrzeni source_code (tabela powiązań external_ids), nie pokazuje się w CRM |
clients[].external_id |
tak* | globalny identyfikator zapisywany w kolumnie external_id klienta CRM (unikalna w obrębie konta, widoczna w filtrach i eksportach). Bez id pełni rolę klucza tożsamości - rozpoznanie po kolumnie, bez wpisu w external_ids |
clients[].fields |
nie | pola własne (JSONB fields) - zapisywane także klucze bez definicji Automation::CustomField (opcja save_unknown_fields, domyślnie włączona; po wyłączeniu nieznane klucze są pomijane i zliczane w statystykach). Definicja pola nie powstaje automatycznie |
* przynajmniej jedno z id / external_id. Rekord bez obu przejdzie z samym email - jest wtedy rozpoznawany wyłącznie po polach łączących (patrz niżej).
Limity: 5000 klientów na request i 20 000 pozycji łącznie (klienci razem z osobami). Odpowiedź: 202 Accepted + { status, accepted, batch_id, duplicate }. Przetwarzanie asynchroniczne w tle. Wysyłaj pełny aktualny stan klienta, nie delty - rekordy w batchu są deduplikowane po kluczu tożsamości, ostatni stan wygrywa. Pole nieobecne w payloadzie nie nadpisuje wartości w CRM.
Pola stałe klienta: name, shortcut, first_name, last_name, company, email, phone, mobile_phone, www, tax_no, register_number, external_id, street, post_code, city, province, country, note, description, kind, paid_to.
Osoby przy kliencie
Rekord klienta może zawierać listę contacts. Każda osoba wymaga id albo external_id (znaczenie jak przy kliencie; kolumna external_id kontaktu nie jest unikalna).
| 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 |
clients[].contacts_complete |
true = lista to pełny stan, brak osoby kończy jej powiązanie z firmą. Bez flagi payload jest przyrostowy i nic nie odłącza |
Pola stałe osoby: name, first_name, last_name, email, phone, mobile_phone, external_id, position, note, description.
Osoba to jeden kontakt niezależnie od liczby firm - rozpoznana po id w przestrzeni source_code (albo po polach łączących) dostaje kolejne powiązania z rolami, nie duplikaty. Powiązania dopisane ręcznie w CRM nie są usuwane przez contacts_complete; gdy choć jedna osoba z listy zostanie odrzucona, flaga nie odłącza nikogo w tym przebiegu.
Pola łączące i merge
Rekord, którego klucza tożsamości nie ma jeszcze w CRM, jest najpierw dopasowywany do istniejących po polach łączących z opcji linking_fields reguły (np. "email, phone"; dostępne: email, phone, tax_no, register_number, name - dwa pierwsze działają też dla osób). Pola sprawdzane są po kolei, łączy tylko jednoznaczne dopasowanie (dokładnie jeden kandydat, pozostałe pola z listy zgodne albo puste po którejś ze stron). E-mail i telefon porównywane po znormalizowanej postaci (telefon po części krajowej, prefiks międzynarodowy jako dodatkowy warunek; numer krajowy dostaje kraj z pola country rekordu albo z ustawień konta), NIP po samych znakach alfanumerycznych. Pusta opcja wyłącza łączenie; aplikacja ustawia na starcie email.
Merge po polach łączących, który zastąpił niepuste wartości, zapisuje poprzednie wartości w polu merge_sync rekordu (plus meta _merged_at i _source_code). Rekord rozpoznany po kluczu tożsamości aktualizuje się bez sprawdzania pól łączących i bez śladu merge_sync. Niejednoznaczne dopasowanie: rekord z id/external_id tworzy nowego klienta, rekord bez identyfikatorów jest odrzucany z błędem w statystykach.
Konfiguracja (opcje linking_fields, save_unknown_fields, batch_size) mieszka na akcji crm_client_sync reguły automatyzacji zakładanej przez aplikację - edycja w panelu aplikacji albo przez PATCH /automation/rules/:id.json.
Podgląd
GET /automation/import_batches.json?processed=false&source_code=... # batche w buforze
GET /automation/import_batches/:id.json # pojedynczy batch
GET /automation/import_batches/stats.json # endpoint_url, źródła, statystyki, ostatnie odrzuty (recent_failed)