Agregar item a nota de crédito

Agrega una nueva mercadería o servicio a la nota de crédito. Permite incluir mercaderías o servicios con sus respectivos precios y cantidades.

---

Entorno

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

Endpoint

POST /notas/credito/{id}/items

Ejemplo de solicitud HTTP (cURL)

# USD
curl -X POST "https://api.guarani.app/notas/credito/{id}/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "mercaderia_id": "ejemplo-uuid-mercaderia-123",
    "precio_unitario": {
      "0": 9.59,
      "5": 0,
      "10": 4.10
    },
    "precio_unitario_original": 13.69,
    "cantidad": 1,
  }' | jq

# PYG
curl -X POST "https://api.guarani.app/notas/credito/{id}/items" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Bearer <access_token>" \
  -d '{
    "mercaderia_id": "ejemplo-uuid-mercaderia-123",
    "precio_unitario": {
      "0": 70000,
      "5": 0,
      "10": 30000
    },
    "precio_unitario_original": 100000,
    "cantidad": 1,
  }' | jq

Nota: Se envía mercaderia_id o servicio_id, pero no ambos. Nota: Asegúrate de reemplazar {id} con el ID de la nota de crédito y <access_token> con un token JWT válido proporcionado por el equipo Guaraní.
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.

---

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
id	uuid	Sí	ID de la nota de crédito a la que se desea agregar el item. (ver notas de crédito)

Encabezados de la Solicitud

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 necesario para acceder al recurso.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Tamaño	Descripción
mercaderia_id	uuid	Condicional	36	ID de la mercadería, si el ítem corresponde a un producto. Se debe enviar mercaderia_id o servicio_id, pero no ambos. (ver mercaderias)
servicio_id	uuid	Condicional	36	ID del servicio, si el ítem corresponde a un servicio. Se debe enviar mercaderia_id o servicio_id, pero no ambos. (ver servicios)
precio_unitario	objeto	Sí	-	Precio por unidad del producto o servicio discriminado por tipo de IVA.
precio_unitario_original	number	No	-	Precio original del producto o servicio. Si no se envía, se usa el precio calculado del objeto precio_unitario.
cantidad	number	Sí	-	Cantidad de unidades del producto o servicio. Debe ser mayor a 0.

precio_unitario (objeto)

Campo	Tipo	Requerido	Tamaño	Descripción
0	number	No	-	Precio con IVA 0%
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-item-123",
    "mercaderia": {
      "id": "ejemplo-uuid-mercaderia-123",
      "codigo_original": "CODIGO ORIGINAL DE EJEMPLO",
      "codigo_fabricante": "CODIGO FABRICANTE DE EJEMPLO",
      "codigo_interno": "01-1234567",
      "codigo_barra": "CODIGO DE BARRAS DE EJEMPLO",
      "descripcion": "DESCRIPCION DE EJEMPLO",
      "descripcion_larga": "DESCRIPCION LARGA DE EJEMPLO",
      "observacion": "OBSERVACION DE EJEMPLO",
      "mercaderia_clasificacion_id": "ejemplo-uuid-clasificacion-mercaderia-123",
      "mercaderia_marca_id": "ejemplo-uuid-marca-123",
      "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"
        }
      },
      "precios": [
        {
          "precio_unitario": {
            "0": 0,
            "5": 0,
            "10": 100000
          },
          "moneda": "PYG",
          "establecimiento_id": "ejemplo-uuid-establecimiento-123"
        }
      ]
    },
    "servicio": null,
    "precio_unitario": 100000,
    "precio_unitario_original": 100000,
    "total": 100000,
    "cantidad": 1,
    "iva": {
      "iva_tipo": 10,
      "importe_gravado": 30000,
      "monto": 10000,
      "afectacion": 100
    }
  }
}

Descripción de Campos de Respuesta

Campos principales

Campo	Tipo	Descripción
id	uuid	UUID único del item creado en la nota de crédito.
mercaderia	objeto	Información completa de la mercadería (null si es servicio).
servicio	objeto	Información completa del servicio (null si es mercadería).
precio_unitario	number	Precio final por unidad aplicado.
precio_unitario_original	number	Precio original por unidad antes de descuentos o ajustes.
total	number	Monto total del item (precio_unitario × cantidad).
cantidad	number	Cantidad de unidades del producto o servicio.
iva	objeto	Información del cálculo del IVA aplicado.

Campos de mercaderia (objeto)

Campo	Tipo	Descripción
id	uuid	UUID de la mercadería.
codigo_original	string	Código original del fabricante o proveedor.
codigo_fabricante	string	Código del fabricante.
codigo_interno	string	Código interno de la mercadería.
codigo_barra	string	Código de barras del producto.
descripcion	string	Nombre o descripción corta de la mercadería.
descripcion_larga	string	Descripción extendida de la mercadería.
observacion	string	Observaciones o notas adicionales.
mercaderia_clasificacion_id	uuid	UUID de la clasificación o categoría de la mercadería.
mercaderia_marca_id	uuid	UUID de la marca de la mercadería.
imagen_url	string	URL de la imagen del producto (null si no tiene imagen).
unidades	objeto	Objeto con información de unidades de medida.
precios	array	Array con información de precios por establecimiento.

Campos del objeto unidades

Campo	Tipo	Descripción
unidad_medida_compra	object	Objeto con información de la unidad de medida de compra (null si no tiene).
factor_conversion	number	Factor de conversión entre unidad de compra y venta (ej: 1 caja = 12 unidades).
unidad_medida_venta	object	Objeto con información de la unidad de medida de venta (null si no tiene).

Campos de unidad_medida_compra y unidad_medida_venta

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 del array precios

Campo	Tipo	Descripción
precio_unitario	object	Objeto con precios discriminados por tipo de IVA (0, 5, 10).
moneda	string	Código de moneda ISO 4217.
establecimiento_id	uuid	Identificador del establecimiento al que pertenece el precio.

Campos de iva (objeto)

Campo	Tipo	Descripción
iva_tipo	number	Tipo de IVA aplicado: 0%, 5% o 10%.
importe_gravado	number	Importe gravado por el IVA.
monto	number	Monto del IVA calculado en la moneda correspondiente.
afectacion	number	Porcentaje de afectación del IVA sobre el precio total.

Recursos adicionales

Para más información sobre posibles errores de notas de crédito, consulta las siguientes secciones: errores.