Obtener una lista de las notas de crédito

Lista todas las notas de crédito registradas en el sistema. Incluye información del cliente, estado de la nota de crédito y totales calculados.

---

Entorno

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

Endpoint

GET /notas/credito

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/notas/credito?page=1&limit=100" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | 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 de la solicitud

Encabezado	Valor	Descripción
x-api-key	Bearer <access_token>	Token de autenticación necesario para acceder al recurso.
Accept	application/json	Indica que la respuesta debe devolverse en formato JSON.

Ejemplo de respuesta

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": [
    {
      "id": "ejemplo-uuid-nota-credito-123",
      "motivo_codigo": 2,
      "motivo_descripcion": "Error de emision",
      "total": 100000,
      "moneda": "PYG",
      "cotizacion": 1,
      "carrito_id": null,
      "fecha_emision": null,
      "estado_nota_credito": 1,
      "numero_documento": null,
      "tipo_origen": 1,
      "cliente": {
        "id": "ejemplo-uuid-cliente-123",
        "tipo_persona": 1,
        "tipo_documento": 1,
        "documento": "1234567890",
        "nombre": "CLIENTE EJEMPLO",
        "nombre_fantasia": "CLIENTE EJEMPLO",
        "nacionalidad": "PRY",
        "fecha_nacimiento": "01/01/1990",
        "whatsapp": "+595981234567",
        "email": "[email protected]",
        "numero_casa": "0",
        "direccion": "Dirección de ejemplo",
        "barrio": "Barrio de ejemplo",
        "ciudad": {
          "id": "67ef2e9f-0fa7-43e7-ad5e-87a694e56341",
          "codigo_sifen": "3556",
          "nombre": "SANTA RITA",
          "distrito": {
            "id": "78d49201-91f9-4e6c-aadb-4927f56767c0",
            "codigo_sifen": "209",
            "nombre": "SANTA RITA",
            "departamento": {
              "id": "750d3163-6a53-45df-b349-e8139d1ff3a9",
              "codigo_sifen": "11",
              "nombre": "ALTO PARANA"
            }
          }
        }
      },
      "documentos_asociados_electronicos": {
        "cdc": "01234567890123456789012345678901234567890123"
      },
      "documentos_asociados_manuales": null,
      "items": [
        {
          "id": "b4bff0a5-ccdd-4d1a-8a23-48a0a1b608a7",
          "mercaderia": {
            "id": "ea8dfd67-d075-4a34-a5e2-743e8092a8b8",
            "codigo_original": "672",
            "codigo_fabricante": "",
            "codigo_interno": "01-0000672",
            "codigo_barra": "",
            "descripcion": "EMISOR GROOVE MIKROTIK 52HPN (L3)",
            "descripcion_larga": "",
            "observacion": "",
            "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": 0
                },
                "moneda": "USD",
                "establecimiento_id": "06dabe45-cbb5-425e-b1c3-13a67d7114e0"
              }
            ]
          },
          "servicio": null,
          "precio_unitario": 100000,
          "precio_unitario_original": 100000,
          "total": 100000,
          "cantidad": 1,
          "iva": {
            "iva_tipo": 10,
            "monto": 2727.2727275,
            "afectacion": 28.03738318
          }
        }
      ]
    }
  ],
  "pagination": {
    "total_registros": 128,
    "pagina": 1,
    "total_paginas": 128
  }
}

Descripción de campos de respuesta

Campos Principales

Campo	Tipo	Descripción
id	uuid	Identificador único de la nota de crédito.
motivo_descripcion	string	Descripción literal del motivo asignado al código anterior.
total	number	Monto total de la nota de crédito en la moneda especificada, incluyendo todos los items e impuestos.
moneda	string	Código de moneda en formato ISO 4217 (ej: PYG, USD, BRL, ARS).
cotizacion	number	Cotización de la moneda respecto a Guaraníes.
fecha_emision	string	Fecha y hora de emisión de la nota de crédito. Es null hasta que la nota de crédito se finalice.
estado_nota_credito	number	Estado actual de la nota de crédito. (ver tablas-referencias)
numero_documento	string	Número del documento de la nota de crédito. Es null hasta que la nota de crédito se finalice.
tipo_origen	number	Tipo de origen de la nota de crédito.
cliente	object	Objeto con la información completa del cliente asociado a la nota de crédito.
documentos_asociados_electronicos	object	Documento electrónico asociado (si aplica). Es null si no hay documento electrónico asociado.
documentos_asociados_manuales	object	Documento manual asociado (si aplica). Es null si no hay documento manual asociado.
items	array	Lista de productos/servicios agregados a la nota de crédito con todos sus detalles.

Campos del Cliente

Campo	Tipo	Descripción
id	uuid	Identificador único del cliente.
tipo_persona	number	Tipo de persona. 1 = Persona Física, 2 = Persona Jurídica.
tipo_documento	number	Tipo de documento de identidad. 1 = Cédula, 2 = Pasaporte, 3 = RUC, etc.
documento	string	Número del documento de identidad del cliente.
nombre	string	Nombre completo del cliente (razón social para personas jurídicas).
nombre_fantasia	string	Nombre comercial o fantasía del cliente.
nacionalidad	string	Código de nacionalidad en formato ISO 3166-1 alpha-3 (ej: PRY, ARG, BRA).
fecha_nacimiento	string	Fecha de nacimiento del cliente en formato YYYY-MM-DD.
whatsapp	string	Número de WhatsApp del cliente en formato internacional.
email	string	Dirección de correo electrónico del cliente.
numero_casa	string	Número de casa o edificio de la dirección del cliente.
direccion	string	Dirección completa del cliente.
barrio	string	Nombre del barrio donde reside el cliente.
ciudad	object	Objeto con información de la ciudad del cliente.

Campos de Ciudad

Campo	Tipo	Descripción
id	uuid	Identificador único de la ciudad.
codigo_sifen	string	Código de la ciudad según el catálogo SIFEN.
nombre	string	Nombre de la ciudad.
distrito	object	Objeto con información del distrito al que pertenece la ciudad.
departamento	object	Objeto con información del departamento al que pertenece la ciudad.

Campos de Distrito

Campo	Tipo	Descripción
id	uuid	Identificador único del distrito.
nombre	string	Nombre del distrito.
codigo_sifen	string	Código del distrito según el catálogo SIFEN.

Campos de Departamento

Campo	Tipo	Descripción
id	uuid	Identificador único del departamento.
nombre	string	Nombre del departamento.
codigo_sifen	string	Código del departamento según el catálogo SIFEN.

Campos de Items

Campo	Tipo	Descripción
id	uuid	Identificador único del item en la nota de crédito.
mercaderia	object	Objeto con información de la mercadería. Es null si el item es un servicio.
servicio	object	Objeto con información del servicio. Es null si el item es una mercadería.
precio_unitario	number	Precio unitario final del item en la moneda de la nota de crédito (puede incluir ajustes o descuentos).
precio_unitario_original	number	Precio unitario original del item sin ajustes.
total	number	Monto total de la línea (precio unitario × cantidad) en la moneda de la nota de crédito.
cantidad	number	Cantidad de unidades del producto o servicio.
iva	object	Objeto con información del IVA aplicado al item.

Campos de Mercadería

Campo	Tipo	Descripción
id	uuid	Identificador único de la mercadería.
codigo_interno	string	Código interno generado por el sistema para identificación única.
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 (EAN/UPC) 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.
factor_conversion	number	Factor de conversión entre unidad de compra y venta.
unidad_medida_compra_id	uuid	ID de la unidad de medida para compras (ver unidades-medidas).
unidad_medida_venta_id	uuid	ID de la unidad de medida para ventas (ver unidades-medidas).
mercaderia_marca_id	uuid	ID de la marca de la mercadería.
mercaderia_clasificacion_id	uuid	ID de la clasificación de la mercadería.
imagen_url	string	URL de la imagen del producto. Es null si no tiene imagen.

Campos de Servicio

Campo	Tipo	Descripción
id	uuid	Identificador único del servicio.
codigo_interno	string	Código interno generado por el sistema para identificación única.
descripcion	string	Descripción corta del servicio.
descripcion_larga	string	Descripción detallada del servicio.
observacion	string	Observaciones adicionales sobre el servicio.
unidad_medida_id	uuid	ID de la unidad de medida del servicio (ver unidades-medidas).
servicio_clasificacion_id	uuid	ID de la clasificación del servicio.
imagen_url	string	URL de la imagen del servicio. Es null si no tiene imagen.

Campos de IVA

Campo	Tipo	Descripción
iva_tipo	number	Tipo de IVA aplicado. 5 = 5%, 10 = 10%, 0 = Exento.
importe_gravado	number	Importe gravado por el IVA.
monto	number	Monto del IVA en la moneda de la nota de crédito.
afectacion	number	Porcentaje de afectación del IVA sobre el precio base (usado para cálculos de facturación).

Campos de Paginación

Campo	Tipo	Descripción
total_registros	number	Cantidad total de notas de crédito encontradas en la base de datos.
pagina	number	Número de la página actual.
total_paginas	number	Cantidad total de páginas disponibles según el límite solicitado.

Recursos adicionales

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