Категории

API: как работать с документацией?

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

Ознакомиться с документацией можно по ссылке — https://gate.lava.top/docs. Не забудьте предварительно авторизоваться. Это можно сделать через:

  • Bearer-токен;
  • API-ключ, который был создан в личном кабинете lava.top.

В верхней части страницы можно найти полный перечень доступных методов API, а в нижней — подробные схемы, которые помогут лучше понять их структуру.

Доступные методы:

Products:

  • GET/api/v1/invoice — этот метод поможет создать контракт на покупку и принять оплаты.
  • GET/api/v2/products — с помощью этого метода можно получить список всех продуктов автора.
  • PATCH/api/v2/products/{productId} — подойдет для обновления стоимости продукта (на данный момент неактивен).

Invoices:

  • POST/api/v2/invoice — метод для создания контракта на покупку контента (аналогичен /api/v1/invoice).
  • GET/api/v1/invoices — метод для получения страницы контрактов API-ключа, использованного в запросе.
  • GET/api/v1/invoices/{id} — поможет проверить конкретный контракт по его id.

Reports:

  • GET/api/v1/sales/ — этот метод поможет увидеть список всех продаж автора.
  • GET/api/v1/sales/{productId} — необходим для просмотра продаж автора по конкретному продукту.

Subscriptions:

  • DELETE/api/v1/subscriptions — этот метод поможет отменить подписку у клиента.

Donate:

  • GET/api/v1/donate — с помощью этого метода можно принимать донаты.

Webhooks:

  • POST/example-of-webhook-route-contract — здесь можно увидеть пример API-метода, которому должен следовать сервис автора для приёма вебхуков от lava.top

Интерактивность документации поможет протестировать методы и убедиться в их корректной работе. Чтобы опробовать метод, нажмите кнопку «Try it out», введите необходимые данные и выберите опцию «Execute».

Далее в статье собраны ответы на вопросы, которые могут возникнуть в процессе работы с документацией.

Содержание:

Общие вопросы

  • С каких IP-адресов будут поступать вебхуки?

  • Какой URL использовать для отправки запросов?

  • Как принимать платежи по API?

  • Как правильно установить валюту и платежный метод?

  • Как выглядят вебхуки при оплате продуктов?

  • Клиент купил продукт, но я не получил Webhook. Почему?

  • Если вебхуки не были отправлены из-за ошибки, будут ли они отправлены позже?

  • Нужно ли отвечать на вебхуки?

  • Есть ли тестовая зона?

  • Есть ли ограничения по времени у ссылки на оплату?

  • Можно ли увидеть скрытый со страницы автора продукт через API?

  • Каким параметром передается ключ на API?

  • Можно ли отправлять вебхуки на HTTP?

  • Необходимо ли пользователю вводить адрес электронной почты на стороне сервиса?

  • Можно ли передать свои данные при создании ссылки на оплату?

  • Осуществляется ли проверка данных?


    • Вопросы о подписках

  • Как создать рекуррентный платеж?

  • Как создать подписку с рекуррентными платежами более чем на один месяц?

  • Как принимать платежи по подписке с разными периодами оплаты?

  • Какие есть периоды оплаты подписок?

  • В чём разница между contractId и parentContractId?

  • Как выглядят вебхуки при оплате подписки?

  • Есть ли дополнительные попытки списания, если платеж не прошел?

  • Как автор может отменить подписку клиента?

  • Можно ли проверить статус подписки через API?

  • Можно ли оформить одну и ту же подписку дважды?

  • Как обновить стоимость подписки?


    • Общие вопросы

    С каких IP-адресов будут поступать вебхуки?

    Исходящие соединения происходят с IP-адреса 158.160.60.174.


    Какой URL использовать для отправки запросов (LAVA_API_URL)?

    Запросы необходимо отправлять на gate.lava.top.

    Как принимать платежи по API?

    Оплаты принимаются через метод POST — /api/v2/invoice. Вот что надо сделать, чтобы создать ссылку на оплату (создать invoice):

    1. Получить список продуктов методом GET v2/products.

    2. Выбрать продукт, который хотим продавать.

    3. Скопировать offer_id продукта, по которому хотим получать платежи.

    4. Отправить запрос на создание invoice методом POST v2/invoice. Для этого укажите в запросе:

    • email покупателя;
    • offer_id продукта;
    • currency — валюту в которой будет покупка;
    • paymentMethod — банк, через который пройдет оплата;
    • language — язык, на котором будут отправляться письма клиенту об успешной покупке;
    • clientUTM — метки, которые можно использовать для более точной информации об оплате (подробнее здесь).

    5. Покупатель получит ссылку на оплату.


    Как правильно установить валюту и платежный метод?

    С карт российских банков можно оплатить в ₽, а с иностранных — в $ или €.

    Для платежей в ₽ (RUB) доступен платежный метод BANK131, для платежей в € (EUR) или $ (USD) — UNLIMINT, PAYPAL и STRIPE.

    *STRIPE доступен только для оплаты продуктов.

    Как выглядят вебхуки при оплате продуктов?

    Успешно оплаченный продукт (не подписка):

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":0,
    "status":"completed",
    "product": {
    "id":"06d8bbba-01ee-437c-b646-b729e8b10d94",
    "title":"Чек-лист для путешественников"
    },
    "currency":"RUB",
    "eventType":"payment.success",
    "timestamp":"2025-02-25T17:41:00.214516Z",
    "contractId":"3115b27b-2312-430a-9ea4-5dfe200afedd",
    "errorMessage":""
    }

    Ошибка при совершении оплаты продукта (не подписка):

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":2050,
    "status":"failed",
    "product": {
    "id":"06d8bbba-01ee-437c-b646-b729e8b10d95",
    "title":"Чек-лист для путешественников"
    },
    "currency":"RUB",
    "timestamp":"2025-01-19T14:00:38.217567Z",
    "contractId":"b6dbcbc8-76c6-44b1-b884-a6fa83e319e3",
    "errorMessage":"Payment window is opened but not completed"
    }

    Успешно оплаченный продукт с UTM-меткой (не подписка):

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":0,
    "status":"completed",
    "product": {
    "id":"06d8bbba-01ee-437c-b646-b729e8b10d98",
    "title":"Чек-лист для путешественников"
    },
    "currency":"EUR",
    "clientUtm": {
    "utm_source":"google"
    },
    "eventType":"payment.success",
    "timestamp":"2025-02-26T05:37:03.253994Z",
    "contractId":"3fbf3ebd-2f3f-473b-820b-7089b5af0231",
    "errorMessage":""
    }


    Клиент купил продукт, но я не получил вебхук. Почему?

    Скорее всего, клиент купил продукт через платформу, а не через настроенную интеграцию. Такие платежи не видны при запросе по API, их можно отслеживать в личном кабинете в разделе «Мои продажи».

    Также важно, чтобы для каждого типа события был настроен соответствующий вебхук.

    Например, для приёма платежей по продуктам нужно создать только вебхук с типом «Результат платежа», а для подписок два: «Результат платежа» — на него будут приходить события оформления подписки (первая оплата) и «Регулярный платёж» — на него будут приходить события продления подписки (все последующие автоматические оплаты).


    Если вебхуки не были отправлены из-за ошибки, будут ли они отправлены позже?

    Если вебхуки не были доставлены, система предпримет попытки повторно отправить их на указанный URL. Периодичность повторных попыток составляет:

    • 1s,
    • 5s,
    • 15s,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1m,
    • 1h,
    • 1h,
    • 1h,
    • 1h,
    • 1h.

    Всего будет сделано до 20 попыток.


    Нужно ли отвечать на вебхуки?

    Да, на вебхуки нужно отвечать кодом 2ХХ или 3ХХ.

    Это подтверждает, что запрос получен успешно. Любая другая информация, возвращаемая в заголовках или теле запроса, в таком случае игнорируется.


    Есть ли тестовая зона?

    Сейчас тестовой зоны нет. Однако можно протестировать интеграцию с минимальным по стоимости контентом. Например, для подписки минимальный платёж составит 50₽, 5$ или 5€.


    Есть ли ограничения по времени у ссылки на оплату?

    Для контрактов в $ и € этот срок составляет 15 минут, а для контрактов в ₽ — 24 часа.


    Можно ли увидеть скрытый со страницы автора продукт через API?

    Продукт будет отображаться, если в запросе на получение списка продуктов указать параметр feedVisibility со значением ALL или ONLY_HIDDEN. Если же указать ONLY_VISIBLE, продукт не будет виден.

    Возможные значения: ALL, ONLY_VISIBLE, ONLY_HIDDEN. По умолчанию используется ONLY_VISIBLE.


    Каким параметром передается ключ на API?

    Ключ передается через хедеры X-Api-Key:{api_key}

    Пример запроса:

    curl --location 'https://gate.lava.top/api/v2/invoice' \
    --header 'accept: application/json' \
    --header 'X-Api-Key: a3qwWQdrzGdASXEoORla2B5BUGhxWlpGW9 Z4U0S9VyGHA1ScHJVXb9VStpj35OLV' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "email":"[email protected]",
    "offerId": "d3d784da-124c-4124-8a00-0a22abcb9bb0",
    "currency": "RUB",
    "buyerLanguage":"EN"
    }'


    Можно ли отправлять вебхуки на HTTP?

    Нет, URL-адрес, по которому будут отправляться вебхуки, должен быть защищён протоколом HTTPS. Мы ввели ограничение на использование HTTP в целях безопасности.


    Необходимо ли пользователю вводить адрес электронной почты на стороне сервиса?

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


    Можно ли передать свои данные при создании ссылки на оплату?

    При создании контракта через API можно указать UTM-метки. Вот как это работает:

    При отправке запроса POST /invoice автор может передать объект clientUtm, который может содержать один или несколько параметров, начинающихся с utm_*.

    Ограничения по длине следующие:
    • utm_source (источник трафика, например Google, Facebook) — максимум 100 символов;
    • utm_medium (средство маркетинговой кампании, например электронная почта, CPC, баннер) — максимум 100 символов;
    • utm_campaign (конкретное имя кампании или идентификатор, например spring_sale, product_launch) — максимум 100 символов;
    • utm_term (ключевые слова или поисковые термины для платных кампаний, например «sneakers») — максимум 100 символов;
    • utm_content (варианты одного и того же объявления или кампании, например «banner_ad_A») — максимум 100 символов.

    Пример:

    }
    curl -X 'POST' \
    'https://gate.lava.top/api/v2/invoice' \
    -H 'accept: application/json' \
    -H 'X-Api-Key: 0oURuGfr83o85FgAyGmzPEzfMo46phQNexByKYTwTtbGst7tPLmKdxraGHZAPNWa' \
    -H 'Content-Type: application/json' \
    -d '{
    "email": "[email protected]",
    "offerId": "77fbbeac-792f-4f19-9d3e-0e6918238944",
    "periodicity": "ONE_TIME",
    "currency": "RUB",
    "paymentMethod": "BANK131",
    "buyerLanguage": "RU",
    "clientUtm": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "summer_sale",
    "utm_term": "running_shoes",
    "utm_content": "homepage_banner"
    }
    }'

    Если при создании контракта были применены UTM-метки, они будут возвращены в веб-хук события.


    Осуществляется ли проверка данных?

    Со своей стороны мы проверяем корректность данных, в частности, email адрес. Например, покупатель не сможет ввести невалидный адрес. Также мы контролируем валюту платежа — нельзя создать платёж в валюте, отличной от ₽, $ или €. Кроме того, мы проверяем offerId — нельзя создать платёж на идентификатор продукта другого автора или несуществующего продукта.


    Вопросы о подписках


    Как создать рекуррентный платеж?

    Тип контракта определяется автоматически в зависимости от выбранного продукта. Можно выделить два основных типа продуктов:

    1. Subscription (подписка) — контракты этого типа всегда будут повторяющимися. Покупатель должен будет совершить первый платёж вручную, а последующие платежи будут происходить автоматически с заданной периодичностью, например, раз в месяц. Также можно настроить другие периоды оплаты.

    2. Все остальные типы (продукт, курс, консультация и донат) — для них будет доступен только обычный платёж, то есть разовое списание.

    Поэтому для подписки нужно создать два вебхука с типами события: «Результат платежа» и «Регулярный платеж». На первый будут приходить события оформления подписки (первый платеж), на второй — продления (все последующие автоматические платежи).


    Как создать подписку с рекуррентными платежами более чем на один месяц?

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


    Как принимать платежи по подписке с разными периодами оплаты?

    Оплаты также принимаются через метод POST — /api/v2/invoice. Вот что нужно сделать:

    1. Создать подписку в личном кабинете, включив нужные периоды оплаты.

    2. Получить список тарифов подписки с различными периодами оплаты методом GET v2/products.

    3. Скопировать offer_id нужного тарифа подписки.

    4. Отправить запрос на создание invoice методом POST v2/invoice. Для этого укажите в запросе:

    • email покупателя;
    • offer_id тарифа;
    • periodicity — период оплаты;
    • currency — валюту в которой будет покупка;
    • paymentMethod — банк, через который пройдет оплата;
    • language — язык, на котором будут отправляться письма клиенту об успешной покупке;
    • clientUTM — метки, которые можно использовать для более точной информации об оплате (подробнее здесь).
    curl --location 'https://gate.lava.top/api/v2/invoice' \
    --header 'accept: application/json' \
    --header 'X-Api-Key: a3qwWQdrzGdASXEoORla2B5BUGhxWlpGW9 Z4U0S9VyGHA1ScHJVXb9VStpj35OLV' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "email": "[email protected]",
    "offerId": "d3d784da-124c-4124-8a00-0a22abcb9bb0",
    "periodicity": "PERIOD_90_DAYS",
    "currency": "RUB",
    "paymentMethod": "BANK131",
    "buyerLanguage": "EN"
    }'

    5. Покупатель получит ссылку на оплату.


    Какие есть периоды оплаты подписок?

    Существуют следующие периоды рекуррентных списаний ("periodicity"):

    • 1 месяц («MONTHLY») — списание через 30 дней;
    • 3 месяца («PERIOD_90_DAYS») — списание через 90 дней;
    • 6 месяцев («PERIOD_180_DAYS») — списание через 180 дней;
    • 12 месяцев («PERIOD_YEAR») — списание через 365 дней.


    В чём разница между contractId и parentContractId?

    ContractId — это уникальный идентификатор платежа. Он будет меняться для каждого нового платежа.

    ParentContractId — это идентификатор родительского (первого успешно осуществленного платежа по подписке) контракта, который используется в каждом последующем дочернем платеже. Для каждого последующего платежа по подписке этот идентификатор будет одинаковым.

    Если покупатель оформляет новую подписку, например, по другому тарифу или если он отменяет подписку и сразу оформляет новую, создается новый parentContractId. В таких случаях формируется новый контракт с уникальным contractId, и во всех последующих платежах будет использоваться родительский идентификатор, связанный с этим первым платежом.

    Таким образом, parentContractId всегда равен contractId первого платежа.


    Как выглядят вебхуки при оплате подписки?

    Успешная оплата подписки:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-active",
    "product": {
    "id":"e3dc5b9b-d511-4b79-9457-edfb405a5cc5",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "eventType":"payment.success",
    "timestamp":"2025-02-26T05:56:37.612665Z",
    "contractId":"32a8f412-2b99-408e-9682-2995971c26fc",
    "errorMessage":""
    }

    Успешный совершенный второй, третий и последующие платежи по подписке:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-active",
    "product": {
    "id":"e3dc5b9b-d511-4b79-9457-edfb404a5vc5",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "eventType":"subscription.recurring.payment.success",
    "timestamp":"2025-02-26T05:39:22.774967Z",
    "contractId":"1e255225-23ac-4b6a-8528-1848cf5e153f",
    "errorMessage":"",
    "parentContractId":"1e180437-56b7-46d9-a649-31c85403d1f2"
    }

    Ошибка при оплате первого платежа по подписке:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-failed",
    "product": {
    "id":"e3dc5b9b-d511-4b79-9457-edfb504a5cc5",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "eventType":"payment.failed",
    "timestamp":"2025-02-26T06:00:07.801014Z",
    "contractId":"9fca98a4-9478-4728-a2af-90ff306ef289",
    "errorMessage":"Payment window is opened but not completed"
    }

    Ошибка при оплате второго, третьего и последующих платежей по подписке:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-failed",
    "product": {
    "id":"e3dc5b9b-d511-5b79-9457-edfb404a5cc5",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "eventType":"subscription.recurring.payment.failed",
    "timestamp":"2025-02-26T05:49:35.206788Z",
    "contractId":"166c85e7-456f-42e0-95fb-346a6fcd59a7",
    "errorMessage":"Not sufficient funds",
    "parentContractId":"a3f8bd97-29b4-47e5-907c-a2c690921120"
    }

    Успешная оплата подписки с UTM-меткой:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-active",
    "product": {
    "id":"2f4e2827-3c4e-4ab3-a2ea-2d03439a8f9c",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "clientUtm": {
    "utm_source":"google"
    },
    "eventType":"payment.success",
    "timestamp":"2025-02-26T06:10:25.520428Z",
    "contractId":"0098bba1-876f-49e4-90af-96028689590f",
    "errorMessage":""
    }


    Есть ли дополнительные попытки списания, если платеж не прошел?

    Да, если очередной платеж по подписке не прошел (например, на карте было недостаточно средств), будет еще две дополнительные попытки списания: через 8 и 24 часа.

    При этом автор получит вебхук только в том случае, если одна из этих попыток будет успешной и подписка продлится:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-active",
    "product": {
    "id":"e3dc5b9b-d511-4b79-9457-edfb404a5vc5",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "eventType":"subscription.recurring.payment.success",
    "timestamp":"2025-02-26T05:39:22.774967Z",
    "contractId":"1e255225-23ac-4b6a-8528-1848cf5e153f",
    "errorMessage":"",
    "parentContractId":"1e180437-56b7-46d9-a649-31c85403d1f2"
    }

    Либо если последняя попытка также будет неуспешной и подписка автоматически отменится:

    {
    "buyer": {
    "email":"[email protected]"
    },
    "amount":1000,
    "status":"subscription-failed",
    "product": {
    "id":"e3dc5b9b-d511-5b79-9457-edfb404a5cc5",
    "title":"Subscription 3094697731"
    },
    "currency":"RUB",
    "eventType":"subscription.recurring.payment.failed",
    "timestamp":"2025-02-26T05:49:35.206788Z",
    "contractId":"166c85e7-456f-42e0-95fb-346a6fcd59a7",
    "errorMessage":"Not sufficient funds",
    "parentContractId":"a3f8bd97-29b4-47e5-907c-a2c690921120"
    }

    Вебхуков по каждой дополнительной попытке списания не будет.


    Как автор может отменить подписку клиента?

    Это можно сделать через API методом DELETE/api/v1/subscriptions. Необходимо передать ID первого контракта и почту покупателя.

    Пример:

    -X 'DELETE' \
    'https://api.lava.top/pas/api/v1/subscriptions?contractId={parentContractId}&email={buyerEmail}' \
    -H 'accept: */*' \
    -H 'X-Api-Key: {api_key}'


    Можно ли проверить статус подписки через API?

    С помощью метода GET/api/v1/invoices можно получить список продаж, в котором также можно увидеть следующие данные:

    • актуальный статус контракта;
    • сумма контракта;
    • почта покупателя и маска номера карты;
    • название продукта и тарифа;
    • для подписок — ParentInvoiceID — ID родительской транзакции по оформлению подписки;
    • статус подписки (исключение — expired — подписку отменили намеренно до наступления повторного списания);
    • назначенные UTM-метки по каждому контракту.

    Пример:

    {
    "items": [
    {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "ONE_TIME",
    "datetime": "2025-01-17T14:02:34.852Z",
    "status": "NEW",
    "receipt": {
    "amount": 0,
    "currency": "RUB",
    "fee": 0
    },
    "buyer": {
    "email": "[email protected]",
    "cardMask": "**** **** **** 1234"
    },
    "product": {
    "name": "Урок по психологии",
    "offer": "Подписка на 12 мес."
    },
    "parentInvoice": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "subscriptionStatus": "ACTIVE",
    "clientUtm": {
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign: "summer_sale",
    "utmTerm": "running_shoes",
    "utmContent: "homepage_banner"
    }
    }
    ],
    "page": 0,
    "size": 0,
    "total": 0
    }


    Можно ли оформить одну и ту же подписку дважды?

    Да, это возможно. Списания привязываются к контракту, то есть, первому платежу по подписке.


    Как обновить стоимость подписки?

    В настоящее время функция обновления стоимости подписки через метод PATCH products/{product_id} недоступна. Изменить стоимость можно только в личном кабинете.


    Если у вас еще остались вопросы, напишите нам https://t.me/lava_sup_bot. Будем рады помочь!м