**Funcionalidad en desarrollo y pruebas:** este servicio está disponible en el ambiente de pruebas y todavía no debe usarse en producción. El funcionamiento, los campos y los mensajes de error pueden cambiar antes del despliegue definitivo.
Este servicio devuelve una **lista paginada de notas de crédito y débito** registradas en nuby, con sus datos principales. Puedes filtrar por factura, por tipo de nota y por rango de fechas.
Úsalo para conciliar las notas de una factura con tu plataforma, para construir un historial de ajustes o para verificar qué notas se crearon en un período.
**¿Para qué sirve este servicio?**
Úsalo cuando necesites **recorrer las notas registradas en nuby**. Los casos de uso más frecuentes son:
- **Conciliar las notas de una factura** con tu plataforma, filtrando por `factura_id`.
- **Construir un historial de ajustes** separando las notas de crédito de las de débito con `tipo`.
- **Cerrar un período contable** revisando las notas creadas entre dos fechas con `desde` y `hasta`.
- **Recorrer resultados largos por páginas** con `page` y `page_size`.
- **Obtener el `nota_id`** para consultar el detalle solo de las notas que vas a mostrar.
---
**Importante:** no incluyas `https://` ni barras diagonales (`/`) al final. La dirección se compone así: `https://` + tu instancia + `/service/v2/public/notes/list`.
##### **Encabezados requeridos**
**Importante:** `page`, `page_size` y `factura_id` deben ser enteros positivos; `desde` no puede ser mayor que `hasta`. Un valor inválido produce `400`.
**Los filtros se combinan.** Si envías `factura_id` y `tipo`, deben cumplirse ambos.
##### **Ejemplos de dirección**
```http
GET /notes/list?factura_id=456
GET /notes/list?tipo=credito&desde=2026-10-01&hasta=2026-10-31
GET /notes/list?page=2&page_size=20
```
##### **Validaciones de parámetros**
Los parámetros se validan antes de ejecutar la consulta. Si uno no cumple su regla, la respuesta es `400 VALIDATION_ERROR` y no se devuelve ningún dato:
- Sin filtros, `filters_applied` es `null`.
- Con filtros, es un objeto con los filtros usados.
- Con resultados, `message` es `null`.
- Sin resultados, `message` es `No se encontraron notas con los filtros aplicados.` y `body` es `[]`.
**Una lista vacía no es un error.** Se responde `200`; revisa `pagination.total` para confirmar que no hay coincidencias.
##### **Cómo interpretar el resultado**
**Orden:** las notas se devuelven por fecha descendente y, a igualdad de fecha, por identificador descendente. El orden es estable entre páginas.
- El listado **nunca** incluye notas de facturas de contrato, aunque no envíes `factura_id`.
- Si filtras por una factura de contrato, la respuesta es `409 FACTURA_CONTRATO_NO_SOPORTADA` con `warnings[]`.
**Atención:** una factura de contrato no es un error de parámetro: el servicio la rechaza explícitamente para no exponer notas de ese flujo.
cURL
```bash
TOKEN="TU_TOKEN_AQUI"
INSTANCIA="tu-inmobiliaria.nuby.app"
# Notas de una factura
curl -G "https://${INSTANCIA}/service/v2/public/notes/list" \
--data-urlencode "factura_id=456" \
-H "Authorization: Bearer ${TOKEN}"
# Notas de crédito de octubre, página 1 de 20
curl -G "https://${INSTANCIA}/service/v2/public/notes/list" \
--data-urlencode "tipo=credito" \
--data-urlencode "desde=2026-10-01" \
--data-urlencode "hasta=2026-10-31" \
--data-urlencode "page=1" \
--data-urlencode "page_size=20" \
-H "Authorization: Bearer ${TOKEN}"
```
PHP
```php
456,
'page' => 1,
'page_size' => 50,
]);
$url = "https://{$instancia}/service/v2/public/notes/list?{$query}";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer {$token}",
]);
$respuesta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$datos = json_decode($respuesta, true);
echo "HTTP: {$codigo}\n";
echo "Total: " . ($datos['pagination']['total'] ?? 0) . "\n";
foreach ($datos['body'] as $nota) {
echo $nota['nota_id'] . ' - ' . $nota['tipo'] . ' - ' . $nota['valor_total'] . "\n";
}
```
Python
```python
import requests
instancia = "tu-inmobiliaria.nuby.app"
token = "TU_TOKEN_AQUI"
url = f"https://{instancia}/service/v2/public/notes/list"
headers = {
"Authorization": f"Bearer {token}",
}
pagina = 1
total_paginas = 1
while pagina <= total_paginas:
respuesta = requests.get(
url,
headers=headers,
params={"tipo": "credito", "desde": "2026-10-01", "hasta": "2026-10-31",
"page": pagina, "page_size": 50},
timeout=30,
)
if respuesta.status_code != 200:
print(respuesta.status_code, respuesta.json())
break
datos = respuesta.json()
total_paginas = datos["pagination"]["total_pages"]
for nota in datos["body"]:
print(nota["nota_id"], nota["tipo"], nota["valor_total"])
pagina += 1
```
JavaScript (Fetch API)
```javascript
const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';
const params = new URLSearchParams({
factura_id: '456',
page: '1',
page_size: '50'
});
const url = `https://${instancia}/service/v2/public/notes/list?${params}`;
const respuesta = await fetch(url, {
headers: { 'Authorization': `Bearer ${token}` }
});
const data = await respuesta.json();
if (respuesta.ok) {
console.log(`Página ${data.pagination.page} de ${data.pagination.total_pages}`);
data.body.forEach(n => console.log(n.nota_id, n.tipo, n.valor_total));
} else {
console.error(`${respuesta.status} ${data.error_code}: ${data.message}`);
}
```
Power Query M (Excel / Power BI)
Power Query consulta una página por vez. El paso `pagination` te permite parametrizar la página y combinar varias con `Table.Combine` si necesitas el historial completo.
```m
let
// 1. Configura tus datos de acceso
instancia = "tu-inmobiliaria.nuby.app",
token = "TU_TOKEN_AQUI",
// 2. Prepara la dirección con los filtros y la página
url = "https://" & instancia & "/service/v2/public/notes/list?factura_id=456&page=1&page_size=1000",
// 3. Envía la petición GET
response = Web.Contents(url, [
Headers = [
#"Authorization" = "Bearer " & token
]
]),
// 4. Decodifica el envelope
jsonResponse = Json.Document(response),
body = jsonResponse[body],
pagination = jsonResponse[pagination],
// 5. Convierte el listado en tabla
tabla = Table.FromList(body, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
expandido = Table.ExpandRecordColumn(tabla, "Column1",
{"nota_id", "factura_id", "tipo", "consecutivo", "fecha", "valor_total",
"estado_id", "clasificacion", "concepto_id", "observaciones"},
{"NotaID", "FacturaID", "Tipo", "Consecutivo", "Fecha", "ValorTotal",
"EstadoID", "Clasificacion", "ConceptoID", "Observaciones"}),
tipos = Table.TransformColumnTypes(expandido, {
{"NotaID", Int64.Type},
{"FacturaID", Int64.Type},
{"Consecutivo", Int64.Type},
{"Fecha", type date},
{"ValorTotal", type number}
}),
totalPaginas = pagination[total_pages]
in
tipos
```
- **Filtra por `factura_id`** cuando busques las notas de un documento concreto.
- **Usa `desde` y `hasta` en lugar de paginar meses completos.**
- **Recorre hasta `total_pages`**, no hasta una página vacía.
- **No uses la lista como detalle:** los ítems y el saldo de la factura están en la página [*Buscar Nota por Código*](https://docs.nuby.ai/books/api-nuby-v2/page/buscar-nota-por-codigo).
- **Guarda el `nota_id`** para evitar búsquedas repetidas.
- Solo expone notas de **facturas de venta**; las de contrato nunca aparecen.
- No devuelve los ítems ni el saldo de la factura: eso está en el detalle de la nota.
- El estado corresponde al que tiene la nota en nuby; las creadas por la API están en borrador.