iRetail PRO store node 1.0.0-m1: receipts

5 операций

← Вся документация · Источник: контракты, openapi/store-v1.yaml на коммите 8000474.

Справочники на английском — на языке контрактов, из которых они созданы.

← iRetail PRO store node 1.0.0-m1

Операции

POST /v1/receipts/calculate Compute receipt amounts without storing anything (spec/RECEIPT_MATH.md).

Any principal's token (an employee's, a device's or an integration's), no permission; a body of at most 256 KiB (413 payload_too_large) within the math's bounds (spec/RECEIPT_MATH.md, Bounds; 422 amount_too_large). It took no token before 1.0 (spec/API.md, Calculating a receipt).

operationId calculateReceipt

Параметры

Имя Где Тип Описание
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Тело запроса обязательный

Ответы

GET /v1/receipts Receipts.

operationId listReceipts · Право receipt.read

Параметры

Имя Где Тип Описание
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
shift_id query string (uuid) Shift.
limit query integer Page size, 1–200.
after query string Cursor from the previous page.

Ответы

POST /v1/receipts Sale (receipt.sell), refund (receipt.refund, receipt.refund.any_shift) or void (receipt.void).

A refund pays back to the sale's tenders, each up to what it paid less earlier refunds; another tender or more needs refund.tender_override (spec/API.md, Payments). What else a receipt needs by its kind and lines is spec/RBAC.md, Permissions by request (data/request-permissions.json).

operationId createReceipt · Право receipt.sell

Параметры

Имя Где Тип Описание
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
Idempotency-Key header string spec/API.md, Idempotency.
Approval-Token header string One-time approval from POST /v1/approvals for this operation's permission.
dry_run query boolean Check and compute the receipt without keeping anything (spec/API.md, "Dry runs"): 200 with the receipt as it would be; payments are not compared with what is due; an approval token is not used up.

Тело запроса обязательный

Ответы

  • 200 A dry run; nothing was kept. Receipt
  • 201 OK Receipt
  • 400 Error (spec/API.md). Error
  • 401 Error (spec/API.md). Error
  • 403 Error (spec/API.md). Error
  • 404 Error (spec/API.md). Error
  • 409 Error (spec/API.md). Error
  • 422 Error (spec/API.md). Error
GET /v1/receipts/{id} One receipt.

operationId getReceipt · Право receipt.read

Параметры

Имя Где Тип Описание
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
id обязательный path string (uuid) Id.

Ответы

POST /v1/receipts/{id}/send Send a receipt to the customer by e-mail or SMS (spec/API.md, "Electronic receipts").

receipt.read, and either the caller's workplace rang the sale less than 30 minutes ago or the caller holds receipt.resend (403 forbidden otherwise). Five sends a receipt; per store 100 SMS and 300 e-mails in a fixed UTC hour (429 too_many_sends, details limit and retry_after).

operationId sendReceipt · Право receipt.read

Параметры

Имя Где Тип Описание
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
id обязательный path string (uuid) Id.

Тело запроса обязательный

Ответы

  • 202 Queued; the outcome lands in the receipt's deliveries. ReceiptDelivery
  • 400 Error (spec/API.md). Error
  • 401 Error (spec/API.md). Error
  • 403 Error (spec/API.md). Error
  • 404 Error (spec/API.md). Error
  • 409 Error (spec/API.md). Error
  • 429 Error (spec/API.md). Error

Схемы

Error object

Every error response.

error обязательный string Stable code, see spec/API.md.
message обязательный string English text for logs.
details object

ReceiptFiscal object

The fiscal document a back end gave the receipt (spec/FISCAL.md, What the node keeps).

kind обязательный "device" | "signer" | "software" | "service"
driver обязательный string
device_serial обязательный string | null
registration_number обязательный string | null
shift_number обязательный integer (int64)
document_number обязательный integer (int64)
sign обязательный string
qr обязательный string | null
at обязательный string (date-time)
extra обязательный map of string

Discount object | object

As in spec/RECEIPT_MATH.md.

ReceiptLineInput object

item_id обязательный string (uuid)
quantity_milli обязательный integer (int64) At most 10^12 (spec/RECEIPT_MATH.md, Bounds; 422 amount_too_large).
unit_price_minor integer (int64) The price before options (spec/FOOD_SERVICE.md); only with receipt.price.override, otherwise the store price. On a line paying a check line, the check line's price less its options' deltas, with no override (spec/RESTAURANT.md, Split and close). With its options' deltas at most 10^12 (spec/RECEIPT_MATH.md, Bounds).
discounts array of Discount At most 16, an amount at most 10^12 (spec/RECEIPT_MATH.md, Bounds).
hold_id string (uuid) | null
original_line_no integer Refund: the line of the original receipt.
modifiers array of string Sale: option ids of the item's modifier groups, in the chosen order (spec/FOOD_SERVICE.md).
serials array of string A serial-tracked item's serial per unit, as read (spec/VARIANTS.md).
lot string | null Sale: the lot a GS1 code named; its batches go first (spec/BARCODES.md, GS1 codes).
expiry string (date) | null Sale: the expiry date a GS1 code carried; a date before the business date is refused as expired unless approved (expired.sell).
marking_code string | null The marking code a GS1 code carried, as scanned (spec/BARCODES.md, GS1 codes).
seller_id string (uuid) | null Sale: the employee who sold the line and earns its bonus (spec/REPORTS.md, Employee bonuses); the cashier when absent.
batch_price boolean Sale: the line's unit_price_minor is a batch price from the price split (spec/PRICING.md, Batch prices).
gift_card_id string (uuid) | null Sale of a gift_card item: the card loaded, found by its number first (POST /v1/gift-cards/balance; spec/LOYALTY.md, Gift cards).
check_line_no integer | null Sale with check: the check line this line pays, carried as the check has it, its unit_price_minor before options (spec/RESTAURANT.md, Split and close).
preorder_line_no integer | null Sale with preorder: the preorder line this line hands over (spec/PREORDERS.md, Handing it over).

PaymentInput object

tender обязательный "cash" | "card" | "ebt_snap" | "ebt_cash" | "gift_card" | "online" | "other" online is a preorder's payment captured at hand-over (spec/PAYMENTS_ONLINE.md), read as other by an app before 1.1.
amount_minor обязательный integer (int64) At most 10^15 (spec/API.md, Payments; 422 amount_too_large).
provider string | null
provider_ref string | null
card_brand string | null
card_last4 string | null
authorization_code string | null
hold_id string (uuid) | null Tender gift_card: the balance hold for the amount, taken with the card's number and PIN; the node fills card_last4 with the card's last four digits (spec/LOYALTY.md, Gift cards).

OfflineInfo object

Present when a register replays a receipt it closed offline.

created_at обязательный string (date-time)
register_number обязательный string The register's own number for the receipt.

ReceiptCreate object

sale: lines and payments; refund: original_receipt_id, lines with original_line_no, payments returned; void: original_receipt_id only.

kind обязательный "sale" | "refund" | "void"
shift_id обязательный string (uuid)
original_receipt_id string (uuid) | null
lines array of ReceiptLineInput At most 1 000 (spec/RECEIPT_MATH.md, Bounds; 422 amount_too_large).
receipt_discounts array of Discount At most 16 (spec/RECEIPT_MATH.md, Bounds).
payments array of PaymentInput At most 20 (spec/API.md, Payments; 422 amount_too_large).
offline OfflineInfo | null
order_type "dine_in" | "take_out" | "delivery" | null How a food-service order leaves; null for retail (spec/FOOD_SERVICE.md).
tip_minor integer (int64) Sale: added to what the payments cover; not part of the total, untaxed. At most 10^15 (spec/API.md, Payments).
order_label string | null Sale: a name or table number for the kitchen display (spec/FOOD_SERVICE.md).
purchaser PsePurchaser | null Sale with a PSE line: the purchaser from the scanned ID (spec/PHARMACY.md); never returned.
fiscal ReceiptFiscal | null The fiscal document the register's back end gave the receipt before it was recorded (spec/FISCAL.md, The sale).
customer_id string (uuid) | null Sale: the customer found online (spec/LOYALTY.md, The sale).
card_number string | null Sale: a loyalty card as scanned, resolved by the node (offline too); never returned.
points ReceiptPointsInput | null Sale: points spent on a bonus card, with their hold.
stamp_holds array of ReceiptStampHold Sale: the holds for stamps rewards take from the cards (spec/LOYALTY.md, Stamps).
gift_card_holds array of ReceiptGiftCardHold Refund and void: for each gift card line taken back, the hold that unloads its amount from the card, taken with the card's number and PIN (spec/LOYALTY.md, Selling, spending, refunds). A gift card line refunded or voided without one is 422 gift_card_hold_required.
voucher ReceiptVoucherInput | null Sale: one voucher or coupon, with its hold when it is limited.
partner_code string | null Sale: a partner's code (spec/LOYALTY.md, Partner codes).
check ReceiptCheckInput | null Sale: the restaurant check whose lines it pays; every line then names its check_line_no (spec/RESTAURANT.md, Split and close).
preorder string (uuid) | null Sale: the preorder it hands over; its lines name their preorder_line_no (spec/PREORDERS.md, Handing it over).
service_charges array of ReceiptServiceChargeInput Sale: every store service charge it carries, each automatic, added or removed; a charge whose conditions hold left out is 422 invalid_service_charge, and a receipt of a check carries the check's (spec/RECEIPT_MATH.md, Service charges).

ReceiptLineBatch object

batch_id обязательный string (uuid)
quantity_milli обязательный integer (int64)
item_id string (uuid) A kit line's component the batch belongs to (spec/STOCK.md, Kits).

ReceiptLine object

line_no обязательный integer
item_id обязательный string (uuid)
name обязательный string The item name in the receipt language at the time of sale.
quantity_milli обязательный integer (int64)
base_unit обязательный "each" | "kg" | "lb" | "l" | "us_gal" | "m" | "ft"
unit_price_minor обязательный integer (int64)
gross обязательный integer (int64)
line_discount обязательный integer (int64)
receipt_discount обязательный integer (int64)
net обязательный integer (int64)
tax обязательный integer (int64)
deposit обязательный integer (int64) The container deposit (spec/TAX.md); 0 without one.
snap обязательный integer (int64) What SNAP paid of the line (spec/TAX.md, "SNAP exemption"); 0 without SNAP.
batches обязательный array of ReceiptLineBatch
promotion_id обязательный string (uuid) | null The promotion that took its discount off the line (spec/PROMOTIONS.md).
modifiers обязательный array of object
serials array of string The line's serials, normalized (spec/VARIANTS.md).
lot string | null Sale: the lot a GS1 code named; its batches go first (spec/BARCODES.md, GS1 codes).
marking_code string | null The marking code a GS1 code carried, as scanned (spec/BARCODES.md, GS1 codes).
seller_id обязательный string (uuid) | null Sale: the employee who sold the line and earns its bonus (spec/REPORTS.md, Employee bonuses); the cashier when absent.
stamp_discount обязательный integer (int64) The loyalty steps' parts of the line's discounts (spec/LOYALTY.md, The order of discounts).
card_discount обязательный integer (int64)
voucher_discount обязательный integer (int64) The voucher's line rule and its share of an amount rule.
points_spent обязательный integer (int64) The points the line took of those spent; 0 without.
points_earned обязательный integer (int64)
bonus_minor обязательный integer (int64) The employee bonus fixed at the sale (spec/REPORTS.md, Employee bonuses).
bonus_employee_id обязательный string (uuid) | null
bonus_rule_id обязательный string (uuid) | null
commission_minor обязательный integer (int64) The line's share of the partner's commission.
gift_card_number_masked string | null A gift card line's card, masked.
check_line_no обязательный integer | null The restaurant check's line this line paid (spec/RESTAURANT.md); null for a sale without a check.
preorder_line_no integer | null The preorder's line this line handed over (spec/PREORDERS.md); null otherwise.
service_charges обязательный array of ServiceChargeShare The line's share of each service charge the receipt applies, with the tax on that share (not in tax); a refund line's, what it took back; empty without (spec/RECEIPT_MATH.md, Service charges).

ReceiptTax object

code обязательный string
base обязательный integer (int64)
amount обязательный integer (int64)

Payment object

id обязательный string (uuid)
tender обязательный "cash" | "card" | "ebt_snap" | "ebt_cash" | "gift_card" | "online" | "other" online is a preorder's payment captured at hand-over (spec/PAYMENTS_ONLINE.md), read as other by an app before 1.1.
amount_minor обязательный integer (int64) At most 10^15 (spec/API.md, Payments; 422 amount_too_large).
provider обязательный string | null
provider_ref обязательный string | null
card_brand обязательный string | null
card_last4 обязательный string | null
authorization_code обязательный string | null

Receipt object

id обязательный string (uuid)
number обязательный integer (int64)
kind обязательный "sale" | "refund" | "void"
original_receipt_id обязательный string (uuid) | null
shift_id обязательный string (uuid)
workplace_id обязательный string (uuid)
cashier_id обязательный string (uuid)
currency обязательный string
created_at обязательный string (date-time)
lines обязательный array of ReceiptLine
taxes обязательный array of ReceiptTax
gross_total обязательный integer (int64)
discount_total обязательный integer (int64)
net_total обязательный integer (int64)
tax_total обязательный integer (int64)
total обязательный integer (int64)
cash_due обязательный integer (int64) | null
payments обязательный array of Payment
change_minor обязательный integer (int64)
needs_review обязательный boolean
offline обязательный OfflineInfo | null
order_type обязательный "dine_in" | "take_out" | "delivery" | null How a food-service order leaves; null for retail (spec/FOOD_SERVICE.md).
tip_minor обязательный integer (int64) Sale: added to what the payments cover; not part of the total, untaxed. At most 10^15 (spec/API.md, Payments).
deposit_total обязательный integer (int64)
snap_total обязательный integer (int64) What the ebt_snap payments paid, exempt from sales tax.
healthcare_total обязательный integer (int64) The FSA- and HSA-eligible lines' net and tax (spec/PHARMACY.md).
rx_total обязательный integer (int64)
order_label обязательный string | null
deliveries обязательный array of ReceiptDelivery
serial_conflicts array of string A receipt closed offline, the serials it sold that a sale online would have refused.
fiscal обязательный ReceiptFiscal | null The fiscal document of the receipt; null without a fiscal back end (spec/FISCAL.md).
customer_id обязательный string (uuid) | null
loyalty обязательный ReceiptLoyalty | null
partner обязательный ReceiptPartner | null
check обязательный ReceiptCheck | null The restaurant check it paid lines of (spec/RESTAURANT.md, Split and close); null otherwise.
preorder string (uuid) | null The preorder it handed over (spec/PREORDERS.md); null otherwise, and absent from a node before 1.1.
service_charges обязательный array of ReceiptServiceCharge Every service charge the receipt carries, removed ones included, as they were at the sale; a refund's, what it took back of each (spec/API.md, Service charges).
service_charge_total обязательный integer (int64) The charges that apply, inside total; 0 without (spec/RECEIPT_MATH.md, Service charges).

CalculateRequest object

The input of a receipt fixture (spec/RECEIPT_MATH.md, schemas/receipt-fixtures.schema.json), within the math's bounds (spec/RECEIPT_MATH.md, Bounds) and 256 KiB.

CalculateResult object

The expected of a receipt fixture.

ReceiptPage object

items обязательный array of Receipt
next обязательный string | null

PsePurchaser object

The purchaser of a PSE product as the scanned ID gives it (spec/PHARMACY.md, "The purchaser").

name обязательный string
address обязательный string
date_of_birth обязательный string (date)
id_type обязательный "driver_license" | "state_id" | "passport" | "military_id" | "other"
id_state обязательный string The issuing state or country, as printed.
id_number обязательный string
signed обязательный boolean The purchaser signed the logbook entry.

ReceiptSend object

channel обязательный "email" | "sms"
to обязательный string An e-mail address, or a phone number in E.164 form; never stored.

ReceiptDelivery object

id обязательный string (uuid)
channel обязательный "email" | "sms"
to_masked обязательный string
status обязательный "queued" | "sent" | "failed"
created_at обязательный string (date-time)
sent_at обязательный string (date-time) | null
error обязательный string | null A short reason when the send failed.

ReceiptLoyalty object

What the receipt's loyalty steps did (spec/LOYALTY.md, The sale).

card_number_masked обязательный string | null
unresolved_card обязательный boolean A card number recorded offline that found no one.
points_spent обязательный integer (int64)
points_value_minor обязательный integer (int64)
points_earned обязательный integer (int64)
stamps обязательный array of object
voucher_id обязательный string (uuid) | null
voucher_code обязательный string | null

ReceiptPartner object

The partner and rate as they were at the sale (spec/LOYALTY.md, Partner codes).

partner_id обязательный string (uuid)
code обязательный string
commission_ppm обязательный integer
commission_minor обязательный integer (int64)

ReceiptPointsInput object

points обязательный integer (int64)
hold_id обязательный string (uuid)

ReceiptStampHold object

program_id обязательный string (uuid)
hold_id обязательный string (uuid)

ReceiptGiftCardHold object

original_line_no обязательный integer The gift card line of the original sale this unloads.
hold_id обязательный string (uuid) A gift_card hold for the line's loaded amount (POST /v1/loyalty/holds).

ReceiptVoucherInput object

code обязательный string
hold_id string (uuid) | null

ReceiptCheckInput object

The check a sale pays lines of (spec/RESTAURANT.md, Split and close).

check_id обязательный string (uuid)
version обязательный integer (int64) The check's version the receipt was figured at; compared online, not on an offline replay.
split обязательный ReceiptCheckSplit

ReceiptCheckSplit object

kind обязательный "none" | "items" | "seats" | "equal"
seat integer | null seats: the seat this receipt is; null for the shared lines.
parts integer | null equal, or the shared lines of seats: how many parts its due was cut into.

ReceiptCheck object

The check a receipt paid lines of.

check_id обязательный string (uuid)
check_number обязательный integer (int64)
table_id обязательный string (uuid) | null
table_name обязательный string | null
area_id обязательный string (uuid) | null
waiter_id обязательный string (uuid)
covers обязательный integer
opened_at обязательный string (date-time)
split обязательный ReceiptCheckSplit
closing обязательный boolean This receipt paid the check's last line and closed it.
conflict обязательный boolean An offline receipt that did not apply to its check (spec/RESTAURANT.md, Offline).
version обязательный integer (int64) | null The check's version after this receipt; the next receipt of a split names it.

ServiceChargeHow "automatic" | "added" | "removed"

automatic (its conditions hold), added by hand, or removed by hand with a reason.

automatic · added · removed

ServiceChargeShare object

A line's share of one service charge and the tax on that share.

id обязательный string
amount_minor обязательный integer (int64)
tax_minor обязательный integer (int64)

ServiceChargePart object

A charge as one item line a fiscal back end gets (spec/FISCAL.md); one per set of tax codes.

tax_codes обязательный array of string
amount_minor обязательный integer (int64)

ReceiptServiceChargeInput object

id обязательный string
how обязательный ServiceChargeHow
reason string | null removed: why, 1 to 200 characters (422 reason_required).

ReceiptServiceCharge object

A service charge as the receipt keeps it (spec/API.md, Service charges).

id обязательный string
label обязательный string In the receipt language at the sale.
notice обязательный string In the receipt language at the sale; empty for none.
rate_ppm обязательный integer
how обязательный ServiceChargeHow
reason обязательный string | null
base обязательный "after_discounts" | "before_discounts"
base_minor обязательный integer (int64) | null What the rate was applied to; null on a refund.
amount_minor обязательный integer (int64) Inside total; 0 for a removed charge.
tax_minor обязательный integer (int64)
parts обязательный array of ServiceChargePart
to_staff_ppm обязательный integer
to_staff_minor обязательный integer (int64) round(the charge without its tax x to_staff_ppm / 1 000 000), fixed at the sale (spec/REPORTS.md, Service charges).