Skip to content

Registrar productos ​

POST /api/Invoice/add_products

Registra o actualiza productos en el catálogo de su negocio. Si el codigoProducto ya existe se actualizan sus datos; si no, se crea. La operación es todo o nada: si algún producto tiene errores, no se guarda ninguno.

Autenticación: Authorization: Bearer <token> (cómo obtenerlo) · Content-Type: application/json

Cuerpo de la solicitud ​

CampoTipoObligatorioDescripción y reglas
productosarraySíLista de productos a registrar o actualizar. Debe contener al menos uno.

productos[] ​

CampoTipoObligatorioDescripción y reglas
codigoProductostringSíCódigo único del producto en su negocio. No puede repetirse dentro de la misma solicitud. Si ya existe en su catálogo, el producto se actualiza. Para poder usarlo luego en Agregar factura, use como máximo 13 caracteres y sin espacios.
nombreProductostringSíNombre del producto.
precionumber | stringSíPrecio unitario en Bs, sin IVA. Número mayor que 0 con punto como separador decimal (la coma no se acepta aquí); máximo 9 enteros y 2 decimales.
tipoImpuestostringSíAlícuota de IVA: G (general, 16 %), R (reducida, 8 %), A (adicional, 31 %), E (exento), P (percibido, 0 %) o X (exportación). No distingue mayúsculas.
descripcionProductostringNoDetalle o descripción del producto.

Alícuota fija

La alícuota con la que se registre el producto es la que se exigirá al facturarlo: Agregar factura rechaza un producto existente si se envía con una alícuota distinta. Si necesita cambiarla, vuelva a enviar el producto aquí con el nuevo tipoImpuesto.

Ejemplo de solicitud ​

json
{
  "productos": [
    {
      "codigoProducto": "PROD001",
      "nombreProducto": "Laptop 14 pulgadas",
      "descripcionProducto": "Laptop de alta gama con procesador i7",
      "tipoImpuesto": "G",
      "precio": "1200.50"
    },
    {
      "codigoProducto": "PROD002",
      "nombreProducto": "Libro de texto",
      "descripcionProducto": "Libro escolar",
      "tipoImpuesto": "E",
      "precio": "25.75"
    }
  ]
}

Respuesta exitosa ​

HTTP 200

json
{
  "success": true,
  "message": "Operación completada exitosamente.",
  "total_productos_agregados": 1,
  "productos_agregados": [
    {
      "codigoProducto": "PROD001",
      "nombreProducto": "Laptop 14 pulgadas",
      "precio": "1200.50",
      "tipoImpuesto": "G"
    }
  ],
  "total_productos_actualizados": 1,
  "productos_actualizados": [
    {
      "codigoProducto": "PROD002",
      "nombreProducto": "Libro de texto",
      "precio": "25.75",
      "tipoImpuesto": "E"
    }
  ]
}
ClaveDescripción
total_productos_agregadosCantidad de productos nuevos creados.
productos_agregadosProductos creados (codigoProducto, nombreProducto, precio tal como se envió y tipoImpuesto en mayúscula).
total_productos_actualizadosCantidad de productos existentes que se actualizaron.
productos_actualizadosProductos actualizados, con la misma estructura.

Errores ​

Cuando hay errores de validación, la respuesta incluye un arreglo errores con un mensaje por problema:

json
{
  "success": false,
  "message": "Se encontraron errores en la validación. No se han registrado productos.",
  "errores": [
    "Faltan los siguientes campos en el producto 2: precio",
    "Tipo de impuesto inválido en el producto 3 (código: PROD003). Los valores válidos son: E, R, G, A, P, X."
  ]
}
HTTPMensaje (ejemplo)Causa
400 / 401—Token ausente, mal formado, inválido o expirado. Ver Errores.
400El comercio indicado aún no está registrado.El negocio del token no está registrado.
400El campo productos es obligatorio y debe contener al menos un producto.Falta productos, no es un arreglo o está vacío.
400Se encontraron duplicados en la solicitud. Corrija los datos y vuelva a intentarlo.El mismo codigoProducto aparece varias veces. errores trae, por ejemplo: El producto con código PROD001 está duplicado en la solicitud (producto(s): 1, 3).
400Se encontraron errores en la validación. No se han registrado productos.Algún producto no pasó la validación. Mensajes posibles en errores:
Faltan los siguientes campos en el producto 1: codigoProducto, precioCampos obligatorios vacíos.
El campo precio debe ser un número mayor a 0 en el producto 1Precio no numérico (por ejemplo con coma) o menor o igual a 0.
El precio debe contener solo 9 (nueve) enteros y 2 (dos) decimalesPrecio con más de 9 enteros o más de 2 decimales.
Tipo de impuesto inválido en el producto 1 (código: PROD001). Los valores válidos son: E, R, G, A, P, X.tipoImpuesto no reconocido.
El tipo de impuesto X no está configurado en la base de datos.La alícuota X no está habilitada en la plataforma.
Error al registrar el producto PROD001 / Error al actualizar el producto PROD001Falló el guardado de ese producto.
500Error en el servidor: ...Error inesperado.

Notas ​

  • Todo o nada: la validación y el guardado se hacen en una transacción; ante cualquier error en errores no se registra ni actualiza ningún producto.
  • Actualización completa: al actualizar un producto existente se reemplazan su nombre, precio, alícuota y descripción con lo enviado (si omite descripcionProducto, la descripción queda vacía).
  • Campos ignorados: solo se leen los campos de la tabla anterior. Por ejemplo, una cantidad de inventario (cantidad) no se guarda.
  • No es obligatorio: Agregar factura registra automáticamente los productos que aún no existan; este endpoint sirve para cargar o corregir el catálogo por adelantado.

API de Facturación · CG Imprenta Digital