Ir al contenido principal

API de códigos QR: un código QR o un QR de pago SEPA en una llamada


Una llamada HTTP, y recibes la imagen de un código QR lista para pegar en un cartel, una factura o un sitio web. Texto, enlace, Wi-Fi, o incluso una transferencia SEPA que tu cliente solo tiene que escanear con su aplicación bancaria.

No hay ninguna biblioteca que instalar, ni ninguna cuenta en un servicio que te planta su logo en medio del código. La API devuelve directamente un archivo PNG o SVG, y eso es todo lo que hace. Este es el aspecto del resultado:

Ejemplo de código QR en blanco y negro generado por la API de Digital3D

Gratis o PRO: lo que tienes

Las dos fórmulas hacen exactamente lo mismo, con los mismos formatos y los mismos tamaños. No hay ni marca de agua ni códigos QR que caduquen. La única diferencia es el número de códigos al día. La barra verde muestra lo que puedes generar en un día.

API gratuita

0 €, basta con la clave de tu cuenta

10al día
  • 10 códigos QR al día
  • QR clásico y QR de pago SEPA
  • PNG y SVG, todos los tamaños, sin marca de agua
  • Lo necesario para hacer tus carteles, tus tarjetas de visita o unas cuantas facturas

API PRO

12 € al mes, todos mis programas incluidos

1000 al día
  • 1000 códigos QR al día
  • Suficiente para un QR de pago en cada factura de un programa de gestión
  • La guía de TV completa durante 11 días y mis programas de regalo
  • Activo desde la siguiente solicitud, con la misma clave

Pasar a PRO

El contador vuelve a empezar a medianoche UTC, es decir, a la 1 o a las 2 de la madrugada en Francia según la estación. Y buenas noticias para los torpes: una solicitud mal formada, un IBAN falso, un texto vacío, se rechaza antes incluso de mirar tu clave, así que no cuesta nada.

Obtener tu clave

Tardas un minuto: crea una cuenta, valida tu dirección de correo electrónico y luego copia la clave que aparece en tu cuenta. Es la misma clave que para mis otros servicios. Se envía en la cabecera Authorization de cada solicitud, en lugar de VotreCleApi en los ejemplos que siguen.

¿Utilizabas la versión antigua con userId en la URL o en el JSON? Este parámetro ya no se lee, ahora la clave pasa únicamente por la cabecera. Consecuencia: ya no se puede pegar la dirección tal cual en la barra del navegador. Para probar con el ratón, está Swagger, vuelvo sobre ello más abajo.

El QR clásico: texto, enlace, Wi-Fi

Es la llamada NormalQr, un simple GET. Tú proporcionas el texto, recibes la imagen:

curl -H "Authorization: Bearer VotreCleApi" "https://qr.digital3d.com/api/QrCreator/NormalQr?text=https%3A%2F%2Fdigital3d.com&format=Png&size=6" -o qr.png
ParámetroValoresLo que hace
textObligatorioEl contenido que hay que codificar. Acuérdate de codificarlo para una URL (los :, / y & deben escaparse).
formatPng (por defecto) o SvgEl tipo de imagen devuelto.
sizeDe 1 a 20, 4 por defectoEl tamaño de cada pequeño cuadrado del código, en píxeles para un PNG.

Donde se pone divertido es que el texto no tiene por qué ser un enlace. Un teléfono sabe interpretar varios formatos. El más práctico en casa: el QR del Wi-Fi, para imprimirlo y pegarlo en la nevera para los invitados. El texto que hay que codificar se parece a esto:

WIFI:T:WPA;S:NomDuReseau;P:MotDePasse;;

El mismo principio con mailto:quelquun@example.com para abrir un correo electrónico, o con una vCard (el formato de las fichas de contacto) para que un escaneo añada tus datos al directorio.

El QR de pago SEPA

Este me gusta mucho. Pones un QR en tu factura, tu cliente lo escanea con su aplicación bancaria, y la transferencia ya está rellenada: beneficiario, IBAN, importe, comunicación. Ya nadie copia un IBAN mal. Es la llamada PaymentQr, un POST con un cuerpo JSON :

curl -X POST "https://qr.digital3d.com/api/QrCreator/PaymentQr" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "Content-Type: application/json" \
  -o paiement.svg \
  -d '{
    "beneficiaryName": "ACME SRL",
    "iban": "BE68539007547034",
    "bic": "GKCCBEBB",
    "amount": 12.34,
    "remittance": "Facture 2026-001",
    "outputFormat": "Svg",
    "size": 8
  }'
CampoObligatorioQué contiene
beneficiaryNameSíEl nombre de quien recibe el dinero, 70 caracteres como máximo.
ibanSíSu cuenta. El IBAN se verifica, se rechaza un número no válido.
bicNoEl código del banco, 8 u 11 caracteres en mayúsculas.
amountNo, pero recomendadoEl importe en euros, de 0,01 a 9.999.999,99.
remittanceNoLa comunicación libre que aparece en el extracto de cuenta, 140 caracteres como máximo.
structuredReferenceNoLa comunicación estructurada, que empieza por RF. Es una u otra: al mismo tiempo que remittance, la solicitud se rechaza.
purposeNoUn código de 4 letras para el motivo del pago, por ejemplo RENT para un alquiler.
infoNoUn pequeño mensaje para el pagador, 140 caracteres como máximo. No todos los bancos lo muestran.
outputFormat y sizeNoComo para el QR clásico: Png o Svg, tamaño de 1 a 20.

Un pero, porque alguno tenía que haber: este QR sigue una norma europea, pero no todas las aplicaciones bancarias lo leen. En Bélgica, los Países Bajos o Alemania, está muy extendido. En otros lugares, haz la prueba con tu propio banco antes de imprimir quinientos.

Bajo el capó

Para quienes quieren saber qué pasa por detrás, estas son las decisiones técnicas.

El QR de pago respeta la norma EPC069-12 del Consejo Europeo de Pagos. En concreto, es un pequeño texto de unas cuantas líneas (versión, beneficiario, IBAN, importe, comunicación) ordenadas según un orden impuesto, y después codificado como cualquier QR. La API construye este texto por ti y comprueba los campos antes.

Todos los códigos se generan con el nivel de corrección de errores M. Un QR lleva datos duplicados para seguir siendo legible incluso si está dañado: con el nivel M, aproximadamente el 15 % de la superficie puede estar manchada, doblada u oculta sin dificultar la lectura. Es, por cierto, el nivel que la norma impone para los QR de pago.

En cuanto al formato, elige el PNG para un correo electrónico o una página web, con un valor de size lo bastante grande para no tener que estirarlo. Para todo lo que vaya a la imprenta, elige el SVG: es un dibujo vectorial, se amplía hasta el tamaño de una lona sin volverse borroso. La respuesta lleva el tipo correcto, image/png o image/svg+xml, y su cuerpo es directamente el archivo, no un JSON que haya que descodificar.

Último detalle: son QR estáticos. Cuando alguien escanea el código, nada pasa por mi servidor, todo el contenido está en la imagen. Así que seguirá funcionando dentro de diez años, exista o no mi servicio.

Seguir tu cuota

En cuanto se acepta la clave, cada respuesta lleva tres cabeceras: X-RateLimit-Limit (tu límite diario), X-RateLimit-Remaining (lo que te queda) y X-RateLimit-Reset (la hora de la puesta a cero, en segundos Unix).

En cuanto a los errores, hay cuatro que prever:

  • 400 : la solicitud no es válida (texto vacío, tamaño fuera de los límites, IBAN falso). Gratis, no se descuenta nada.
  • 401 : falta la clave, está mal escrita, o la cuenta aún no está validada. También es gratis.
  • 429 : la cuota del día se ha agotado. La cabecera Retry-After indica el número de segundos que hay que esperar antes de la puesta a cero.
  • 503 : el servicio no ha podido verificar la clave. Se puede volver a intentar 30 segundos después.

Probar sin escribir una línea de código

Todo está documentado en el Swagger de la API (una página que enumera las llamadas y permite ejecutarlas desde el navegador). Haz clic en «Authorize», pega tu clave y prueba cada llamada con el botón «Try it out». La imagen se muestra en la página. Ojo de todos modos: estas pruebas cuentan para tu cuota, como cualquier otra solicitud.

¿Por qué una suscripción?

Porque todo esto funciona en un servidor que pago. Lo gratuito sigue ahí para probar y para un uso ligero, y diez códigos al día cubren de sobra las necesidades de un particular. Si conectas la API a un programa de facturación o a un sitio, la suscripción PRO de 12 € al mes aumenta el límite a 1000 códigos al día, incluye la guía de TV completa y todos mis programas, y es lo que mantiene vivo el servicio. El uso comercial sin suscripción no está autorizado.

Únete a la conversación

Debes tener una cuenta para comentar este artículo. Crear una cuenta es gratis y lleva menos de un minuto.

  • El archivo XMLTV para descargar gratis, cada día
  • Comentar los artículos y responder a los demás lectores
  • Recibir un aviso por correo electrónico sobre los nuevos artículos que sigues

Ningún comentario por el momento.

Une erreur s'est produite. Cette application peut ne plus répondre jusqu'à ce qu'elle soit rechargée.Veuillez contacter l'auteur. Reload 🗙