Crear producto

POST

/products

curl --request POST \
  --url https://api.posdata.so/public/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "name": "example", "description": "example", "description_short": "example", "sku": "example", "category_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "base_price": 1, "final_price": 1, "percent_discount": 1, "tax_class": "standard", "active": true, "sellable": true, "base_unit": "und", "sold_by_weight": false, "initial_stock": 1, "warehouse_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

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

Crea un producto sin variantes. Con initial_stock registra además un movimiento de entrada en la bodega indicada. El cambio llega a las cajas del negocio por su sincronización normal (en segundos si están en línea; si están sin conexión, al reconectarse).

Permiso requerido: products:write.

Autorización

• bearerAuth

Parámetros

Parámetros de cabecera

Idempotency-Key

obligatorio

string

<= 255 caracteres /^[A-Za-z0-9_\-:.]{1,255}$/

Obligatorio en todo POST. Un valor único por operación (p. ej. un UUID); reutilízalo solo para reintentar la MISMA operación. Válido 24 h.

Cuerpo de la petición^obligatorio

Tipo de contenidoapplication/json

object

name

obligatorio

string

<= 200 caracteres

description

string

<= 5000 caracteres

description_short

string

<= 300 caracteres

sku

string

<= 60 caracteres

category_id

Cualquiera de:

string

string formato: uuid

null

null

base_price

obligatorio

Precio base en pesos.

integer

<= 10000000000

final_price

Precio al que vende la caja. Si no se envía, es igual a base_price.

integer

<= 10000000000

percent_discount

number

<= 100

tax_class

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

string

por defecto: standard

Valores permitidos: standard reduced_5 excluded exempt service_19 event_package bag passthrough

active

boolean

por defecto: true

sellable

false = insumo que no se vende solo.

boolean

por defecto: true

base_unit

string

por defecto: und

Valores permitidos: und g kg lb oz ml l doc

sold_by_weight

Requiere base_unit g, kg o lb.

boolean

initial_stock

Crea además un movimiento de entrada con este stock.

integer

>= 1 <= 1000000000

warehouse_id

Bodega del stock inicial. Por defecto, la bodega predeterminada.

string formato: uuid

Respuestas

201

Creado

Tipo de contenidoapplication/json

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

Ejemplo

{
  "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"
  }
}

409

Conflicto (CONFLICT, SKU_ALREADY_EXISTS, IDEMPOTENCY_IN_PROGRESS, NO_WAREHOUSE, DEVICES_OUTDATED).

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"
  }
}

422

Regla de negocio o idempotencia (IDEMPOTENCY_KEY_REUSED, VARIANT_STOCK_UNSUPPORTED, COMPOSITE_STOCK_UNSUPPORTED).

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"
  }
}