Ricardo Carneiro 9c393f01e5 fix: trocar es-PY por es

2026-03-09 11:45:55 -03:00

5.5 KiB

Raw Permalink Blame History

title	description	keywords	author	date	lastmod	image
Código QR Pix Estático: Cómo Funciona y Responsabilidades del Desarrollador	Entiende qué es el QR Pix estático, cómo lo genera la API, sus limitaciones y por qué la verificación del pago es responsabilidad de tu aplicación — no de QRRapido.	qr code pix, pix estatico, qr code pix api, integración pix qr code, pix sin bacen	QRRapido	2026-03-08	2026-03-08

Código QR Pix Estático: Cómo Funciona y Responsabilidades del Desarrollador

¿Qué es un Código QR Pix Estático?

El Pix tiene dos tipos de QR: estático y dinámico.

	Pix Estático	Pix Dinámico
Valor	Variable (lo decide el pagador)	Fijo (definido por el receptor)
Generación	Cualquier sistema	Intermediario PSP/BACEN
Registro en BACEN	No	Sí
Notificación de pago	No	Sí (webhook)
Uso típico	Donaciones, cobros simples	E-commerce, cobro con control

La API QRRapido genera exclusivamente QR Pix estático. Eso es intencional y suficiente para la mayoría de los casos de uso.

Cómo la API Genera el QR Pix

Al enviar una solicitud con type: "pix", la API arma un string en el estándar EMV® QR Code (estándar internacional adoptado por el Banco Central de Brasil) y genera la imagen:

{
  "type": "pix",
  "content": "contacto@tuempresa.com.br"
}

El campo content debe contener solo la clave Pix del receptor. La API se encarga de armar el payload EMV correctamente.

Claves aceptadas:

E-mail: contacto@empresa.com.br
CPF/CNPJ: solo dígitos — 12345678901 o 12345678000195
Teléfono: +5511999999999
Clave aleatoria (EVP): 123e4567-e89b-12d3-a456-426614174000

Lo que la API NO hace (y por qué eso importa)

QRRapido no tiene integración con el Banco Central, con ningún banco ni PSP (Proveedor de Servicio de Pago).

Eso significa:

La API no sabe si el pago fue realizado. Solo genera la imagen del QR. Lo que pasa después — si el cliente escaneó, si el Pix fue enviado, si llegó a la cuenta correcta — está fuera del alcance de la API.
No hay webhook de confirmación de pago. La API no envía notificaciones cuando se recibe un Pix.
El QR no expira automáticamente. Un QR Pix estático es válido indefinidamente (o hasta que la clave Pix sea eliminada por el receptor en su banco).
No hay rastreabilidad de transacción. Dos solicitudes con la misma clave generan el mismo QR (con caché). No es posible asociar un escaneo a una transacción específica vía API.

Responsabilidad de Tu Aplicación

Si usas la API para generar QR Pix en un flujo de pago, es responsabilidad de tu aplicación verificar el cobro. Las formas correctas de hacerlo son:

Opción 1 — API Pix del Banco del Receptor

Conéctate directamente a la API Pix del banco donde está registrada la clave. La mayoría de los bancos ofrece:

Consulta de cobros recibidos
Webhook de notificación en tiempo real (cuando el banco lo soporta)

Opción 2 — PSP / Gateway de Pago

Usa un intermediario como Mercado Pago, PagSeguro, Efí Bank, Asaas, etc. Ofrecen Pix dinámico con control completo: valor fijo, expiración, webhooks e identificación única por cobro.

Opción 3 — Verificación Manual

Para volúmenes bajos o contextos informales (donaciones, ventas presenciales), el responsable del cobro verifica el extracto bancario manualmente.

Flujo Recomendado (con confirmación)

Tu App                     API QRRapido           Banco del Receptor
    |                           |                        |
    |-- POST /generate (pix) -->|                        |
    |<-- qrCodeBase64 ----------|                        |
    |                           |                        |
    |-- Muestra QR al cliente   |                        |
    |                           |                        |
    |-- Consulta pago ---------------------------------->|
    |<-- Estado recibido o no ----------------------------|
    |                           |                        |
    |-- Libera producto/servicio|                        |

Ejemplo de Solicitud Completa

curl -X POST https://qrrapido.site/api/v1/QRManager/generate \
  -H "X-API-Key: tu_clave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "contacto@tuempresa.com.br",
    "type": "pix",
    "size": 400,
    "outputFormat": "webp"
  }'

Casos de Uso Adecuados para Pix Estático vía API

QR de donación en sitio institucional
Menú digital con clave para pago presencial
Generación de QR en lote para materiales impresos (flyers, tarjetas)
Aplicaciones donde el vendedor y comprador interactúan presencialmente y el vendedor confirma el cobro en la app del banco

Casos de Uso que Requieren Pix Dinámico (no cubiertos por esta API)

E-commerce con confirmación automática del pedido
Cobro con valor fijo y expiración
Emisión de factura vinculada al pago
Conciliación financiera automatizada

Resumen

Lo que la API hace	Lo que la API NO hace
Genera la imagen del QR Pix	Verifica si el pago fue hecho
Formatea el payload EMV correctamente	Envía webhook de confirmación
Entrega PNG, WebP o SVG	Se comunica con el BACEN o bancos
Funciona con cualquier clave Pix válida	Garantiza que la clave pertenece a quien dice

La generación correcta del QR es responsabilidad de la API. La confirmación del pago es responsabilidad de tu aplicación — y eso queda claro desde el principio.

5.5 KiB Raw Permalink Blame History