Factura dentro, QR de pago fuera — vía API

Listo en tres pasos

1. 1

   Crea una clave API

   Inicia sesión en la app y crea una clave en «API e integraciones». Empieza por gsk_live_ y se muestra exactamente una vez — guárdala en lugar seguro. 10 tokens gratis ya están en la cuenta.

2. 2

   Elige una puerta

   REST para tu sistema, MCP para tu agente de IA, correo para tus flujos de envío existentes — o simplemente la aplicación web. La clave es la misma en todas partes.

3. 3

   Envía facturas

   Documento dentro, respuesta con los datos de pago y el GiroCode fuera — para PDF, también el PDF estampado. Cada respuesta indica los tokens cobrados y restantes.

La API REST y el servidor MCP se autentican con la misma clave API de GiroSnap como bearer token. No existe una «clave MCP» aparte — la clave gsk_live_ de la app es la única clave:

Authorization: Bearer gsk_live_...

Las claves solo se crean y revocan en la app (sesión iniciada) — una clave filtrada nunca puede generar claves nuevas. El texto en claro no puede recuperarse después de crearla.

JSON o multipart, máx. 12 MB por documento (JPG, PNG, WEBP, PDF). El comienzo más rápido es el endpoint todo-en-uno:

curl -X POST https://www.girosnap.eu/api/v1/invoices \
  -H "Authorization: Bearer gsk_live_..." \
  -F "file=@rechnung.pdf"

• POST/api/v1/invoicesTodo en uno: datos de pago + QR, para PDF también el PDF estampado.
• POST/api/v1/extractExtraer solo los datos de pago (sin QR, sin estampado).
• POST/api/v1/qrSolo QR — desde datos de pago (sin extracción) o desde un documento.
• POST/api/v1/stampEstampar el GiroCode en un PDF.
• GET/api/v1/balanceConsultar saldo de tokens, umbral de aviso y paquetes (gratis).
• POST/api/v1/checkoutCrear un enlace de Stripe directamente pagable para un paquete de tokens.

Todos los parámetros, formatos de respuesta y códigos de error — con «try it out» directamente en el navegador: Abrir la referencia interactiva de la API

MCP (Model Context Protocol) es el estándar abierto con el que los agentes de IA (p. ej., Claude) usan herramientas externas. Nuestro servidor MCP entrega GiroSnap a tu agente como caja de herramientas: fotografía una factura, llama a una herramienta y recibe el GiroCode o el PDF estampado directamente en su flujo.

El camino más fácil — Claude (web y escritorio): Ajustes → Conectores → «Añadir conector personalizado», nómbralo «GiroSnap» y pega esta URL con tu clave. Deja vacíos los campos OAuth:

https://www.girosnap.eu/api/mcp?key=GIROSNAP_API_KEY

Esta URL contiene tu clave API — trátala como una contraseña y no la compartas.

Conexión: introduce la URL del servidor y pasa tu clave API en la cabecera Authorization — la misma configuración funciona en Claude, agentes de IDE y tus propios agentes SDK:

{
  "mcpServers": {
    "girosnap": {
      "type": "http",
      "url": "https://www.girosnap.eu/api/mcp",
      "headers": {
        "Authorization": "Bearer gsk_live_..."
      }
    }
  }
}

GIROSNAP_API_KEY es tu clave gsk_live_ normal de la app — no hay una clave MCP aparte.

Las herramientas en detalle

• extract_invoice1 token/página

  Lee beneficiario, IBAN, BIC, importe (en céntimos) y concepto desde una foto de factura o un PDF. Solo hace falta si tu agente no puede o no debe leer la factura por sí mismo.

• create_payment_qr1 token/página

  Genera el EPC/GiroCode escaneable — como imagen, SVG y payload en bruto. Acepta datos de pago listos (la vía más rápida, sin extracción) o un documento.

• stamp_invoice_pdf1 token/página

  Estampa el GiroCode en la factura PDF — en espacio libre o en una página añadida; los PDF firmados y las e-facturas quedan intactos y reciben una hoja adjunta.

• get_token_balancegratis

  Saldo de tokens actual, indicador de umbral, lista de paquetes y enlace de recarga.

• buy_tokensgratis

  Crea un enlace de Stripe Checkout directamente pagable para un paquete de tokens — los tokens se abonan automáticamente tras el pago.

Truco: si tu agente ya conoce los datos de pago (al fin y al cabo, ha visto la factura), los pasa como payment a create_payment_qr o stamp_invoice_pdf — en nuestro lado no corre ninguna extracción y la respuesta es la más rápida.

Envía facturas simplemente por correo — sin nada de código. A las fotos respondemos con el GiroCode en el cuerpo; los PDF vuelven estampados como adjuntos, incluso varios por correo.

1. Registra tu dirección de remitente en la app en «API e integraciones».
2. Haz clic en el enlace de confirmación del correo — listo.
3. Envía facturas (PDF, JPG, PNG, WEBP) a la dirección de procesamiento y espera la respuesta.

Hasta 10 adjuntos por correo, 12 MB cada uno. La respuesta siempre indica los tokens cobrados y restantes; cuando el saldo va justo, incluye el enlace de recarga.

La propia app es la cuarta puerta: subir, revisar, estampar — directamente en el navegador. Y entre por la puerta que entre una factura, todo queda registrado en tu historial, con QR, PDF y costes consultables en cualquier momento.

Una regla, en todas partes: 1 token por página (un QR desde datos listos cuenta como una página). Las cuentas nuevas empiezan con 10 tokens gratis; se recarga vía Stripe — en la app, vía POST /api/v1/checkout o con la herramienta buy_tokens.

Cuando el saldo va justo te avisamos por correo; a 0 el procesamiento se pausa en todas las puertas (no se llama a ningún servicio de IA) y cada respuesta lleva el enlace de recarga.

Cobro justo: si el procesamiento falla por nuestra parte, el token se devuelve. Si el modelo corrió pero no pudo leer la factura, queda gastado.

Todos los errores usan el mismo envelope — un code legible por máquina, un message comprensible y, con tokens insuficientes (HTTP 402), el enlace de recarga directamente en la respuesta:

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Not enough tokens for this operation.",
    "needed": 3,
    "balance": 1,
    "checkoutUrl": "https://www.girosnap.eu/app?screen=tokens"
  }
}

Códigos clave: insufficient_tokens (402), unreadable (422, el modelo corrió — token gastado), extraction_failed (502, devuelto), unsupported_media (415), file_too_large (413). Catálogo completo en la referencia interactiva.