Интеграция по API позволяет отправлять заказы в AFF1 со своего лендинга или с лендинга, размещённого на вашем хостинге. Ваш сервер принимает форму заказа и передаёт заказ в AFF1 POST-запросом.
Настроить интеграцию можно двумя способами:
- Архив — скачать готовый лендинг AFF1 с уже настроенным API и загрузить его на хостинг. Самый простой способ, см. Интеграция по API: готовый архив.
- Ручная (экспертный режим) — запрос вы пишете сами. Об этом способе — эта статья.
Что понадобится
- API работает только для целей офферов с интеграцией по API. В списке офферов у таких целей есть зелёная иконка API (Доступна интеграция по API).
- Нужен доступ к цели оффера. Если оффер По запросу, сначала запросите доступ.
- Нужен серверный скрипт (на PHP или любом другом языке), который принимает форму заказа. Запрос отправляется с вашего сервера, а не из браузера посетителя.
Никогда не вставляйте API ключ в HTML или JavaScript страницы: любой может открыть код страницы и отправлять заказы с вашим ключом. Ключ должен храниться только на сервере.
Где взять данные для API
- Откройте страницу оффера и нажмите API на панели внизу.
- В окне API интеграция откройте вкладку Ручная (экспертный режим).
Что есть на вкладке:
- Api ключ (api_key) — ваш персональный ключ, один для всех офферов.
- Привязать к потоку — лиды будут попадать в один из ваших потоков. Выберите Поток, и вместо Hash цели (target_hash) окно покажет Hash потока (flow_hash). В списке только потоки, цели которых имеют API интеграцию.
- Цель и таблица Страна / Код (country_code) — цель и коды её стран.
- Hash цели (target_hash) — идентификатор цели, который передаётся в запросе.
- Создать лид — адрес запроса:
POST https://api.aff1.com/v3/lead.create. - Доступные поля — поля, которые можно передавать, и пример на PHP под таблицей.
Полное описание всех методов и полей — в Инструменты → API.
Кнопка Получить новый выпускает новый API ключ, и текущий ключ сразу перестаёт работать. Все лендинги и скрипты со старым ключом перестанут отправлять заказы, пока вы не замените в них ключ.
Как отправить заказ
Отправьте POST-запрос на https://api.aff1.com/v3/lead.create с полями формы:
| Поле | Обязательное | Что передавать |
|---|---|---|
api_key | да | ваш API ключ |
target_hash или flow_hash | да | hash цели или hash потока, если привязываете лиды к потоку |
phone | да | телефон из формы, от 6 до 24 символов |
country_code | код страны ISO 3166-1 alpha-2 (PE, PH…), по нему определяется гео цель | |
name | полное имя клиента | |
ip, user_agent, referer, browser_locale | IP посетителя, User-Agent, адрес страницы и двухбуквенный язык браузера | |
clickid | id клика вашего трекера, возвращается в постбеках как {clickid} | |
data1…data4 | ваши параметры, до 32 символов каждый | |
fbclid, fbpx | для Facebook Conversions API |
Адрес, email, комментарий, количество, удобное время звонка и другие поля описаны в Инструменты → API.
Пример запроса через curl (подставьте свои значения):
curl https://api.aff1.com/v3/lead.create \
-F api_key=YOUR_API_KEY \
-F target_hash=AbCd1234 \
-F country_code=PE \
-F name="Juan Perez" \
-F phone=51900000000 \
-F clickid=abc123В примере на PHP на вкладке Ручная (экспертный режим) уже подставлены ваш ключ и hash, а также передаются IP, User-Agent, referer и язык посетителя.
Ответ и ошибки
Успешный ответ:
{"status":"success","data":{"lead_hash":"..."}}Сохраните lead_hash — это id заказа в AFF1, по нему проверяется статус.
Если что-то не так, в ответе будет "status":"error" и поля error_code, error_message, error_fields:
| Ошибка | Что значит |
|---|---|
FORBIDDEN_ERROR | Доступ с этим API ключом запрещён: ключ неверный или был заменён |
VALIDATION_ERROR | Поле не передано или в неверном формате; какое — видно в error_fields |
NOT_VALID_TARGET_HASH | Неверный target_hash |
CANNOT_DETECT_TARGET_GEO | AFF1 не смог определить гео цель — передайте country_code одной из стран цели |
LEAD_DOUBLE | Дубль: заказ с тем же телефоном на ту же гео цель уже приходил менее 30 минут назад. В error_fields — lead_hash первого заказа |
HTTP 429 | Слишком много заказов, сработала защита от спама (см. ниже) |
SERVER_ERROR | Ошибка на стороне AFF1, повторите запрос позже |
Защита от спама
Стандартные лимиты на количество добавляемых заказов:
- 20 лидов в минуту;
- 60 лидов за последние 5 минут;
- 100 лидов за последние 15 минут.
Если превысить лимит, добавление заказов блокируется на следующий час (HTTP 429). Для интенсивных потоков валидных заказов лимиты можно изменить или отключить — обратитесь к личному менеджеру.
Как проверить статус заказов
GET https://api.aff1.com/v3/lead.info с параметрами api_key и hashes — один или несколько lead_hash через запятую.
| Статус | Значение |
|---|---|
new | заказ добавлен и ещё не обработан |
approved | заказ подтверждён |
cancelled | заказ отменён |
trashed | заказ отменён как трэш: невалидные данные, дубль или тест |
Чтобы получать статусы сразу, используйте постбек, а не регулярные запросы к lead.info.
Баланс: GET https://api.aff1.com/v3/my.balance с api_key возвращает balance_usd, balance_eur, hold_usd и hold_eur.
Как проверить интеграцию
- Отправьте форму на своём лендинге и проверьте, что скрипт получил ответ с
lead_hash. - Найдите заказ в Статистика → Лиды.
- Если настроен постбек, проверьте, что он пришёл в трекер.
Тестовые заказы уходят в трэш. Если нужно проверить всю воронку до колл-центра, заранее согласуйте тест с личным менеджером.