Crear Productos

Descripción

Permite crear uno o múltiples productos en el sistema mediante una única petición. Este endpoint está diseñado para operaciones en lote (batch), permitiendo insertar hasta 10,000 registros por petición.

Los productos representan los artículos o servicios que la empresa comercializa, organizados jerárquicamente por grupos, familias y líneas.

El sistema utiliza una operación MERGE que solo inserta productos nuevos. Si un producto con el mismo code ya existe, será ignorado (no se actualizará).

---

Endpoint

POST /api/products/batch-create

---

Headers

Header	Valor	Descripción
Content-Type	application/json	Especifica que el contenido es JSON

---

Body (JSON)

El body debe ser un array de objetos, donde cada objeto representa un producto a crear.

Límites

Parámetro	Valor	Descripción
Mínimo de items	1	El array no puede estar vacío
Máximo de items	10,000	Número máximo de productos por petición

---

Campos Requeridos

Estos campos son obligatorios en cada objeto del array:

Campo	Tipo	Longitud	Descripción
code	String	Max 20	Código único del producto
group_code	String	Max 40	Código del grupo al que pertenece el producto
family_code	String	Max 40	Código de la familia del producto
line_code	String	Max 40	Código de la línea del producto
tax	Decimal	(18, 2)	Porcentaje de impuesto aplicable al producto

Formato de tipos de datos

• String: Cadena de texto. La longitud indica el máximo de caracteres permitidos.
• Decimal (p, s): Número decimal donde p es la precisión total (dígitos enteros + decimales) y s es la escala (dígitos decimales).
  • Ejemplo: Decimal (18, 2) permite hasta 16 dígitos enteros y 2 decimales (ej: 9999999999999999.99)

---

Campos Opcionales

Estos campos pueden incluirse opcionalmente en cada objeto:

Campo	Tipo	Longitud	Descripción
description	String	Max 200	Descripción detallada del producto
charges	Decimal	(10, 2)	Valor de cargos adicionales aplicables
ean	String	Max 20	Código EAN/código de barras del producto
business_unit	String	Max 20	Unidad de negocio a la que pertenece
observations	String	Max 500	Observaciones o notas adicionales del producto
reference	String	Max 100	Referencia externa o código alternativo
weight	Decimal	(18, 2)	Peso del producto (en kilogramos u otra unidad definida)
volume	Decimal	(18, 2)	Volumen del producto (en litros u otra unidad definida)
commercial_unit	String	Max 40	Casa comercial o marca del producto

---

Ejemplo de Petición

A continuación se muestra un ejemplo completo de creación de productos:

curl -X POST "https://your-api-url/api/products/batch-create" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "PROD-001",
      "description": "Aceite de motor 10W40 1L",
      "group_code": "GRP-LUBRIC",
      "family_code": "FAM-ACEITES",
      "line_code": "LIN-MOTOR",
      "tax": 19.00,
      "charges": 0.00,
      "ean": "7701234567890",
      "business_unit": "AUTOMOTRIZ",
      "observations": "Producto de alta rotación",
      "reference": "REF-ACE-10W40",
      "weight": 0.95,
      "volume": 1.00,
      "commercial_unit": "CASTROL"
    },
    {
      "code": "PROD-002",
      "description": "Filtro de aire para vehículo",
      "group_code": "GRP-FILTROS",
      "family_code": "FAM-AIRE",
      "line_code": "LIN-VEHIC",
      "tax": 19.00,
      "ean": "7709876543210",
      "weight": 0.35
    }
  ]'

Ejemplo mínimo (solo campos requeridos)

curl -X POST "https://your-api-url/api/products/batch-create" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "PROD-003",
      "group_code": "GRP-GENERAL",
      "family_code": "FAM-VARIOS",
      "line_code": "LIN-DEFAULT",
      "tax": 19.00
    },
    {
      "code": "PROD-004",
      "group_code": "GRP-GENERAL",
      "family_code": "FAM-VARIOS",
      "line_code": "LIN-DEFAULT",
      "tax": 0.00
    }
  ]'

---

Respuesta Exitosa

Status Code: 201 Created

{
  "statusCode": 201,
  "message": "Products created successfully"
}

Importante

Los productos que ya existan en el sistema (mismo code) serán ignorados sin generar error. Solo se insertarán los productos nuevos.

---

Respuestas de Error

Error 400 - JSON Inválido

Se produce cuando el body de la petición no contiene un JSON válido.

Status Code: 400 Bad Request

{
  "statusCode": 400,
  "errors": [
    {
      "message": "Invalid JSON in request body"
    }
  ]
}

---

Error 400 - Body No Es Un Array

Se produce cuando el body no es un array de objetos.

Status Code: 400 Bad Request

{
  "statusCode": 400,
  "errors": [
    {
      "index": null,
      "field": null,
      "message": "Request body must be an array"
    }
  ]
}

---

Error 400 - Array Vacío

Se produce cuando el array no contiene ningún elemento.

Status Code: 400 Bad Request

{
  "statusCode": 400,
  "errors": [
    {
      "index": null,
      "field": null,
      "message": "Request body cannot be empty"
    }
  ]
}

---

Error 400 - Excede Límite de Batch

Se produce cuando el array contiene más de 10,000 elementos.

Status Code: 400 Bad Request

{
  "statusCode": 400,
  "errors": [
    {
      "index": null,
      "field": null,
      "message": "Array exceeds maximum limit of 10000 items"
    }
  ]
}

---

Error 400 - Errores de Validación por Item

Se produce cuando uno o más items del array tienen errores de validación. Cada error incluye el índice del item en el array.

Status Code: 400 Bad Request

{
  "statusCode": 400,
  "errors": [
    {
      "index": 0,
      "errors": [
        {
          "field": "code",
          "message": "Field is required"
        },
        {
          "field": "tax",
          "message": "Field must be of type decimal"
        }
      ]
    },
    {
      "index": 2,
      "errors": [
        {
          "field": "code",
          "message": "Field exceeds maximum length of 20 characters"
        }
      ]
    }
  ]
}

Tipos de errores de validación por campo

Error	Descripción
Field is required	El campo obligatorio no fue enviado o está vacío
Field must be a string	El valor no es una cadena de texto
Field must be of type integer	El valor no es un número entero válido
Field must be of type decimal	El valor no es un número decimal válido
Field must be a valid decimal (e.g., 1.5, 10.25)	El formato del decimal es inválido
Field exceeds maximum length of X characters	La cadena excede la longitud máxima permitida
Field exceeds maximum of X integer digits	El número excede los dígitos enteros permitidos
Field exceeds maximum of X decimal places	El número excede los decimales permitidos
Unknown field	Se envió un campo que no existe en la configuración
Item must be an object	Un elemento del array no es un objeto JSON

---

Error 500 - Error de Validación Inesperado

Se produce cuando ocurre un error inesperado durante el proceso de validación de datos.

Status Code: 500 Internal Server Error

{
  "statusCode": 500,
  "errors": [
    {
      "message": "Unexpected validation error: [descripción del error]"
    }
  ]
}

---

Error 500 - Error de Conexión a Base de Datos

Se produce cuando hay problemas de conexión con la base de datos.

Status Code: 500 Internal Server Error

{
  "statusCode": 500,
  "errors": [
    {
      "message": "Error connecting to database: [descripción del error]"
    }
  ]
}

---

Error 500 - Error de Operación en Base de Datos

Se produce cuando la operación en la base de datos falla durante la ejecución.

Status Code: 500 Internal Server Error

{
  "statusCode": 500,
  "errors": [
    {
      "message": "Database operation failed: [descripción del error]"
    }
  ]
}

---

Error 500 - Error Inesperado

Se produce ante cualquier error no controlado durante el procesamiento.

Status Code: 500 Internal Server Error

{
  "statusCode": 500,
  "errors": [
    {
      "message": "Unexpected error: [descripción del error]"
    }
  ]
}

---

Códigos de Estado HTTP

Código	Descripción
201	Productos creados exitosamente
400	Error en la estructura o validación de los datos
500	Error interno del servidor

Para más información sobre los códigos de estado, consulta la sección de Códigos de estado HTTP.

---

Notas Importantes

• El endpoint utiliza una operación MERGE que solo inserta registros nuevos.
• Los productos existentes (mismo code) son ignorados sin generar error.
• Todos los campos de texto son sensibles a mayúsculas/minúsculas.
• Los valores decimales pueden enviarse como números (19.00) o strings ("19.00").
• La fecha de creación (FECHA_CREA) se asigna automáticamente por el sistema.
• El estado del producto (PRODUCTO_ESTADO) se configura automáticamente como activo (“Y”).
• Se recomienda enviar lotes de máximo 1,000 registros para un mejor rendimiento.
• Los campos group_code, family_code y line_code permiten organizar los productos en una jerarquía de clasificación.
• El campo ean es útil para integración con lectores de códigos de barras y sistemas de inventario.