GET `/api-client/search`

apiClientUniversalSearch · Universal Search

API_CLIENT catalog.read + PUBLIC_API, tenant derived from key. Only active variants of active published products, including optional exact unit hits. includeArchived=true rejected. Exact pipeline precedence: IMEI, SKU, barcode, serial, model. Prefix FTS and word trigram are fallback only when there are no authorized visible exact matches. IMEI/SKU/serial are exact/indexed and never enter automatic text projection. Unit branches participate only with BOTH inventory.read and inventory.serials.read checked freshly inside transaction; lacking either quietly skips unit lookup. Unit hits expose IDs/status/version/condition/grade with safe catalog fields, no IMEI/serial, custody, actor, arbitrary attributes, costs, prices or audit. Text indexes name/active brand/model/storage/color/condition/grade/SIM and curated aliases using simple tsvector, unaccent and pg_trgm; aliases managed by Catalog write. Literal input, no user tsquery syntax. Stage ascending/rank descending/kind/id tie break, dedup per kind/id. No total counts or side-effect writes; query/cursor are never logged. Fresh filters enforced after projection. No anonymous access, external search service or business UI.

Autenticación: PlatformApiKey · http bearer
required-scopes: catalog.read
optional-serial-scopes: inventory.readinventory.serials.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/search?q=<q>' \
  --header 'Authorization: Bearer <PlatformApiKey>'

Parámetros

Nombre	En	Tipo	Descripción
`q`obligatorio	query	`stringlongitud mín. 1longitud máx. 200`	NFKC/trim/collapse spaces, max12 alphanumeric tokens; no controls. Exact input may be one character; text prefixes ignore tokens shorter than two; fuzzy requires at least three alphanumeric characters.
`limit`	query	`integermín. 1máx. 100por defecto 20`
`cursor`	query	`stringpatrón ^[A-Za-z0-9_-]+$longitud máx. 600`
`includeArchived`	query	`booleanpor defecto false`	Human ERP only; true rejected for API clients.

Respuestas

200 Ranked search page; exact hits first, each resource once. Empty results return items=[] and nextCursor=null.

application/json

SearchPage

objectsin otras propiedades

itemsobligatorio
arrayelementos máx. 100
Cada elemento
Exactamente una de

SearchVariant

objectsin otras propiedades

kindobligatorio
stringvalor fijo "VARIANT"

idobligatorio
stringformato uuid

variantIdobligatorio
stringformato uuid

productIdobligatorio
stringformato uuid

productNameobligatorio
string

skuobligatorio
string

matchobligatorio
stringuno de "EXACT_IMEI", "EXACT_SKU", "EXACT_BARCODE", "EXACT_SERIAL", "EXACT_MODEL", "TEXT", "TRIGRAM"

modelNumberobligatorio
string | nulllongitud máx. 100

barcodeobligatorio
string | nulllongitud máx. 100

storageobligatorio
string | nulllongitud máx. 100

colorobligatorio
string | nulllongitud máx. 100

conditionobligatorio
uno de "NEW", "USED", "REFURBISHED", "OPEN_BOX", "AS_IS", null

gradeobligatorio
uno de "A", "B", "C", null

simTypeobligatorio
uno de "ESIM", "PHYSICAL_SIM", "PHYSICAL_ESIM", "DUAL_SIM", "NOT_APPLICABLE"por defecto NOT_APPLICABLE

SearchUnit

objectsin otras propiedades

kindobligatorio
stringvalor fijo "INVENTORY_UNIT"

idobligatorio
stringformato uuid

variantIdobligatorio
stringformato uuid

productIdobligatorio
stringformato uuid

productNameobligatorio
string

skuobligatorio
string

matchobligatorio
stringuno de "EXACT_IMEI", "EXACT_SKU", "EXACT_BARCODE", "EXACT_SERIAL", "EXACT_MODEL", "TEXT", "TRIGRAM"

modelNumberobligatorio
string | nulllongitud máx. 100

barcodeobligatorio
string | nulllongitud máx. 100

storageobligatorio
string | nulllongitud máx. 100

colorobligatorio
string | nulllongitud máx. 100

conditionobligatorio
uno de "NEW", "USED", "REFURBISHED", "OPEN_BOX", "AS_IS", null

gradeobligatorio
uno de "A", "B", "C", null

simTypeobligatorio
uno de "ESIM", "PHYSICAL_SIM", "PHYSICAL_ESIM", "DUAL_SIM", "NOT_APPLICABLE"por defecto NOT_APPLICABLE

unitStatusobligatorio
stringuno de "AVAILABLE", "RESERVED", "SOLD", "IN_TRANSIT", "DAMAGED", "RETURNED", "RMA", "LOST", "QUARANTINED"

unitVersionobligatorio
integermín. 1
nextCursorobligatorio
string | nulllongitud máx. 600
Opaque cursor bound to normalized input, tenant/principal, archive visibility and current serial capability; fresh state may change results between pages.

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.