Счета

Структура базы

Счета (invoice)

  • id - Идентификатор
  • user_id(int) - Создавший пользователь - связь на пользователей
  • paid(bool) - оплачен/нет
  • closed(bool) - зыкрыт/нет
  • number(str) - Номер счета
  • date(timestamp) - Дата выставления счета (может отличаться от даты создания - редактируется пользователем)
  • performer_id(int) - Моя компания - связь на исполнителя
  • notice(text) - примечание к счету
  • deal_id(int) - Сделка - связь на сделку
  • type_id(int) - Тип счета - связь на тип счета
  • total_count(int) - количество наименований
  • total_price(money?) - Общая сумма
  • vat_price(money?) - Сумма НДС
  • pay_price(money?) - Сумма к оплате
  • created_on(timestamp) - Дата и время создания
  • paid_on(timestamp) - Дата и время оплаты
  • updated_on(timestamp) - Дата и время последнего изменения

Товары в счете (invoice_items)

  • id(int)
  • invoice_id(int) - Идентиф. счета
  • name(text) - название товара/услуги
  • units(string) - Единицы измерения
  • count(float?) - Количество единиц
  • price(money?) - Стоимость за единицу
  • total_price(money?) - Стоимость по позиции

Тип счета (invoice_type)

  • id(int)
  • name(string)

Запросы осуществляются на URL:

http://<domain.ru>/rest/invoice[parameters]

Обязательные параметры:

  • auth_key - токен авторизации для stateless доступа к сервису

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

Запрос списка в сокращенном виде:

GET https://<domain.ru>/rest/invoice

Эквивалент запросу:

GET https://<domain>.ru/rest/invoice?page=1&per_page=20

Для списка нужно по умолчанию раскрыть поля

  • компания
  • Менеджер
  • Тип
  • Статус

Допустимые параметры:
Таблица 1

Имя параметра Тип данных Описание
number string Фильтр
%LIKE%
по атрибуту number
client_id integer Фильтр по клиенту (через сделки)
deal_id integer Фильтр по сделке
company string Фильтр
%LIKE%
по атрибуту name привязанной сущности client
user_id integer Вводит ограничение на выставившего счет пользователя системы с id равным user_id
type_id integer Ограничивает выборку списка конкретным типом счетов
status_id integer Ограничивает выборку по статусам см. Таблицу 2
year integer{4} Ограничивает результирующий набор конкретным годом выставления (date, а не даты создания)
month integer[1..12] Ограничивает результирующий набор конкретным месяцем выставления (date, а не даты создания)
year integer{4} Ограничивает результирующий набор конкретным годом выставления (date, а не даты создания)
month integer[1..12] Ограничивает результирующий набор конкретным месяцем выставления (date, а не даты создания)
paid_year integer{4} Ограничивает результирующий набор конкретным годом оплаты (paid_on)
paid_month integer[1..12] Ограничивает результирующий набор конкретным месяцем оплаты (paid_on)
page unsigned integer Не обязательное. Ограничивает результат списком клиентов для страницы page с учетом per_page
per_page unsigned integer Не обязательное. Ограничивает результат списком клиентов в количестве per_page
sort string Не обязательное. Указатель на необходимость сортировки по конкретному атрибуту сущности см. описание сущности client. Доступны только общие атрибуты.
fields string Не обязательное. Указатель на необходимость выборки конкретных атрибутов сущности. см Сущность "client". Доступны только общие атрибуты.
expand string Не обязательное. Список связных сущностей, которые нужно развернуть

Таблица 2 - Статусы

id Название Оплачен Закрыт
1 Не оплачен 0 0
2 Оплачен 1 0
3 Закрыт 1 1
4 Отменен 0 0

Формат ответа

<response>
    <id>1</id>
    <paid>1</paid>
    <closed/>
    <number>1234567890</number>
    <date>2014-10-29 16:42:06</date>
    <performer>
        <id>70</id>
        <status>1</status>
        <name>Stoltenberg-Reichel</name>
        <company_name>Stoltenberg-Reichel</company_name>
        <company_address>9571 Lauryn Harbors
            Port Kianfurt, PA 30303
        </company_address>
        <real_address>314 Nader Camp
            Hettingerstad, NY 59537-5805
        </real_address>
        <bank_details>I hadn't drunk quite so much!' Alas! it was getting quite crowded with the next witness would be
            four thousand miles down, I think--' (she was so long that they must needs come wriggling down from.
        </bank_details>
        <company_details>Queen till she was considering in her pocket, and pulled out a new idea to Alice, she went
            slowly after it: 'I never said I didn't!' interrupted Alice. 'You did,' said the Queen, 'and he shall tell.
        </company_details>
        <leader>MartaRath</leader>
        <leader_rank>director</leader_rank>
        <booker>GaetanoGleason</booker>
        <phone>02134084433</phone>
        <email>nola.vonrueden@wehner.net</email>
        <vat_use>1</vat_use>
        <vat_percent>98</vat_percent>
        <stamp_file>/files/stamp.jpg</stamp_file>
        <leader_sig_file>/files/leader_sig.jpg</leader_sig_file>
        <booker_sig_file>/files/booker_sig.jpg</booker_sig_file>
        <logo>/files/logo.jpg</logo>
        <created_at>2014-10-22 16:45:14</created_at>
        <updated_at>2014-10-22 16:45:14</updated_at>
    </performer>
    <notice>Описание счета</notice>
    <type>
        <id>3</id>
        <name>typeC</name>
    </type>
    <total_count>1</total_count>
    <total_price>2342.0000</total_price>
    <vat_price>2222.0000</vat_price>
    <pay_price>4444.0000</pay_price>
    <created_on>2014-10-29 16:42:06</created_on>
    <paid_on>2014-10-29 16:42:06</paid_on>
    <update_on>2014-10-29 16:42:06</update_on>
</response>

Постраничная навигация

Заголовки

X_Pagination_Total_Count: общее количество ресурсов;
X_Pagination_Page_Count: количество страниц;
X_Pagination_Current_Page: текущая страница (начиная с 1);
X_Pagination_Per_Page: количество ресурсов на страницу;

Ссылки

<https://max.crm.ru/rest/client?access-token=<token>[&param1=value1[&...]]>; rel=self,
<https://max.crm.ru/rest/client?access-token=<token>[&param1=value1[&...]]>; rel=next, 
<https://max.crm.ru/rest/client?access-token=<token>[&param1=value1[&...]]>; rel=last

Получение по идентификатору

Запрос

Запрос в сокращенном виде:

GET https://domain.ru/rest/invoice/<id>

Возвращает карточку счета.
Возможно применение дополнительных параметров.

Допустимые параметры:
Таблица 3

Имя параметра Тип данных Описание
fields string Указатель на необходимость конкретных атрибутов сущности. см Сущность "Сделка"
expand string Содержит список сущностей, которые требуется развернуть

Формат ответов

Идентичен формату для списка

Добавление данных

POST https://domain.ru/rest/invoice

Обязательный набор атрибутов при добавлении

  • number
  • date
  • performer_id
  • client_id
  • type_id

Для строк товаров

  • name
  • units
  • items_count
  • item_price

При этом должны автоматически переписываться при создании и обновлении поля:

  • created_on
  • updated_on
  • paid_on - меняется при смене paid c 0 на 1 (или при 1 при создании)
  • total_price
  • total_count
  • pay_price
  • vat_price

Для записей товаров

  • items_total_price

При создании в историю смены статусов смены статусов должна добавиться новая запись с id текущего статуса для сделки.

Формат ответов

В случае успешного выполнения запроса:

  • Сервер возвращает код ответа 200
  • В теле ответа приходит вновь добавленная сущность в формате запроса по идентификатору (см. Получение-по-идентификатору )

В случае ошибки возвращается код ответа, отличный от 200

Изменение данных

PUT https://domain.ru/rest/invoice/<id>
PATCH https://domain.ru/rest/invoice/<id>

Тело запроса формируется идентичным запросу на добавление. Набор атрибутов идентичен. Формат ответов идентичен.

Удаление данных

DELETE https://domain.ru/rest/invoice/<id>

Тело запроса отсутствует

Формат ответов

Возвращает код ответа от сервера 200 в случае успешного выполнения запроса либо отличный от него в случае возникновения ошибки.

Документация

© «Копирайт», 2017

Web-canape - быстрое создание сайтов и продвижение