Consultar una Factura

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

---

Endpoint

GET https://sandbox-api.lummy.com/invoices/{invoiceId}

---

Parámetros de Ruta

Parámetro	Tipo	Descripción
invoiceId	string (UUID)	ID interno de la factura en Lummy

---

Headers Requeridos

Header	Valor	Descripción
x-organization-id	string (UUID)	ID de tu organización
x-api-key	string	Tu API Key

---

Ejemplos de Código

cURL

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

Node.js (TypeScript)

import axios from 'axios';

async function consultarFactura(invoiceId: string) {
  const API_URL = `https://sandbox-api.lummy.com/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');

Python

import os
import requests

def consultar_factura(invoice_id: str):
    """Consulta los detalles de una factura por su ID."""
    api_url = f"https://sandbox-api.lummy.com/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 (Guzzle)

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

function consultarFactura(string $invoiceId): array
{
    $apiUrl = "https://sandbox-api.lummy.com/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

Respuesta Exitosa (HTTP 200 OK)

{
  "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:00Z",
  "receptor": {
    "rfc": "XAXX010101000",
    "nombre": "PUBLICO EN GENERAL"
  },
  "total": 1160.00,
  "moneda": "MXN",
  "verificationUrl": "https://verificacfdi.facturaelectronica.sat.gob.mx/...",
  "xmlS3Url": "https://lummy-invoices.s3.amazonaws.com/.../factura.xml",
  "pdfS3Url": "https://lummy-invoices.s3.amazonaws.com/.../factura.pdf",
  "createdAt": "2025-11-19T10:00:05Z",
  "updatedAt": "2025-11-19T10:00:05Z"
}

Campos de la Respuesta

Campo	Tipo	Descripción
invoiceId	string (UUID)	ID interno de la factura
cfdiUuid	string (UUID)	UUID fiscal del SAT (Folio Fiscal)
status	string	Estado: active, cancelled, pending
tipoDeComprobante	string	Tipo de comprobante (I, E, T, P, N)
total	number	Total del comprobante
verificationUrl	string (URL)	URL de verificación en el portal del SAT
xmlS3Url	string (URL)	URL de descarga del XML
pdfS3Url	string (URL)	URL de descarga del PDF

---

Respuesta de Error (HTTP 404 Not Found)

{
  "statusCode": 404,
  "message": "Invoice not found",
  "error": "Not Found"
}

---

Consultar por UUID Fiscal

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

GET https://sandbox-api.lummy.com/invoices/by-uuid/{cfdiUuid}

Ejemplo:

curl -X GET "https://sandbox-api.lummy.com/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://sandbox-api.lummy.com/invoices?page=1&limit=50

Query Parameters:

Parámetro	Tipo	Por Defecto	Descripción
page	number	1	Número de página
limit	number	50	Facturas por página (máx. 100)
status	string	-	Filtrar por estado: active, cancelled
startDate	string (ISO 8601)	-	Fecha inicio (YYYY-MM-DD)
endDate	string (ISO 8601)	-	Fecha fin (YYYY-MM-DD)

Ejemplo:

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

Respuesta:

{
  "data": [
    { /* factura 1 */ },
    { /* factura 2 */ }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 10,
    "totalItems": 200,
    "itemsPerPage": 20
  }
}

---

Próximos Pasos

• Cancelar una Factura
• Emitir una Factura