Listar productos

GET

/products

curl --request GET \
  --url 'https://api.posdata.so/public/v1/products?limit=25&include_deleted=false' \
  --header 'Authorization: Bearer <token>'

• Producción (keys pdk_live_)
• Pruebas (keys pdk_test_, datos de prueba, puede reiniciarse)

Productos con sus variantes, del más reciente al más antiguo.

Permiso requerido: products:read.

Autorización

• bearerAuth

Parámetros

Parámetros de consulta

limit

integer

por defecto: 25 >= 1 <= 100

starting_after

string

El next_cursor de la página anterior, tal cual.

created_since

string formato: date-time

ISO 8601 con zona horaria. Incluye.

created_until

string formato: date-time

ISO 8601 con zona horaria. Excluye.

updated_since

string formato: date-time

ISO 8601 con zona horaria. Para sincronización incremental.

active

boolean

Solo activos (true) o inactivos (false).

category_id

string formato: uuid

Productos de esa categoría.

sku

string

<= 100 caracteres

Coincidencia exacta con el SKU del producto o de cualquiera de sus variantes.

q

string

>= 2 caracteres <= 100 caracteres

Busca en el nombre (sin distinguir mayúsculas).

include_deleted

boolean

Si es true, incluye los registros eliminados (con deleted_at).

Respuestas

200

OK

Tipo de contenidoapplication/json

object

object

obligatorio

Valor permitido: list

data

obligatorio

Array<object>

Producto del catálogo. Precios en pesos enteros, digitados como los digita el negocio: con impuestos incluidos cuando su perfil fiscal dice pricesIncludeTax (lo normal), antes de impuestos si no.

object

object

obligatorio

Valor permitido: product

id

obligatorio

string formato: uuid

name

obligatorio

string

description

obligatorio

string

description_short

obligatorio

string

sku

obligatorio

Cualquiera de:

string

string

null

null

category_id

obligatorio

Cualquiera de:

string

string formato: uuid

null

null

kind

obligatorio

composite = se arma desde una receta y no descuenta su propio stock.

string

Valores permitidos: simple composite

sellable

obligatorio

false = insumo que no se vende por sí solo.

boolean

active

obligatorio

boolean

tax_class

obligatorio

Clase fiscal del ítem. standard hereda del perfil fiscal del negocio.

string

Valores permitidos: standard reduced_5 excluded exempt service_19 event_package bag passthrough

base_price

obligatorio

Precio de lista, antes del descuento propio del producto.

integer

final_price

obligatorio

Precio al que el POS vende. Si el producto no tiene descuento es igual a base_price.

integer

percent_discount

obligatorio

Descuento del producto sobre base_price, en porcentaje (0-100, puede tener decimales).

number

base_unit

obligatorio

Unidad base (und, g, kg, lb, oz, ml, l, doc). Stock y costo se expresan en ella.

string

sold_by_weight

obligatorio

Se vende por peso: la cantidad de la línea es un peso en base_unit.

boolean

stock

obligatorio

Cualquiera de:

integer

integer

null

null

unit_cost

obligatorio

Costo promedio ponderado por unidad base (informativo).

number

image_url

obligatorio

Cualquiera de:

string

string formato: uri

null

null

images

obligatorio

Array<string>

has_variants

obligatorio

boolean

variants

obligatorio

Variantes vigentes (no eliminadas).

Array<object>

Variante de un producto. Precios en pesos enteros, digitados como los digita el negocio: con impuestos incluidos cuando su perfil fiscal dice pricesIncludeTax (lo normal), antes de impuestos si no.

object

object

obligatorio

Valor permitido: product_variant

id

obligatorio

string formato: uuid

product_id

obligatorio

string formato: uuid

label

obligatorio

Nombre de la variante (“Talla M / Rojo”).

string

sku

obligatorio

Cualquiera de:

string

string

null

null

base_price

obligatorio

Precio de lista, antes del descuento propio del producto.

integer

final_price

obligatorio

Precio al que el POS vende esta variante. Si es 0 en la variante, el POS usa el del producto.

integer

percent_discount

obligatorio

Descuento del producto sobre base_price, en porcentaje (0-100, puede tener decimales).

number

images

obligatorio

Array<string>

is_default

obligatorio

boolean

active

obligatorio

boolean

created_at

obligatorio

string formato: date-time

updated_at

obligatorio

string formato: date-time

deleted_at

obligatorio

Cualquiera de:

string

string formato: date-time

null

null

created_at

obligatorio

string formato: date-time

updated_at

obligatorio

string formato: date-time

has_more

obligatorio

boolean

next_cursor

obligatorio

Cualquiera de:

string

string

null

null

Ejemplo

{
  "object": "list",
  "data": [
    {
      "object": "product",
      "kind": "simple",
      "tax_class": "standard",
      "variants": [
        {
          "object": "product_variant"
        }
      ]
    }
  ]
}

400

Petición inválida (VALIDATION_ERROR, INVALID_JSON, INVALID_CURSOR).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

401

Sin API key válida (UNAUTHENTICATED, INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED, API_KEY_WRONG_ENVIRONMENT, ACCOUNT_INACTIVE).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

403

Sin permiso (PLAN_REQUIRED, INSUFFICIENT_SCOPE, BROWSER_REQUESTS_NOT_ALLOWED).

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

429

Límite de peticiones (RATE_LIMITED). Respeta Retry-After.

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

500

Error interno (INTERNAL_ERROR). Reintenta y comparte el request_id si persiste.

Tipo de contenidoapplication/json

object

error

obligatorio

object

code

obligatorio

string

Valores permitidos: UNAUTHENTICATED INVALID_API_KEY API_KEY_REVOKED API_KEY_EXPIRED API_KEY_WRONG_ENVIRONMENT ACCOUNT_INACTIVE PLAN_REQUIRED INSUFFICIENT_SCOPE BROWSER_REQUESTS_NOT_ALLOWED VALIDATION_ERROR INVALID_JSON PAYLOAD_TOO_LARGE INVALID_CURSOR NOT_FOUND ROUTE_NOT_FOUND IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS CONFLICT SKU_ALREADY_EXISTS VARIANT_STOCK_UNSUPPORTED COMPOSITE_STOCK_UNSUPPORTED NO_WAREHOUSE DEVICES_OUTDATED RATE_LIMITED INTERNAL_ERROR

message

obligatorio

Explicación en español, con el siguiente paso.

string

param

Campo que causó el error, si aplica.

string

request_id

obligatorio

string

key

propiedades adicionales

any

Ejemplo

{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}