# Detalle de CFDI

Este endpoint permite **obtener el detalle completo de un CFDI timbrado** a partir de su
UUID fiscal (folio fiscal). Devuelve toda la información del comprobante incluyendo datos
del emisor, receptor, conceptos, impuestos y la URL de verificación ante el SAT.

Es útil para:

- Mostrar el detalle de una factura al usuario
- Obtener los datos fiscales completos del comprobante
- Verificar la información del CFDI timbrado


## Endpoint

```
GET /v1/qrs/invoices/detail/{uuid}
```

**Host (DEV):**

```
https://api-dev.qrwey.com
```

**Host (PROD):**

```
https://api.qrwey.com
```

## Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

## Parámetros de ruta

| Parámetro | Descripción |
|  --- | --- |
| `uuid` | UUID fiscal (folio fiscal) del CFDI (ej. `A1B2C3D4-E5F6-7890-ABCD-EF1234567890`) |


## Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/invoices/detail/A1B2C3D4-E5F6-7890-ABCD-EF1234567890" \
  -H "Authorization: Bearer {{access_token}}"
```

## Respuesta

```json
{
  "uuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "invoiceDate": "2026-03-19T14:30:00",
  "invoiceStatus": "GENERATED",
  "serie": "A",
  "folio": "1001",
  "cancellationRequestReason": null,
  "issuerTaxId": "FUNK671228PH6",
  "issuerLegalName": "KARLA FUENTE NOLASCO",
  "issuerZip": "06600",
  "issuerTaxRegimeCode": "601",
  "issuerTaxRegimeDesc": "General de Ley Personas Morales",
  "issuerCertificateNumber": "30001000000500003416",
  "receiverTaxId": "EKU9003173C9",
  "receiverLegalName": "ESCUELA KEMPER URGATE",
  "receiverTaxRegimeCode": "601",
  "receiverTaxRegimeDesc": "General de Ley Personas Morales",
  "cfdiUsageCode": "G03",
  "cfdiUsageDesc": "Gastos en general",
  "paymentFormCode": "04",
  "paymentFormDesc": "Tarjeta de crédito",
  "paymentMethodCode": "PUE",
  "paymentMethodDesc": "Pago en una sola exhibición",
  "currency": "MXN",
  "exchangeRate": "1",
  "invoiceItems": [
    {
      "satCode": "15101515",
      "description": "Gasolina Magna",
      "quantity": 49.210,
      "unitPrice": 20.321,
      "totalAmount": 1000.00
    }
  ],
  "urlSat": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?&id=A1B2C3D4-E5F6-7890-ABCD-EF1234567890&re=FUNK671228PH6&rr=EKU9003173C9&tt=0000000001160.000000&fe=abcd1234",
  "subtotal": 1000.00,
  "total": 1160.00,
  "iva": 160.00
}
```

### Campos de la respuesta

| Campo | Descripción |
|  --- | --- |
| `uuid` | UUID fiscal (folio fiscal) del CFDI |
| `invoiceDate` | Fecha de timbrado del CFDI |
| `invoiceStatus` | Estado del CFDI: `GENERATED`, `CANCELLED`, `CANCEL_REQUESTED`, `CANCEL_IN_PROGRESS` |
| `serie` | Serie del comprobante |
| `folio` | Folio del comprobante |
| `cancellationRequestReason` | Motivo de cancelación (solo si aplica) |


### Datos del emisor

| Campo | Descripción |
|  --- | --- |
| `issuerTaxId` | RFC del emisor |
| `issuerLegalName` | Razón social del emisor |
| `issuerZip` | Código postal del lugar de expedición |
| `issuerTaxRegimeCode` | Clave del régimen fiscal del emisor |
| `issuerTaxRegimeDesc` | Descripción del régimen fiscal del emisor |
| `issuerCertificateNumber` | Número de certificado del CSD del emisor |


### Datos del receptor

| Campo | Descripción |
|  --- | --- |
| `receiverTaxId` | RFC del receptor |
| `receiverLegalName` | Razón social del receptor |
| `receiverTaxRegimeCode` | Clave del régimen fiscal del receptor |
| `receiverTaxRegimeDesc` | Descripción del régimen fiscal del receptor |


### Datos fiscales

| Campo | Descripción |
|  --- | --- |
| `cfdiUsageCode` | Clave de uso del CFDI SAT |
| `cfdiUsageDesc` | Descripción del uso del CFDI |
| `paymentFormCode` | Clave de forma de pago SAT |
| `paymentFormDesc` | Descripción de la forma de pago |
| `paymentMethodCode` | Clave del método de pago SAT |
| `paymentMethodDesc` | Descripción del método de pago |
| `currency` | Moneda del CFDI |
| `exchangeRate` | Tasa de cambio |


### Conceptos (`invoiceItems`)

| Campo | Descripción |
|  --- | --- |
| `satCode` | Clave de producto/servicio SAT |
| `description` | Descripción del concepto |
| `quantity` | Cantidad |
| `unitPrice` | Precio unitario |
| `totalAmount` | Importe total del concepto |


### Totales y verificación

| Campo | Descripción |
|  --- | --- |
| `subtotal` | Subtotal del CFDI |
| `iva` | IVA calculado |
| `total` | Total del CFDI |
| `urlSat` | URL de verificación del CFDI ante el SAT |


## Descargar el PDF del CFDI

Para obtener la **representación impresa (PDF)** de un CFDI a partir de su UUID fiscal, usa el
siguiente endpoint. El PDF se devuelve **codificado en Base64**, listo para decodificar y
guardar o mostrar al usuario. Solo es accesible por el integrador dueño de la factura.

```
GET /v1/qrs/invoices/uuid/{uuid}/pdf
```

### Headers requeridos

```http
Authorization: Bearer {{access_token}}
```

### Parámetros de ruta

| Parámetro | Descripción |
|  --- | --- |
| `uuid` | UUID fiscal (folio fiscal) del CFDI (ej. `A1B2C3D4-E5F6-7890-ABCD-EF1234567890`) |


### Ejemplo de request (DEV)

```bash
curl -X GET "https://api-dev.qrwey.com/v1/qrs/invoices/uuid/A1B2C3D4-E5F6-7890-ABCD-EF1234567890/pdf" \
  -H "Authorization: Bearer {{access_token}}"
```

### Respuesta

```json
{
  "uuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
  "pdfBase64": "JVBERi0xLjQKJeLjz9MK...=="
}
```

| Campo | Descripción |
|  --- | --- |
| `uuid` | UUID fiscal (folio fiscal) del CFDI |
| `pdfBase64` | Representación impresa (PDF) del CFDI codificada en Base64 |


> Decodifica el valor de `pdfBase64` para reconstruir el archivo `.pdf`. Si el PDF aún no ha
sido generado, la operación fallará con error `400`.


## Errores comunes

| Código | Motivo |
|  --- | --- |
| 400 | No fue posible obtener el detalle del CFDI o el PDF aún no ha sido generado (XML corrupto o factura no timbrada) |
| 401 | Token inválido o expirado |
| 403 | No tiene acceso a la factura solicitada |
| 404 | Factura no encontrada con el UUID proporcionado |


Consulta: [Manejo de errores](/guides/error-handling)

## Buenas prácticas

- Usa este endpoint para mostrar el detalle completo de una factura al usuario.
- El campo `urlSat` puede usarse para que el usuario verifique el CFDI directamente en el portal del SAT.
- Solo CFDIs con estatus `GENERATED`, `CANCELLED`, `CANCEL_REQUESTED` o `CANCEL_IN_PROGRESS` devuelven detalle. Si la factura tiene otro estatus, la operación fallará con error `400`.


## ¿Qué sigue?

- Consulta el estatus ante el SAT: [Consultar estatus de CFDI](/guides/cfdi-status)
- Cancela un CFDI: [Cancelar CFDI 4.0](/guides/cancel-cfdi)
- Vuelve al índice: [Gestión de Clientes](/guides/customer-portal)