--- title: "Listar notas de crédito de venta" method: POST path: "/tools/creditNotes_listCreditNotes" tags: ["Sales Documents"] --- # Listar notas de crédito de venta `POST /tools/creditNotes_listCreditNotes` ## Request - Base URL: `https://mcp.alegra.com` - URL: `https://mcp.alegra.com/tools/creditNotes_listCreditNotes` - Auth: HTTP bearer Herramienta MCP: `creditNotes_listCreditNotes`. Lista notas de crédito de venta: los documentos que reducen lo que un cliente debe sobre facturas de venta ya emitidas (devoluciones, anulaciones, descuentos y bonificaciones) y que, cuando se emiten electrónicamente, se timbran ante la autoridad fiscal de cada país. Úsala para encontrar notas cuando no conoces sus IDs, o para reportar por cliente, período, numeración, ítem o estado de emisión electrónica. No lista facturas de venta: una nota de crédito es un documento aparte que apunta a las facturas que acredita a través de su arreglo `invoices`; para las facturas usa las herramientas de facturas de venta. Para consultar una sola nota por ID, usa `creditNotes_getCreditNote`. La respuesta es siempre un objeto: `data` contiene las notas encontradas y `returnedByApi`, `discardedByClientFilter` y `note` reportan el filtrado, porque los filtros de período (`dateFrom`/`dateTo`) y de estado (`status`) los aplica esta herramienta y no la API — lee `note` antes de concluir que un período no tiene notas de crédito. `apiTotal` siempre indica cuántas notas de crédito tiene la empresa en total. Por defecto cada registro es una versión ligera (IDs, fechas, estado, numeración, cliente, facturas acreditadas y montos); con `detail: true` se incluye el payload completo (ítems, impuestos, reembolsos, bodega, direcciones, etc.). Reglas de filtrado y paginación: `date` es el único filtro de fecha que aplica la propia API. El filtro `id` acepta hasta 30 IDs separados por comas (sin espacios) y, cuando se envía, la API ignora todos los demás filtros: no lo combines con `client_id`, `date` ni `number`. `limit` está limitado a 30 (máximo y valor por defecto de la API; valores mayores se rechazan); cuando se usan `dateFrom`, `dateTo` o `status`, ese límite restringe los registros escaneados, por lo que pueden coincidir menos. Avanza con `start` hasta que la API devuelva menos registros que `limit`. Para conjuntos grandes (más de ~120 registros) o descargas de rangos completos de fechas, usa la herramienta exportable en lugar de paginar. Notas por país: en México la nota se convierte en un CFDI de egreso y `emission_status` refleja el timbrado ante el SAT (incluye `STAMPED_AND_CANCELLED`). En Colombia la validación electrónica es de la DIAN y su catálogo incluye `STAMPED_AND_ACCEPTED_WITH_OBSERVATIONS`. En Costa Rica el timbrado es ante Hacienda (incluye `STAMPED_AND_WAITING_RESPONSE`). En Panamá la validación es de la DGI, cuyo catálogo de estados no incluye estado de cancelación. El enum de `emission_status` documentado es la unión de los catálogos por país; usa los valores del catálogo de tu país. Solo lectura. ## Request body - object - `attachment` boolean: Si es true, cada nota de crédito incluye un objeto `attachment` con los archivos adjuntos. Por defecto false; déjalo desactivado salvo que el usuario pregunte por adjuntos, porque agranda la respuesta. - `client_id` string: Filtra por el ID de Alegra del cliente (contacto) al que se emitió la nota, por ejemplo "21". Es el ID interno del contacto, no el RFC/NIT/RUC. Es el parámetro a usar cuando el usuario pide las notas de crédito de un cliente. - `client_name` string: Filtra por nombre del cliente, coincidencia parcial (por ejemplo "Comercial" encuentra "Comercial del Norte S.A."). Usa `client_id` cuando conozcas el ID exacto del contacto. - `date` string: Filtra por fecha de emisión EXACTA en formato YYYY-MM-DD. Es el único filtro de fecha que la propia API aplica. Para un período usa `dateFrom`/`dateTo`, y no los combines con este parámetro. - `dateFrom` string: Inicio del período a reportar, INCLUSIVO, en formato YYYY-MM-DD. La API no tiene filtro de rango de fechas: este filtro lo aplica la herramienta sobre las notas de la página actual — los registros fuera del período se descartan y se cuentan en `discardedByClientFilter`. Avanza con `start` hasta que la API devuelva menos registros que `limit`. Puede usarse solo (sin límite superior) o junto con `dateTo`. - `dateTo` string: Fin del período a reportar, INCLUSIVO, en formato YYYY-MM-DD. Debe ser mayor o igual a `dateFrom` cuando se envían ambos. Igual que `dateFrom`, lo aplica la herramienta y no la API (véase `dateFrom`). Puede usarse solo (sin límite inferior). - `detail` boolean: Con false (por defecto) cada nota vuelve como versión ligera (IDs, fechas, estado, numeración, cliente, facturas acreditadas y montos). Ponlo en true para incluir el payload completo (ítems, impuestos, reembolsos, bodega, direcciones, etc.), solo cuando el usuario pide ese detalle. - `emission_status` 'PENDING' | 'STAMPED_AND_WAITING_RESPONSE' | 'STAMPED_AND_ACCEPTED' | 'STAMPED_AND_REJECTED' | 'STAMPED_AND_CANCELLED' | 'STAMPED_AND_ACCEPTED_WITH_OBSERVATIONS': Filtra por el estado de emisión electrónica de la nota ante la autoridad fiscal. Enum en unión de los catálogos por país: México usa `PENDING`, `STAMPED_AND_ACCEPTED`, `STAMPED_AND_REJECTED` y `STAMPED_AND_CANCELLED` (ante el SAT); Colombia `PENDING`, `STAMPED_AND_WAITING_RESPONSE`, `STAMPED_AND_ACCEPTED`, `STAMPED_AND_REJECTED` y `STAMPED_AND_ACCEPTED_WITH_OBSERVATIONS` (ante la DIAN); Costa Rica los mismos cinco que Colombia (ante Hacienda); Panamá `PENDING`, `STAMPED_AND_WAITING_RESPONSE`, `STAMPED_AND_ACCEPTED` y `STAMPED_AND_REJECTED` (ante la DGI, sin estado de cancelación). Es el estado FISCAL, independiente del estado de Alegra (`status`). Omitido, incluye notas de cualquier estado de emisión. - `id` string: Lista separada por comas de IDs concretos de notas a recuperar, sin espacios (por ejemplo "1,2,10"), máximo 30. ATENCIÓN: cuando se envía, la API ignora todos los demás filtros, así que no lo combines con `client_id`, `date` ni `number`. - `item_id` string: Filtra las notas que incluyen este ID de producto/servicio entre sus ítems, por ejemplo "2". - `limit` integer: Número de notas por petición. Máximo 30, que también es el valor por defecto de la API (valores mayores se rechazan). Cuando se usan `dateFrom`, `dateTo` o `status`, este límite restringe los registros ESCANEADOS, por lo que pueden coincidir menos. - `number` string: Filtra por la numeración impresa de la nota; puede darse el prefijo y/o el número (por ejemplo "NC-12" o "12"). - `start` integer: Desplazamiento basado en cero del primer registro a devolver (0 para la primera página, 30 para la segunda). Es una posición en el conjunto de resultados, no un ID de nota. Omítelo para empezar desde el principio. - `status` string: Filtra por el estado de Alegra de la nota, comparado sin distinguir mayúsculas. Estados: "open" (queda saldo por aplicar), "closed" (totalmente aplicada o reembolsada), "void" (anulada) y "draft" (borrador). Separa por comas para combinar, por ejemplo "open,closed". Es el estado CONTABLE del documento; para el estado fiscal usa `emission_status`. La API no tiene filtro de estado para notas de crédito: lo aplica la herramienta sobre los registros de la página actual (véase `dateFrom`). Omitido, incluye todos los estados. ## Response `200` Notas de crédito de venta que coinciden con los filtros ## Other responses - `401`: No autorizado --- [API](https://skmtc.dev/alegra/apis/mcp-alegra.md) - [All operations](https://skmtc.dev/alegra/apis/mcp-alegra/llms.txt) - [OpenAPI document](https://skmtc.dev/alegra/apis/mcp-alegra/revisions/528447af020b?raw)