143 lines
5.6 KiB
Markdown
143 lines
5.6 KiB
Markdown
---
|
|
title: "Código QR Pix Estático: Cómo Funciona y Responsabilidades del Desarrollador"
|
|
description: "Entendé qué es el QR Pix estático, cómo lo genera la API, sus limitaciones ha por qué la verificación del pago es responsabilidad de tu aplicación — no de QRRapido."
|
|
keywords: "qr code pix, pix estatico, qr code pix api, integración pix qr code paraguay, pix sin bacen"
|
|
author: "QRRapido"
|
|
date: 2026-03-08
|
|
lastmod: 2026-03-08
|
|
image: ""
|
|
---
|
|
|
|
# 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** ha **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 ha 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) ha genera la imagen:
|
|
|
|
```json
|
|
{
|
|
"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 (ha 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:
|
|
|
|
1. **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.
|
|
|
|
2. **No hay webhook de confirmación de pago.** La API no envía notificaciones cuando se recibe un Pix.
|
|
|
|
3. **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).
|
|
|
|
4. **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 usás 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
|
|
Conectate 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
|
|
Usá 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
|
|
|
|
```bash
|
|
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 ha comprador interactúan presencialmente ha 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 ha 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** — ha eso, ñande lo tenemos claro ko'aga.
|