Apariencia
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
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
productos | array | Sí | Lista de productos a registrar o actualizar. Debe contener al menos uno. |
productos[]
| Campo | Tipo | Obligatorio | Descripción y reglas |
|---|---|---|---|
codigoProducto | string | Sí | 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. |
nombreProducto | string | Sí | Nombre del producto. |
precio | number | string | Sí | 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. |
tipoImpuesto | string | Sí | 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. |
descripcionProducto | string | No | Detalle 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"
}
]
}| Clave | Descripción |
|---|---|
total_productos_agregados | Cantidad de productos nuevos creados. |
productos_agregados | Productos creados (codigoProducto, nombreProducto, precio tal como se envió y tipoImpuesto en mayúscula). |
total_productos_actualizados | Cantidad de productos existentes que se actualizaron. |
productos_actualizados | Productos 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."
]
}| HTTP | Mensaje (ejemplo) | Causa |
|---|---|---|
| 400 / 401 | — | Token ausente, mal formado, inválido o expirado. Ver Errores. |
| 400 | El comercio indicado aún no está registrado. | El negocio del token no está registrado. |
| 400 | El campo productos es obligatorio y debe contener al menos un producto. | Falta productos, no es un arreglo o está vacío. |
| 400 | Se 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). |
| 400 | Se 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, precio | Campos obligatorios vacíos. | |
El campo precio debe ser un número mayor a 0 en el producto 1 | Precio no numérico (por ejemplo con coma) o menor o igual a 0. | |
El precio debe contener solo 9 (nueve) enteros y 2 (dos) decimales | Precio 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 PROD001 | Falló el guardado de ese producto. | |
| 500 | Error 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
erroresno 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.
