Справочник API POSfix

Обзор

API-сервер POSfix работает локально на POS-устройстве и предоставляет REST API на порту 4567 (HTTP). Он позволяет внешней ERP-системе выполнять фискальные операции — продажи, внесение/выдача наличных, отчёты Z/X, периодические отчёты и запросы — напрямую на POS-терминале через локальную сеть.

Базовый URL: http://<ip-устройства>:4567

Быстрый старт

1. Убедитесь, что POS-устройство и ERP находятся в одной локальной сети.
2. Получите IP-адрес устройства из Настройки > Оборудование в приложении POS или из endpoint-а health.
3. Получите API-ключ в панели управления POSfix cloud.
4. Проверьте подключение:

   GET http://<ip-устройства>:4567/api/health

5. Начните выполнять фискальные операции, используя заголовок X-API-Key.

---

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

Все endpoint-ы (кроме /api/health) требуют заголовок X-API-Key.

X-API-Key: ваш-api-ключ

API-ключ предоставляется через облачную платформу POSfix и уникален для каждого терминала.

Ключ отсутствует → 401 MISSING_API_KEY Недействительный ключ → 401 INVALID_API_KEY

---

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

Каждый ответ соответствует следующему формату:

{
  "success": true,
  "data": { ... },
  "error": null,
  "timestamp": "2026-02-16T12:00:00.000Z"
}

В случае ошибки:

{
  "success": false,
  "error": {
    "code": "КОД_ОШИБКИ",
    "message": "Описание ошибки",
    "details": [ ... ]
  },
  "timestamp": "2026-02-16T12:00:00.000Z"
}

Поле	Тип	Описание
success	boolean	true если операция выполнена успешно
data	object | null	Данные ответа (null при ошибке)
error	object | null	Информация об ошибке (null при успехе)
error.code	string	Машиночитаемый код ошибки
error.message	string	Читаемое описание ошибки
error.details	array | null	Детали ошибок валидации (на уровне полей)
timestamp	string	Временная метка ISO 8601 UTC

---

Endpoint-ы

1. Состояние и здоровье

GET /api/health

Проверка состояния сервера. Аутентификация не требуется.

Возвращает версию приложения, фискальный статус, ID терминала, IP устройства и время работы.

Поля ответа:

Поле	Тип	Описание
status	string	Состояние сервера: "ready"
version	string	Версия приложения (напр. "1.0.1+5")
fiscalStatus	string	Фискальный статус: "online", "offline", "not_fiscal"
terminalId	string	Идентификатор терминала
serverPort	int	Порт прослушивания (4567)
uptime	int	Время работы сервера в секундах
serverStartedAt	string	Временная метка ISO 8601 запуска сервера
deviceIp	string	IP-адрес устройства в локальной сети

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

{
  "success": true,
  "data": {
    "status": "ready",
    "version": "1.0.1+5",
    "fiscalStatus": "online",
    "terminalId": "T-12345",
    "serverPort": 4567,
    "uptime": 3600,
    "serverStartedAt": "2026-02-16T10:00:00.000Z",
    "deviceIp": "192.168.1.50"
  },
  "error": null,
  "timestamp": "2026-02-16T12:00:00.000Z"
}

---

2. Продажи

POST /api/sales

Создание новой продажи. Выполняет фискальную регистрацию в MEV (налоговый орган), печатает чек и опционально доставляет чек по SMS/email.

Тело запроса:

Поле	Тип	Обязательно	По умолч.	Описание
items	array	Да	—	Массив позиций продажи (минимум 1)
items[].id	string	Нет	null	Внешний ID товара из ERP. Если опущен, payload синхронизации будет содержать null
items[].name	string	Да	—	Название товара (1-100 символов)
items[].unitPrice	number	Да	—	Цена за единицу (должна быть > 0)
items[].quantity	number	Да	—	Количество (должно быть > 0). Десятичные допускаются при allowDecimals: true
items[].vatCode	string	Да	—	Код НДС: A, B, C, D, E или _
items[].discountPercent	number	Нет	0	Процент скидки на позицию (0-100)
items[].allowDecimals	boolean	Нет	false	Разрешить дробное количество (напр. 0.750 кг)
cartDiscount	object	Нет	null	Скидка на уровне корзины
cartDiscount.percent	number	Да	—	Процент скидки на корзину (0-100)
payments	array	Да	—	Массив платежей (минимум 1)
payments[].type	string	Да	—	Код типа оплаты ACPS (см. Типы оплаты)
payments[].amount	number	Да	—	Сумма платежа
payments[].rrn	string	Нет	null	RRN карточного платежа, уже проведённого в другом приложении или на другом терминале, не более 12 символов. С ним касса не запускает банковский терминал и только выдаёт чек; без него касса сама проводит оплату картой. Отмену и возврат платежа, отправленного с RRN, делают в приложении, которое провело оплату.
amountReceived	number	Да	—	Общая сумма, полученная от клиента
change	number	Да	—	Сдача, возвращённая клиенту
delivery	object	Нет	null	Опции доставки чека (SMS/email)
delivery.customerPhone	string	Нет	null	Номер телефона для доставки по SMS (формат: +XXXXXXXXXXX)
delivery.customerEmail	string	Нет	null	Email для доставки чека
delivery.customerName	string	Нет	null	Имя клиента (макс. 60 символов)
delivery.language	string	Нет	"ro"	Язык чека: "ro", "en", "ru"
printReceipt	boolean	Нет	true	Печатать чек на принтере POS

Поля ответа:

Поле	Тип	Описание
saleId	string	Локальный UUID продажи
purchaseId	string	ID покупки на сервере
serverSaleId	string	ID продажи на сервере
fiscalOperationId	string	UUID фискальной операции
receiptNumber	int	Порядковый номер чека в текущем отчёте Z
reportNumber	int	Номер текущего отчёта Z
fiscalCode	string	Фискальный код от MEV
mevId	string | null	ID транзакции MEV (null при offline)
isOffline	boolean	true если MEV был недоступен (офлайн фискальный чек)
offlineFiscalCode	string | null	Офлайн фискальный код (при работе в офлайне)
total	number	Итоговая сумма продажи (после скидок)
subtotal	number	Подитог до скидки на корзину
amountReceived	number	Сумма, полученная от клиента
change	number	Возвращённая сдача
vatBreakdown	object	Разбивка по кодам НДС (см. Разбивка НДС)
paymentBreakdown	array	Массив объектов { type, amount }
qrCodeData	string	URL QR-кода для проверки чека
mevResponseXml	string	SOAP XML ответ от MEV
receiptDelivery	object | null	{ smsSent, emailSent } — указывает, что доставка запрошена, но не подтверждена
createdAt	string	Временная метка ISO 8601

Пример — Простая продажа (1 позиция, наличные):

// Запрос
POST /api/sales
{
  "items": [
    {
      "name": "Cafea espresso",
      "unitPrice": 45.00,
      "quantity": 1,
      "vatCode": "B"
    }
  ],
  "payments": [
    { "type": "1", "amount": 45.00 }
  ],
  "amountReceived": 45.00,
  "change": 0,
  "printReceipt": true
}

// Ответ 200
{
  "success": true,
  "data": {
    "saleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "purchaseId": "server-purchase-001",
    "serverSaleId": "server-sale-001",
    "fiscalOperationId": "fiscal-op-001",
    "receiptNumber": 1,
    "reportNumber": 1,
    "fiscalCode": "MEV-TXN-001",
    "mevId": "MEV-TXN-001",
    "isOffline": false,
    "offlineFiscalCode": null,
    "total": 45.00,
    "subtotal": 45.00,
    "amountReceived": 45.00,
    "change": 0.00,
    "vatBreakdown": {
      "B": {
        "code": "B",
        "percent": 20.0,
        "vatAmount": 7.50,
        "taxableBase": 37.50,
        "totalWithVat": 45.00
      }
    },
    "paymentBreakdown": [
      { "type": "1", "amount": 45.00 }
    ],
    "qrCodeData": "https://sift-mev.sfs.md/verify?id=MEV-TXN-001",
    "mevResponseXml": "<?xml version=\"1.0\"?><soap:Envelope>...</soap:Envelope>",
    "receiptDelivery": null,
    "createdAt": "2026-02-16T12:00:00.000Z"
  },
  "error": null,
  "timestamp": "2026-02-16T12:00:00.000Z"
}

Пример — Сложная продажа (несколько позиций, смешанная оплата, скидки, доставка):

// Запрос
POST /api/sales
{
  "items": [
    {
      "id": "prod-001",
      "name": "Cafea espresso",
      "unitPrice": 45.00,
      "quantity": 2,
      "vatCode": "B"
    },
    {
      "name": "Tort Napoleon (kg)",
      "unitPrice": 180.00,
      "quantity": 0.750,
      "vatCode": "B",
      "discountPercent": 10.0,
      "allowDecimals": true
    },
    {
      "name": "Apa minerala 0.5L",
      "unitPrice": 15.00,
      "quantity": 3,
      "vatCode": "B"
    }
  ],
  "cartDiscount": {
    "percent": 5.0
  },
  "payments": [
    { "type": "1", "amount": 200.00 },
    { "type": "2", "amount": 50.00, "rrn": "123456789012" }
  ],
  "amountReceived": 250.00,
  "change": 0,
  "delivery": {
    "customerPhone": "+37369123456",
    "customerEmail": "client@email.com",
    "customerName": "Vasile Munteanu",
    "language": "ro"
  },
  "printReceipt": true
}

Ошибки валидации возвращают HTTP 400 с деталями на уровне полей:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "items[0].name",
        "code": "ITEM_NAME_INVALID",
        "message": "Item name must be 1-100 characters"
      },
      {
        "field": "items[0].unitPrice",
        "code": "ITEM_PRICE_INVALID",
        "message": "Unit price must be greater than 0"
      }
    ]
  },
  "timestamp": "2026-02-16T12:00:00.000Z"
}

---

GET /api/sales

Список продаж с фильтрацией по диапазону дат и пагинацией.

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

Параметр	Тип	Обязательно	По умолч.	Описание
dateFrom	string	Нет	—	Дата начала (ISO: YYYY-MM-DD)
dateTo	string	Нет	—	Дата окончания (ISO: YYYY-MM-DD)
limit	int	Нет	50	Макс. количество результатов на страницу
offset	int	Нет	0	Смещение пагинации

Поля ответа:

Поле	Тип	Описание
sales	array	Массив сводок продаж
sales[].id	string	UUID продажи
sales[].purchaseId	string	ID покупки на сервере
sales[].serverSaleId	string	ID продажи на сервере
sales[].fiscalOperationId	string	UUID фискальной операции
sales[].cashierId	string	ID кассира
sales[].cashierName	string	Имя кассира
sales[].subtotal	number	Сумма подитога
sales[].total	number	Итоговая сумма
sales[].paymentType	string	Метка основного типа оплаты
sales[].paymentAmount	number	Оплаченная сумма
sales[].changeAmount	number	Возвращённая сдача
sales[].status	string	Статус синхронизации
sales[].createdAt	string	Временная метка ISO 8601
total	int	Общее количество найденных продаж
limit	int	Применённый лимит
offset	int	Применённое смещение

Пример:

GET /api/sales?dateFrom=2026-02-01&dateTo=2026-02-16&limit=50&offset=0

---

GET /api/sales/{saleId}

Получение полных деталей конкретной продажи, включая позиции, платежи и данные фискальной операции.

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

Параметр	Тип	Описание
saleId	string	UUID продажи

Ответ включает:

Раздел	Описание
items[]	Детали товара: productId, productName, quantity, unitPrice, originalPrice, discountAmount, markupAmount, netAmount, vatCode, vatPercent, vatAmount
payments[]	Детали оплаты: paymentType, amount, notes
fiscalOperation	Фискальные данные: mevId, receiptNumber, reportNumber, status, isOffline, mevResponseXml, qrCodeData

Ошибка: 404 SALE_NOT_FOUND если ID продажи не существует.

---

3. Операции с наличными

POST /api/cash/in

Внесение наличных в кассу. Создаёт фискальный сервисный чек, отправляемый в MEV.

Тело запроса:

Поле	Тип	Обязательно	По умолч.	Описание
amount	number	Да	—	Сумма для внесения (должна быть > 0)
reason	string	Нет	null	Причина внесения
printReceipt	boolean	Нет	true	Печатать сервисный чек

Поля ответа:

Поле	Тип	Описание
operationId	string	UUID операции
fiscalOperationId	string	UUID фискальной операции
receiptNumber	int	Номер сервисного чека
reportNumber	int	Номер текущего отчёта Z
mevId	string | null	ID транзакции MEV
isOffline	boolean	Была ли операция офлайн
amount	number	Внесённая сумма
newBalance	number	Новый баланс наличных
operationType	string	"cashIn"
mevResponseXml	string	SOAP XML ответ
createdAt	string	Временная метка ISO 8601

Пример:

// Запрос
POST /api/cash/in
{
  "amount": 500.00,
  "reason": "Depunere inceput zi",
  "printReceipt": true
}

// Ответ 200
{
  "success": true,
  "data": {
    "operationId": "op-uuid-001",
    "fiscalOperationId": "fiscal-op-003",
    "receiptNumber": 1,
    "reportNumber": 1,
    "mevId": "MEV-SVC-001",
    "isOffline": false,
    "amount": 500.00,
    "newBalance": 500.00,
    "operationType": "cashIn",
    "mevResponseXml": "...",
    "createdAt": "2026-02-16T08:00:00.000Z"
  }
}

---

POST /api/cash/out

Выдача наличных из кассы. Проверяет достаточность баланса перед выполнением.

Тело запроса:

Поле	Тип	Обязательно	По умолч.	Описание
amount	number	Да	—	Сумма для выдачи (должна быть > 0)
reason	string	Нет	null	Причина выдачи
printReceipt	boolean	Нет	true	Печатать сервисный чек

Поля ответа: Аналогичны внесению, с operationType: "cashOut".

Ошибка: 409 INSUFFICIENT_CASH_BALANCE если текущий баланс меньше запрашиваемой суммы.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CASH_BALANCE",
    "message": "Cash balance (300.00) is insufficient for withdrawal of 500.00"
  }
}

---

4. Отчёты

POST /api/reports/z

Генерация Z-отчёта — закрытие фискального дня.

warning

Это необратимая операция. Она сбрасывает счётчики чеков и увеличивает номер отчёта.

Тело запроса:

Поле	Тип	Обязательно	По умолч.	Описание
printReport	boolean	Нет	true	Печатать отчёт

Требуется: Терминал должен быть фискализирован и иметь действительные учётные данные MEV.

Поля ответа:

Поле	Тип	Описание
reportNumber	int	Номер Z-отчёта
operationId	string	UUID фискальной операции
mevId	string | null	ID транзакции MEV
isOffline	boolean	Была ли операция офлайн
reportData	object	Полные данные отчёта (см. Объект Report Data ниже)
mevResponseXml	string	SOAP XML ответ от MEV
generatedAt	string	Временная метка ISO 8601

Объект Report Data:

Поле	Тип	Описание
reportNumber	int	Номер Z-отчёта
dailyTotal	number	Общая сумма продаж за день
dailyTax	number	Общая сумма НДС за день
dailyUntaxed	number	Необлагаемая сумма
vatBreakdown	object	Разбивка по кодам НДС
receiptsIssued	int	Количество выданных чеков
lastReceiptNumber	int	Последний номер чека
receiptsSentToMev	int	Чеки, успешно отправленные в MEV
paymentTotals	object	Сумма по коду типа оплаты ACPS (напр. { "1": 3000.00, "2": 2000.00 })
paymentCounts	object	Количество по коду типа оплаты ACPS (напр. { "1": 25, "2": 17 })
cashIn	number	Общая сумма внесений наличных
cashOut	number	Общая сумма выдач наличных
cashBalance	number	Текущий баланс наличных
yearTotal	number | null	Накопительный годовой итог (только Z)
yearTax	number | null	Накопительный годовой НДС (только Z)
totalSales	number	Общая сумма продаж (брутто)
totalReturns	number	Общая сумма возвратов
returnsCount	int	Количество операций возврата
cashInCount	int	Количество операций внесения
cashOutCount	int	Количество операций выдачи
generatedAt	string	Временная метка ISO 8601

---

POST /api/reports/x

Генерация X-отчёта — промежуточный снимок фискального дня.

НЕ сбрасывает счётчики. Структура запроса/ответа аналогична Z-отчёту.

---

POST /api/reports/periodic

Генерация Периодического отчёта — агрегированные данные по нескольким Z-отчётам.

Это только локальный отчёт (не отправляется в MEV). Поддерживает два взаимоисключающих режима фильтрации.

Тело запроса:

Поле	Тип	Обязательно	По умолч.	Описание
dateFrom	string	Условно	—	Дата начала (ISO: YYYY-MM-DD). Обязательно для режима диапазона дат
dateTo	string	Условно	—	Дата окончания (ISO: YYYY-MM-DD). Обязательно для режима диапазона дат
reportFrom	int	Условно	—	Начальный номер Z-отчёта. Для режима диапазона отчётов
reportTo	int	Условно	—	Конечный номер Z-отчёта. Для режима диапазона отчётов
detailed	boolean	Нет	false	Включить разбивку по отдельным Z-отчётам
printReport	boolean	Нет	true	Печатать отчёт на принтере POS

Режимы фильтрации (взаимоисключающие — укажите один набор):

1. Диапазон дат: dateFrom + dateTo
2. Диапазон номеров отчётов: reportFrom и/или reportTo (оба необязательны — опустите reportFrom для начала с Z#1, опустите reportTo для последнего)

Поля ответа:

Поле	Тип	Описание
filterMode	string	"dateRange" или "reportRange"
dateFrom	string	Дата начала (YYYY-MM-DD)
dateTo	string	Дата окончания (YYYY-MM-DD)
reportFrom	int	(только диапазон отчётов) Начальный номер Z-отчёта
reportTo	int	(только диапазон отчётов) Конечный номер Z-отчёта
totalSales	number	Агрегированная сумма продаж
totalTax	number	Агрегированная сумма НДС
totalUntaxed	number	Агрегированная необлагаемая сумма
vatBreakdown	object	Агрегированная разбивка по кодам НДС
receiptsCount	int	Общее количество чеков по всем Z-отчётам
paymentTotals	object	Агрегированные итоги платежей по типам
cashIn	number	Общая сумма внесений наличных
cashOut	number	Общая сумма выдач наличных
cashInCount	int	Количество операций внесения
cashOutCount	int	Количество операций выдачи
zReportsCount	int	Количество Z-отчётов в диапазоне
xReportsCount	int	Количество X-отчётов в диапазоне
firstZReportNumber	int	Первый номер Z-отчёта в диапазоне
lastZReportNumber	int	Последний номер Z-отчёта в диапазоне
firstZReportTimestamp	string	Временная метка закрытия первого Z-отчёта
lastZReportTimestamp	string	Временная метка закрытия последнего Z-отчёта
totalReturns	number	Агрегированные возвраты
returnsCount	int	Количество операций возврата
individualZReports	array | null	Разбивка по каждому Z (при detailed: true)
generatedAt	string	Временная метка ISO 8601

Поля индивидуального Z-отчёта (при detailed: true):

Поле	Тип	Описание
reportNumber	int	Номер Z-отчёта
closedAt	string	Временная метка ISO 8601 закрытия Z
firstReceiptNumber	int	Первый номер чека в этом Z
lastReceiptNumber	int	Последний номер чека в этом Z
receiptsCount	int	Количество чеков
totalSales	number	Общая сумма продаж за этот Z
totalTax	number	Общая сумма НДС за этот Z
vatBreakdown	object	Разбивка НДС за этот Z
paymentTotals	object	Итоги платежей по типам
cashIn	number	Внесения наличных в этом Z
cashOut	number	Выдачи наличных в этом Z

Пример — Сводка по диапазону дат:

// Запрос
POST /api/reports/periodic
{
  "dateFrom": "2026-02-01",
  "dateTo": "2026-02-16",
  "detailed": false,
  "printReport": true
}

Пример — Сводка по диапазону номеров Z-отчётов:

// Запрос
POST /api/reports/periodic
{
  "reportFrom": 5,
  "reportTo": 10,
  "detailed": false,
  "printReport": true
}

Пример — Детализированный по диапазону дат:

// Запрос
POST /api/reports/periodic
{
  "dateFrom": "2026-02-01",
  "dateTo": "2026-02-16",
  "detailed": true,
  "printReport": false
}

Ошибки валидации:

Код	Условие
FILTER_REQUIRED	Не указан ни диапазон дат, ни диапазон отчётов
DATE_RANGE_INVALID	dateFrom позже dateTo
DATE_TO_FUTURE	dateTo в будущем
REPORT_NUMBER_INVALID	reportFrom или reportTo < 1
REPORT_RANGE_INVALID	reportFrom > reportTo

---

5. Фискальные запросы

GET /api/fiscal/operations

Запрос фискальных операций из аудиторской базы данных с фильтрацией.

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

Параметр	Тип	Обязательно	Описание
dateFrom	string	Нет	Дата начала (ISO: YYYY-MM-DD)
dateTo	string	Нет	Дата окончания (ISO: YYYY-MM-DD)
type	string	Нет	Фильтр по типу операции (см. Справочные таблицы)
status	string	Нет	Фильтр по статусу операции (см. Справочные таблицы)
limit	int	Нет	Макс. количество результатов (по умолч. 50)
offset	int	Нет	Смещение пагинации (по умолч. 0)

Поля ответа:

Поле	Тип	Описание
operations	array	Массив фискальных операций
operations[].id	string	UUID операции
operations[].operationType	string	Тип фискальной операции
operations[].receiptNumber	int	Номер чека
operations[].reportNumber	int	Номер Z-отчёта
operations[].mevId	string | null	ID транзакции MEV
operations[].status	string	Статус операции
operations[].isOffline	boolean	Работал ли в офлайне
operations[].totalAmount	number	Сумма операции
operations[].vatBreakdown	object	Упрощённая разбивка НДС
operations[].vatDetails	object	Детализированный НДС с процентом, ставкой, себестоимостью, брутто
operations[].paymentsBreakdown	object	Платежи по типам
operations[].mevResponseXml	string	SOAP XML ответ
operations[].errorMessage	string | null	Сообщение об ошибке при неудачной операции
operations[].createdAt	string	Временная метка ISO 8601 создания
operations[].completedAt	string	Временная метка ISO 8601 завершения
total	int	Общее количество найденных операций
limit	int	Применённый лимит
offset	int	Применённое смещение

---

GET /api/fiscal/daily-summary

Получение сводки текущего фискального дня. Возвращает те же данные, что и X-отчёт, но без отправки в MEV. Только чтение, фискальная блокировка не требуется.

Требуется: Терминал должен быть фискализирован.

Ответ: Аналогичен объекту Report Data (см. раздел Z-отчёт).

---

6. Печать

POST /api/print

Печать нефискального текста на термопринтере POS. Поддерживает многоколоночную раскладку.

Тело запроса:

Поле	Тип	Обязательно	По умолч.	Описание
lines	array	Да	—	Массив массивов строк
feedLines	int	Нет	3	Количество пустых строк после содержимого
cut	boolean	Нет	true	Обрезать бумагу после печати

Формат строки — каждая строка представляет собой массив из 1-3 строковых значений:

Колонки	Раскладка
["текст"]	Полная ширина, выравнивание по левому краю
["лево", "право"]	Выравнивание по левому + правому краю
["лево", "центр", "право"]	Трёхколоночная раскладка
[""]	Пустая строка (разделитель)

info

Это нефискальная операция — без взаимодействия с MEV, без фискального чека.

Поля ответа:

Поле	Тип	Описание
linesCount	int	Количество напечатанных строк
printedAt	string	Временная метка ISO 8601

Пример — Отчёт по инвентаризации (3 колонки):

POST /api/print
{
  "lines": [
    ["RAPORT INVENTAR"],
    ["Data:", "16.02.2026"],
    [""],
    ["Cod", "Denumire", "Cantitate"],
    ["────────────────────────────────"],
    ["001", "Cafea espresso", "150 buc"],
    ["002", "Tort Napoleon", "12.5 kg"],
    ["003", "Apa minerala 0.5L", "340 buc"],
    [""],
    ["Total pozitii:", "4"],
    ["────────────────────────────────"],
    ["Responsabil:", "", "Ion Popescu"]
  ],
  "feedLines": 3,
  "cut": true
}

Ошибка: 503 PRINTER_UNAVAILABLE если принтер отключён или недоступен.

---

Справочные таблицы

Коды ошибок

Код	HTTP-статус	Описание
MISSING_API_KEY	401	Заголовок X-API-Key не предоставлен
INVALID_API_KEY	401	Предоставленный API-ключ недействителен
VALIDATION_ERROR	400	Валидация тела запроса не пройдена (см. details[])
INVALID_JSON	400	Тело запроса не является валидным JSON
TERMINAL_NOT_FISCAL	409	Терминал не фискализирован (нет сертификата MEV)
MEV_CREDENTIALS_MISSING	409	Терминал фискализирован, но учётные данные MEV отсутствуют
FISCAL_DAY_EXPIRED	409	Прошло 24ч с первого чека фискального дня — необходим Z-отчёт для продолжения
INSUFFICIENT_CASH_BALANCE	409	Баланс наличных недостаточен для запрашиваемой выдачи
MEV_ERROR	502	Связь с MEV (SFS) не удалась (таймаут, ошибка SOAP, истёкший сертификат)
BUSY	429	Другая фискальная операция в процессе (превышен таймаут 30с)
SALE_NOT_FOUND	404	Продажа с указанным ID не найдена
PRINTER_UNAVAILABLE	503	Принтер недоступен или отключён

Коды НДС

Код	Описание
A	Ставка НДС A (согласно настройкам терминала)
B	Ставка НДС B (обычно 20%)
C	Ставка НДС C
D	Ставка НДС D
E	Ставка НДС E
_	Освобождён (без НДС)

Типы оплаты (ACPS WSDL)

Тип	Описание
"1"	NUMERAR (Наличные)
"2"	CARD (Карта)
"3.1"	VAUCHER (Ваучер)
"3.2"	CEC / Certificat valoric (Чек / Ценный сертификат)
"3.3"	TICHET — оплата документом установленной стоимости (MDL)
"5"	TME — электронный талон на питание
"6"	ABONAMENT (Абонемент)
"7"	ALT IP (другой платёжный инструмент)
"8.1"	Credit (Кредит)
"8.2"	Leasing (Лизинг)
"8.3"	Avans (Аванс)
"8.4"	Arvuna (Задаток)
"8.5"	Gaj (Залог)
"8.8"	Compensare (Взаимозачёт)
"8.9"	Alt mod (Другой способ)

Типы фискальных операций

Тип	Описание
receipt	Фискальный чек (продажа)
cash_in	Внесение наличных
cash_out	Выдача наличных
refund	Возврат
x_report	X-отчёт
z_report	Z-отчёт

Статусы фискальных операций

Статус	Описание
pending	Создана, ещё не отправлена в MEV
sent	Отправлена в MEV, ожидание ответа
success	Успешно обработана MEV
failed	MEV вернул ошибку
offline	Сохранена локально (MEV недоступен)

Объект разбивки НДС

{
  "B": {
    "code": "B",
    "percent": 20.0,
    "vatAmount": 7.50,
    "taxableBase": 37.50,
    "gross": 45.00
  }
}

Поле	Тип	Описание
code	string	Код ставки НДС
percent	number	Процент НДС
vatAmount	number	Сумма НДС
taxableBase	number	Сумма нетто (без НДС)
gross	number	Сумма брутто (с НДС)

---

Примечания

• Все денежные суммы указаны в MDL (Молдавский лей) как number с точностью до 2 десятичных знаков.
• Все временные метки в формате ISO 8601 UTC.
• Сервер использует блокировку фискальных операций — только одна фискальная операция (продажа, внесение/выдача, отчёт Z/X) может выполняться одновременно. Параллельные запросы будут ожидать до 30 секунд перед возвратом 429 BUSY.
• Офлайн режим: Когда MEV (сервер налогового органа) недоступен, фискальные операции сохраняются локально и синхронизируются позже. Ответ будет содержать isOffline: true и mevId: null.
• Печать чеков выполняется по принципу fire-and-forget — ответ API не ожидает завершения печати.

---

Коллекции Postman

Две коллекции — для двух разных API. Импортируются через Import → File.

Коллекция	Что внутри	Скачать
API терминала	Справочник API кассы — 28 запросов: продажи, касса, X/Z и периодические отчёты, печать, каталог, отмена и возврат оплаты картой, лоты доставки. У каждого запроса описаны поля запроса и ответа, ошибки с HTTP-статусом и примеры. Один и тот же API на Android и на PC-ECC (Windows); где они различаются, это указано в описании запроса.	posfix-terminal-api.postman_collection.json
Публичный API интеграции	24 запроса, которыми внешняя система (интернет-магазин, ERP) читает и пишет данные торговца: каталог, остатки, цены, клиенты, заказы, Z-отчёты, вебхуки.	posfix-integration-api.postman_collection.json

API терминала

Заполните переменные коллекции:

• baseUrl → http://<ip-терминала>:4567 в локальной сети или https://api.posfix.md/api/relay/<publicId> через relay — адрес показан на кассе, в окне режима Provider
• apiKey → ключ с терминала (Настройки → Developer → Показать API-ключ)

Нажмите на название коллекции в Postman, чтобы открыть её описание: полную карту ошибок, правила повтора с Idempotency-Key и справочные таблицы. Вся коллекция, включая описания, — на румынском.

Z-отчёт закрывает день

POST /api/reports/z нельзя отменить, он обнуляет счётчики дня. Не запускайте его как тест на рабочем терминале.

Смена открывается сама

Открывать смену не нужно: терминал открывает её при первой продаже, внесении или изъятии наличных. День закрывается Z-отчётом.

Публичный API интеграции

Ключ создаётся в панели управления → Ключи API интеграции и показывается открытым текстом один раз, при создании. Впишите его в переменную apiKey; он уходит с каждым запросом в заголовке X-Posfix-Api-Key.

У каждого ключа только те права (scopes), которые выбраны при создании — в описании каждого запроса указано, какое нужно. Без него ответ 403.

Модуль подписки

API требует активного модуля «API Integrare» у торговца. Без него ответ 403 даже с действующим ключом и нужным scope.

Торговец не передаётся параметром: организация берётся из ключа, поэтому чужие данные прочитать нельзя. Начните с GET /api/public/v1/ping — он подтверждает ключ, торговца и scopes.