# Guías de QRwey!

Las Guías de QRwey! están diseñadas para ayudarte a integrar un **flujo completo de autofactura CFDi**
basado en **códigos QR**, desde el primer request hasta la generación de un **XML timbrado y su
representación impresa**.

Aquí aprenderás a integrar QRwey! de forma correcta, segura y lista para producción.

## ¿A quién van dirigidas estas guías?

QRwey! expone **dos APIs** según el tipo de integración, cada una con su propio esquema de autenticación:

- **Comercios** (puntos de venta que emiten intenciones de autofactura): consumen los endpoints de
**generación y resolución de QR**, autenticados con `X-API-Key`. Empieza por
[Autenticación](/guides/authentication) y [Generar código QR](/guides/generate-qr).
- **Integradores** (quienes tienen la relación comercial con QRwey! y administran grupos, emisores
de RFC y comercios): consumen la **Gestión de Clientes**, autenticado con
`Authorization: Bearer {access_token}`. Empieza por [Gestión de Clientes](/guides/customer-portal).


En la práctica, los Integradores dan de alta a los Comercios en el Portal y les emiten la
`X-API-Key` que el Comercio usa desde su backend. Los dos esquemas no son independientes:
están encadenados.

## ¿Qué aprenderás aquí?

A lo largo de estas guías aprenderás a:

- Autenticarte correctamente contra la API de QRwey!
- Generar **intenciones de autofactura** mediante códigos QR
- Obtener el detalle completo de una transacción QR
- Convertir una intención validada en un **CFDi timbrado (XML)**
- Generar la **representación impresa (PDF)** del CFDi
- Manejar expiración, idempotencia y errores
- Construir una integración confiable para entornos productivos


## Empieza aquí

Si es tu primera vez integrando QRwey!, comienza por aquí:

- **[Guía Rápida](/guides/quickstart)**
Integra un flujo completo: generar un QR, resolverlo y completar la autofactura.


## Conceptos básicos

Antes de ir a producción, es importante entender cómo funciona QRwey! y sus reglas principales:

- **[Cómo funciona QRwey!](/guides/introduction)**
Visión general del flujo de autofactura basado en QR.
- **[Autenticación](/guides/authentication)**
Cómo usar tu API Key de forma segura.
- **[Ciclo de vida del QR](/guides/qr-lifecycle)**
Estados, expiración y validaciones de los códigos QR.


## Operación

Estas guías cubren las operaciones principales que usarás en tu integración:

- **[Generar códigos QR](/guides/generate-qr)**
Crear intenciones de autofactura y generar códigos QR seguros.
- **[Obtener detalle de QR](/guides/resolve-qr)**
Obtener el detalle completo de una transacción QR por su identificador.


## Gestión de Clientes

La Gestión de Clientes permite gestionar tu configuración de facturación y timbrar CFDIs directamente:

- **[Gestión de Clientes](/guides/customer-portal)**
Visión general del API de la Gestión de Clientes.
- **[Gestión de grupos](/guides/groups)**
Crear y administrar grupos para organizar emisores.
- **[Gestión de emisores](/guides/issuers)**
Registrar y sincronizar emisores (RFCs) con el SAT.
- **[Gestión de comercios](/guides/merchants)**
Configurar comercios, llaves CSD y API keys.
- **[Gestión de transacciones](/guides/transactions)**
Consultar y cancelar transacciones de un comercio.
- **[Reportes del cliente](/guides/customer-reports)**
Consultar reportes de consumo, RFCs frecuentes y tarifa óptima.
- **[Catálogos SAT](/guides/sat-catalogs)**
Consultar formas de pago, claves de unidad y productos/servicios del SAT.
- **[Planes de facturación](/guides/budget-plans)**
Consultar planes disponibles y configuración del simulador de costos.


## Facturación

Estos endpoints permiten timbrar CFDIs 4.0 directamente desde el API:

- **[Timbrar CFDI 4.0](/guides/stamp-cfdi)**
Generar y timbrar facturas de ingreso (tipo I).
- **[Notas de crédito](/guides/credit-notes)**
Generar notas de crédito (tipo E) vinculadas a una factura existente.
- **[Complementos de pago](/guides/payment-complements)**
Generar complementos de pago (tipo P) para facturas con método PPD.
- **[Consulta de facturas](/guides/invoice-list)**
Listar facturas emitidas por integrador, emisor o comercio.
- **[Detalle de CFDI](/guides/cfdi-detail)**
Obtener el detalle completo de un CFDI timbrado por su UUID fiscal.
- **[Cancelar CFDI 4.0](/guides/cancel-cfdi)**
Cancelar un CFDI 4.0 previamente timbrado.
- **[Consultar estatus de CFDI](/guides/cfdi-status)**
Consultar el estatus actual de un CFDI ante el SAT.


## Confiabilidad y seguridad

Para evitar errores, duplicados y comportamientos inesperados:

- **[Idempotencia & Reintentos](/guides/idempotency)**
Cómo prevenir operaciones duplicadas.
- **[Manejo de errores](/guides/error-handling)**
Interpretar códigos de error y actuar correctamente.
- **[Expiración & Reuso de tokens](/guides/expiration-and-reuse)**
Qué pasa cuando un QR expira o ya fue consumido.


## Buenas prácticas

Para operar QRwey! correctamente en producción:

- **[Uso responsable](/legal/responsible-use)**
Lineamientos y buenas prácticas de uso.
- **[Preguntas frecuentes](/tools/faq)**
Respuestas a dudas comunes de integración y operación.


## Siguiente paso

Cuando tengas dudas sobre parámetros específicos, esquemas o respuestas exactas,
consulta siempre la **[Referencia del API](/apis/qrwey)**, generada directamente a partir
del OpenAPI oficial.