Descripción general

Endpoint /items

Los productos o servicios representan lo que tu negocio vende y/o compra.

Los productos son objetos tangibles que tu empresa tiene disponible para la venta y a los cuales les controlas el inventario. (En la aplicación se conoce como inventariables). Estos deben tener una unidad de medida (metros, cm, litros), una cantidad inicial (el número de productos disponibles inicialmente para la venta) y un costo unitario. Al realizar movimientos con estos productos la aplicación automáticamente actualiza el inventario en cuanto a costo unitario y cantidades.

A un servicio, por el contrario, no se le controla el inventario.

Alegra soporta listas de precios, por lo tanto el precio de un producto o servicio puede estar conformado por varias listas de precio. Todas las cuentas de Alegra cuentan con una lista de precios llamada "General", en ésta se registra el precio general del producto. Al consultar un producto o servicio por el API, el precio va a estar conformado por todas las listas de precio. Si se desea consultar el precio general del producto, se debe consultar el precio indicado en la lista de precios General (o identificada con el id 1). Para saber más sobre listas de precio haz clic aquí.

Los productos se separan en 4 tipos, sencillo (simple), items que contienen otros items (combo), items que comparten ciertas características pero derivan otras (items con variantes) y items agrupados por un item padre con características comunes (item variante). Para identificar el tipo de un producto se utiliza el atributo type. Si el producto no contiene el atributo type se encontrará en simple; si está compuesto otros ítems se encontrará kit, si es un item con variantes se encontrará variantParent y es un item variante se encontrará variant. Cuando un producto es de tipo kit los productos de los que está compuesto se pueden encontrar en el atributo subitems.
Se debe indicar en un combo la bodega que se desea asociar a los productos que lo componen para indicar en el momento que se está haciendo una venta la bodega de la cual salen los productos. Si no se asocia una bodega al crear el combo, éste queda asociado a la bodega principal. Cuando se manejan múltiples bodegas todos los productos dentro del combo deben pertenecer a la misma bodega o almacén.

Un producto o servicio contiene los siguientes atributos:

Nombre

Tipo

Descripción

Ejemplo

id

Integer

Identificador único que representa un producto o servicio específico. La aplicación lo asigna automáticamente.

12

name

String

Nombre del producto o servicio.

Billetera de cuero

description

String

Descripción del producto o servicio.

Billetera de cuero negro

reference

String

Referencia o código que identifica un producto o servicio.

BILL-123

reference

Object

Solo para versión Alegra Costa Rica.

Objeto reference que indica la referencia del producto.

Contiene los siguientes atributos:

  • reference: India el código de referencia establecido para el producto.

  • type: Indica el tipo de referencia del producto.

Consulta el catálogo de parámetros correspondiente a cada país haciendo clic aquí.

{
"reference": "P001",
"type": "CODE_OF_THE_SELLER"
}

price

Array de objetos PriceList

Indica los precios asociados al producto o servicio. Cada objeto PriceList contiene los siguientes atributos:

  • idPriceList : Identificador único que representa una lista de precios específica.
  • name: Nombre de la lista de precios. Por ejemplo "General", "Distribuidor"
  • price: precio del producto en esa lista de precios.
[ {                                   "idPriceList" : 1,
"name" : "Principal",
  "price" : 1200
} ]

tax

Array de objetos Tax

Indica el impuesto asociado al producto o servicio. Cada objeto tax contiene los siguientes atributos:

  • id: Identificador del impuesto.
  • name : Nombre del impuesto. Por ejemplo "IVA".
  • percentage: Porcentaje del impuesto. Ej: 16.
  • description: Descripción del impuesto.
  • status: Estado del impuesto, puede ser active para un impuesto activo, o inactive para un impuesto que se encuentra deshabilitado
[ {
"id" : 6,
"name" : "IVA",
"percentage" : 16,
"description" : "Impuesto de valor agregado",
"status": "active"
} ]

category

Object

Objeto que contiene la información de la categoría asociada al producto o servicio. Este objeto indica la categoría de Alegra a la cual se llevan los registros de tus ventas cuando realizas movimientos con este producto o servicio.
La categoría está compuesta por los siguientes atributos:

  • id: Identificador de la categoría.
  • name : Nombre de la categoría.
{
"id": 54,
"name" : "Ventas"
}

inventory

Object

Objeto que contiene la información del inventario del producto. Si este objeto está presente indica que el artículo es inventariable, si no lo está se asume como servicio.
Contiene los siguientes atributos:

  • unit : Indica la unidad de medida del producto.
  • availableQuantity: Indica la cantidad disponible en el inventario. Si el producto se encuentra distribuido en múltiples bodegas, este atributo retorna la cantidad disponible en todas las bodegas.
  • unitCost : Indica el costo unitario del producto.
  • initialQuantity: Indica la cantidad inicial con la cual se creó el producto. Si el producto se encuentra distribuido en múltiples bodegas, este atributo retorna la cantidad inicial en todas las bodegas.
  • warehouses : Array de objetos warehouse que indican las bodegas asociadas al producto. Cada objeto warehouse contiene los siguientes atributos:
    • id: Identificador único de la bodega.
    • name: Nombre de la bodega.
    • observations : Observaciones de la bdoega.
    • isDefault: Indica si la bodega es la de por defecto.
    • address: Dirección de la bodega.
    • status : Estado de la bodega, puede ser active o inactive.
    • initialQuantity: Cantidad inicial del producto en la bodega.
    • availableQuantity: Cantidad disponible del producto en la bodega.
    • minQuantity: Cantidad mínima establecida para el producto en la bodega.
    • maxQuantity: Cantidad máxima establecida para el producto en la bodega.
{
"unit" : "meter",
"availableQuantity" : 150,
"unitCost" : 560,
 "initialQuantity" : 320,
 "warehouses": [
   {
     "id": "1",
     "name": "Bodega Norte",
     "observations": null,
     "isDefault": true,
     "address":"Dirección de la bodega Norte",
     "status": "active",
     "initialQuantity": "320.0",
     "availableQuantity": "150",
     "minQuantity": "100",
     "maxQuantity": "400"
   }
 ]
}

status

String

Indica el estado del producto o servicio. Las opciones posibles son:

  • active: para productos que se encuentran activos
  • inactive: para productos que se encuentran inactivos

active

type

String

Indica el tipo del producto. Las opciones posibles son :

  • simple: Producto sencillo.
  • kit: Producto que está compuesto por otros.
  • variantParent: Producto con características variantes (como el color o la talla). Es el item padre, compuesto de items variantes.
  • variant: Producto asociado a un item con variantes, representa un conjunto de variantes en especifico. Es el item hijo asociado a un padre.

simple

productKey (México)

String

Solo para versión Alegra México.
Indica la clave de producto o ProdServKey.

01010101

productKey (Costa Rica)

String

Solo para versión Alegra Costa Rica.
Indica la clave de producto.

112299020200

productKey (Panamá)

String

Solo para versión Alegra Panamá.
Indica la codificación panameña de bienes y servicios.

1040

subitems

Array

Array de objetos que contienen la información de los productos que componen el kit. Aplica únicamente para productos tipo kit.
Contiene los siguientes atributos:

  • quantity: Cantidad del subitem necesaria para conformar el kit.
  • item : Objeto item que contiene toda la información del producto relacionado al combo
{
    "quantity": "4.00",
    "item": {
                "name": "Cuaderno escolar",
                "description": "Cuaderno a rayas",
                "reference": null,
                "status": "active",
                "id": 1,
                "type": "simple"
            }
},

kitWarehouse

Objeto

Objeto que indica la bodega asociada al combo. Contiene un objeto warehouse.

{
        "id": "1",
        "name": "Principal",
        "observations": null,
        "isDefault": true,
        "address": null,
        "status": "active"
    }

tariffHeading (Costa Rica)

String

Solo para versión Alegra CostaRica.
Cadena de 12 caracteres que indica la partida arancelaria de un ítem.

010121000000

tariffHeading (Colombia)

String

Solo para versión Alegra Colombia.
Cadena de 10 caracteres que indica la partida arancelaria de un ítem. Aplica para facturas electrónicas de exportación.

2710121300

brand (Colombia)

String

Solo para versión Alegra Colombia.
Cadena de caracteres que indica la marca de un ítem. Aplica para facturas electrónicas de exportación.

Genius

model (Colombia)

String

Solo para versión Alegra Colombia.
Cadena de caracteres que indica el modelo de un ítem. Aplica para facturas electrónicas de exportación.

2020

itemCategory

Objeto

Objeto que indica la categoría de ítem asociada. Contiene un objeto itemCategory.

{
"id": "1",
"name": "Telas",
"description": "De la mejor calidad",
"status": "active"
}

hasNoIvaDays (Colombia)

Boolean

Retorna true si el ítem puede participar en el programa días sin IVA.

true

customFields

Array

Array con atributos adicionales asociados al producto.

Contiene los siguientes atributos:

  • id: Id del atributo adicional.
  • name: Nombre del atributo adicional
  • key: Identificador del atributo adicional.
  • value: Valor del atributo adicional para el item.
[
                {
                    "id": "2",
                    "name": "Fecha de vencimiento",
                    "key": null,
                    "value": "2020-07-01"
                }
]

variantAttributes

Array

Array con atributos variantes asociados al producto.

Contiene los siguientes atributos:

  • id: Id del atributo variante.
  • name: Nombre del atributo variante.
  • status: Estado del atributo variante.
  • options: Array con las opciones del atributo variante.

Nota: Aplica únicamente para items de tipo "variantParent" y "variant"

[
    {
        "id": "1",
        "name": "Color",
        "status": "active",
        "options": [
            {
                "id": "1",
                "value": "Rojo"
            },
            {
                "id": "2",
                "value": "Verde"
            }
        ]
    }
]

itemVariants

Array

Array con los subitems del item variantes.

Notas:

  • Aplica únicamente para items de tipo "variantParent"
  • Un item con variantes contiene un item variante por cada una de las combinaciones posibles de sus atributos variantes, ej: La compañía X tiene un item que contiene los atributos variantes "COLOR" y "TALLA" con las opciones "Color: Blanco", "Color:Rojo", "Talla: XS", "Talla: M". Esto quiere decir que el item padre, contendrá 4 items variantes (un item Blanco XS, otro Blanco M, otro Rojo XS y otro Rojo M)
[
    {
        "inventory": { 
           "initialQuantity": 10
        },
    "variantAttributes": [
     {               
            "id": "1",
       "options": [
          {
             "id": "1",
             "value": "BLANCO"               
              }
        ]
         },
     {               
            "id": "2",
       "options": [
          {
             "id": "4",
             "value": "XS"               
              }
        ]
    }
       ]
    }
]

accounting

Object

Objeto que representa las cuentas de inventario y costo de ventas. Solo aplica para items inventariables.

inventory: Cuenta de inventario

inventariablePurchase: Costo del inventario

"accounting": {
  "inventory": {
    "id": "5025",
    "idParent": "5002",
    "name": "Inventarios",
    "description": "",
    "type": "asset",
    "code": null,
    "readOnly": false,
    "categoryRule": {
      "id": "7",
      "name": "Inventario",
      "key": "INVENTORY"
    },
    "metadata": {
      "satGroupingCode": "",
      "satGroupingText": ""
    }
  },
  "inventariablePurchase": {
    "id": "5074",
    "idParent": "5073",
    "name": "Costos del inventario",
    "description": "",
    "type": "expense",
    "code": null,
    "readOnly": true,
    "categoryRule": {
      "id": "33",
      "name": "Compras inventariables",
      "key": "INVENTARIABLE_PURCHASES"
    },
    "metadata": {
      "satGroupingCode": "",
      "satGroupingText": ""
    }
  }
},