Editar Factura en Borrador [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 modifica una factura de venta que todavía está en borrador en nuby. Puedes cambiar la cabecera y los ítems; nuby vuelve a calcular los totales, el saldo y la contabilidad del documento. La factura sigue en estado 5 (Borrador) y sigue sin numerar: la edición no consume consecutivo.

Solo puedes editar tus borradores: los que creó tu consumidor por API. Una factura generada desde un contrato de arrendamiento, una factura ya emitida o un borrador creado por la interfaz de nuby quedan fuera del alcance de este servicio. La emisión es un paso aparte: editar no envía nada a la DIAN.

¿Para qué sirve este servicio?
Sirve para corregir un borrador antes de emitirlo. La creación y la emisión son actos separados justamente para que exista este paso: entre una y otra puedes ajustar el documento tantas veces como necesites, sin gastar numeración y sin enviar nada a la DIAN.

Casos de uso concretos

Resumen del servicio

Lo que este servicio NO hace

Dónde encaja en el ciclo

1. Crear borrador         POST /invoices                              (guía anterior)
2. Editar borrador        PUT|PATCH /invoices/{factura_id}            (esta página)
3. Emitir a la DIAN       POST /invoices/{factura_id}/issue
4. Consultar detalle      GET /invoices/{factura_id}
5. Obtener el PDF         GET /invoices/{factura_id}/pdf

Si todavía no tienes un borrador, créalo primero con Crear Factura en Borrador. El factura_id que devuelve esa operación es el que va en el path de esta.

1. El Endpoint (La dirección web)

Apunta tu sistema a la siguiente dirección. Puedes usar PUT o PATCH: las dos llegan al mismo servicio y tienen la misma semántica (documento completo).

PUT   https://{{instancia}}/service/v2/public/invoices/{factura_id}
PATCH https://{{instancia}}/service/v2/public/invoices/{factura_id}

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

La dirección web principal que utilizas a diario para ingresar a tu plataforma, incluyendo la terminación .nuby.app o .arrendasoft.co. Por ejemplo inmobiliaria.nuby.app.

Importante: no incluyas https:// ni barras diagonales (/) al final. La dirección se compone así: https:// + tu instancia + /service/v2/public/invoices/{factura_id}.

¿Qué debes colocar en {factura_id}? El identificador interno que devolvió la creación (campo body.factura_id). Debe ser un entero mayor que 0. Si no lo es, la respuesta es 400 con Debe indicar un factura_id entero mayor que 0 para operar sobre la factura. No construyas ese valor a partir del consecutivo: en un borrador el consecutivo es un marcador sin numerar.

Encabezados requeridos

Permiso requerido (scope)

El cliente OAuth con el que se genera el token debe tener habilitado el permiso invoices:update. Ojo: es distinto del permiso de creación (invoices:create). Un cliente con permiso para crear no necesariamente puede editar.

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

Precondiciones del documento

La edición no revalida la configuración del sistema. Ni ENABLE_FACT_ELECT ni el período contable de la fecha se vuelven a evaluar aquí: se validaron al crear el borrador y la fecha del documento no cambió de período por editarse.

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

El cuerpo es un objeto JSON con el mismo contrato de entrada de la creación: la referencia de idempotencia de esta edición y, al mismo nivel, la cabecera y los ítems del documento.

Cabecera de la factura

Ítems (items[])

La edición reutiliza el mismo contrato de ítem de la creación: producto_id, cantidad y valor_unitario son obligatorios y se validan todos antes de tocar el documento; el resto de campos (descuentos, impuestos, retenciones, descripcion, descuentos_id, otros_impuestos, tercero_aplica_id, valor_unitario_ori) son opcionales. Si un ítem es inválido, la factura no se modifica.

El detalle se reemplaza, no se mezcla. Envía todas las líneas que debe tener el documento. Una línea que no envíes deja de existir en la factura, y los totales se recalculan con las líneas enviadas.

El factura_id del path manda

Si tu cuerpo trae un factura_id, nuby lo descarta: la factura que se edita es la del path. Es una protección deliberada contra errores de tu integración, porque un identificador equivocado en el cuerpo cambiaría el documento equivocado.

{
  "referencia_externa": "INV-2026-0001-EDIT-1",
  "tercero_id": 4821,
  "fecha": "2026-10-21",
  "dias_vencimiento": 15,
  "items": [
    { "producto_id": 340, "descripcion": "Administración octubre 2026", "cantidad": 2, "valor_unitario": 1500 }
  ]
}

Enviado a PUT /invoices/10231, edita la factura 10231 y la respuesta también dice factura_id: 10231.

Campos que siguen prohibidos

La edición valida los mismos guardas que la creación, en este orden:

{
  "success": false,
  "status": 422,
  "message": "El payload intenta fijar el campo estado_id, que solo el sistema puede asignar en una factura de venta.",
  "error_code": "CAMPO_NO_PERMITIDO",
  "errors": {
    "estado_id": [
      "El campo estado_id solo lo puede asignar el sistema."
    ]
  }
}

Ejemplos de petición

Cambiar plazo y observaciones (documento completo)

PUT /service/v2/public/invoices/10231
Authorization: Bearer <token>
Content-Type: application/json

{
  "referencia_externa": "INV-2026-0001-EDIT-1",
  "tercero_id": 4821,
  "fecha": "2026-10-21",
  "dias_vencimiento": 15,
  "moneda": "COP",
  "observaciones": "Administración octubre 2026 (ajustada)",
  "pago_total": false,
  "items": [
    {
      "producto_id": 340,
      "descripcion": "Administración octubre 2026",
      "cantidad": 1,
      "valor_unitario": 1200000,
      "por_iva": 19,
      "iva": 228000
    }
  ]
}

Reemplazar el detalle con dos líneas (PATCH)

{
  "referencia_externa": "INV-2026-0001-EDIT-2",
  "tercero_id": 4821,
  "fecha": "2026-10-22",
  "fecha_vencimiento": "2026-11-21",
  "items": [
    { "producto_id": 340, "descripcion": "Administración octubre 2026", "cantidad": 1, "valor_unitario": 1000000 },
    { "producto_id": 512, "descripcion": "Servicio de aseo octubre 2026", "cantidad": 2, "valor_unitario": 150000 }
  ]
}

Pasar el documento a contado

{
  "referencia_externa": "INV-2026-0001-EDIT-3",
  "tercero_id": 4821,
  "fecha": "2026-10-21",
  "pago_total": true,
  "formas_de_pago": [
    { "tipo_pago_id": 1, "valor": 1190000 }
  ],
  "items": [
    { "producto_id": 340, "cantidad": 1, "valor_unitario": 1000000, "por_iva": 19, "iva": 190000 }
  ]
}

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

Si la edición es válida, nuby regraba el documento, recalcula totales y saldo, vuelve a escribir la contabilidad y responde 200:

{
  "success": true,
  "status": 200,
  "message": "La factura de venta se actualizó correctamente.",
  "body": {
    "factura_id": 10231,
    "estado_id": 5,
    "consecutivo": -1,
    "prefijo": "FE",
    "valor_total": 3570,
    "valor_saldo": 3570
  },
  "idempotent_replay": false
}

Estructura principal de la respuesta

Campos de body

No des por hecho el valor de consecutivo. Compara siempre contra estado_id y contra la presencia de cufe: mientras estado_id = 5 el documento no está numerado y su consecutivo es un marcador interno que no debes mostrar al cliente final.

Qué se recalcula exactamente

4. Idempotencia y reintentos

Reintento de una edición ya completada (replay)

Si repites la petición con la misma referencia_externa, la misma factura y el mismo contenido, nuby devuelve la respuesta guardada con idempotent_replay: true. No se vuelve a escribir el documento:

{
  "success": true,
  "status": 200,
  "message": "La factura de venta se actualizó correctamente.",
  "body": {
    "factura_id": 10231,
    "estado_id": 5,
    "consecutivo": -1,
    "prefijo": "FE",
    "valor_total": 3570,
    "valor_saldo": 3570
  },
  "idempotent_replay": true
}

La clave de idempotencia incluye el factura_id: la misma referencia aplicada a otra factura responde 409 IDEMPOTENCY_PAYLOAD_MISMATCH, no un replay. Y la misma referencia con otro contenido también es 409: La referencia externa ya fue usada con un payload distinto.

Reglas de reintento

5. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expira y el sistema bloquea el acceso. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y reintentar con la misma referencia_externa.

{
  "statusCode": 401,
  "error": {
    "type": "SERVER_ERROR",
    "description": "JWT Token expired."
  }
}

Ese 401 lo emite el middleware de autenticación, no el servicio de facturas, así que su forma es distinta: no trae success ni error_code.

Orden de evaluación: es contrato, no detalle interno

nuby evalúa en este orden exacto. Importa porque determina qué error recibes cuando hay varios problemas a la vez:

El alcance gana sobre la pertenencia y sobre el estado. Una factura de contrato responde 409 FACTURA_CONTRATO_NO_SOPORTADA aunque además sea de otro consumidor o esté fuera de borrador: nuby no evalúa nada más. Y el estado gana sobre la validación: una factura ya emitida responde 409 aunque tu payload también tenga errores.

Tabla de códigos HTTP, causas y mensajes

Forma exacta de warnings[] al rechazar una factura de contrato

Es un arreglo con un solo elemento, y su forma es fija: code, factura_id y scope.

{
  "success": false,
  "status": 409,
  "message": "La factura 990 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": 990, "scope": "solo_facturas_de_venta" }
  ]
}

Y esta es la forma de la advertencia cuando el payload trae datos de contrato (sin factura_id, porque todavía no hay documento):

{
  "success": false,
  "status": 422,
  "message": "El payload intenta crear o modificar una factura con datos de contrato (movimiento_id). Esta API solo crea facturas de venta; las facturas de contrato se generan desde el flujo de contratos.",
  "error_code": "FACTURA_CONTRATO_NO_PERMITIDA",
  "errors": {
    "movimiento_id": [
      "El payload no puede incluir el campo movimiento_id en una factura de venta."
    ]
  },
  "warnings": [
    { "code": "FACTURA_CONTRATO_NO_PERMITIDA", "scope": "solo_facturas_de_venta" }
  ]
}

Un factura_id que no existe suele responder 403 RECURSO_AJENO. La pertenencia se evalúa antes de la existencia: si nuby no tiene registrado que tu consumidor creó ese identificador, no puede distinguir "no es tuya" de "no existe" y responde 403. El 404 FACTURA_NO_ENCONTRADA aparece cuando la pertenencia sí está registrada pero la factura ya no existe.

6. Ejemplos de integración

Cada ejemplo envía el documento completo y usa una referencia_externa nueva por edición.

TOKEN="TU_TOKEN_AQUI"
INSTANCIA="mi-inmobiliaria.nuby.app"
FACTURA_ID=10231

curl -X PUT "https://${INSTANCIA}/service/v2/public/invoices/${FACTURA_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_externa": "INV-2026-0001-EDIT-1",
    "tercero_id": 4821,
    "fecha": "2026-10-21",
    "dias_vencimiento": 15,
    "moneda": "COP",
    "observaciones": "Administración octubre 2026 (ajustada)",
    "pago_total": false,
    "items": [
      {
        "producto_id": 340,
        "descripcion": "Administración octubre 2026",
        "cantidad": 1,
        "valor_unitario": 1200000,
        "por_iva": 19,
        "iva": 228000
      }
    ]
  }'

<?php

$instancia = 'mi-inmobiliaria.nuby.app'; // Reemplaza con tu dirección web completa
$token = 'TU_TOKEN_AQUI';                // Token obtenido del servicio Login
$facturaId = 10231;                      // factura_id devuelto al crear el borrador

$url = "https://{$instancia}/service/v2/public/invoices/{$facturaId}";

$payload = [
    'referencia_externa' => 'INV-2026-0001-EDIT-1',
    'tercero_id' => 4821,
    'fecha' => '2026-10-21',
    'dias_vencimiento' => 15,
    'moneda' => 'COP',
    'observaciones' => 'Administración octubre 2026 (ajustada)',
    'pago_total' => false,
    'items' => [
        [
            'producto_id' => 340,
            'descripcion' => 'Administración octubre 2026',
            'cantidad' => 1,
            'valor_unitario' => 1200000,
            'por_iva' => 19,
            'iva' => 228000,
        ],
    ],
];

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

$respuesta = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'Error de conexión: ' . curl_error($ch); // reintenta con la MISMA referencia
} else {
    $info = json_decode($respuesta, true);

    if ($httpCode === 200) {
        echo "Borrador actualizado: factura_id={$info['body']['factura_id']}"
            . " total={$info['body']['valor_total']}"
            . " saldo={$info['body']['valor_saldo']}\n";

        if (!empty($info['idempotent_replay'])) {
            echo "Nota: fue un reintento idempotente, no se regrabó el documento.\n";
        }
    } else {
        echo "Rechazo HTTP {$httpCode}: {$info['message']}\n";
        echo "error_code: " . ($info['error_code'] ?? 'N/A') . "\n";

        if (!empty($info['warnings'])) {
            print_r($info['warnings']);
        }
    }
}

curl_close($ch);

?>

import requests

# 1. Configura tus datos de acceso
instancia = 'mi-inmobiliaria.nuby.app'  # Reemplaza con tu dirección web completa
token = 'TU_TOKEN_AQUI'                 # Token obtenido del servicio Login
factura_id = 10231                      # factura_id devuelto al crear el borrador

# 2. Prepara la dirección y el cuerpo
url = f"https://{instancia}/service/v2/public/invoices/{factura_id}"

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

payload = {
    "referencia_externa": "INV-2026-0001-EDIT-1",
    "tercero_id": 4821,
    "fecha": "2026-10-21",
    "dias_vencimiento": 15,
    "moneda": "COP",
    "observaciones": "Administración octubre 2026 (ajustada)",
    "pago_total": False,
    "items": [
        {
            "producto_id": 340,
            "descripcion": "Administración octubre 2026",
            "cantidad": 1,
            "valor_unitario": 1200000,
            "por_iva": 19,
            "iva": 228000
        }
    ]
}

# 3. Envía la petición y procesa la respuesta
try:
    response = requests.put(url, json=payload, headers=headers, timeout=30)

    print(f"Código de estado HTTP: {response.status_code}")

    if response.status_code == 200:
        info = response.json()
        body = info.get("body", {})

        print(f"Borrador actualizado: factura_id={body.get('factura_id')}")
        print(f"Total: {body.get('valor_total')} | Saldo: {body.get('valor_saldo')}")

        if info.get("idempotent_replay"):
            print("Nota: reintento idempotente, no se regrabó el documento.")
    else:
        info = response.json()
        print(f"Mensaje: {info.get('message')}")
        print(f"error_code: {info.get('error_code')}")

        for aviso in info.get("warnings") or []:
            print(f"  advertencia: {aviso}")

except Exception as e:
    # Ante un timeout, reintenta con la MISMA referencia_externa.
    print(f"Ocurrió un error de conexión: {e}")

// 1. Configura tus datos de acceso
const instancia = 'mi-inmobiliaria.nuby.app'; // Reemplaza con tu dirección web completa
const token = 'TU_TOKEN_AQUI';                // Token obtenido del servicio Login
const facturaId = 10231;                      // factura_id devuelto al crear el borrador

const url = `https://${instancia}/service/v2/public/invoices/${facturaId}`;

const payload = {
    referencia_externa: 'INV-2026-0001-EDIT-1',
    tercero_id: 4821,
    fecha: '2026-10-21',
    dias_vencimiento: 15,
    moneda: 'COP',
    observaciones: 'Administración octubre 2026 (ajustada)',
    pago_total: false,
    items: [
        {
            producto_id: 340,
            descripcion: 'Administración octubre 2026',
            cantidad: 1,
            valor_unitario: 1200000,
            por_iva: 19,
            iva: 228000
        }
    ]
};

// 2. Función para editar el borrador
async function editarBorrador() {
    try {
        const response = await fetch(url, {
            method: 'PUT', // PATCH tiene la misma semántica
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`
            },
            body: JSON.stringify(payload)
        });

        console.log(`Código de estado HTTP: ${response.status}`);

        const info = await response.json();

        if (response.status === 200) {
            const body = info.body || {};

            console.log(`Borrador actualizado: factura_id=${body.factura_id}`);
            console.log(`Total: ${body.valor_total} | Saldo: ${body.valor_saldo}`);

            if (info.idempotent_replay) {
                console.log('Nota: reintento idempotente, no se regrabó el documento.');
            }
        } else {
            console.log(`Mensaje: ${info.message}`);
            console.log(`error_code: ${info.error_code}`);

            (info.warnings || []).forEach((aviso) => console.log('  advertencia:', aviso));
        }
    } catch (error) {
        // Ante un timeout, reintenta con la MISMA referencia_externa.
        console.error(`Ocurrió un error de conexión: ${error}`);
    }
}

// 3. Ejecutamos la función
editarBorrador();

let
    // 1. Configura la dirección de TU función, que reenvía con PUT a nuby
    urlFuncion = "https://tu-servicio.example.com/facturas/10231/editar",
    token = "TU_TOKEN_AQUI",  // Token obtenido del servicio Login

    // 2. Construye el cuerpo JSON del contrato de edición
    cuerpo = Json.FromValue([
        referencia_externa = "INV-2026-0001-EDIT-1",
        tercero_id = 4821,
        fecha = "2026-10-21",
        dias_vencimiento = 15,
        moneda = "COP",
        observaciones = "Administración octubre 2026 (ajustada)",
        pago_total = false,
        items = {
            [
                producto_id = 340,
                descripcion = "Administración octubre 2026",
                cantidad = 1,
                valor_unitario = 1200000,
                por_iva = 19,
                iva = 228000
            ]
        }
    ]),

    // 3. Envía el cuerpo a tu función (ella añade el verbo PUT y el token)
    response = Web.Contents(urlFuncion, [
        Headers = [
            #"Content-Type" = "application/json",
            #"Authorization" = "Bearer " & token
        ],
        Content = cuerpo
    ]),

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

    // 5. Convierte el resultado en tabla
    tabla = Table.FromRecords({body}),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"factura_id", "estado_id", "consecutivo", "prefijo", "valor_total", "valor_saldo"},
        {"FacturaID", "EstadoID", "ConsecutivoSinNumerar", "ValorTotal", "ValorSaldo"})
in
    expandido