Crear mercadería

Registra una nueva mercadería en el sistema. Permite crear mercaderías con su configuración completa.

---

Entorno

URL Base: https://api.guarani.app

Endpoint

POST /mercaderias

Ejemplo de solicitud

curl -X POST "https://api.guarani.app/mercaderias" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "codigo_interno": "01-1234567",
    "codigo_original": "CODIGO ORIGINAL DE EJEMPLO",
    "codigo_fabricante": "CODIGO FABRICANTE DE EJEMPLO",
    "codigo_barra": "CODIGO DE BARRAS DE EJEMPLO",
    "descripcion": "DESCRIPCION DE EJEMPLO",
    "descripcion_larga": "DESCRIPCION LARGA DE EJEMPLO",
    "observacion": "OBSERVACION DE EJEMPLO",
    "imagen": "",
    "unidades": {
      "unidad_medida_compra_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
      "unidad_factor_conversion": 1,
      "unidad_medida_venta_id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab"
    },
    "mercaderia_marca_id": "ejemplo-uuid-marca-123",
    "mercaderia_clasificacion_id": "ejemplo-uuid-clasificacion-123",
    "precios": [
      {
        "precio_unitario": {
          "0":7000,
          "5":0,
          "10":3300
        },
        "moneda": "PYG",
        "establecimiento_id": "ejemplo-uuid-establecimiento-123"
      }
    ]
  }' | jq

Nota: Asegúrate de reemplazar <access_token> con un token JWT válido proporcionado por el equipo Guarani.
Importante:
Es imprescindible incluir un token de acceso válido en el encabezado x-api-key para autenticar y autorizar el uso de este endpoint. Sin este token, la solicitud será rechazada.

---

Encabezados

Encabezado	Valor	Descripción
Content-Type	application/json	Indica que los datos se envían en formato JSON.
x-api-key	Bearer <access_token>	Token de autenticación JWT del usuario

Descripción de Campos

Parámetro	Tipo	Requerido	Tamaño	Descripción
codigo_interno	string	Sí	20	Código interno de la mercaderia. Ver tabla de código interno
codigo_original	string	No	20	Código original del producto, si aplica.
codigo_fabricante	string	No	20	Código proporcionado por el fabricante del producto.
codigo_barra	string	No	45	Código de barras estándar del producto.
descripcion	string	Sí	120	Descripción corta del producto.
descripcion_larga	string	No	500	Descripción extendida o técnica.
observacion	string	No	500	Observaciones internas o de control.
imagen	string	No	-	Imagen en base64, no es requerido
unidades	objeto	Sí	-	Contiene información sobre las unidades de compra y venta.
mercaderia_marca_id	uuid	No	36	ID de la marca asociada. (ver marcas)
mercaderia_clasificacion_id	uuid	No	36	ID de la clasificación asociada. (ver clasificaciones)
precios	array	Sí	-	Array de objetos con los datos de los precios asignado a un establecimiento o mas establecimientos.

unidades (objeto)

Campo	Tipo	Requerido	Tamaño	Descripción
unidad_medida_compra_id	uuid	Sí	36	ID de la unidad de compra. (ver unidades)
unidad_factor_conversion	decimal	Sí	-	Factor de conversión entre unidad de compra y venta.
unidad_medida_venta_id	uuid	Sí	36	ID de la unidad de venta. (ver unidades)

precios (array)

Campo	Tipo	Requerido	Tamaño	Descripción
precio_unitario	objeto	Sí	-	Objeto con los precios por tipo de IVA.
moneda	string	Sí	3	Moneda del precio (por ejemplo, PYG, USD).
establecimiento_id	uuid	Sí	36	ID del establecimiento asociado. (ver establecimientos)

precio_unitario (objeto)

Campo	Tipo	Requerido	Descripción
0	number	No	Precio con IVA 0% (exento)
5	number	No	Precio con IVA 5%
10	number	No	Precio con IVA 10%

Ejemplo de respuesta

{
  "success": true,
  "codigo": "201",
  "message": "Recurso creado con éxito.",
  "data": {
    "id": "ejemplo-uuid-mercaderia-123",
    "codigo_interno": "01-1234567",
    "codigo_original": "CODIGO ORIGINAL DE EJEMPLO",
    "codigo_fabricante": "CODIGO FABRICANTE DE EJEMPLO",
    "codigo_barra": "CODIGO DE BARRAS DE EJEMPLO",
    "descripcion": "DESCRIPCION DE EJEMPLO",
    "descripcion_larga": "DESCRIPCION LARGA DE EJEMPLO",
    "observacion": "OBSERVACION DE EJEMPLO",
    "imagen_url": null,
    "unidades": {
      "unidad_medida_compra": {
        "id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "codigo_sifen": "77",
        "representacion": "UNI",
        "descripcion": "Unidad"
      },
      "factor_conversion": 1,
      "unidad_medida_venta": {
        "id": "5f49c6c1-d622-4f5b-9d8b-2d1636b584ab",
        "codigo_sifen": "77",
        "representacion": "UNI",
        "descripcion": "Unidad"
      }
    },
    "marca": {
      "id": "00000000-0000-4000-8000-000000000000",
      "nombre": "Sin definir"
    },
    "clasificacion": {
      "id": "00000000-0000-4000-8000-000000000000",
      "codigo": "99",
      "nombre": "Sin definir"
    },
    "precios": [
      {
        "precio_unitario": {
          "0": 7000,
          "5": 0,
          "10": 3300
        },
        "moneda": "PYG",
        "establecimiento_id": "ejemplo-uuid-establecimiento-123"
      }
    ]
  }
}

Descripción de Campos de Respuesta

Campos principales

Campo	Tipo	Descripción
id	uuid	Identificador único de la mercadería creada.
codigo_interno	string	Código interno de la mercadería.
codigo_original	string	Código original del proveedor o fabricante.
codigo_fabricante	string	Código asignado por el fabricante.
codigo_barra	string	Código de barras del producto.
descripcion	string	Descripción corta de la mercadería.
descripcion_larga	string	Descripción detallada de la mercadería.
observacion	string	Observaciones adicionales sobre la mercadería.
imagen_url	string	URL de la imagen del producto. Es null si no tiene imagen.
unidades	objeto	Información de unidades de medida y factor de conversión.
marca	objeto	Información de la marca de la mercadería.
clasificacion	objeto	Información de la clasificación de la mercadería.
precios	array	Lista de precios por establecimiento y moneda.

Campos de unidades

Campo	Tipo	Descripción
unidad_medida_compra	objeto	Unidad de medida para compras.
factor_conversion	number	Factor de conversión entre unidad de compra y venta.
unidad_medida_venta	objeto	Unidad de medida para ventas.

Campos de unidad de medida

Campo	Tipo	Descripción
id	uuid	Identificador único de la unidad de medida.
codigo_sifen	string	Código de la unidad según el catálogo SIFEN.
representacion	string	Representación corta de la unidad (ej: “UNI”).
descripcion	string	Descripción de la unidad de medida.

Campos de marca

Campo	Tipo	Descripción
id	uuid	Identificador único de la marca.
nombre	string	Nombre de la marca.

Campos de clasificacion

Campo	Tipo	Descripción
id	uuid	Identificador único de la clasificación.
codigo	string	Código de la clasificación.
nombre	string	Nombre de la clasificación.

Campos de precios

Campo	Tipo	Descripción
precio_unitario	objeto	Precios según tipo de IVA (0%, 5%, 10%).
moneda	string	Código de moneda (ej: “PYG”, “USD”).
establecimiento_id	uuid	ID del establecimiento donde aplica el precio.

Recursos adicionales

Para más información sobre posibles errores y cómo manejarlos, consulta errores.