**Nota sobre el envelope:** es una consulta de un solo registro, así que `pagination` y `filters_applied` siempre vienen como listas vacías. En una respuesta exitosa **no aparece** la clave `warnings`.
##### **Campos de la factura (`body`)**
**Ojo con los nombres.** En el detalle la fila trae `valor_saldo`, `consecutivo` y `fecha`; en el listado los mismos datos se llaman `saldo`, `factura_numero` y `fecha_factura`. Es intencional: cada servicio conserva su contrato.
##### **Campos de cada ítem (`items[]`)**
**Un borrador también se consulta.** Si la factura sigue en `estado_id = 5`, el detalle devuelve sus datos con `consecutivo` en cero o negativo, el `cufe` y el `estado_dian` en `null`. Es la forma de revisar el borrador antes de emitirlo.
**Los importes del detalle llegan como número.** A diferencia del listado, aquí `valor_total`, `valor_saldo` y los valores de cada ítem se entregan convertidos a número decimal. Aun así, valida el tipo en tu cliente antes de operar con ellos.
**Ojo con la forma:** los errores del middleware usan `statusCode` y `error.description`, no `success` ni `error_code`. El valor de `type` depende del manejador de errores de la versión desplegada (el libro publicado muestra `SERVER_ERROR` y el manejador actual responde `UNAUTHENTICATED`); lo estable es `statusCode` y la `description`.
**Trata el `404` como un caso de negocio**, no como una falla técnica: significa que el identificador no existe en nuby. No lo reintentes con el mismo valor.
**Buenas prácticas de seguridad:** el token viaja en el encabezado `Authorization`, nunca en la dirección (query string). No registres datos personales del tercero en tus logs: para trazar la consulta te basta con el `factura_id`.
cURL
```bash
TOKEN="TU_TOKEN_AQUI"
INSTANCIA="mi-inmobiliaria.nuby.app"
FACTURA_ID=10231
curl "https://${INSTANCIA}/service/v2/public/invoices/${FACTURA_ID}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
PHP
```php
Python
```python
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 = {
"Content-Type": "application/json",
"Authorization": f"Bearer {token}",
}
respuesta = requests.get(url, headers=headers, timeout=30)
# 3. Procesa la respuesta
if respuesta.status_code == 200:
factura = respuesta.json()["body"]
print(f"Factura {factura['consecutivo']} del {factura['fecha']}")
print(f"Total: {factura['valor_total']} - Saldo: {factura['valor_saldo']}")
print(f"Estado DIAN: {factura['estado_dian'] or 'sin enviar'}")
print(f"CUFE: {factura['cufe'] or 'sin CUFE'}")
print(f"PDF: {factura['pdf_link']}")
for item in factura["items"]:
print(f" - {item['descripcion']} x {item['cantidad']} = {item['valor_unitario']}")
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}")
```
JavaScript (Fetch API)
```javascript
// 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 consulta el detalle de una factura
async function obtenerFactura(facturaId) {
const url = `https://${instancia}/service/v2/public/invoices/${facturaId}`;
const response = await fetch(url, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'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. Consume el detalle
obtenerFactura(10231).then((factura) => {
if (!factura) {
return;
}
console.log(`Factura ${factura.consecutivo} del ${factura.fecha}`);
console.log(`Total: ${factura.valor_total} - Saldo: ${factura.valor_saldo}`);
console.log(`Estado DIAN: ${factura.estado_dian ?? 'sin enviar'}`);
console.log(`PDF: ${factura.pdf_link}`);
factura.items.forEach((item) => {
console.log(` - ${item.descripcion} x ${item.cantidad} = ${item.valor_unitario}`);
});
});
```
Power Query M (Excel / Power BI)
```m
let
// 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
facturaId = "10231", // Identificador interno de la factura
// 2. Prepara la dirección de la petición
url = "https://" & instancia & "/service/v2/public/invoices/" & facturaId,
// 3. Envía la petición GET
response = Web.Contents(url, [
Headers = [
#"Content-Type" = "application/json",
#"Authorization" = "Bearer " & token
]
]),
// 4. Decodifica la respuesta JSON y toma el cuerpo
jsonResponse = Json.Document(response),
factura = jsonResponse[body],
// 5. Cabecera como tabla de una fila
cabecera = Table.FromRecords({[
FacturaID = factura[factura_id],
Consecutivo = factura[consecutivo],
Fecha = factura[fecha],
FechaVencimiento = factura[fecha_vencimiento],
ValorTotal = factura[valor_total],
ValorSaldo = factura[valor_saldo],
EstadoDian = factura[estado_dian],
Cufe = factura[cufe],
PdfLink = factura[pdf_link],
TerceroID = factura[tercero_id]
]}),
// 6. Ítems como tabla aparte, unida por el identificador de la factura
items = Table.FromList(factura[items], Splitter.SplitByNothing(), null, null, ExtraValues.Error),
itemsExpandidos = Table.ExpandRecordColumn(items, "Column1",
{"detalle_id", "producto", "descripcion", "cantidad", "valor_unitario", "iva", "por_iva"},
{"DetalleID", "Producto", "Descripcion", "Cantidad", "ValorUnitario", "Iva", "PorIva"}),
itemsConFactura = Table.AddColumn(itemsExpandidos, "FacturaID", each factura[factura_id], Int64.Type)
in
itemsConFactura
```
**Sobre Power Query M:** el detalle de una factura se modela mejor como dos tablas (cabecera e ítems) relacionadas por `FacturaID`. El ejemplo devuelve los ítems; usa `cabecera` si solo necesitas los datos del documento.
- **Consulta el detalle solo cuando lo necesites.** El listado ya entrega el `factura_id`, los valores y el estado; el detalle agrega CUFE, ítems y el enlace del PDF.
- **Verifica `null` antes de usar un dato.** `cufe` y `estado_dian` llegan en `null` mientras la factura no se haya enviado.
- **Usa el detalle para confirmar el estado antes de emitir.** `estado_id` decide si la factura todavía se puede editar o emitir.
- **No uses `pdf_link` como enlace permanente.** Tiene vigencia de 30 días; pídelo de nuevo con el servicio de [PDF](https://docs.nuby.ai/obtener-pdf-factura.html).
- **No guardes el detalle como si fuera inmutable.** El estado DIAN y el saldo cambian con el tiempo: vuelve a consultar antes de tomar decisiones de cobro.
- **No registres datos personales en tus logs.** Para trazar una consulta te basta con el `factura_id`.
- **Solo devuelve facturas de venta.** Las de contrato se rechazan con `409 FACTURA_CONTRATO_NO_SOPORTADA`.
- **No devuelve el archivo PDF**, solo el enlace seguro de impresión.
- **No devuelve los datos del tercero.** Solo su `tercero_id`: para el nombre y el documento usa el listado o el servicio de terceros.
- **No devuelve las notas crédito o débito.** El conteo está en el listado (`notas`), pero el detalle de cada nota no forma parte de esta respuesta.
- **No pagina.** Es una consulta de un solo documento: `pagination` y `filters_applied` vienen como listas vacías.
- **No expone datos de contrato** (movimientos, documento de respaldo ni inmobiliaria): esta API es solo de venta.
- **No permite elegir campos.** La respuesta siempre trae el mismo conjunto de datos.
**¿Necesitas el listado completo?** El [**listado de facturas de venta**](https://docs.nuby.ai/listar-facturas-venta.html) devuelve los documentos paginados con sus filtros. ¿Solo necesitas el comprobante? Pide el [**enlace del PDF**](https://docs.nuby.ai/obtener-pdf-factura.html).