GET `/api-client/sales/orders`

apiSalesGetOrders · Sales

Tenant-scoped sales with fresh USER RBAC or API_CLIENT scopes and PUBLIC_API entitlement. Customers require customers.read/write. Orders require sales.read; draft writes require sales.create (machine sales.write) plus pricing.read. Confirmation adds inventory.adjust (machine inventory.write), refreshes current prices, freezes snapshots and reserves all stock/selected unit UUIDs. Completion requires sales.create+inventory.adjust (machine sales.write+inventory.write) and atomically consumes reservations and appends SALE movements; serialized units become SOLD without custody. Cancellation requires sales.cancel+inventory.adjust (machine sales.write+inventory.write) and releases reservations without reversing physical movements. State DRAFT→CONFIRMED→COMPLETED or cancellation before completion; expectedVersion mandatory. Single legal entity, warehouse and price-list currency per order; at most100 distinct lines and100 serial units. Decimal quantities/prices scale6, unrounded commercial totals scale12. All writes require Idempotency-Key; replay is denied after permission/scope/entitlement revocation. Machine pricing accepts public lists and published active variants. No anonymous access, purchase costs/margins, serial identities, payment, tax, invoice, return or UI in the Sales endpoints; cash checkout composes delivery through POS.

Autenticación: PlatformApiKey · http bearer
required-scopes: purchases.read

Ejemplo

Los valores entre <> y {} son marcadores: sustitúyelos por los tuyos antes de ejecutarlo.

curl --request GET \
  --url 'https://api.marky.ec/v1/api-client/sales/orders' \
  --header 'Authorization: Bearer <PlatformApiKey>'

Parámetros

Nombre	En	Tipo
`limit`	query	`integermín. 1máx. 100por defecto 50`
`cursor`	query	`stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`
`status`	query	`stringuno de "DRAFT", "CONFIRMED", "COMPLETED", "CANCELLED"`

Respuestas

200 Success

Cache-Controlvalor fijo "no-store"

application/json

ApiSalesOrderHeaderPage

objectsin otras propiedades

itemsobligatorio
arrayelementos máx. 100
Cada elemento
ApiSalesOrder
objectsin otras propiedades

idobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

statusobligatorio
stringuno de "DRAFT", "CONFIRMED", "COMPLETED", "CANCELLED"

versionobligatorio
integermín. 1máx. 2147483646

createdAtobligatorio
stringformato date-time

updatedAtobligatorio
stringformato date-time

numberobligatorio
stringlongitud mín. 1longitud máx. 64

customerIdobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

currencyCodeobligatorio
stringlongitud mín. 1longitud máx. 3
Price-list currency, frozen on confirmation. No FX or fiscal rounding.

itemsobligatorio
arrayelementos máx. 100
Cada elemento

SalesOrderItem

objectsin otras propiedades

idobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

variantIdobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

quantityobligatorio
stringpatrón ^(0|[1-9][0-9]{0,11})\.[0-9]{6}$

trackingModeobligatorio
stringuno de "NONE", "QUANTITY", "SERIALIZED"

lineTotalobligatorio
stringpatrón ^[0-9]{1,26}\.[0-9]{12}$

priceIdobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

unitPriceobligatorio
stringpatrón ^(0|[1-9][0-9]{0,11})\.[0-9]{6}$

allocationsobligatorio
arrayelementos máx. 100
Cada elemento

SalesAllocation

objectsin otras propiedades

idobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

reservationIdobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

quantityobligatorio
stringpatrón ^(0|[1-9][0-9]{0,11})\.[0-9]{6}$

movementIdobligatorio
string | nullformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

listUnitPrice
string | nullpatrón ^(0|[1-9][0-9]{0,11})\.[0-9]{6}$
Reference: the list price the line was settled against. For a negotiated line it is a snapshot and does not follow the list. Null on an invoice line that has no list reference.

priceNegotiated
boolean
True when the agreed unit price is not the list price. Such a line keeps its price through confirmation, delivery, invoicing and collection.

discountPercent
string | nullpatrón ^(100|[0-9]{1,2})\.[0-9]{4}$
The discount the price was stated as, when it was stated as one.

discountAmount
string | nullpatrón ^(0|[1-9][0-9]{0,11})\.[0-9]{6}$
What one unit is discounted by: list price minus agreed price. Null when the agreed price is not below the list price.

priceReason
string | nulllongitud máx. 500

priceOrigin
string | nulluno de "QUOTATION", "SALES_ORDER", "SALES_INVOICE", null
The document the price was negotiated in. A line carried to another document keeps it.

units
arrayelementos máx. 100
Only on the record read by a person: the units this line reserved or delivered, read from the allocations of the order itself. Identifiers and state are sent only on the record of the document and only to a reader of inventory.serials.read; everyone else receives the unit references and their count.

Cada elemento
objectsin otras propiedades

unitIdobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

outcomeobligatorio
uno de "RESERVED", "DELIVERED", "RELEASED"
RESERVED: held by the confirmed order. DELIVERED: it left with the sale. RELEASED: the order was cancelled and let it go.

serialNumber
string | null

imei1
string | null

imei2
string | null

status
uno de "AVAILABLE", "RESERVED", "SOLD", "IN_TRANSIT", "DAMAGED", "RETURNED", "RMA", "LOST", "QUARANTINED"
State of the unit today, wherever it is now.

totalobligatorio
stringpatrón ^[0-9]{1,26}\.[0-9]{12}$

priceListIdobligatorio
stringformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
nextCursorobligatorio
string | nullformato uuidpatrón ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

400 Invalid request

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

401 Missing or invalid access token

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

403 Identity, membership or permission denied

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

404 Unknown resource

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

409 Duplicate permanent identity/IMEI, stale unit version, reserved/illegal unit state, custody/legal entity constraint or idempotency conflict.

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

413 Payload too large

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

429 Per-minute rate or monthly quota exceeded; authenticated API clients require PUBLIC_API entitlement.

Retry-Afterintegermín. 1 Seconds before retrying; quota reset is UTC next month.

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

500 Internal failure

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.

503 Auth/database/governance unavailable; no memory fallback for Redis.

application/problem+json

ProblemDetails

objectsin otras propiedades

typeobligatorio
valor fijo "about:blank"
statusobligatorio
integer
codeobligatorio
string
titleobligatorio
string
detailobligatorio
string
requestIdobligatorio
stringformato uuid
errors
arrayelementos máx. 200
Where each problem is, for the codes that can say it: a JSON pointer into the request or the record (`/items/0/devices/1/imei1`) and the reason. A line of a serialized article that is short of units also says how many it bills and how many are identified. Never a value typed by the user, and never an identifier of a unit.
Cada elemento
objectsin otras propiedades
- pointerobligatorio
  string
- codeobligatorio
  string
- required
  integermín. 0máx. 1000
  For a line short of units (UNITS_DIFFER_FROM_QUANTITY, RECEIPT_REQUIRED, DELIVERY_REQUIRED): how many units the line bills.
- identified
  integermín. 0máx. 1000
  For the same line: how many units are identified and linked to it. Given to every reader of the document; no IMEI or serial number is.