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

Контрагенты: список, карточка, создание и правка. Карточка запрашивается методом POST — единственное чтение в API, устроенное так.

Контрагент · `contractor`¶

`GET` `/api/contractors`¶

Список записей с постраничной выборкой.

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

Параметр	Тип	Ограничения
`limit`	int	диапазон 1..100, по умолчанию 100
`offset`	int	по умолчанию 0

Коды ответа

Код	Что значит
`200`	успешный
`401`	нет доступа: ключ не передан, просрочен или неверен
`400`	неверный запрос: не хватает параметра или он не того типа

Поля ответа

Поле	Тип	Значение
`meta`	object	Метаданные о выдаче
`meta.allCount`	int	Количество всех контрагентов
`meta.count`	int	Размер выданного списка
`meta.limit`	int	Максимальное количество элементов в выданном списке. Максимальное количество элементов в списке равно 100.
`meta.offset`	int	Отступ в выданном списке
`data`	array (object)	Массив JSON объектов, представляющих собой контрагент.
`data[].id`	int	Идентификатор контрагента
`data[].type`	string	Тип контрагента (Значения: ЮЛ - Юр. лицо, ИП - Индивидуальный предприниматель, ФЛ - Физ. лицо)
`data[].name`	string	Наименование контрагента
`data[].contactPerson`	string	Контактное лицо
`data[].inn`	string	ИНН
`data[].kpp`	string	КПП
`data[].status`	string	Статус контрагента
`data[].discount`	double	Скидка % для контрагента
`data[].legalAddress`	string	Юридический адрес
`data[].actualAddress`	string	Фактический адрес
`data[].phone1`	string	Номер телефона 1
`data[].phone2`	string	Номер телефона 2
`data[].email`	string	Эл. адрес почты
`data[].staff`	object	Ответственный сотрудник
`data[].staff.id`	int	Идентификатор сотрудника
`data[].staff.name`	string	Наименование сотрудника
`data[].balance`	float	Баланс контрагента
`data[].bonus`	object	Бонусная система контрагента
`data[].bonus.status`	int	Статус бонусной системы (0 - Не участвует, 1 - Участвует)
`data[].bonus.percent`	float	Процент % накопления
`data[].bonus.usePercent`	float	Процент % использования
`data[].bonus.code`	string	Код накопления (номер карты)
`data[].bonus.balance`	float	Баланс бонусов контрагента
`data[].giftCards`	array (object)	Подарочные карты
`data[].giftCards[].code`	string	Код/Номер карты
`data[].giftCards[].price`	string	Цена карты
`data[].banks`	array (object)	Расчетные счета контрагента
`data[].banks[].bik`	string	БИК банка
`data[].banks[].bank`	string	Наименования банка
`data[].banks[].korNumber`	string	Корр. счет
`data[].banks[].rasNumber`	string	Расчетный счет

Ошибки

ERROR_LIMIT ERROR_OFFSET ERROR_USER_ACCESS ERROR_NO_API_KEY

Запрос получения списка контрагентов

Host: app.masterkassa.com

GET /api/contractors?limit=10&offset=40

Authorization: Bearer <ключ>

Ответ получения списка контрагентов

HTTP code: 200

{
  "meta": {
    "allCount": 42,
    "count": 2,
    "limit": 10,
    "offset": 40
  },
  "data": [
    {
      "id": 10,
      "type": "ЮЛ",
      "name": "ООО «Ромашка»",
      "contactPerson": "Иванов Иван Иванович",
      "inn": "7700000000",
      "kpp": "770001001",
      "status": "Поставщик",
      "discount": 0,
      "legalAddress": "г. Москва, ул. Примерная, 1",
      "actualAddress": "",
      "phone1": "+7 900 000-00-00",
      "phone2": "",
      "email": "info@example.com",
      "staff": {
        "id": 5,
        "name": "ООО «Ромашка»"
      },
      "balance": 12540,
      "bonus": {
        "status": 1,
        "percent": 5,
        "usePercent": 30,
        "code": "0000000000000",
        "balance": 1143.5
      },
      "giftCards": [
        {
          "code": "0000000000000",
          "price": 10000
        },
        {
          "code": "0000000000000",
          "price": 25000
        }
      ],
      "banks": [
        {
          "bik": "044500000",
          "bank": "АО \"АЛЬФА-БАНК\"",
          "korNumber": "30101810000000000000",
          "rasNumber": "40702810000000000000"
        }
      ]
    },
    {
      "id": 11,
      "type": "ФЛ",
      "name": "Иванов Иван Иванович",
      "contactPerson": "Иванов Иван Иванович",
      "inn": "",
      "kpp": "",
      "status": "Покупатель",
      "discount": 10,
      "legalAddress": "",
      "actualAddress": "",
      "phone1": "+7 900 000-00-00",
      "phone2": "",
      "email": "",
      "staff": {
        "id": 0,
        "name": "ООО «Ромашка»"
      },
      "balance": -1200,
      "bonus": {
        "status": 0,
        "percent": 0,
        "usePercent": 0,
        "code": "0000000000000",
        "balance": 0
      },
      "giftCards": [],
      "banks": []
    }
  ]
}

`POST` `/api/contractor`¶

Одна запись по идентификатору.

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

Параметр	Тип	Ограничения
`id`	int	Идентификатор контрагента в системе
`phone`	string	Номер телефона контрагента
`inn`	string	ИНН контрагента

Тело запроса

Поле	Тип	Ограничения
`id`	int
`phone`	string
`inn`	string

Коды ответа

Код	Что значит
`200`	успешный
`401`	нет доступа: ключ не передан, просрочен или неверен
`400`	неверный запрос: не хватает параметра или он не того типа

Поля ответа

Поле	Тип	Значение
`data`	object	JSON объект контрагент
`data.id`	int	Идентификатор контрагента
`data.type`	string	Тип контрагента (Значения: ЮЛ - Юр. лицо, ИП - Индивидуальный предприниматель, ФЛ - Физ. лицо)
`data.name`	string	Наименование контрагента
`data.contactPerson`	string	Контактное лицо
`data.inn`	string	ИНН
`data.kpp`	string	КПП
`data.status`	string	Статус контрагента
`data.discount`	double	Скидка % для контрагента
`data.legalAddress`	string	Юридический адрес
`data.actualAddress`	string	Фактический адрес
`data.phone1`	string	Номер телефона 1
`data.phone2`	string	Номер телефона 2
`data.email`	string	Эл. адрес почты
`data.staff`	object	Ответственный сотрудник
`data.staff.id`	int	Идентификатор сотрудника
`data.staff.name`	string	Наименование сотрудника
`data.balance`	float	Баланс контрагента
`data.bonus`	object	Бонусная система контрагента
`data.bonus.status`	int	Статус бонусной системы (0 - Не участвует, 1 - Участвует)
`data.bonus.percent`	float	Процент % накопления
`data.bonus.usePercent`	float	Процент % использования
`data.bonus.code`	string	Код накопления (номер карты)
`data.bonus.balance`	float	Баланс бонусов контрагента
`data.giftCards`	array (object)	Подарочные карты
`data.giftCards[].code`	string	Код/Номер карты
`data.giftCards[].price`	string	Цена карты
`data.banks`	array (object)	Расчетные счета контрагента
`data.banks[].bik`	string	БИК банка
`data.banks[].bank`	string	Наименования банка
`data.banks[].korNumber`	string	Корр. счет
`data.banks[].rasNumber`	string	Расчетный счет

Ошибки

ERROR_ID ERROR_PHONE ERROR_INN ERROR_USER_ACCESS ERROR_NO_API_KEY

Запрос получения информация контрагента

Host: app.masterkassa.com

POST /api/contractor

Authorization: Bearer <ключ>

Ответ получения информация контрагента

HTTP code: 200

{
  "data": {
    "id": 10,
    "type": "ЮЛ",
    "name": "ООО «Ромашка»",
    "contactPerson": "Иванов Иван Иванович",
    "inn": "7700000000",
    "kpp": "770001001",
    "status": "Поставщик",
    "discount": 0,
    "legalAddress": "г. Москва, ул. Примерная, 1",
    "actualAddress": "",
    "phone1": "+7 900 000-00-00",
    "phone2": "",
    "email": "info@example.com",
    "staff": {
      "id": 5,
      "name": "ООО «Ромашка»"
    },
    "balance": 12540,
    "bonus": {
      "status": 1,
      "percent": 5,
      "usePercent": 30,
      "code": "0000000000000",
      "balance": 1143.5
    },
    "giftCards": [
      {
        "code": "0000000000000",
        "price": 10000
      },
      {
        "code": "0000000000000",
        "price": 25000
      }
    ],
    "banks": [
      {
        "bik": "044500000",
        "bank": "АО \"АЛЬФА-БАНК\"",
        "korNumber": "30101810000000000000",
        "rasNumber": "40702810000000000000"
      }
    ]
  }
}

POST, хотя операция читающая — единственный такой случай в API.

`GET+POST` `/api/add-contractor`¶

Создание записей.

Запись в два шага

GET /api/add-contractor -> access_token, живёт 1 минуту. POST /api/add-contractor с заголовком X-Access-Token. Предел пакета — 100 записей.

Тело запроса — объект contractors со списком записей

Поле	Тип	Ограничения
`type`	string	обязательное
`name`	string	обязательное
`contactPerson`	string	обязательное
`phone1`	string	обязательное
`inn`	string
`kpp`	string
`status`	string
`discount`	double

Коды ответа

Код	Что значит
`200`	успешный
`401`	нет доступа: ключ не передан, просрочен или неверен
`400`	неверный запрос: не хватает параметра или он не того типа

Поля ответа

Поле	Тип	Значение
`data`	object	JSON объект ключа
`data.access_token`	string	Ключ доступа
`data.expired`	date, time	Время окончания жизни ключа доступа (по Московскому времени)
`contractors`	array (object)	Массив JSON объектов контрагента (Максимум 100 контрагентов в одном запросе)
`contractors[].inn`	string	ИНН
`contractors[].kpp`	string	КПП
`contractors[].status`	string	Статус контрагента (Если нет в системе, то создается)
`contractors[].discount`	double	Скидка %
`contractors[].legalAddress`	string	Юридический адрес
`contractors[].actualAddress`	string	Фактический адрес
`contractors[].phone2`	string	Номер телефона 2
`contractors[].email`	string	Эл. адрес почты
`contractors.data`	array (object)	Массив JSON объектов, представляющих собой идентификаторы контрагентов.
`contractors.data[].id`	int	Идентификатор контрагента
`contractors.data[].name`	string	Наименование контрагента

Ошибки

ERROR_CONTRACTORS ERROR_NAME ERROR_TYPE ERROR_PHONE ERROR_INN ERROR_USER_ACCESS ERROR_NO_API_KEY

1. Запрос получения ключа доступа для добавления контрагентов

Host: app.masterkassa.com

GET /api/add-contractor/

Authorization: Bearer <ключ>

1. Ответ получения ключа доступа для добавления контрагентов

HTTP code: 200

{
  "data": {
    "access_token": "c87efe57719607ca1f8ec87fbe219607ca1fefe577edf3ffbe2426bdf3f8426b",
    "expired": "2025-05-24 13:17:45"
  }
}

2.Запрос добавления контрагентов

Host: app.masterkassa.com

POST /api/add-contractor/

Authorization: Bearer <ключ>

X-Access-Token: c87efe57719607ca1f8ec87fbe219607ca1fefe577edf3ffbe2426bdf3f8426b

{
  "contractors": [
    {
      "type": "ЮЛ",
      "name": "ООО «Ромашка»",
      "contactPerson": "Иванов Иван Иванович",
      "inn": "7700000000",
      "kpp": "770001001",
      "status": "Поставщик",
      "discount": 0,
      "legalAddress": "г. Москва, ул. Примерная, 1",
      "actualAddress": "г. Москва, ул. Примерная, 1",
      "phone1": "+7 900 000-00-00",
      "phone2": "",
      "email": ""
    },
    {
      "type": "ФЛ",
      "name": "Иванов Иван Иванович",
      "contactPerson": "Иванов Иван Иванович",
      "phone1": "+7 900 000-00-00"
    }
  ]
}

2. Ответ добавления контрагентов

HTTP code: 200

{
  "data": [
    {
      "id": 10,
      "name": "ООО «Ромашка»"
    },
    {
      "id": 11,
      "name": "ООО «Ромашка»"
    }
  ]
}

`GET+POST` `/api/edit-contractor`¶

Изменение записей.

Запись в два шага

GET /api/edit-contractor -> access_token, живёт 1 минуту. POST /api/edit-contractor с заголовком X-Access-Token. Предел пакета — 100 записей.

Тело запроса — объект contractors со списком записей

Поле	Тип	Ограничения
`id`	int	обязательное
`type`	string	обязательное
`name`	string	обязательное
`contactPerson`	string	обязательное
`phone1`	string	обязательное

Коды ответа

Код	Что значит
`200`	успешный
`401`	нет доступа: ключ не передан, просрочен или неверен
`400`	неверный запрос: не хватает параметра или он не того типа

Поля ответа

Поле	Тип	Значение
`data`	object	JSON объект ключа
`data.access_token`	string	Ключ доступа
`data.expired`	date, time	Время окончания жизни ключа доступа (по Московскому времени)
`contractors`	array (object)	Массив JSON объектов контрагента (Максимум 100 контрагентов в одном запросе)
`contractors[].inn`	string	ИНН
`contractors[].kpp`	string	КПП
`contractors[].status`	string	Статус контрагента (Если нет в системе, то создается)
`contractors[].discount`	double	Скидка %
`contractors[].legalAddress`	string	Юридический адрес
`contractors[].actualAddress`	string	Фактический адрес
`contractors[].phone2`	string	Номер телефона 2
`contractors[].email`	string	Эл. адрес почты
`contractors.data`	array (object)	Массив JSON объектов, представляющих собой идентификаторы контрагентов.
`contractors.data[].id`	int	Идентификатор контрагента
`contractors.data[].name`	string	Наименование контрагента

Ошибки

ERROR_CONTRACTORS ERROR_ID ERROR_NAME ERROR_TYPE ERROR_PHONE ERROR_INN ERROR_USER_ACCESS ERROR_NO_API_KEY

1. Запрос получения ключа доступа для редактирования контрагентов

Host: app.masterkassa.com

GET /api/edit-contractor/

Authorization: Bearer <ключ>

1. Ответ получения ключа доступа для редактирования контрагентов

HTTP code: 200

{
  "data": {
    "access_token": "c87efe57719607ca1f8ec87fbe219607ca1fefe577edf3ffbe2426bdf3f8426b",
    "expired": "2025-05-24 13:17:45"
  }
}

2.Запрос редактирования контрагентов

Host: app.masterkassa.com

POST /api/edit-contractor/

Authorization: Bearer <ключ>

X-Access-Token: c87efe57719607ca1f8ec87fbe219607ca1fefe577edf3ffbe2426bdf3f8426b

{
  "contractors": [
    {
      "id": 10,
      "type": "ЮЛ",
      "name": "ООО «Ромашка»",
      "contactPerson": "Иванов Иван Иванович",
      "inn": "7700000000",
      "kpp": "770001001",
      "status": "Поставщик",
      "discount": 0,
      "legalAddress": "г. Москва, ул. Примерная, 1",
      "actualAddress": "г. Москва, ул. Примерная, 1",
      "phone1": "+7 900 000-00-00",
      "phone2": "",
      "email": ""
    },
    {
      "id": 11,
      "type": "ФЛ",
      "name": "Иванов Иван Иванович",
      "contactPerson": "Иванов Иван Иванович",
      "phone1": "+7 900 000-00-00"
    }
  ]
}

2. Ответ редактирования контрагентов

HTTP code: 200

{
  "data": [
    {
      "id": 10,
      "name": "ООО «Ромашка»"
    },
    {
      "id": 11,
      "name": "ООО «Ромашка»"
    }
  ]
}

GET отдаёт access_token, POST с заголовком X-Access-Token применяет правку. В ответе — изменённая запись в поле data.

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

Контрагент · contractor¶

GET /api/contractors¶

POST /api/contractor¶

GET+POST /api/add-contractor¶

GET+POST /api/edit-contractor¶

Контрагент · `contractor`¶

`GET` `/api/contractors`¶

`POST` `/api/contractor`¶

`GET+POST` `/api/add-contractor`¶

`GET+POST` `/api/edit-contractor`¶