Buscar Nota por Código [BETA]

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 el detalle completo de una nota de crédito o débito a partir de su identificador interno en nuby (nota_id): cabecera, ítems con sus impuestos y retenciones, y el estado y saldo actuales de la factura anotada.

Úsalo después de crear una nota, o cuando ya guardaste su nota_id y necesitas verificarla sin recorrer el listado.

¿Para qué sirve este servicio?
Úsalo cuando necesites ver el detalle de una nota sin recorrer el listado. Los casos de uso más frecuentes son:

1. El Endpoint (La dirección web)

Método y dirección

GET https://{{instancia}}/service/v2/public/notes/{nota_id}

¿Qué debo colocar en {{instancia}}?

La dirección web principal con la que ingresas a tu plataforma, incluyendo la terminación .nuby.app o .arrendasoft.co.

Importante: no incluyas https:// ni barras diagonales (/) al final. La dirección se compone así: https:// + tu instancia + /service/v2/public/notes/ + el identificador de la nota.

Encabezados requeridos

Permiso requerido (scope): catalogs:read

Este servicio es de solo lectura y exige el permiso catalogs:read. Si falta, la respuesta es 403 con RECURSO_NO_AUTORIZADO.

Si aún no tienes un token, consulta la página Login del libro API nuby V2.

2. La Petición (¿Qué debes enviarnos?)

Este servicio no requiere cuerpo. Solo necesitas el encabezado de autorización y el identificador de la nota en la dirección.

Parámetros de la ruta (path)

¿De dónde saco el nota_id?

Ejemplos de petición

GET https://tu-inmobiliaria.nuby.app/service/v2/public/notes/789

3. La Respuesta (¿Qué te entregaremos?)

Si la nota existe y pertenece a una factura de venta, el sistema devuelve el envelope y el cuerpo con el detalle de la nota:

{
  "status": 200,
  "message": null,
  "body": {
    "nota_id": 789,
    "factura_id": 456,
    "tipo": "credito",
    "consecutivo": 1024,
    "fecha": "2026-10-21",
    "resolucion_id": 3,
    "valor_total": 59500,
    "estado_id": 5,
    "moneda": "COP",
    "tasa_cambio": 1,
    "observaciones": "Ajuste acordado",
    "clasificacion": 1,
    "tercero_id": 123,
    "concepto_id": 6,
    "items": [
      {
        "producto_id": 159,
        "descripcion": "Ajuste plan X",
        "cantidad": 1,
        "valor_unitario": 50000,
        "por_iva": 19,
        "iva": 9500,
        "por_retencion": 0,
        "retencion": 0,
        "por_reteiva": 0,
        "reteiva": 0,
        "por_reteica": 0,
        "reteica": 0,
        "por_descuento": 0,
        "descuento": 0
      }
    ],
    "factura_estado_id": 1,
    "factura_saldo": 150000
  },
  "pagination": null,
  "filters_applied": null
}

Nota sobre el envelope: es una consulta de un solo registro, así que pagination y filters_applied siempre vienen en null.

Cabecera de la nota

Campos de cada ítem

Cada ítem trae la base y los porcentajes junto con los montos ya calculados por nuby:

Cómo se compone el valor total

El total del ítem suma la base y el IVA, y resta la retención, el reteIVA, el reteICA y el descuento. El valor_total de la nota es la suma de los totales de sus ítems, en la moneda original y con redondeo a dos decimales.

Estado y saldo de la factura

factura_estado_id indica el estado actual de la factura (1 activa, 6 anulada por nota crédito) y factura_saldo su saldo después de las notas.

Variantes de respuesta

El mismo endpoint devuelve una nota de crédito, una de débito o un rechazo de factura de contrato. Los tres casos cambian el contenido del body y, en el último, el estado HTTP:

Nota de crédito

{
  "status": 200,
  "message": null,
  "body": {
    "nota_id": 789,
    "factura_id": 456,
    "tipo": "credito",
    "consecutivo": 1024,
    "fecha": "2026-10-21",
    "resolucion_id": 3,
    "valor_total": 59500,
    "estado_id": 5,
    "moneda": "COP",
    "tasa_cambio": 1,
    "observaciones": "Ajuste acordado",
    "clasificacion": 1,
    "tercero_id": 123,
    "concepto_id": 6,
    "items": [
      {
        "producto_id": 159,
        "descripcion": "Ajuste plan X",
        "cantidad": 1,
        "valor_unitario": 50000,
        "por_iva": 19,
        "iva": 9500,
        "por_retencion": 0,
        "retencion": 0,
        "por_reteiva": 0,
        "reteiva": 0,
        "por_reteica": 0,
        "reteica": 0,
        "por_descuento": 0,
        "descuento": 0
      }
    ],
    "factura_estado_id": 1,
    "factura_saldo": 150000
  },
  "pagination": null,
  "filters_applied": null
}

La nota de crédito reduce el saldo de la factura. Si el saldo llega a cero, factura_estado_id pasa a 6.

Nota de débito

{
  "status": 200,
  "message": null,
  "body": {
    "nota_id": 790,
    "factura_id": 456,
    "tipo": "debito",
    "consecutivo": 1025,
    "fecha": "2026-10-21",
    "resolucion_id": 3,
    "valor_total": 20000,
    "estado_id": 5,
    "moneda": "COP",
    "tasa_cambio": 1,
    "observaciones": "Cargo adicional acordado",
    "clasificacion": 1,
    "tercero_id": 123,
    "concepto_id": 8,
    "items": [
      {
        "producto_id": 159,
        "descripcion": "Cargo adicional octubre",
        "cantidad": 1,
        "valor_unitario": 20000,
        "por_iva": 0,
        "iva": 0,
        "por_retencion": 0,
        "retencion": 0,
        "por_reteiva": 0,
        "reteiva": 0,
        "por_reteica": 0,
        "reteica": 0,
        "por_descuento": 0,
        "descuento": 0
      }
    ],
    "factura_estado_id": 1,
    "factura_saldo": 170000
  },
  "pagination": null,
  "filters_applied": null
}

La nota de débito aumenta el saldo. La factura conserva el estado 1 mientras siga ACTIVA.

Nota de una factura de contrato (409)

Cuando la nota pertenece a una factura de contrato, nuby no devuelve sus datos: responde 409 con el código estable y la advertencia estructurada. El scope siempre es solo_facturas_de_venta.

{
  "success": false,
  "status": 409,
  "message": "La factura 456 fue generada desde un contrato de arrendamiento. Esta API solo admite facturas de venta; las facturas de contrato se gestionan en el flujo de contratos de nuby.",
  "error_code": "FACTURA_CONTRATO_NO_SOPORTADA",
  "warnings": [
    {
      "code": "FACTURA_CONTRATO_NO_SOPORTADA",
      "factura_id": 456,
      "scope": "solo_facturas_de_venta"
    }
  ]
}

Estados que puedes recibir

Campos que no expone el detalle

El detalle se limita a la nota y al estado y saldo de la factura. Estos datos no forman parte de la respuesta y debes consultarlos en otro servicio:

Importante: los campos sin valor vienen en null, no se omiten. Verifica null antes de usar un dato en tu interfaz.

4. Seguridad y Posibles Errores

Ejemplo de nota inexistente (404)

{
  "success": false,
  "status": 404,
  "message": "No se encontró la nota con el código solicitado.",
  "error_code": "NOTA_NO_ENCONTRADA"
}

Ojo con el identificador: nota_id es el número interno de la nota, no el consecutivo ni el número de la factura. Para buscar las notas de una factura usa /notes/list?factura_id=....

Errores frecuentes y solución

5. Ejemplos de integración

TOKEN="TU_TOKEN_AQUI"
INSTANCIA="tu-inmobiliaria.nuby.app"
NOTA_ID=789

curl "https://${INSTANCIA}/service/v2/public/notes/${NOTA_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

<?php

$instancia = 'tu-inmobiliaria.nuby.app';
$token = 'TU_TOKEN_AQUI';
$notaId = 789;

$url = "https://{$instancia}/service/v2/public/notes/{$notaId}";

$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);

if ($codigo === 200) {
    $nota = $datos['body'];
    echo "{$nota['tipo']} {$nota['consecutivo']} - total {$nota['valor_total']}\n";
    echo "Factura {$nota['factura_id']}: estado {$nota['factura_estado_id']}, saldo {$nota['factura_saldo']}\n";

    foreach ($nota['items'] as $item) {
        echo "{$item['descripcion']} - {$item['cantidad']} x {$item['valor_unitario']}\n";
    }
} else {
    echo "HTTP {$codigo}: " . $datos['message'] . "\n";
}

import requests

instancia = "tu-inmobiliaria.nuby.app"
token = "TU_TOKEN_AQUI"
nota_id = 789
url = f"https://{instancia}/service/v2/public/notes/{nota_id}"

headers = {
    "Authorization": f"Bearer {token}",
}

respuesta = requests.get(url, headers=headers, timeout=30)

if respuesta.status_code == 200:
    nota = respuesta.json()["body"]
    print(f"{nota['tipo']} {nota['consecutivo']} — total {nota['valor_total']}")
    print(f"Factura {nota['factura_id']}: estado {nota['factura_estado_id']}, saldo {nota['factura_saldo']}")

    for item in nota["items"]:
        print(item["descripcion"], item["cantidad"], item["valor_unitario"])
else:
    print(respuesta.status_code, respuesta.json())

const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';
const notaId = 789;

const url = `https://${instancia}/service/v2/public/notes/${notaId}`;

const respuesta = await fetch(url, {
  headers: { 'Authorization': `Bearer ${token}` }
});

const data = await respuesta.json();

if (respuesta.ok) {
  const nota = data.body;
  console.log(`${nota.tipo} ${nota.consecutivo} — total ${nota.valor_total}`);
  console.log(`Factura ${nota.factura_id}: estado ${nota.factura_estado_id}, saldo ${nota.factura_saldo}`);
  nota.items.forEach(i => console.log(i.descripcion, i.cantidad, i.valor_unitario));
} else {
  console.error(`${respuesta.status} ${data.error_code}: ${data.message}`);
}

let
    // 1. Configura tus datos de acceso
    instancia = "tu-inmobiliaria.nuby.app",
    token = "TU_TOKEN_AQUI",
    notaId = "789",

    // 2. Prepara la dirección de la petición
    url = "https://" & instancia & "/service/v2/public/notes/" & notaId,

    // 3. Envía la petición GET
    response = Web.Contents(url, [
        Headers = [
            #"Authorization" = "Bearer " & token
        ]
    ]),

    // 4. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response),
    body = jsonResponse[body],

    // 5. Convierte la cabecera en tabla
    cabecera = Table.FromList({body}, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    columnas = Table.ExpandRecordColumn(cabecera, "Column1",
        {"nota_id", "factura_id", "tipo", "consecutivo", "fecha", "valor_total",
         "estado_id", "concepto_id", "factura_estado_id", "factura_saldo"},
        {"NotaID", "FacturaID", "Tipo", "Consecutivo", "Fecha", "ValorTotal",
         "EstadoID", "ConceptoID", "FacturaEstadoID", "FacturaSaldo"}),
    tipos = Table.TransformColumnTypes(columnas, {
        {"NotaID", Int64.Type},
        {"FacturaID", Int64.Type},
        {"Consecutivo", Int64.Type},
        {"Fecha", type date},
        {"ValorTotal", type number},
        {"FacturaSaldo", type number}
    }),

    // 6. Expande los ítems en una tabla aparte
    items = Table.FromList(body[items], Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    itemsExpandidos = Table.ExpandRecordColumn(items, "Column1",
        {"producto_id", "descripcion", "cantidad", "valor_unitario", "por_iva", "iva",
         "por_retencion", "retencion", "por_reteiva", "reteiva",
         "por_reteica", "reteica", "por_descuento", "descuento"},
        {"ProductoID", "Descripcion", "Cantidad", "ValorUnitario", "PorIVA", "IVA",
         "PorRetencion", "Retencion", "PorReteIVA", "ReteIVA",
         "PorReteICA", "ReteICA", "PorDescuento", "Descuento"})
in
    tipos

6. Buenas prácticas y límites conocidos

Recomendaciones

Límites

El detalle no admite paginación ni filtros: el nota_id identifica un único registro. Si necesitas recorrer varias notas, usa Listar Notas y consulta el detalle solo de las que vayas a mostrar. Así evitas una petición por cada nota del período.

Para crear una nota, revisa la página Crear Nota. Para listar notas, revisa Listar Notas.