# QRwey! API La API de **QRwey!** permite a los negocios generar códigos QR seguros y efímeros para representar intenciones de autofactura. - Los comercios registran una venta enviando los datos de la transacción. - La API retorna un **código QR** con un enlace seguro (deep link). - Los clientes escanean el QR con la app móvil de QRwey! y pueden consultar los detalles de la venta para generar un CFDi. - La API asegura la integridad de cada transacción usando **tokens opacos** firmados con **HMAC-SHA256**, con control de expiración y protección contra reuso. Version: 1.0.0 ## Servers Entorno de Producción ``` https://api.qrwey.com ``` Entorno de Desarrollo/Pruebas ``` https://api-dev.qrwey.com ``` ## Security ### ApiKeyAuth API Key proporcionada por QRwey! para autenticación de endpoints de operación de QR. Ejemplo: 17e82f0a-4693-40f0-974f-b7607c575cb8 Type: apiKey In: header Name: X-API-Key ### BearerAuth Token OAuth 2.0 (Bearer) para autenticación en la Gestión de Clientes. Se obtiene mediante el flujo de client credentials configurado en tu cuenta de QRwey!. Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [QRwey! API](https://developers.qrwey.com/_bundle/apis/QRwey.yaml) ## QRs Generación y consulta de códigos QR (intenciones de autofactura). ### Generar Código QR - [POST /v1/qrs](https://developers.qrwey.com/apis/qrwey/qrs/generateqr.md): Crea una nueva intención de autofactura y genera su correspondiente código QR seguro y efímero. ### Obtener detalle de QR - [GET /v1/qrs/{qrId}](https://developers.qrwey.com/apis/qrwey/qrs/getqrdetail.md): Obtiene el detalle completo de una transacción QR usando su identificador único. ## Grupos Gestión de grupos para organizar emisores. ### Crear grupo - [POST /v1/qrs/groups](https://developers.qrwey.com/apis/qrwey/grupos/creategroup.md): Registra un nuevo grupo asociado al customer del token. ### Listar grupos - [GET /v1/qrs/groups](https://developers.qrwey.com/apis/qrwey/grupos/getgroups.md): Devuelve una lista paginada de todos los grupos del customer. ### Obtener grupo por ID - [GET /v1/qrs/groups/{groupId}](https://developers.qrwey.com/apis/qrwey/grupos/getgroupbyid.md): Obtiene la información de un grupo específico. ### Actualizar grupo - [PUT /v1/qrs/groups/{groupId}](https://developers.qrwey.com/apis/qrwey/grupos/updategroup.md): Actualiza la información de un grupo existente. ## Emisores Gestión de emisores (RFCs) registrados ante el SAT. ### Crear emisor - [POST /v1/qrs/issuers](https://developers.qrwey.com/apis/qrwey/emisores/createissuer.md): Registra un nuevo emisor (RFC) asignado a un grupo. ### Listar emisores - [GET /v1/qrs/issuers](https://developers.qrwey.com/apis/qrwey/emisores/getissuers.md): Devuelve una lista paginada de emisores. Si se proporciona groupId, filtra por grupo. ### Obtener emisor por ID - [GET /v1/qrs/issuers/{issuerId}](https://developers.qrwey.com/apis/qrwey/emisores/getissuerbyid.md): Obtiene los detalles completos de un emisor específico. ### Actualizar emisor - [PUT /v1/qrs/issuers/{issuerId}](https://developers.qrwey.com/apis/qrwey/emisores/updateissuer.md): Actualiza alias, email, régimen fiscal y logo de un emisor existente. ### Sincronizar emisor con el SAT - [POST /v1/qrs/issuers/{issuerId}/synchronize](https://developers.qrwey.com/apis/qrwey/emisores/synchronizeissuer.md): Sincroniza los datos del emisor con la Constancia de Situación Fiscal (CSF) del SAT. ## Comercios Gestión de comercios, logos, llaves CSD y API keys. ### Crear comercio - [POST /v1/qrs/merchants](https://developers.qrwey.com/apis/qrwey/comercios/createmerchant.md): Registra un nuevo comercio asignado a un emisor de factura. ### Listar comercios - [GET /v1/qrs/merchants](https://developers.qrwey.com/apis/qrwey/comercios/getmerchants.md): Devuelve una lista paginada de comercios asignados a un emisor. ### Obtener comercio por ID - [GET /v1/qrs/merchants/{merchantId}](https://developers.qrwey.com/apis/qrwey/comercios/getmerchantbyid.md): Obtiene los detalles completos de un comercio específico. ### Actualizar comercio - [PUT /v1/qrs/merchants/{merchantId}](https://developers.qrwey.com/apis/qrwey/comercios/updatemerchant.md): Actualiza los datos de un comercio existente. ### Subir logos del comercio - [POST /v1/qrs/merchants/{merchantId}/logos](https://developers.qrwey.com/apis/qrwey/comercios/uploadmerchantlogos.md): Sube los logos (factura y app) de un comercio existente. ### Activar comercio - [PUT /v1/qrs/merchants/{merchantId}/status/active](https://developers.qrwey.com/apis/qrwey/comercios/activatemerchant.md): Activa un comercio actualizando su estatus a ACTIVE. ### Desactivar comercio - [PUT /v1/qrs/merchants/{merchantId}/status/inactive](https://developers.qrwey.com/apis/qrwey/comercios/deactivatemerchant.md): Inactiva un comercio actualizando su estatus a INACTIVE. ### Guardar modelo de facturación - [POST /v1/qrs/merchants/{merchantId}/invoice-mode](https://developers.qrwey.com/apis/qrwey/comercios/savemerchantinvoicemode.md): Guarda las llaves del SAT (CSD) para que un comercio pueda facturar. ### Actualizar modelo de facturación - [PUT /v1/qrs/merchants/{merchantId}/invoice-mode](https://developers.qrwey.com/apis/qrwey/comercios/updatemerchantinvoicemode.md): Actualiza las llaves del SAT (CSD) de un comercio. ### Obtener modelo de facturación - [GET /v1/qrs/merchants/{merchantId}/invoice-mode](https://developers.qrwey.com/apis/qrwey/comercios/getmerchantinvoicemode.md): Obtiene la información del modelo de facturación de un comercio. ### Regenerar llaves de acceso - [PUT /v1/qrs/merchants/{merchantId}/api-key/regenerate](https://developers.qrwey.com/apis/qrwey/comercios/regenerateapikey.md): Regenera las llaves de acceso de un comercio. La API Key anterior dejará de funcionar. ## Transacciones Consulta y cancelación de transacciones QR de comercios. ### Listar transacciones por comercio - [GET /v1/qrs/merchants/{merchantId}/transactions](https://developers.qrwey.com/apis/qrwey/transacciones/gettransactions.md): Devuelve una lista paginada de transacciones realizadas por un comercio. ### Obtener detalle de transacción - [GET /v1/qrs/merchants/{merchantId}/transactions/{transactionId}](https://developers.qrwey.com/apis/qrwey/transacciones/gettransactiondetail.md): Obtiene el detalle completo de una transacción QR. ### Cancelar transacción - [PATCH /v1/qrs/merchants/{merchantId}/transactions/{transactionId}/cancel](https://developers.qrwey.com/apis/qrwey/transacciones/canceltransaction.md): Cancela una transacción QR actualizando su estado a CANCELED. ## Reportes Reportes y métricas de consumo de clientes QRwey. ### Obtener top RFC por transacciones - [GET /v1/qrs/customers/reports/top-rfc](https://developers.qrwey.com/apis/qrwey/reportes/gettoprfc.md): Devuelve los RFC que más transacciones han realizado para el cliente en el mes actual. ### Obtener historial de consumo - [GET /v1/qrs/customers/reports/invoice-usage](https://developers.qrwey.com/apis/qrwey/reportes/getinvoiceusage.md): Devuelve una lista paginada del historial de consumo mensual del cliente. ### Obtener tarifa óptima - [GET /v1/qrs/customers/reports/optimal-tariff](https://developers.qrwey.com/apis/qrwey/reportes/getoptimaltariff.md): Calcula la tarifa más económica para el cliente con base en su consumo del mes actual. ## Planes Consulta de planes de facturación disponibles. ### Consultar planes QRwey - [GET /v1/qrs/budget/plans](https://developers.qrwey.com/apis/qrwey/planes/getbudgetplans.md): Devuelve los planes de facturación disponibles en QRwey. ## Catálogos SAT Consulta de catálogos oficiales del SAT. ### Obtener formas de pago - [GET /v1/qrs/sat-catalogs/payment-forms](https://developers.qrwey.com/apis/qrwey/catalogos-sat/getpaymentforms.md): Devuelve el catálogo de formas de pago del SAT. ### Obtener claves de unidad - [GET /v1/qrs/sat-catalogs/unit-keys](https://developers.qrwey.com/apis/qrwey/catalogos-sat/getunitkeys.md): Devuelve el catálogo paginado de claves de unidad del SAT con filtro por código o descripción. ### Obtener productos y servicios - [GET /v1/qrs/sat-catalogs/product-services](https://developers.qrwey.com/apis/qrwey/catalogos-sat/getproductservices.md): Devuelve el catálogo paginado de productos y servicios del SAT con filtro por código o descripción. ### Obtener permisos de operación EDS - [GET /v1/qrs/sat-catalogs/eds-operating-permits](https://developers.qrwey.com/apis/qrwey/catalogos-sat/getedsoperatingpermits.md): Devuelve el catálogo de permisos de operación de estaciones de servicio del SAT. ### Obtener motivos de cancelación - [GET /v1/qrs/sat-catalogs/cancellation-reasons](https://developers.qrwey.com/apis/qrwey/catalogos-sat/getcancellationreasons.md): Devuelve el catálogo de motivos de cancelación de CFDI del SAT. ## Facturación Timbrado directo de CFDI 4.0 (ingreso, notas de crédito, complementos de pago, cancelación y estatus). ### Timbrar CFDI 4.0 - [POST /v1/qrs/invoices](https://developers.qrwey.com/apis/qrwey/facturacion/stampcfdi.md): Genera y timbra un CFDI 4.0 de tipo Ingreso para el customer autenticado. ### Generar Nota de Crédito - [POST /v1/qrs/invoices/credit-notes](https://developers.qrwey.com/apis/qrwey/facturacion/stampcreditnote.md): Genera y timbra un CFDI 4.0 de tipo Egreso (nota de crédito) para el customer autenticado. ### Generar Complemento de Pago - [POST /v1/qrs/invoices/payment-complements](https://developers.qrwey.com/apis/qrwey/facturacion/stamppaymentcomplement.md): Genera y timbra un CFDI 4.0 de tipo Pago (complemento de pago) para el customer autenticado. ### Obtener detalle de CFDI - [GET /v1/qrs/invoices/detail/{uuid}](https://developers.qrwey.com/apis/qrwey/facturacion/getinvoicedetailbyuuid.md): Obtiene el detalle completo de un CFDI timbrado a partir de su UUID fiscal (folio fiscal). ### Listar facturas por integrador - [GET /v1/qrs/invoices/by-customer](https://developers.qrwey.com/apis/qrwey/facturacion/getinvoicesbycustomer.md): Devuelve una lista paginada de facturas emitidas por todos los comercios del customer autenticado. ### Listar facturas por emisor - [GET /v1/qrs/invoices/by-issuer/{issuerId}](https://developers.qrwey.com/apis/qrwey/facturacion/getinvoicesbyissuer.md): Devuelve una lista paginada de facturas emitidas por los comercios de un emisor (RFC) específico. ### Listar facturas por comercio - [GET /v1/qrs/invoices/by-merchant/{merchantId}](https://developers.qrwey.com/apis/qrwey/facturacion/getinvoicesbymerchant.md): Devuelve una lista paginada de facturas emitidas por un comercio específico. ### Consultar estatus de CFDI - [GET /v1/qrs/invoices/{invoiceId}/status](https://developers.qrwey.com/apis/qrwey/facturacion/getcfdistatus.md): Consulta el estatus actual de un CFDI ante el SAT y actualiza el registro local. ### Cancelar CFDI 4.0 - [DELETE /v1/qrs/invoices/{invoiceId}](https://developers.qrwey.com/apis/qrwey/facturacion/cancelcfdi.md): Cancela un CFDI 4.0 previamente timbrado para el customer autenticado.