Документация по REST API Chekly.ru

Это руководство поможет вам интегрировать ваши системы с сервисом Chekly для автоматического создания счетов и управления ими.

Начало работы

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

Все запросы к API должны быть аутентифицированы с помощью API-токена. Вы можете найти ваш персональный токен на странице "Профиль".

Токен необходимо передавать в заголовке Authorization каждого запроса.

Authorization: Bearer <ваш_api_токен>

Ресурсы

Счета (Invoices)

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

Возвращает список счетов с возможностью фильтрации и пагинации.

Параметры запроса (Query)

Параметр	Тип	Описание
limit	integer	Количество записей на странице (по умолчанию 50, макс. 500).
offset	integer	Смещение для пагинации (по умолчанию 0).
id	integer	Фильтр по ID счета.
payment_state	string	Фильтр по статусу оплаты (paid, not_paid).
date_from / date_to	string	Фильтр по диапазону дат создания (формат YYYY-MM-DD).
customer_email	string	Фильтр по email клиента (частичное совпадение).
customer_phone	string	Фильтр по телефону клиента (частичное совпадение).

Пример ответа

{
  "data": [
    {
      "id": 101,
      "name": "СЧЕТ/2024/09/001",
      "create_date": "2024-09-27T10:00:00Z",
      "amount": 1500.00,
      "payment_state": "not_paid",
      "customer_email": "client@example.com",
      "customer_phone": "+79991234567",
      "receipt_id": null,
      "receipt_url": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Создание счета

Создает новый счет в статусе "черновик".

Тело запроса (JSON)

Поле	Тип	Описание
datetime	string	Дата создания счета в формате ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
customer_email	string	(Опционально) Email клиента для отправки фискального чека.
customer_phone	string	(Опционально) Телефон клиента для отправки фискального чека.

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

curl -X POST "https://chekly.ru/api/v1/invoices" \
-H "Authorization: Bearer <ваш_токен>" \
-H "Content-Type: application/json" \
-d '{
  "datetime": "2024-09-27T10:00:00Z",
  "customer_email": "client@example.com"
}'

Пример ответа

{
  "id": 102,
  "name": "СЧЕТ/2024/09/002"
}

Позиции счета (Invoice Lines)

Получение позиций счета

Возвращает список всех позиций для указанного счета.

Параметры запроса (Query)

invoice_id

integer

(Обязательный) ID счета, для которого нужно получить позиции.

Пример ответа

[
  {
    "id": 205,
    "product_id": 1,
    "product_name": "Консультация",
    "quantity": 1.5,
    "price": 2000.00,
    "discount": 10.0,
    "price_total": 2700.00
  }
]

Добавление позиции в счет

Добавляет новую товарную позицию в существующий счет.

Тело запроса (JSON)

Поле	Тип	Описание
invoice_id	integer	(Обязательный) ID счета, в который добавляется позиция.
product_id	integer	(Обязательный) ID услуги из вашего каталога услуг.
quantity	float	(Обязательный) Количество.
price	float	(Опционально) Цена за единицу. Если не указана, используется цена из каталога.
discount	float	(Опционально) Скидка на позицию в процентах (например, 10.5 для 10.5%). По умолчанию 0.

Пример ответа

{
  "id": 205,
  "name": "Консультация",
  "sequence": 10,
  "product_id": 1,
  "quantity": 1.5,
  "price": 2000.00,
  "discount": 10.0,
  "price_total": 2700.00
}

Платежи (Payments)

Создание платежа

Инициирует процесс оплаты для счета и возвращает ссылку на платежную форму ЮKassa.

Тело запроса (JSON)

invoice_id	integer	(Обязательный) ID счета для оплаты.
amount	float	(Обязательный) Сумма платежа.

Пример ответа

{
  "id": 55,
  "amount": 2700.00,
  "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=..."
}

Получение платежей для счета

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

Параметры запроса (Query)

invoice_id

integer

(Обязательный) ID счета, для которого нужно получить платежи.

Пример ответа

[
  {
    "id": 55,
    "amount": 2700.00,
    "is_paid": true,
    "create_date": "2024-09-27T10:05:00Z"
  }
]

Получение транзакций для платежа

Возвращает список всех транзакций (попыток оплаты) для указанного платежа.

Параметры запроса (Query)

payment_id

integer

(Обязательный) ID платежа, для которого нужно получить транзакции.

Пример ответа

[
  {
    "id": 123,
    "reference": "2d1b73c8-000f-5000-8000-1d5d81745467",
    "amount": 2700.00,
    "state": "succeeded",
    "is_processed": true,
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=...",
    "create_date": "2024-09-27T10:05:10Z"
  }
]

Услуги (Products)

Получение каталога Услуг

Возвращает список всех товаров и услуг из вашего каталога.

Пример ответа

[
  {
    "id": 1,
    "name": "Консультация",
    "price": 2000.00,
    "unit_of_measure": 71
  }
]

Создание Услуги

Создает новый товар или услугу в вашем каталоге.

Тело запроса (JSON)

name	string	(Обязательный) Название.
price	float	(Обязательный) Цена.
unit_of_measure	integer	(Обязательный) ID единицы измерения (получается из GET /api/v1/units).

Пример ответа

{
  "id": 2,
  "name": "Разработка сайта",
  "price": 50000.00,
  "unit_of_measure": 0
}

Удаление Услуги

Удаляет (архивирует) Услугу из каталога.

Параметры пути

product_id

integer

(Обязательный) ID Услуги для удаления.

Единицы измерения (Units)

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

Возвращает список всех доступных единиц измерения, которые можно использовать при создании Услуги.

Пример ответа

[
  {
    "id": 0,
    "name": "шт",
    "rounding": 1.0
  },
  {
    "id": 71,
    "name": "ч",
    "rounding": 1.0
  }
]