Crear
Crea un producto con su categoría y sus impuestos.
Descripción general
Este endpoint crea un producto en tu organización. El único campo obligatorio es name; los demás son opcionales. Los campos siguen las mismas reglas que el formulario de productos de la aplicación. Una solicitud exitosa devuelve 201 con el producto creado, con la misma forma que Consultar producto.
Los impuestos se envían como porcentaje: "16" es 16 %. Acepta el header Idempotency-Key para reintentar sin duplicar el producto.
Requiere el permiso Crear en Productos.
Endpoint
https://app.credonix.mx/api/v1/productsSolicitud mínima
Envía name y, si quieres, unit_price. Sin category_id ni taxes, el producto se crea con category: null y taxes: []. Los campos de texto que no envías llegan en null.
{
"name": "Timbre fiscal adicional",
"unit_price": "99.5"
}Con categoría e impuestos
category_id debe ser el id de una categoría de tu organización; la respuesta incluye la categoría con su nombre. unit_price se envía como texto y la API quita las comas: "1,234.50" se guarda como "1234.5". Cada impuesto lleva type, category y percentage.
{
"name": "Servicio de facturación",
"unit_price": "1,234.50",
"code": "84111506",
"category_id": "cmu218zcd001wv1dqsvl2rdq5",
"taxes": [
{ "type": "iva", "category": "transferred", "percentage": "16" }
]
}Reglas de los campos
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
name | string | Sí | Nombre del producto/servicio. No puede estar vacío. |
description | string | null | No | Texto libre. |
unit_price | string | null | No | Precio unitario. Solo se acepta como texto; un número JSON responde 400. Se quitan las comas y debe ser un número mayor o igual a 0. |
code | string | null | No | Código producto y/o servicio. Texto libre. |
unit_code | string | null | No | Unidad de medida. Texto libre. |
tariff_code | string | null | No | Código de tarifa. Texto libre. |
customs_unit | string | null | No | Unidad de medida aduanera. Texto libre. |
category_id | string | null | No | id de una categoría de tu organización. null o "" crea el producto sin categoría. |
taxes | array | No | Impuestos del producto. Ver abajo. |
No se aceptan otros campos: cualquier campo desconocido, incluido note, responde 400 con VALIDATION_ERROR.
taxes[]
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
type | string | Sí | iva, isr o ieps. |
category | string | Sí | transferred (trasladado), withheld (retenido) o exempt (exento). IVA acepta los tres; ISR solo withheld; IEPS acepta transferred o withheld. |
percentage | string | Sí | Porcentaje en puntos porcentuales: "16" es 16 %. Debe ser numérico y mayor o igual a 0. |
Errores
| Status | Código | Causa |
|---|---|---|
400 | VALIDATION_ERROR | Un campo no cumple sus reglas. errors indica el campo y el motivo. |
400 | CATEGORY_NOT_FOUND | category_id no es una categoría de tu organización. |
401 | MISSING_API_KEY, INVALID_API_KEY, API_KEY_REVOKED | API key ausente, inválida o revocada. |
403 | INSUFFICIENT_PERMISSIONS | La API key no tiene el permiso Crear en Productos. |
400 — precio enviado como número
{
"code": "VALIDATION_ERROR",
"message": "La petición contiene datos inválidos. Revisa errors para ver el detalle de cada campo.",
"errors": [
{
"field": "unit_price",
"code": "invalid_type",
"message": "Entrada inválida: se esperaba texto, recibido número"
}
],
"request_id": "e0c8bd79-59a1-47b5-b9e8-169deb451936"
}400 — aplicación de impuesto no permitida
Con { "type": "isr", "category": "transferred", "percentage": "10" } en taxes, el error indica la posición del impuesto en field:
{
"code": "VALIDATION_ERROR",
"message": "La petición contiene datos inválidos. Revisa errors para ver el detalle de cada campo.",
"errors": [
{
"field": "taxes.0.category",
"code": "custom",
"message": "ISR solo puede ser retenido"
}
],
"request_id": "aec16b77-e603-4334-a697-a49d4d3261e4"
}400 — categoría no encontrada
{
"code": "CATEGORY_NOT_FOUND",
"message": "La categoría no pertenece a tu organización.",
"errors": [
{
"field": "category_id",
"code": "not_found",
"message": "La categoría no pertenece a tu organización."
}
],
"request_id": "4b856461-7ec9-4b32-9d42-dd08a5fc3425"
}