Быстрый старт

Сначала — модель

Если ещё не читали Основные понятия — начните с них: там разобрано, чем отклик отличается от предложения, почему сделку нельзя создать напрямую и как связаны статусы. Дальше эта страница читается заметно быстрее.

Подготовка

Чтобы начать работать с API маркетплейса, вам необходимо выпустить API-ключ. Ключ передаётся в заголовке Authorization: Bearer <API-ключ> каждого запроса.

Кроме ключа понадобится organisationId — он подставляется в URL всех методов ниже. Как его получить, описано в разделе Получение ID организации.

Основной флоу работы с API

Создание объявления → (Отправка приглашений) → Принятие откликов → (Закрытие объявления) → Отправка акта → Выплата

---

Шаг 1. Создание объявления

Создайте объявление о задаче, указав категории, адрес, описание и условия.

Метод: POST /openapi/v2/organisation/{organisationId}/announcements

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/announcements" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
  "categories": ["5f2d2604af74f046a9a86844", "5f2d2643af74f046a9a86846"],
  "address": "г. Москва, ул. Ленина, д. 1",
  "description": "Требуется доставка комплекта документов в офис",
  "service": "Курьерская доставка",
  "price": 50000,
  "reward": "500 рублей за доставку",
  "workTime": "с 10:00 до 12:00"
}'

В ответе вы получите объект объявления с id и статусом PUBLISHED. Сохраните id — он потребуется на следующих шагах.

Подробнее о параметрах запроса и ответа — в разделе Объявления.

---

Шаг 2. Отправка приглашений исполнителям (опционально)

Если вы хотите предложить задачу конкретным исполнителям, отправьте им приглашение по ИНН.

Метод: POST /openapi/v2/organisation/{organisationId}/suggestions/send

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/suggestions/send" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
  "items": [
    {
      "inn": "123456789012",
      "announcementId": 809
    }
  ],
  "ignoreErrors": true
}'

Если этот шаг пропустить, исполнители смогут самостоятельно найти ваше объявление и откликнуться на него.

Подробнее — в разделе Предложения.

---

Шаг 3. Принятие откликов исполнителей

Когда исполнители откликнутся на объявление, вы можете просмотреть отклики и принять подходящих.

3.1. Получение списка откликов

Метод: POST /openapi/v2/organisation/{organisationId}/offers/filter

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/offers/filter" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
  "filters": [
    { "name": "ANNOUNCEMENT_ID", "value": [809] },
    { "name": "STATUS", "value": ["APPLIED"] }
  ],
  "pagination": { "limit": 20, "lastId": null }
}'

3.2. Принятие откликов

Передайте массив id откликов, которые хотите принять.

Метод: POST /openapi/v2/organisation/{organisationId}/offers/accept

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/offers/accept" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
  "offers": ["698b0486535a85cec7d3f47e"]
}'

После принятия отклика автоматически создается сделка со статусом WORK_IN_PROGRESS.

Подробнее — в разделе Отклики.

---

Шаг 4. Закрытие набора по объявлению (опционально)

Когда вы набрали достаточно исполнителей, можно закрыть прием откликов.

Метод: POST /openapi/v2/organisation/{organisationId}/announcements/{announcementId}/close-recruitment

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/announcements/809/close-recruitment" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ"

Подробнее — в разделе Объявления.

---

Шаг 5. Отправка акта исполнителю

После выполнения работы отправьте исполнителю акт с финальной суммой и назначением платежа. Для этого потребуется dealId — идентификатор сделки, который можно получить через фильтрацию сделок.

Метод: POST /openapi/v2/organisation/{organisationId}/deals/{dealId}/act/send

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/deals/6985de55458a10588ab84c73/act/send" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
  "amount": 50000,
  "paymentPurpose": "Оплата за курьерскую доставку"
}'

После отправки акта сделка переходит в статус PROPOSED. Исполнитель должен принять акт — после этого статус сменится на AWAITING_PAYMENT.

Подробнее — в разделе Сделки.

---

Шаг 6. Выплата по сделке

После того как исполнитель принял акт (статус сделки — AWAITING_PAYMENT), отправьте сделку в оплату.

Метод: POST /openapi/v2/organisation/{organisationId}/deals/{dealId}/pay

curl -X POST "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/deals/6985de55458a10588ab84c73/pay" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ"

Сделка перейдет в статус PAYMENT_IN_PROGRESS, а после успешной обработки банком — в COMPLETED.

Подробнее — в разделе Сделки.

---

Схема статусов сделки

Статус	Описание
WORK_IN_PROGRESS	Исполнитель выполняет работу
PROPOSED	Компания отправила акт, ожидается подтверждение исполнителя
AWAITING_PAYMENT	Акт принят, сделка готова к оплате
PAYMENT_IN_PROGRESS	Платеж отправлен в банк
COMPLETED	Выплата проведена, сделка закрыта
REJECTED	Сделка отклонена
CANCELLED	Сделка отменена
PAYMENT_FAILED_CRITICAL	Критическая ошибка при проведении платежа