Контрагенты

Контрагент в ERP — это физическое лицо или компания, привязанная к менеджеру и типу. Поле is_company (boolean) разделяет две модели:

Физлицо (is_company: false) — first_name, last_name, middle_name, birthday, address.
Компания (is_company: true) — name, inn, kpp, head, registered_at, legal_address.

Общие поля для обоих: avatar, type, manager, phone_1, phone_2, email, created_at, updated_at.

Список и таблица

Список контрагентов

Метод: GET
URL: https://api.gigma.ru/api/counterparties
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

query — поисковая строка
is_company — фильтр компании/физлица (boolean)
counterparty_type_id[] — массив ID типов контрагентов
manager_id[] — массив ID менеджеров
date_from, date_to — диапазон по дате добавления
credit — задолженность равна (int)
credit_gt — задолженность больше
credit_lt — задолженность меньше

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

GET https://api.gigma.ru/api/counterparties?counterparty_type_id[]=2&query=иванов

Ответ

При успешном действии возвращается HTTP код 200.

{
    "counterparties": [
        {
            "id": 1,
            "is_company": true,
            "type": { "id": 2, "name": "Юр. лицо", "avatar": null, "created_at": "2024-03-22T14:01:37.000000Z" },
            "manager": { "id": 1, "first_name": "Артём", "last_name": "Полищук", "middle_name": "Николаевич", "name": "Полищук Артём" },
            "avatar": null,
            "name": "ООО "АЙТЕКО"",
            "inn": "5403057658",
            "kpp": "540301001",
            "head": "Снегирёв Алексей Игоревич",
            "registered_at": "2020-04-02",
            "phone_1": "79999999999",
            "phone_2": "78888888888",
            "email": "support@itecho.ru",
            "legal_address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
            "created_at": "2024-03-22T14:01:37.000000Z",
            "updated_at": "2024-04-03T07:07:11.000000Z"
        }
    ]
}

Описание полей ответа

id — первичный ключ
is_company — true для компании, false для физлица
type — объект типа контрагента (id, name, avatar, created_at) или null
manager — объект менеджера (id, first_name, last_name, middle_name, name) или null
avatar — объект файла аватара (id, url, …) или null
Поля компании: name, inn, kpp, head, registered_at, legal_address
Поля физлица: first_name, last_name, middle_name, birthday, address
Общие: phone_1, phone_2, email, created_at, updated_at

Таблица контрагентов (для UI с колонками и пагинацией)

Метод: GET
URL: https://api.gigma.ru/api/tables/counterparties
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

Возвращает данные в формате, пригодном для отрисовки таблицы: список колонок, упрощённое представление контрагентов и пагинацию. Поддерживает те же query-фильтры, что и /api/counterparties.

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

Те же, что у /api/counterparties, плюс пагинация: page, per_page.

Ответ

{
    "columns": [
        { "id": 1, "table_id": 3, "order": 1, "key": "name", "has_icon": 1, "text": "Название" },
        { "id": 2, "table_id": 3, "order": 2, "key": "type", "has_icon": 1, "text": "Тип" },
        { "id": 3, "table_id": 3, "order": 3, "key": "manager", "has_icon": 1, "text": "Менеджер" },
        { "id": 4, "table_id": 3, "order": 4, "key": "inn", "has_icon": 0, "text": "ИНН" },
        { "id": 5, "table_id": 3, "order": 5, "key": "credit", "has_icon": 0, "text": "Задолженность" }
    ],
    "counterparties": [
        {
            "id": 1,
            "created_at": "2024-03-22T14:01:37.000000Z",
            "type":    { "icon": "/icons/company.svg", "value": "Юр. лицо" },
            "name":    { "icon": null, "value": "ООО "АЙТЕКО"" },
            "manager": { "icon": null, "value": "Полищук Артём" },
            "inn": "5403057658",
            "contact": null,
            "credit": 0
        }
    ],
    "pagination": {
        "total": 42,
        "per_page": 15,
        "current_page": 1,
        "last_page": 3,
        "from": 1,
        "to": 15
    }
}

Описание полей ответа

columns[] — определения колонок:
- id, table_id, order — служебные
- key — ключ поля контрагента
- has_icon — 1 если рядом со значением показывается иконка
- text — заголовок колонки
counterparties[] — упрощённые контрагенты, где type, name, manager и т.п. имеют форму { icon, value }
pagination — стандартный Laravel-пагинатор: total, per_page, current_page, last_page, from, to

Карточка контрагента

Получение контрагента по ID

Метод: GET
URL: https://api.gigma.ru/api/counterparties/{id}
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

Параметры запроса

Только id контрагента в пути URL.

Ответ

{
    "counterparty": {
        "id": 1,
        "is_company": false,
        "type": { "id": 2, "name": "Розница", "avatar": null, "created_at": "2024-03-22T14:01:37.000000Z" },
        "manager": { "id": 1, "first_name": "Артём", "last_name": "Полищук", "middle_name": "Николаевич", "name": "Полищук Артём" },
        "avatar": null,
        "first_name": "Алексей",
        "last_name": "Петров",
        "middle_name": "Викторович",
        "birthday": "1980-04-02",
        "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26",
        "phone_1": "79999999990",
        "phone_2": "78888888888",
        "email": "support@itecho.ru",
        "created_at": "2024-03-22T14:01:37.000000Z",
        "updated_at": "2024-04-03T07:07:11.000000Z"
    }
}

Создание контрагента

Метод: POST
URL: https://api.gigma.ru/api/counterparties
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

Формат тела зависит от is_company.

Физлицо (is_company: false):

is_company — false
counterparty_type_id — ID типа контрагента (nullable)
avatar_id — ID файла аватара (optional)
first_name, last_name, middle_name — ФИО
birthday — YYYY-MM-DD
phone_1, phone_2, email, address

Компания (is_company: true):

is_company — true
counterparty_type_id — ID типа
avatar_id — ID файла (optional)
name — название
inn, kpp
head — ФИО директора
registered_at — дата регистрации YYYY-MM-DD
phone_1, phone_2, email, legal_address

Пример запроса (физлицо)

{
    "is_company": false,
    "counterparty_type_id": 2,
    "first_name": "Алексей",
    "last_name": "Петров",
    "middle_name": "Викторович",
    "birthday": "1980-04-02",
    "phone_1": "79999999990",
    "phone_2": "78888888888",
    "email": "support@itecho.ru",
    "address": "630073, г. Новосибирск, Новогодняя ул., д. 20/1, кв. 26"
}

Ответ

{
    "counterparty": { "id": 42, "is_company": false, "...": "поля как в GET" }
}

Изменение контрагента

Метод: PUT
URL: https://api.gigma.ru/api/counterparties/{id}
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

Те же поля, что и в POST /api/counterparties (соответствующий вариант is_company).

Ответ

{
    "counterparty": { "id": 42, "...": "обновлённый объект" }
}

Удаление контрагента

Метод: DELETE
URL: https://api.gigma.ru/api/counterparties/{id}
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

Параметры запроса

Только id контрагента в пути URL.

Ответ

При успешном действии возвращается HTTP код 200.

{
    "message": "Counterparty deleted"
}

Банковские реквизиты

Список банковских реквизитов контрагента

Метод: GET
URL: https://api.gigma.ru/api/counterparties/{id}/bank_requisites
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

Ответ

{
    "bankRequisites": [
        {
            "id": 1,
            "name": "Расчётный счёт в Сбербанке",
            "bik": "045004641",
            "kpp": "540301001",
            "payment_account": "40702810844050003101",
            "address": "630007, Новосибирская область, г. Новосибирск, Красный проспект, д. 5",
            "created_at": "2024-03-22T14:01:37.000000Z",
            "updated_at": "2024-04-03T07:07:11.000000Z"
        }
    ],
    "bankRequisitesCount": 1
}

Описание полей ответа

bankRequisites[] — массив реквизитов:
- id, name — название счёта/банка
- bik — БИК
- kpp — КПП
- payment_account — номер расчётного счёта
- address — адрес банка
bankRequisitesCount — общее количество

Добавление банковского реквизита

Метод: POST
URL: https://api.gigma.ru/api/counterparties/{id}/bank_requisites
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

name — название счёта/банка
bik — БИК
kpp — КПП
payment_account — номер расчётного счёта
address — адрес банка

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

{
    "name": "Расчётный счёт в Сбербанке",
    "bik": "045004641",
    "kpp": "540301001",
    "payment_account": "40702810844050003101",
    "address": "630007, г. Новосибирск, Красный проспект, д. 5"
}

Ответ

{
    "bankRequisites": [
        { "id": 1, "name": "Расчётный счёт в Сбербанке", "bik": "045004641", "kpp": "540301001", "payment_account": "40702810844050003101", "address": "630007, г. Новосибирск, Красный проспект, д. 5" }
    ],
    "bankRequisitesCount": 1
}

Изменение банковского реквизита

Метод: PUT
URL: https://api.gigma.ru/api/counterparties/{id}/bank_requisites/{requisiteId}
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

Те же поля, что и в POST: name, bik, kpp, payment_account, address.

Ответ

Структура аналогична GET — массив bankRequisites и bankRequisitesCount.

Контакты контрагента

Список контактов контрагента

Метод: GET
URL: https://api.gigma.ru/api/counterparties/{id}/contacts
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

Ответ

{
    "contacts": [
        {
            "id": 1,
            "first_name": "Анна",
            "last_name": "Иванова",
            "middle_name": "Сергеевна",
            "birthday": "1985-07-15",
            "phone_1": "79991234567",
            "phone_2": "",
            "email": "anna@itecho.ru",
            "address": "г. Новосибирск, ул. Ленина, 1"
        }
    ],
    "contactsCount": 1
}

Описание полей ответа

contacts[] — массив контактных лиц: id, first_name, last_name, middle_name, birthday, phone_1, phone_2, email, address
contactsCount — общее количество

Добавление контакта

Метод: POST
URL: https://api.gigma.ru/api/counterparties/{id}/contacts
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

first_name, last_name, middle_name — ФИО
birthday — YYYY-MM-DD
phone_1, phone_2, email, address

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

{
    "first_name": "Анна",
    "last_name": "Иванова",
    "middle_name": "Сергеевна",
    "birthday": "1985-07-15",
    "phone_1": "79991234567",
    "phone_2": "",
    "email": "anna@itecho.ru",
    "address": "г. Новосибирск, ул. Ленина, 1"
}

Ответ

Структура аналогична GET — массив contacts и contactsCount.

Изменение контакта

Метод: PUT
URL: https://api.gigma.ru/api/counterparties/{id}/contacts/{contactId}
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

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

Те же поля, что и в POST.

Ответ

Структура аналогична GET.

История изменений

История изменений контрагента

Метод: GET
URL: https://api.gigma.ru/api/counterparties/{id}/history
Авторизация: Bearer token
Headers: Accept: application/json; Content-Type: application/json

Возвращает события по контрагенту в формате таймлайна с пагинацией.

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

page, per_page — пагинация

Ответ

{
    "counterparties": {
        "current_page": 1,
        "data": [
            {
                "id": 101,
                "icon": "edit",
                "color": "info",
                "title": "Изменён телефон",
                "description": "phone_1: 79999999990 → 79991112233",
                "dateTime": "2024-04-03T07:07:11.000000Z"
            }
        ],
        "first_page_url": "https://api.gigma.ru/api/counterparties/1/history?page=1",
        "from": 1,
        "last_page": 2,
        "last_page_url": "https://api.gigma.ru/api/counterparties/1/history?page=2",
        "next_page_url": "https://api.gigma.ru/api/counterparties/1/history?page=2",
        "path": "https://api.gigma.ru/api/counterparties/1/history",
        "per_page": 15,
        "prev_page_url": null,
        "to": 15,
        "total": 20,
        "links": [
            { "url": null, "label": "&laquo; Previous", "active": false },
            { "url": "https://api.gigma.ru/api/counterparties/1/history?page=1", "label": "1", "active": true },
            { "url": "https://api.gigma.ru/api/counterparties/1/history?page=2", "label": "2", "active": false }
        ]
    }
}

Описание полей ответа

counterparties.data[] — события:
- id — ID события
- icon — имя иконки (edit, add, delete, …)
- color — primary | secondary | info | success | warning | error | dark | light
- title — короткий заголовок события
- description — описание изменения
- dateTime — ISO-8601
Остальные поля — стандартный Laravel-пагинатор