Productos

Un producto es una unidad vendible que puede estar compuesto por uno o más SKU

Listar productos

get

/products/search

Retorna un listado paginado de productos de la cuenta autenticada. También incluye productos de cuentas proveedoras asociadas (dropshipping). En el listado, los SKUs solo incluyen código y unidades; para ver atributos físicos completos usar GET /products/{id}.

Autorizaciones

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de consulta

per_pageinteger · máx: 100Opcional

Cantidad de productos por página (máximo 100, por defecto 50)

Default: 50Example: 50

searchstringOpcional

Búsqueda de texto libre por nombre o código de referencia del producto

Example: camiseta

supplier_idintegerOpcional

Filtrar por ID de proveedor asociado a la cuenta. Cuando se especifica, solo se retornan productos de ese proveedor.

Example: 5

sort_bystring · enumOpcional

Campo por el que ordenar los resultados

Default: created_atValores posibles:

sort_directionstring · enumOpcional

Dirección del ordenamiento

Default: descValores posibles:

pageintegerOpcional

Número de página

Example: 1

Respuestas

200

Listado paginado de productos

application/json

Respuesta paginada del listado de productos.

401

No autenticado.

422

Parámetros de consulta inválidos.

500

Error interno del servidor.

get

/products/search

GET /v2/products/search HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Accept: */*

{
  "data": [
    {
      "id": 1,
      "account_id": 12,
      "reference_code": "PROD-001",
      "name": "[Proveedor X] Producto Ejemplo",
      "skus": [
        {
          "sku": "SKU-001",
          "units": 2,
          "data": {
            "name": "Caja pequeña",
            "internal_sku": "INT-001",
            "barcode": "7798164800027",
            "attributes": {
              "unit_declared_value": 100.5,
              "weight": 500,
              "length": 20,
              "width": 15,
              "height": 10
            },
            "classification": "default",
            "stackable": false
          }
        }
      ],
      "created_at": "2024-06-01T12:00:00Z",
      "updated_at": "2024-06-01T12:00:00Z",
      "supplier": {
        "id": 3,
        "name": "Proveedor X",
        "account_id": 100
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 237,
    "last_page": 5,
    "from": 1,
    "to": 50
  },
  "links": {
    "first": "https://api.zipnova.com.ar/v2/products/search?page=1",
    "last": "https://api.zipnova.com.ar/v2/products/search?page=5",
    "prev": null,
    "next": "https://api.zipnova.com.ar/v2/products/search?page=2"
  }
}

Obtener detalle de producto

get

/products/{product}

Retorna el detalle completo de un producto, incluyendo los atributos físicos de cada SKU (peso, dimensiones, código de barras, clasificación, etc.) y el stock disponible por depósito.

Autorizaciones

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de ruta

productintegerRequerido

ID del producto

Example: 1

Respuestas

200

Detalle del producto

application/json

Representa un producto del catálogo con sus SKUs asociados.

idintegerOpcional

ID del producto

Example: 1

account_idintegerOpcional

ID de la cuenta propietaria del producto

Example: 12

reference_codestringOpcional

Código de referencia único del producto en la cuenta

Example: PROD-001

namestringOpcional

Nombre del producto. Si es un producto de proveedor, el nombre del proveedor se antepone entre corchetes.

Example: [Proveedor X] Producto Ejemplo

created_atstring · date-timeOpcional

Fecha de creación del producto

Example: 2024-06-01T12:00:00Z

updated_atstring · date-timeOpcional

Fecha de última actualización del producto

Example: 2024-06-01T12:00:00Z

401

No autenticado.

404

Producto no encontrado o sin acceso.

500

Error interno del servidor.

get

/products/{product}

GET /v2/products/{product} HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Accept: */*

{
  "id": 1,
  "account_id": 12,
  "reference_code": "PROD-001",
  "name": "[Proveedor X] Producto Ejemplo",
  "skus": [
    {
      "sku": "SKU-001",
      "units": 2,
      "data": {
        "name": "Caja pequeña",
        "internal_sku": "INT-001",
        "barcode": "7798164800027",
        "attributes": {
          "unit_declared_value": 100.5,
          "weight": 500,
          "length": 20,
          "width": 15,
          "height": 10
        },
        "classification": "default",
        "stackable": false
      }
    }
  ],
  "created_at": "2024-06-01T12:00:00Z",
  "updated_at": "2024-06-01T12:00:00Z",
  "supplier": {
    "id": 3,
    "name": "Proveedor X",
    "account_id": 100
  }
}

Crear producto

post

/products

Crea un nuevo producto para la cuenta autenticada.

Los SKUs se especifican en el campo skus, donde cada entrada puede ser:

Referencia a SKU existente: pasar el código del SKU como string (ej. "SKU-001").
Nuevo SKU inline: pasar un objeto con los datos del SKU a crear.

Al crear el producto, se calculan automáticamente el peso total y el volumen total a partir de las dimensiones de los SKUs y las unidades por SKU.

Autorizaciones

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Cuerpo

Datos para crear un nuevo producto con SKUs asociados.

reference_codestring · máx: 255Requerido

Código de referencia único del producto en la cuenta. Se sanitiza automáticamente (se convierten caracteres especiales).

Example: PROD-001

namestring · máx: 255Requerido

Nombre del producto

Example: Camiseta Manga Corta

Respuestas

201

Producto creado exitosamente

application/json

401

No autenticado.

422

Error de validación. Ver el objeto errors para detalles.

500

Error interno del servidor.

post

/products

POST /v2/products HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 96

{
  "reference_code": "PROD-001",
  "name": "Camiseta Manga Corta",
  "skus": [
    {
      "sku": "SKU-001",
      "units": 1
    }
  ]
}

{
  "id": 1,
  "account_id": 12,
  "reference_code": "PROD-001",
  "name": "[Proveedor X] Producto Ejemplo",
  "skus": [
    {
      "sku": "SKU-001",
      "units": 2,
      "data": {
        "name": "Caja pequeña",
        "internal_sku": "INT-001",
        "barcode": "7798164800027",
        "attributes": {
          "unit_declared_value": 100.5,
          "weight": 500,
          "length": 20,
          "width": 15,
          "height": 10
        },
        "classification": "default",
        "stackable": false
      }
    }
  ],
  "created_at": "2024-06-01T12:00:00Z",
  "updated_at": "2024-06-01T12:00:00Z",
  "supplier": {
    "id": 3,
    "name": "Proveedor X",
    "account_id": 100
  }
}

Actualizar producto

put

/products/{product}

Actualiza los datos de un producto existente de la cuenta autenticada. Todos los campos son opcionales; solo se actualizan los que se envíen.

Si se envía el campo skus, reemplaza completamente la lista de SKUs asociados al producto (operación de sincronización). Los SKUs no incluidos en el listado serán desvinculados del producto (aunque no eliminados del inventario). Cada entrada puede ser una referencia a un SKU existente (string con el código) o un objeto con datos para crear un nuevo SKU.

Tras cualquier modificación de SKUs, se recalculan automáticamente el peso total y el volumen total del producto.

Autorizaciones

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de ruta

productintegerRequerido

ID del producto

Example: 1

Cuerpo

Datos para actualizar un producto existente. Todos los campos son opcionales; solo se actualizan los que se envíen. Si se envía el campo skus, reemplaza completamente la lista de SKUs asociados al producto.

namestring · máx: 255Opcional

Nombre del producto

Example: Camiseta Manga Corta v2

reference_codestring · máx: 100Opcional

Código de referencia único del producto en la cuenta. Se sanitiza automáticamente.

Example: PROD-001-V2

Respuestas

200

Producto actualizado exitosamente

application/json

Representa un producto del catálogo con sus SKUs asociados.

idintegerOpcional

ID del producto

Example: 1

account_idintegerOpcional

ID de la cuenta propietaria del producto

Example: 12

reference_codestringOpcional

Código de referencia único del producto en la cuenta

Example: PROD-001

namestringOpcional

Nombre del producto. Si es un producto de proveedor, el nombre del proveedor se antepone entre corchetes.

Example: [Proveedor X] Producto Ejemplo

created_atstring · date-timeOpcional

Fecha de creación del producto

Example: 2024-06-01T12:00:00Z

updated_atstring · date-timeOpcional

Fecha de última actualización del producto

Example: 2024-06-01T12:00:00Z

401

No autenticado.

404

Producto no encontrado o sin acceso.

422

Error de validación. Ver el objeto errors para detalles.

500

Error interno del servidor.

put

/products/{product}

PUT /v2/products/{product} HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "name": "Camiseta Manga Corta v2",
  "reference_code": "PROD-001-V2",
  "skus": [
    {
      "sku": "SKU-001",
      "units": 1
    }
  ]
}

{
  "id": 1,
  "account_id": 12,
  "reference_code": "PROD-001",
  "name": "[Proveedor X] Producto Ejemplo",
  "skus": [
    {
      "sku": "SKU-001",
      "units": 2,
      "data": {
        "name": "Caja pequeña",
        "internal_sku": "INT-001",
        "barcode": "7798164800027",
        "attributes": {
          "unit_declared_value": 100.5,
          "weight": 500,
          "length": 20,
          "width": 15,
          "height": 10
        },
        "classification": "default",
        "stackable": false
      }
    }
  ],
  "created_at": "2024-06-01T12:00:00Z",
  "updated_at": "2024-06-01T12:00:00Z",
  "supplier": {
    "id": 3,
    "name": "Proveedor X",
    "account_id": 100
  }
}

Eliminar producto

delete

/products/{product}

Elimina un producto específico para la cuenta autenticada.

Autorizaciones

AuthorizationstringRequerido

Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña

Parámetros de ruta

productintegerRequerido

ID del producto

Respuestas

200

Producto eliminado exitosamente. Los SKUs con stock o asociados a otros productos no se eliminan del inventario (se retornan en skus_kept).

application/json

messagestringOpcionalExample: Producto eliminado exitosamente

product_idintegerOpcionalExample: 42

skus_deletedstring[]Opcional

Códigos de SKUs eliminados del inventario junto con el producto

Example: SKU-001

skus_keptstring[]Opcional

Códigos de SKUs que no se eliminaron porque tienen stock o están asociados a otros productos

Example: SKU-002

skus_kept_reasonstringOpcionalExample: SKUs con stock o asociados a otros productos

401

No autenticado.

404

Producto no encontrado o sin acceso.

500

Error interno del servidor.

delete

/products/{product}

DELETE /v2/products/{product} HTTP/1.1
Host: api.zipnova.com.ar
Authorization: Basic username:password
Accept: */*

{
  "message": "Producto eliminado exitosamente",
  "product_id": 42,
  "skus_deleted": [
    "SKU-001"
  ],
  "skus_kept": [
    "SKU-002"
  ],
  "skus_kept_reason": "SKUs con stock o asociados a otros productos"
}

AnteriorGestión de productos y SKUs SiguienteSKUs y Stocks

Última actualización hace 28 días