в разработке

API для организаций: выгрузка намерений

Организации смогут загружать свои намерения в «ХочуМогу» пакетно — файлом или по API, без ручного ввода через мастер. Ниже — планируемый интерфейс. Он ещё в разработке; параметры могут измениться. Когда всё будет готово, в личном кабинете организации появится поле для ссылки на .yaml и выдача токена доступа.

1. Аутентификация

Каждый запрос авторизуется персональным токеном организации в заголовке Authorization: Bearer <org_token>. Токен будет выдаваться в личном кабинете организации (раздел «Выгрузка намерений по API»). Токен привязан к аккаунту организации — намерения создаются от её имени.

2. Загрузка намерений

Два способа, оба принимают один и тот же формат (YAML или JSON):

  • По ссылке на .yaml. Организация указывает в ЛК URL файла; сервис периодически его читает и синхронизирует намерения.
  • Прямой вызов. POST /v1/org/intentions/import с телом-файлом.
POST /v1/org/intentions/import
Authorization: Bearer <org_token>
Content-Type: application/yaml

# тело — список намерений (см. формат ниже)

3. Формат файла

Список намерений. Каждое намерение — пара «я хочу»/«я могу» из 7 пар сервиса, тип, название, теги, территория и параметры пары (цена, количество, состояние — по типу).

version: 1
intentions:
  - kind: may            # may (я могу) | want (я хочу)
    type: sell           # тип из пары: sell/buy, rent_out/rent, ...
    title: Велосипед горный
    tags: [велосипед, спорт]
    territory:
      type: city         # country | region | city | address | online
      value: Хабаровск
    price: { amount: 15000, currency: RUB }
    condition: used      # new | used (для товаров)
    quantity: { value: 1, unit: шт }
    description: Рама 19", 27 скоростей
    external_id: bike-42 # ваш идентификатор — для синхронизации

4. Обработка и синхронизация

  • external_id связывает запись файла с намерением в сервисе: повторная загрузка обновляет намерение на месте (не создаёт дубль), пропавшее из файла — снимается с публикации.
  • Намерения проходят те же правила, что и созданные вручную: валидация, автомодерация медиа, лимиты активных намерений по типу аккаунта.
  • Ответ содержит счётчики созданных / обновлённых / отклонённых записей и список ошибок по строкам.

5. Ограничения

  • Территория — по справочнику DaData/ФИАС (регион, город, адрес до дома) или «вся страна» / «онлайн».
  • Матчинг, статусы и лимиты — на стороне сервиса; файл задаёт только исходные данные намерения.
  • Оплата услуг организацией — банковским переводом по реквизитам из профиля (ИНН, БИК, расчётный счёт).

Появились вопросы или хотите подключиться раньше — напишите нам через форму «Идея» или на почту поддержки. Мы уведомим, когда API станет доступен.