claritos
deenru

Лиды от агентств партнёров

Как маркетинговое агентство партнёра отправляет лиды прямо как потенциальных клиентов партнёра и сразу получает для каждого персональную ссылку для записи: согласие на собственной посадочной странице, затем запись на приём без повторного ввода данных.

Процесс

Агентство работает с ключом партнёра, привязанным ровно к одному партнёру (аффилиату). Оно один раз читает описание формы, отправляет значения по каждому лиду и в том же ответе получает идентификатор потенциального клиента, а с типом приёма также персональную ссылку партнёра для записи. Кто открывает ссылку, видит свои данные уже заполненными и выбирает только время. Приём относится к партнёру и его команде.

1. Выдать ключ партнёра

Выдать ключ может партнёр в портале партнёра в разделе «Интерфейс для моего агентства» или администратор организации в управлении аффилиатами у партнёра. Оба видят одни и те же ключи и могут их отозвать. Название, по желанию срок действия и разрешённые IP-адреса; ключ (capi_…) показывается только один раз. Ротация выдаёт новый ключ, старый действует ещё 24 часа. Ключ вызывает ровно три эндпоинта: GET /forms/{id}, POST /forms/{id}/responses и POST /appointment-types/{id}/partner-links. Он действует, только пока партнёр активен и интерфейс организации включён; доступ через MCP его не принимает. Идентификаторы форм и типов приёма, которыми он может пользоваться, показывает инструкция в портале.

2. Прочитать форму

GET /forms/{id} называет поля (key, required, options), согласия с идентификатором (elementId), текстом (labelHtml) и обязательностью, а также страницы. Посадочная страница агентства показывает текст согласий точно в таком виде: только тогда отправленное согласие действительно. С ключом партнёра возвращаются только формы, открытые для портала партнёра и создающие потенциальных клиентов; на любую другую ответ 404. responseCount считает только отправки своего партнёра, publicUrl пуст. Если организация меняет форму, вместе с ней меняется и описание; перед кампанией его стоит прочитать заново.

curl
curl "https://www.claritos.io/api/v1/forms/<FORMULAR>?locale=de" \
  -H "Authorization: Bearer capi_…"
json
{
  "id": "<FORMULAR>",
  "fields": [
    { "key": "std:firstName", "required": true },
    { "key": "std:email", "required": true },
    { "key": "cf:interesse", "required": false, "options": [ … ] }
  ],
  "consents": [
    { "elementId": "<EINWILLIGUNG>", "required": true, "labelHtml": "<p>Ich bin einverstanden, …</p>" }
  ]
}

3. Отправить лид, ссылка для записи в том же ответе

POST /forms/{id}/responses с values (ключи из шага 2) и consents (идентификатор согласия со значением true). С appointmentTypeId, типом приёма, открытым партнёру, сразу приходит персональная ссылка для записи; senderContactId по желанию выбирает, от чьего имени она отправляется, иначе от ответственного за потенциального клиента или владельца партнёра. affiliateId передавать не нужно: ключ сам задаёт своего партнёра. Idempotency-Key для каждого лида не даёт повторному вызову создать лид дважды. Если не удалась только ссылка, лид остаётся сохранённым: bookingUrl тогда пуст, а bookingError называет причину (prospect-without-contact, appointment-type-not-released-to-partner, sender-not-in-team, prospect-not-found, booking-failed). Если человек уже является потенциальным клиентом другого партнёра, действуют те же правила, что и для публичной формы.

curl
curl -X POST https://www.claritos.io/api/v1/forms/<FORMULAR>/responses \
  -H "Authorization: Bearer capi_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: <je Lead eindeutig>" \
  -d '{ "values": { "std:firstName": "Anna", "std:lastName": "Muster", "std:email": "anna@example.com" },
        "consents": { "<EINWILLIGUNG>": true },
        "appointmentTypeId": "<TERMINART>" }'
json
{
  "id": "<EINSENDUNG>",
  "prospectId": "<INTERESSENT>",
  "contactId": "<KONTAKT>",
  "affiliateId": "<PARTNER>",
  "bookingUrl": "https://www.claritos.io/t/…",
  "bookingError": null
}

4. Получить ссылку позже

По идентификатору из ответа (prospectId) POST /appointment-types/{id}/partner-links в любой момент снова возвращает ссылку, в том числе для другого открытого типа приёма. Если она уже есть, возвращается та же ссылка.

curl
curl -X POST https://www.claritos.io/api/v1/appointment-types/<TERMINART>/partner-links \
  -H "Authorization: Bearer capi_…" -H "Content-Type: application/json" \
  -d '{ "prospectId": "<INTERESSENT>" }'

Ошибки

401: ключ отозван или партнёр больше не активен; key-expired после окончания срока действия, в том числе через 24 часа после ротации. 403: ip-not-allowed, api-disabled (интерфейс организации выключен), forbidden с reason partner-key-endpoint (другой эндпоинт). 404: форма не открыта для партнёров. 422 validation-failed: в body.values.<key> или body.consents.<id> при отсутствии обязательных данных, в body.affiliateId с кодом partner-affiliate, если передан другой партнёр, в body.prospectId с кодом not_found для неизвестного потенциального клиента или клиента другого партнёра (оба случая выглядят одинаково). 422 precondition-failed для ссылки: prospect-without-contact, appointment-type-not-released-to-partner.

С ключом организации

Те же эндпоинты работают и с ключом организации. affiliateId тогда выбирает партнёра, которому принадлежит потенциальный клиент; appointmentTypeId при отправке дополнительно требует appointments:write, а POST /appointment-types/{id}/partner-links требует человека с правом управлять планированием приёмов. Для агентства правильный путь ключ партнёра: он больше ничего не умеет.