Crear Nota [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 registra una nota de crédito o una nota de débito sobre una factura de venta de nuby. La nota se guarda en borrador y actualiza el saldo de la factura en el acto: una nota de crédito lo reduce y puede anular la factura si llega a cero; una nota de débito lo aumenta.

Es el servicio que necesitas cuando tu plataforma debe ajustar o anular una factura emitida desde nuby, sin volver a digitar el documento en la interfaz.

¿Para qué sirve este servicio?
Úsalo cuando necesites ajustar una factura de venta desde tu plataforma sin volver a digitar el documento en nuby. Los casos de uso más frecuentes son:

1. El Endpoint (La dirección web)

Método y dirección

POST https://{{instancia}}/service/v2/public/notes

¿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.

Encabezados requeridos

Permiso requerido (scope): notes:create

El cliente OAuth debe tener habilitado notes:create. Si el token es válido pero falta el permiso, la respuesta es 403 con el código RECURSO_NO_AUTORIZADO.

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

2. ¿Qué hace este servicio?

La nota se crea reutilizando la misma lógica de la interfaz de nuby: se asigna su consecutivo, se guarda su detalle y se recalcula el saldo de la factura. La API no reimplementa numeración, contabilidad ni DIAN.

Qué SÍ hace

Qué NO hace

Importante: la factura debe estar en estado ACTIVA (facturada). Una factura en borrador o anulada no admite notas y la API responde 409 FACTURA_NO_ANOTABLE.

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

Campos obligatorios

fecha es opcional: si no la envías, se usa la fecha de hoy en formato AAAA-MM-DD.

Campos opcionales

Datos que hereda de la factura

No necesitas enviarlos y, de hecho, no se aceptan si difieren: resolucion_id, tercero_id, moneda y tasa_cambio se toman de la factura. Si envías una moneda o una tasa distinta, la respuesta es 422 CAMPO_NO_PERMITIDO: el saldo se calcula sin conversión y un valor distinto lo descuadraría.

Campos que el consumidor no puede fijar

La nota hereda de la factura los datos que garantizan la coherencia del saldo y de la numeración. Si envías uno de estos campos con valor, la respuesta es 422 CAMPO_NO_PERMITIDO y la nota no se crea:

Concepto de la nota

Si omites concepto_id, nuby aplica el concepto por defecto del tipo. El concepto se resuelve contra los target y codigo de la maestra:

Si envías un concepto_id, nuby no aplica el default: valida que el concepto exista y que su target corresponda al tipo de nota. Si no existe o no corresponde, la respuesta es 422 CONCEPTO_NO_DISPONIBLE y no se crea la nota.

Montos: tú envías tasas, nuby calcula

Por cada ítem envía valor_unitario y los porcentajes. El servidor calcula el IVA, las retenciones y el descuento, y recalcula el total de la nota a partir del detalle. Si envías montos ya calculados, se ignoran.

El total del ítem se obtiene al sumar la base y el IVA, y restar la retención, el reteIVA, el reteICA y el descuento. Con el ejemplo anterior, el total de la nota es 59500. Todos los montos se calculan en la moneda original de la factura y se redondean a dos decimales.

Importante: el IVA de un ítem requiere que el producto tenga configurado su tipo de IVA en nuby. Si no lo tiene, la operación falla y no se crea la nota.

Ejemplo: nota de crédito total

Cuando el total de la nota de crédito iguala el saldo de la factura, el saldo queda en 0 y la factura pasa al estado 6 (anulada por nota crédito). La respuesta lo confirma en factura_estado_id y factura_saldo.

{
  "referencia_externa": "NOTE-000046",
  "factura_id": 456,
  "tipo": "credito",
  "fecha": "2026-10-21",
  "observaciones": "Anulación total acordada",
  "items": [
    {
      "producto_id": 159,
      "descripcion": "Anulación total factura 456",
      "cantidad": 1,
      "valor_unitario": 100000,
      "por_iva": 19,
      "por_retencion": 0,
      "por_reteiva": 0,
      "por_reteica": 0,
      "por_descuento": 0
    }
  ]
}

La nota calcula iva = 100000 × 19 % = 19000 y un total de 119000. Si el saldo de la factura es exactamente 119000, la respuesta devuelve factura_saldo: 0 y factura_estado_id: 6.

Ejemplo: nota de débito

La nota de débito aumenta el saldo. Úsala para cobrar un ajuste posterior, por ejemplo un cargo no incluido en la factura original. La factura debe seguir ACTIVA.

{
  "referencia_externa": "NOTE-000047",
  "factura_id": 456,
  "tipo": "debito",
  "fecha": "2026-10-21",
  "observaciones": "Cargo adicional acordado",
  "items": [
    {
      "producto_id": 159,
      "descripcion": "Cargo adicional octubre",
      "cantidad": 1,
      "valor_unitario": 20000,
      "por_iva": 0,
      "por_retencion": 0,
      "por_reteiva": 0,
      "por_reteica": 0,
      "por_descuento": 0
    }
  ]
}

Si el saldo era 119000, después de esta nota de débito será 139000. La factura conserva el estado 1 (ACTIVA).

Ejemplo completo

{
  "referencia_externa": "NOTE-000045",
  "factura_id": 456,
  "tipo": "credito",
  "concepto_id": null,
  "fecha": "2026-10-21",
  "observaciones": "Ajuste acordado",
  "items": [
    {
      "producto_id": 159,
      "descripcion": "Ajuste plan X",
      "cantidad": 1,
      "valor_unitario": 50000,
      "por_iva": 19,
      "por_retencion": 0,
      "por_reteiva": 0,
      "por_reteica": 0,
      "por_descuento": 0
    }
  ]
}

4. Cómo afecta el saldo de la factura

Escenario → resultado en la factura

La nota se crea en borrador y aun así afecta el saldo, porque nuby recalcula la cartera al guardarla. La emisión a la DIAN es un paso posterior y no cambia el saldo.

Ojo con el estado de la factura: solo se anotan facturas ACTIVAS. Si la factura ya fue anulada o está en borrador, la respuesta es 409 FACTURA_NO_ANOTABLE.

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

Si la nota se crea correctamente, la respuesta es un JSON con el resultado de la operación y el estado en que queda la factura anotada:

{
  "success": true,
  "status": 201,
  "message": "Nota creada en borrador.",
  "body": {
    "nota_id": 789,
    "tipo": "credito",
    "consecutivo": 1024,
    "estado_id": 5,
    "factura_id": 456,
    "factura_estado_id": 1,
    "factura_saldo": 150000
  },
  "idempotent_replay": false
}

Estructura de la respuesta

Escenario de reintento (replay)

Si repites la petición con la misma referencia_externa y el mismo contenido, nuby no crea una segunda nota: devuelve la respuesta original con idempotent_replay en true.

{
  "success": true,
  "status": 201,
  "message": "Nota creada en borrador.",
  "body": {
    "nota_id": 789,
    "tipo": "credito",
    "consecutivo": 1024,
    "estado_id": 5,
    "factura_id": 456,
    "factura_estado_id": 1,
    "factura_saldo": 150000
  },
  "idempotent_replay": true
}

Para ver el detalle completo de la nota, consulta la página Buscar Nota por Código.

6. Idempotencia y reintentos

La escritura exige referencia_externa. nuby recuerda qué respondió para esa referencia, así que un reintento no duplica la nota.

Importante: un error 422 de validación no consume la referencia. Puedes corregir el payload y reintentar con la misma referencia_externa.

Token renovado: el contenido interno que agrega la autenticación no forma parte de la comparación de idempotencia. Puedes renovar el token y reintentar sin conflicto.

7. Seguridad y Posibles Errores

Errores de validación frecuentes

Atención: cuando la respuesta es 409 o 422, nuby no deja una nota a medias. La operación se revierte completa.

8. Ejemplos de integración

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

curl -X POST "https://${INSTANCIA}/service/v2/public/notes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "referencia_externa": "NOTE-000045",
    "factura_id": 456,
    "tipo": "credito",
    "fecha": "2026-10-21",
    "observaciones": "Ajuste acordado",
    "items": [
      {
        "producto_id": 159,
        "descripcion": "Ajuste plan X",
        "cantidad": 1,
        "valor_unitario": 50000,
        "por_iva": 19,
        "por_retencion": 0,
        "por_reteiva": 0,
        "por_reteica": 0,
        "por_descuento": 0
      }
    ]
  }'

<?php

$instancia = 'tu-inmobiliaria.nuby.app';
$token = 'TU_TOKEN_AQUI';
$url = "https://{$instancia}/service/v2/public/notes";

$payload = [
    'referencia_externa' => 'NOTE-000045',
    'factura_id' => 456,
    'tipo' => 'credito',
    'fecha' => '2026-10-21',
    'observaciones' => 'Ajuste acordado',
    'items' => [
        [
            'producto_id' => 159,
            'descripcion' => 'Ajuste plan X',
            'cantidad' => 1,
            'valor_unitario' => 50000,
            'por_iva' => 19,
            'por_retencion' => 0,
            'por_reteiva' => 0,
            'por_reteica' => 0,
            'por_descuento' => 0,
        ],
    ],
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    "Authorization: Bearer {$token}",
]);

$respuesta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP: {$codigo}\n";
print_r(json_decode($respuesta, true));

import requests

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

payload = {
    "referencia_externa": "NOTE-000045",
    "factura_id": 456,
    "tipo": "credito",
    "fecha": "2026-10-21",
    "observaciones": "Ajuste acordado",
    "items": [
        {
            "producto_id": 159,
            "descripcion": "Ajuste plan X",
            "cantidad": 1,
            "valor_unitario": 50000,
            "por_iva": 19,
            "por_retencion": 0,
            "por_reteiva": 0,
            "por_reteica": 0,
            "por_descuento": 0,
        }
    ],
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

respuesta = requests.post(url, json=payload, headers=headers, timeout=30)

if respuesta.status_code == 201:
    datos = respuesta.json()
    print(f"Nota {datos['body']['nota_id']} — saldo factura: {datos['body']['factura_saldo']}")
else:
    print(respuesta.status_code, respuesta.json())

const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';
const url = `https://${instancia}/service/v2/public/notes`;

const payload = {
  referencia_externa: 'NOTE-000045',
  factura_id: 456,
  tipo: 'credito',
  fecha: '2026-10-21',
  items: [{
    producto_id: 159,
    descripcion: 'Ajuste plan X',
    cantidad: 1,
    valor_unitario: 50000,
    por_iva: 19,
    por_retencion: 0,
    por_reteiva: 0,
    por_reteica: 0,
    por_descuento: 0
  }]
};

const respuesta = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(payload)
});

const data = await respuesta.json();

if (respuesta.ok) {
  console.log(`Nota ${data.body.nota_id} — saldo factura: ${data.body.factura_saldo}`);
} else {
  console.error(`${respuesta.status} ${data.error_code}: ${data.message}`, data.errors ?? {});
}

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

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

    // 3. Construye el cuerpo JSON
    cuerpo = Json.FromValue([
        referencia_externa = "NOTE-000045",
        factura_id = 456,
        tipo = "credito",
        fecha = "2026-10-21",
        observaciones = "Ajuste acordado",
        items = {
            [
                producto_id = 159,
                descripcion = "Ajuste plan X",
                cantidad = 1,
                valor_unitario = 50000,
                por_iva = 19,
                por_retencion = 0,
                por_reteiva = 0,
                por_reteica = 0,
                por_descuento = 0
            ]
        }
    ]),

    // 4. Envía la petición POST
    response = Web.Contents(url, [
        Headers = [
            #"Content-Type" = "application/json",
            #"Authorization" = "Bearer " & token
        ],
        Content = cuerpo
    ]),

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

    // 6. Convierte el resultado en tabla
    tabla = Table.FromList({body}, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"nota_id", "tipo", "consecutivo", "estado_id", "factura_id", "factura_estado_id", "factura_saldo"},
        {"NotaID", "Tipo", "Consecutivo", "EstadoID", "FacturaID", "FacturaEstadoID", "FacturaSaldo"})
in
    expandido

9. Buenas prácticas y límites conocidos

Recomendaciones

Límites

Para consultar notas ya registradas, revisa las páginas Listar Notas y Buscar Nota por Código.