Field mapping

Если ваш payload не похож на наш канонический формат — ничего страшного. У каждого партнёра в Cartel CRM есть отдельный field_mapping, который маппит ваши JSON-пути на наши канонические поля. Никаких изменений на вашей стороне.

Канонический набор полей

external_id, first_name, last_name, full_name,
email, phone, country, country_code, language, ip, user_agent,
source, funnel, sub_id, click_id, landing_url

Всё остальное, что есть в вашем payload, мы складываем в metadata (доступно агентам в карточке лида, но не используется бизнес-логикой).

Пример: ваш payload — глубоко вложенный

{
  "lead_id": "abc-001",
  "profile": {
    "firstName": "Иван",
    "lastName": "Петров"
  },
  "contact": {
    "phone": "+380501234567",
    "email": "ivan@example.com"
  },
  "geo": { "country": "UA" },
  "tracking": {
    "funnel": "crypto-v3",
    "subId": "sub-789",
    "clickId": "fb-click-abc"
  }
}

Соответствующий field_mapping (настраивается менеджером при создании партнёра):

{
  "external_id": "lead_id",
  "first_name": "profile.firstName",
  "last_name":  "profile.lastName",
  "phone":      "contact.phone",
  "email":      "contact.email",
  "country":    "geo.country",
  "funnel":     "tracking.funnel",
  "sub_id":     "tracking.subId",
  "click_id":   "tracking.clickId"
}

Точки в путях — стандартный JSONpath. Поддерживается любая вложенность.

Sentinel-значения

Иногда нужно положить в поле не значение из payload, а что-то вычисляемое или литеральное. Для этого есть «сентинелы»:

Sentinel	Что делает
_literal:<value>	Подставляет литеральную строку.
_ip	Подставляет IP, с которого пришёл запрос.
_now	Подставляет текущий ISO-timestamp.
_titlecase:<path>	Извлекает по пути и приводит к Title Case.
_lower:<path>	Извлекает и приводит к lowercase.
_upper:<path>	Извлекает и приводит к UPPERCASE.
_digits:<path>	Извлекает и оставляет только цифры (для нормализации телефонов).

Пример:

{
  "first_name": "_titlecase:profile.firstName",
  "language":   "_literal:EN",
  "source":     "_literal:affiliate",
  "ip":         "_ip",
  "phone":      "_digits:contact.phoneRaw"
}

Когда mapping не задан

Если для вашего партнёра field_mapping не сконфигурирован — мы попробуем прямое сопоставление 1:1 канонических ключей с верхнего уровня вашего payload. Это удобно для простых интеграций:

{
  "external_id": "abc-001",
  "first_name": "Иван",
  "last_name": "Петров",
  "phone": "+380501234567",
  "email": "ivan@example.com",
  "country": "UA",
  "source": "facebook_ads"
}

— уже принимается без mapping'а.

Derived поля

Если вы прислали first_name + last_name, но не full_name — мы соберём его сами (конкатенацией с пробелом). Аналогично для country_code — выведем из country, если он 2-буквенный ISO.

Metadata bucket

Всё, что не было замаплено ни в одно каноническое поле, попадёт в metadata — это JSON-поле на лиде, видимое в карточке. Полезно для:

• кастомных полей вашего трекера (например, affId, campaignTag, geoBin)
• forensic-данных (что вы изначально прислали — чтобы понять, что было не так)
• отладки field-mapping'а

Запросить кастомный mapping

Если вы новый партнёр и формат payload нестандартный — пришлите менеджеру один реальный пример запроса (с замазанными PII), мы под него настроим field_mapping за ~10 минут. Дальше всё работает автоматически.