Eliminar un Borrador de Factura [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 elimina un borrador de factura de venta creado por el consumidor autenticado. Es la operación de compensación cuando el flujo local falla después de crear el borrador: nuby borra la factura y toda su cascada (detalle, impuestos, contabilidad y pagos/recibos) para no dejar documentos huérfanos.

Solo aplica a facturas de venta en estado borrador creadas por el propio consumidor. Una factura de contrato, una factura ya emitida o una factura de la UI se rechazan.

¿Para qué sirve este servicio?
Úsalo como compensación de tu propio flujo: si después de crear el borrador algo falla en tu plataforma, eliminas el documento para no dejarlo colgado en nuby. Los casos de uso más frecuentes son:

1. El Endpoint (La dirección web)

Método y dirección

DELETE https://{{instancia}}/service/v2/public/invoices/{factura_id}

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

Es la dirección web principal con la que ingresas a tu plataforma, incluyendo la terminación .nuby.app o .arrendasoft.co. Si entras a nuby escribiendo inmobiliaria.nuby.app en el navegador, esa es tu instancia.

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

Encabezados requeridos

Permiso requerido (scope): invoices:update

Este servicio exige el permiso invoices:update en el cliente OAuth. Si el token es válido pero al cliente le 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. Allí se explica cómo identificarte y cómo se construye el encabezado Authorization.

Qué necesitas

No hay soft delete. La eliminación es física e irreversible. La trazabilidad de la operación queda en api_solicitudes y en los logs de nuby.

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

Path parameter

Body

No se envía cuerpo. Tampoco se envía referencia_externa: la idempotencia usa la clave interna eliminar:{factura_id}.

Orden de evaluación

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

Respuesta exitosa

{
  "success": true,
  "status": 200,
  "message": "La factura de venta se eliminó correctamente.",
  "body": {
    "factura_id": 10231,
    "eliminada": true,
    "idempotent_replay": false
  }
}

Estructura principal de la respuesta

Las respuestas de escritura no traen pagination ni filters_applied: esos campos pertenecen a las consultas de lectura.

Reintento idempotente

Si repites el DELETE de una factura que ya eliminaste, nuby devuelve la respuesta original con idempotent_replay: true. No intenta borrar dos veces ni responde 404.

Campos de la respuesta

Escenario alternativo: el reintento

La segunda llamada sobre el mismo factura_id responde 200 con el body de la respuesta original y el indicador en true:

{
  "factura_id": 10231,
  "eliminada": true,
  "idempotent_replay": true
}

4. Idempotencia y reintentos

Este servicio no usa referencia_externa. La clave de idempotencia es eliminar:{factura_id}, registrada en api_solicitudes con el recurso factura y la operación eliminar.

Reintenta sin miedo. Mientras la solicitud siga registrada, repetir el DELETE es seguro: nunca borra dos veces y nunca responde 404 por un borrado previo exitoso.

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 sistema te bloquea el acceso con un error 401 y tu sistema debe volver a consumir el servicio de Login para pedir un pase nuevo.

Esta respuesta la produce el middleware de autenticación y no el contrato de la operación, así que usa el envelope heredado (statusCode y error.description), no success ni error_code:

Errores del contrato de la operación

Los errores de la operación traen success: false, el código HTTP, un message legible y un error_code estable:

Forma del rechazo de contrato

El rechazo por contrato llega con el código FACTURA_CONTRATO_NO_SOPORTADA, un mensaje que explica el motivo y una advertencia que identifica la factura y el alcance del endpoint:

Trata el 404 como un caso de negocio, no como una falla técnica: significa que el identificador no existe en nuby (o que nunca lo creó tu consumidor). No lo reintentes con el mismo valor.

Trata el 409 FACTURA_NO_ELIMINABLE como un caso de negocio: la factura ya salió de borrador y no se elimina por esta vía. Revisa el estado actual en el mensaje antes de decidir qué hacer.

6. Ejemplos de integración

Aquí tienes ejemplos listos para adaptar a tu plataforma. Todos usan {{instancia}}, Authorization: Bearer, eliminan un borrador y tratan el éxito junto con los rechazos de negocio más frecuentes (404 y 409).

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

curl -X DELETE "https://${INSTANCIA}/service/v2/public/invoices/${FACTURA_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

curl -X DELETE "https://${INSTANCIA}/service/v2/public/invoices/${FACTURA_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

<?php
$instancia = 'mi-inmobiliaria.nuby.app'; // Tu dirección web completa
$token     = 'TU_TOKEN_AQUI';            // Token obtenido del servicio Login
$facturaId = 10231;

$ch = curl_init("https://{$instancia}/service/v2/public/invoices/{$facturaId}");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$token}",
]);

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

$info = json_decode($respuesta, true);

if ($httpCode === 200) {
    echo "Factura eliminada: {$info['body']['factura_id']}\n";
    echo "Reintento idempotente: " . var_export($info['body']['idempotent_replay'], true) . "\n";
} elseif ($httpCode === 404 || $httpCode === 409) {
    echo "Rechazo de negocio {$info['error_code']}: {$info['message']}\n";
} else {
    echo "Error HTTP {$httpCode}: {$info['message']}\n";
}

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

# 2. Envía la petición
url = f"https://{instancia}/service/v2/public/invoices/{factura_id}"
headers = {"Authorization": f"Bearer {token}"}

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

# 3. Procesa la respuesta
if respuesta.status_code == 200:
    body = respuesta.json()["body"]
    print(f"Factura {body['factura_id']} eliminada: {body['eliminada']}")
    print(f"Reintento idempotente: {body['idempotent_replay']}")
elif respuesta.status_code in (404, 409):
    error = respuesta.json()
    print(f"Rechazo de negocio {error['error_code']}: {error['message']}")
else:
    print(f"Error HTTP {respuesta.status_code}: {respuesta.text}")

// 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

// 2. Función que elimina el borrador
async function eliminarBorrador(facturaId) {
  const url = `https://${instancia}/service/v2/public/invoices/${facturaId}`;

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

  const info = await response.json().catch(() => ({}));

  if (!response.ok) {
    console.error(`Error HTTP ${response.status} ${info.error_code ?? ''}: ${info.message ?? ''}`);
    return null;
  }

  return info.body;
}

// 3. Elimina el borrador y revisa si fue un reintento
eliminarBorrador(10231).then((body) => {
  if (!body) {
    return;
  }

  console.log(`Factura ${body.factura_id} eliminada: ${body.eliminada}`);
  console.log(`Reintento idempotente: ${body.idempotent_replay}`);
});

7. Buenas prácticas y límites conocidos

Recomendaciones

Límites de este servicio