Consultar una Factura

Obtén los detalles completos de una factura previamente emitida utilizando su invoiceId o cfdiUuid.

Endpoint

GET https://api.lummy.io/v1/invoices/{invoiceId}

Entorno	URL
Producción	`https://api.lummy.io/v1/invoices/{invoiceId}`
Sandbox	`https://sandbox.lummy.io/v1/invoices/{invoiceId}`

Parámetros de Ruta

{

"invoiceId": string (UUID)requerido

↳Identificador único interno de la factura en el sistema Lummy. Se genera automáticamente al momento de crear la factura y se utiliza para todas las operaciones subsecuentes de consulta, actualización o cancelación del CFDI.

}

Headers Requeridos

{

"x-organization-id": string (UUID),requerido

↳Identificador único de tu organización en Lummy. Este valor se obtiene al crear tu cuenta y es necesario para todas las operaciones relacionadas con facturación electrónica.

"x-api-key": stringrequerido

↳Clave de API para autenticación. Se genera desde el panel de Lummy y debe mantenerse confidencial. Es una alternativa al token Bearer JWT para autenticar tus solicitudes.

}

Ejemplos de Código

cURL
Node.js (TypeScript)
Python
PHP (Guzzle)

curl -X GET "https://sandbox.lummy.io/invoices/d290f1ee-6c54-4b01-90e6-d701748f0851" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}"

import axios from 'axios';

async function consultarFactura(invoiceId: string) {
  const API_URL = `https://sandbox.lummy.io/invoices/${invoiceId}`;

  try {
    const response = await axios.get(API_URL, {
      headers: {
        'x-organization-id': process.env.LUMMY_ORG_ID!,
        'x-api-key': process.env.LUMMY_API_KEY!,
      },
    });

    console.log('Factura encontrada:', response.data);
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error('Error consultando factura:', error.response?.data);
      throw error;
    }
    throw error;
  }
}

// Uso
consultarFactura('d290f1ee-6c54-4b01-90e6-d701748f0851');

import os
import requests

def consultar_factura(invoice_id: str):
    """Consulta los detalles de una factura por su ID."""
    api_url = f"https://sandbox.lummy.io/invoices/{invoice_id}"

    headers = {
        "x-organization-id": os.getenv("LUMMY_ORG_ID"),
        "x-api-key": os.getenv("LUMMY_API_KEY"),
    }

    try:
        response = requests.get(api_url, headers=headers, timeout=30)
        response.raise_for_status()

        data = response.json()
        print(f"Factura encontrada: {data['cfdiUuid']}")
        return data

    except requests.exceptions.HTTPError as e:
        print(f"Error HTTP: {e.response.status_code}")
        print(f"Respuesta: {e.response.json()}")
        raise

# Uso
consultar_factura("d290f1ee-6c54-4b01-90e6-d701748f0851")

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

function consultarFactura(string $invoiceId): array
{
    $apiUrl = "https://sandbox.lummy.io/invoices/{$invoiceId}";

    $client = new Client([
        'timeout' => 30,
        'headers' => [
            'x-organization-id' => getenv('LUMMY_ORG_ID'),
            'x-api-key' => getenv('LUMMY_API_KEY'),
        ],
    ]);

    try {
        $response = $client->get($apiUrl);
        $data = json_decode($response->getBody()->getContents(), true);

        echo "Factura encontrada: {$data['cfdiUuid']}\n";
        return $data;

    } catch (RequestException $e) {
        $statusCode = $e->getResponse() ? $e->getResponse()->getStatusCode() : 'N/A';
        $errorBody = $e->getResponse() ? $e->getResponse()->getBody()->getContents() : 'Sin detalles';

        echo "Error HTTP {$statusCode}\n";
        echo "Respuesta: {$errorBody}\n";

        throw $e;
    }
}

// Uso
consultarFactura("d290f1ee-6c54-4b01-90e6-d701748f0851");

Response

Todas las respuestas siguen el formato estándar StandardResponse.

Respuesta Exitosa (HTTP 200 OK)

{
  "requestId": "abc123-def456",
  "data": {
    "invoiceId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "cfdiUuid": "cfa52b8b-93f2-4e6b-8c73-64ad88deb17c",
    "status": "active",
    "tipoDeComprobante": "I",
    "serie": "F",
    "folio": "1234",
    "fecha": "2025-11-19T10:00:00.000Z",
    "receptor": {
      "rfc": "XAXX010101000",
      "nombre": "PUBLICO EN GENERAL"
    },
    "total": 1160.00,
    "moneda": "MXN",
    "verificationUrl": "https://verificacfdi.facturaelectronica.sat.gob.mx/...",
    "xmlUrl": "https://lummy-invoices.s3.amazonaws.com/.../factura.xml",
    "pdfUrl": "https://lummy-invoices.s3.amazonaws.com/.../factura.pdf",
    "createdAt": "2025-11-19T10:00:05.000Z",
    "updatedAt": "2025-11-19T10:00:05.000Z"
  },
  "timestamp": "2025-11-19T10:00:05.000Z",
  "path": "/invoices/d290f1ee-6c54-4b01-90e6-d701748f0851",
  "method": "GET"
}

Campos de la Respuesta

{

"invoiceId": string (UUID),requerido

↳Identificador único interno de la factura en el sistema Lummy.

"cfdiUuid": string (UUID),requerido

↳Folio fiscal (UUID) asignado por el SAT al momento del timbrado. Es el identificador único e irrepetible del CFDI ante el SAT y se utiliza para todas las operaciones de validación, verificación y cancelación del comprobante fiscal.

"status": string,requerido

↳Estado actual del CFDI. Valores posibles: "active" (CFDI vigente y válido), "cancelled" (CFDI cancelado ante el SAT), "pending" (CFDI en proceso de timbrado). El estado determina la validez fiscal del comprobante.

"tipoDeComprobante": string,requerido

↳Clave del tipo de comprobante según el catálogo c_TipoDeComprobante del SAT. Valores: "I" (Ingreso), "E" (Egreso), "T" (Traslado), "P" (Pago), "N" (Nómina). Define la naturaleza de la operación fiscal documentada.

"total": number,requerido

↳Importe total del comprobante en la moneda especificada. Incluye subtotal más impuestos trasladados menos impuestos retenidos. Este valor debe coincidir con el total calculado en el XML del CFDI.

"verificationUrl": string (URL),requerido

↳URL del portal del SAT para verificar la autenticidad y vigencia del CFDI. Permite consultar el estado del comprobante directamente en los sistemas del SAT ingresando el UUID, RFC emisor, RFC receptor y total.

"xmlUrl": string (URL),requerido

↳URL de descarga del archivo XML del CFDI timbrado y sellado. El XML es el documento fiscal oficial que debe conservarse durante 5 años según la legislación fiscal mexicana. Incluye el timbre fiscal digital del SAT.

"pdfUrl": string (URL)requerido

↳URL de descarga de la representación impresa del CFDI en formato PDF. Es un documento de cortesía para facilitar la lectura del comprobante, pero el documento fiscal oficial es el XML.

}

Respuesta de Error (HTTP 404 Not Found)

{
  "requestId": "abc123-def456",
  "error": {
    "message": "Invoice not found",
    "code": "NotFoundException",
    "status": 404
  },
  "timestamp": "2025-11-19T10:00:05.000Z",
  "path": "/invoices/d290f1ee-6c54-4b01-90e6-d701748f0851",
  "method": "GET"
}

Consultar por UUID Fiscal

También puedes consultar una factura usando su UUID fiscal (cfdiUuid):

GET https://api.lummy.io/v1/invoices/by-uuid/{cfdiUuid}

Entorno	URL
Producción	`https://api.lummy.io/v1/invoices/by-uuid/{cfdiUuid}`
Sandbox	`https://sandbox.lummy.io/v1/invoices/by-uuid/{cfdiUuid}`

Ejemplo:

curl -X GET "https://sandbox.lummy.io/invoices/by-uuid/cfa52b8b-93f2-4e6b-8c73-64ad88deb17c" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}"

Listar Facturas (Paginación)

Para obtener un listado paginado de todas tus facturas:

GET https://api.lummy.io/v1/invoices?page=1&limit=50

Entorno	URL
Producción	`https://api.lummy.io/v1/invoices`
Sandbox	`https://sandbox.lummy.io/v1/invoices`

Query Parameters

{

"page": number,opcional

↳Número de página para la paginación de resultados. Por defecto es 1. Permite navegar a través de múltiples páginas de facturas cuando el total de registros excede el límite especificado.

"limit": number,opcional

↳Cantidad de facturas a retornar por página. Por defecto es 50. El valor máximo permitido es 100. Un límite mayor mejora el rendimiento al reducir el número de solicitudes necesarias para obtener grandes volúmenes de datos.

"status": string,opcional

↳Filtro por estado del CFDI. Valores permitidos: "active" (CFDIs vigentes), "cancelled" (CFDIs cancelados ante el SAT). Si se omite, se retornan facturas de todos los estados.

"startDate": string (ISO 8601),opcional

↳Fecha de inicio para filtrar facturas por fecha de emisión. Formato: YYYY-MM-DD. Incluye todas las facturas emitidas desde esta fecha (inclusive) hasta la fecha fin especificada o hasta la fecha actual.

"endDate": string (ISO 8601)opcional

↳Fecha de fin para filtrar facturas por fecha de emisión. Formato: YYYY-MM-DD. Incluye todas las facturas emitidas hasta esta fecha (inclusive). Si se omite, se usa la fecha actual.

}

Ejemplo:

curl -X GET "https://sandbox.lummy.io/invoices?page=1&limit=20&status=active" \
  -H "x-organization-id: ${LUMMY_ORG_ID}" \
  -H "x-api-key: ${LUMMY_API_KEY}"

Respuesta:

{
  "requestId": "abc123-def456",
  "data": [
    { /* factura 1 */ },
    { /* factura 2 */ }
  ],
  "total": 200,
  "page": 1,
  "limit": 20,
  "totalPages": 10,
  "timestamp": "2025-11-19T10:00:05.000Z",
  "path": "/invoices",
  "method": "GET"
}

Endpoint​

Parámetros de Ruta​

Headers Requeridos​

Ejemplos de Código​

Response​

Respuesta Exitosa (HTTP 200 OK)​

Campos de la Respuesta​

Respuesta de Error (HTTP 404 Not Found)​

Consultar por UUID Fiscal​

Listar Facturas (Paginación)​

Query Parameters​

Próximos Pasos​