← Volver

API para POS

Para el programador del sistema de punto de venta (Odoo u otro). Cada venta genera el QR de la encuesta para imprimirlo en el ticket; además se consultan clientes y se canjean premios y cupones.

🔌 REST + JSON🔑 Una llave por caja🧾 Pensada para Odoo POS
Parte 1

Empezar

  • 💳El negocio activa el módulo API para POS en Gago → Suscripción.
  • 🔑En Gago → Mi negocio → API para POS, el dueño crea una llave por cada caja con POS. Cada llave «actúa como» un usuario de caja: usa sus permisos y su sucursal, y todo queda a su nombre en los reportes.
  • 🌐Dirección: https://www.getgago.com/api/v1
  • 🛡️Manda la llave en cada llamada: Authorization: Bearer gago_… (o X-Api-Key: gago_…). Guárdala en el servidor, no en el navegador.
  • ⏱️Límite: 300 llamadas por minuto por llave.

Todas las respuestas son JSON con "ok": true o "ok": false y un objeto error con codigo (estable, para tu programa) y mensaje (en español, para mostrar al cajero).

Parte 2

Flujo recomendado en el POS

🧾Al cobrar: «¿Acumula puntos?»

  1. Al cobrar, pregunta «¿Acumula puntos? Sí / No». Con No, la venta sigue normal.
  2. Con Sí, toma la factura y el monto de la venta y pide escanear el QR de la tarjeta del cliente («Mi código»).
  3. Llama a POST /compras/cliente. En el celular del cliente se abre la encuesta; al responderla gana sus puntos (o su sello, si el negocio da sellos).
  4. Si responde registrada: false con un aviso, el cliente tiene una encuesta sin responder: pregunta al cajero y, si confirma, vuelve a llamar con confirmado: true.
  5. Cliente nuevo (aún sin tarjeta): llama a POST /compras e imprime el qr_png en el ticket.

🎁Premios y cupones

  1. El cajero escanea el QR del premio o del cupón que muestra el cliente (o lo escribe).
  2. Llama a POST /canjes con ese código.
  3. Si es un descuento o producto, aplícalo en la venta.

🔎Consultar al cliente

Con su WhatsApp, GET /clientes devuelve sus sellos o puntos, si tiene premio listo y sus cupones vigentes. Útil para mostrarlo en la pantalla del POS.

↩️Devoluciones

Si se anula la venta antes de que el cliente responda la encuesta, POST /compras/anular invalida su código.

Prueba de conexión

Estado

GET/estado

Confirma que la llave funciona y devuelve el programa del negocio.

curl https://www.getgago.com/api/v1/estado \
  -H "Authorization: Bearer gago_TU_LLAVE"
{ "ok": true, "negocio": "Café La Ceiba", "llave": "Odoo caja 1",
  "programa": "puntos", "sellos_meta": 8, "recompensa": "Café gratis" }

programa: sellos, puntos o encuesta (sin programa de lealtad).

Lo principal

Registrar una compra

POST/compras

CampoTipoDescripción
facturatextoNúmero de factura o ticket (hasta 40). Obligatorio si el negocio da puntos. La misma factura no genera dos códigos.
montonúmeroTotal de la venta. Obligatorio si el negocio da puntos (Gago calcula los puntos).
monedatextoGTQ o USD. Obligatorio si el negocio da puntos.
telefonotextoOpcional: WhatsApp del cliente con lada (50255551111). Devuelve whatsapp_url para mandarle la encuesta.
curl -X POST https://www.getgago.com/api/v1/compras \
  -H "Authorization: Bearer gago_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"factura":"A-1043","monto":125.50,"moneda":"GTQ"}'
{ "ok": true,
  "codigo": "K7Q29MDX",
  "puntos": 12,
  "expira_en": "2026-11-12T18:42:00Z",
  "encuesta_url": "https://www.getgago.com/s/cafe-la-ceiba?c=K7Q29MDX",
  "qr_png": "data:image/png;base64,iVBORw0KGgo…" }

Imprime qr_png en el ticket (es una imagen PNG en base64) o genera tu propio QR con encuesta_url. El código sirve una sola vez y vence según lo que configuró el negocio.

«¿Acumula puntos? Sí»

Compra con la tarjeta del cliente

POST/compras/cliente

CampoTipoDescripción
qrtextoLo que lee el escáner del QR de «Mi código» en la tarjeta del cliente (cambia cada 30 segundos).
factura, monto, monedaIgual que en /compras: obligatorios si el negocio da puntos.
confirmadosí/noSolo en la segunda llamada, cuando el cajero decide registrar aunque haya una encuesta pendiente.
{ "ok": true, "registrada": true, "nombre": "Ana", "codigo": "K7Q29MDX", "puntos": 12, "horas": 24 }
{ "ok": true, "registrada": false, "nombre": "Ana",
  "aviso": { "puntos": 8, "minutos": 2880, "abierta": false } }

Con registrada: true, en el celular del cliente se abrió la encuesta: tiene horas para responderla. Con registrada: false, pregunta al cajero «Tiene una encuesta sin responder: si registras, pierde 8 puntos» y vuelve a llamar con "confirmado": true si dice que sí.

El negocio debe tener activado el QR en la tarjeta del cliente (Gago → Configuración → QR en caja). Si no, la respuesta es qr_apagado: usa /compras e imprime el QR en el ticket.

Consulta

Consultar un cliente

GET/clientes?telefono=50255551111

El WhatsApp con lada; sin lada se usa la del negocio.

{ "ok": true, "encontrado": true, "nombre": "Ana",
  "programa": "sellos", "sellos": 8, "sellos_meta": 8, "puntos": 0,
  "premio_listo": { "codigo": "4821-…", "premio": "Café gratis" },
  "cupones": [ { "codigo": "CUPON1", "descripcion": "2×1 en café",
                 "vence": "2026-12-31", "suma": null } ] }

Si no existe: { "ok": true, "encontrado": false }. suma = sellos o puntos que el cupón suma al canjearlo.

Premios y cupones

Canjear

POST/canjes

{ "codigo": "…" }: el código del QR del premio o del cupón. Gago reconoce cuál es.

{ "ok": true, "tipo": "cupon", "descripcion": "2×1 en café", "puntos": null, "sellos": true }
{ "ok": true, "tipo": "premio", "nombre": "Ana", "por_puntos": false, "sellos_restantes": 0 }

El usuario de la llave necesita permiso de canje (Gago → Equipo). Cada premio y cupón sirve una sola vez.

Devoluciones

Anular una compra

POST/compras/anular

{ "factura": "A-1043" }: si el cliente aún no respondió la encuesta, su código deja de servir.

{ "ok": true, "anulada": true, "codigo": "K7Q29MDX" }

Si ya respondió, devuelve compra_ya_registrada: sus puntos ya se sumaron y el ajuste se hace en Gago.

Copiar y pegar

Código listo

Elige tu sistema. Cada bloque tiene su botón Copiar. Solo cambia la llave (gago_…) por la que creaste en Gago.

  • 📁Crea la carpeta gago_pos en tu carpeta de módulos (addons) con estos archivos.
  • 🔑En Odoo: Ajustes → Técnico → Parámetros del sistema → nuevo: clave gago.api_key, valor tu llave.
  • ⬆️Aplicaciones → Actualizar lista → instala Gago para Punto de Venta. Cierra y abre la sesión del POS.
  • ✅Al cobrar sale «¿Acumula puntos? Sí / No». Con Sí, el cajero escanea el QR de la tarjeta del cliente y en su celular se abre la encuesta (cliente nuevo: deja el campo vacío y el QR sale en el ticket). Con No, la venta sigue normal. En la venta también aparece el botón 🎁 Canjear Gago.

Hecho para Odoo 17 (Community y Enterprise). Odoo 18 cambió las ventanas del POS: si usas 18, pídenos la versión para 18. Pruébalo primero en una base de pruebas de Odoo.

gago_pos/__manifest__.py

# gago_pos/__manifest__.py
{
    "name": "Gago para Punto de Venta",
    "version": "17.0.1.0.0",
    "summary": "Lealtad y encuestas de Gago en el POS: QR de la encuesta en el ticket y botón para canjear premios y cupones.",
    "category": "Point of Sale",
    "depends": ["point_of_sale"],
    "data": [],
    "assets": {
        "point_of_sale._assets_pos": [
            "gago_pos/static/src/**/*",
        ],
    },
    "license": "LGPL-3",
    "installable": True,
}

gago_pos/__init__.py y gago_pos/models/__init__.py

# gago_pos/__init__.py
from . import models

# gago_pos/models/__init__.py
from . import pos_order

gago_pos/models/pos_order.py

# gago_pos/models/pos_order.py
# La llave de Gago va en Ajustes > Técnico > Parámetros del sistema, con la clave «gago.api_key».
# Las llamadas salen del servidor de Odoo: la llave nunca llega al navegador.
import requests

from odoo import _, api, models
from odoo.exceptions import UserError

GAGO_URL = "https://www.getgago.com/api/v1"


class PosOrder(models.Model):
    _inherit = "pos.order"

    @api.model
    def _gago(self, metodo, ruta, datos=None, params=None):
        llave = self.env["ir.config_parameter"].sudo().get_param("gago.api_key")
        if not llave:
            raise UserError(_("Falta la llave de Gago: Ajustes > Técnico > Parámetros del sistema > gago.api_key"))
        try:
            r = requests.request(
                metodo,
                GAGO_URL + ruta,
                json=datos,
                params=params,
                headers={"Authorization": "Bearer " + llave},
                timeout=10,
            )
            respuesta = r.json()
        except Exception:
            raise UserError(_("No se pudo conectar con Gago. Revisa el internet e intenta de nuevo."))
        if not respuesta.get("ok"):
            raise UserError(respuesta.get("error", {}).get("mensaje") or _("Gago no pudo completar la operación."))
        return respuesta

    @api.model
    def gago_compra_cliente(self, qr, factura, monto, moneda="GTQ", confirmado=False):
        """«¿Acumula puntos? Sí»: registra la venta con el QR de la tarjeta del cliente. En su celular se abre
        la encuesta. Si tiene una encuesta pendiente, devuelve registrada=False y el aviso."""
        return self._gago("POST", "/compras/cliente", {
            "qr": qr, "factura": factura, "monto": monto, "moneda": moneda, "confirmado": bool(confirmado),
        })

    @api.model
    def gago_compra(self, factura, monto, moneda="GTQ"):
        """Cliente nuevo (aún sin tarjeta): devuelve el QR de la encuesta (qr_png) para imprimirlo en el ticket."""
        return self._gago("POST", "/compras", {"factura": factura, "monto": monto, "moneda": moneda})

    @api.model
    def gago_canjear(self, codigo):
        """Canjea un premio o un cupón de Gago."""
        return self._gago("POST", "/canjes", {"codigo": codigo})

    @api.model
    def gago_cliente(self, telefono):
        """Sellos o puntos, premio listo y cupones del cliente."""
        return self._gago("GET", "/clientes", params={"telefono": telefono})

gago_pos/static/src/gago_pos.js

/** @odoo-module */
// gago_pos/static/src/gago_pos.js
// 1) Al cobrar: «¿Acumula puntos? Sí / No».
//    Sí → escanea el QR de la tarjeta del cliente («Mi código») y Gago le abre la encuesta en su celular.
//         Cliente nuevo (sin tarjeta): deja el campo vacío y el QR de la encuesta sale impreso en el ticket.
//    No → la venta sigue normal.
// 2) Botón «Canjear Gago» en la pantalla de venta, para premios y cupones.
import { Component } from "@odoo/owl";
import { patch } from "@web/core/utils/patch";
import { useService } from "@web/core/utils/hooks";
import { usePos } from "@point_of_sale/app/store/pos_hook";
import { ProductScreen } from "@point_of_sale/app/screens/product_screen/product_screen";
import { PaymentScreen } from "@point_of_sale/app/screens/payment_screen/payment_screen";
import { Order } from "@point_of_sale/app/store/models";
import { TextInputPopup } from "@point_of_sale/app/utils/input_popups/text_input_popup";
import { ConfirmPopup } from "@point_of_sale/app/utils/confirm_popup/confirm_popup";
import { ErrorPopup } from "@point_of_sale/app/errors/popups/error_popup";

const mensajeError = (e) => e?.data?.message || e?.message || "Intenta de nuevo.";

// ── Al cobrar: ¿Acumula puntos? ─────────────────────────────────────────
patch(PaymentScreen.prototype, {
    async validateOrder(isForceValidate) {
        const orden = this.currentOrder;
        // Se pregunta una sola vez por venta (aunque el pago se valide de nuevo).
        if (!orden.gago_preguntado) {
            orden.gago_preguntado = true;
            await this.gagoAcumular(orden);
        }
        return await super.validateOrder(...arguments);
    },

    async gagoAcumular(orden) {
        const popup = this.env.services.popup;
        const orm = this.env.services.orm;
        const { confirmed: acumula } = await popup.add(ConfirmPopup, {
            title: "¿Acumula puntos?",
            body: "¿El cliente quiere sumar esta compra a su tarjeta de Gago?",
            confirmText: "Sí",
            cancelText: "No",
        });
        if (!acumula) return;

        const datos = [orden.name, orden.get_total_with_tax(), this.pos.currency.name === "USD" ? "USD" : "GTQ"];
        const { confirmed, payload } = await popup.add(TextInputPopup, {
            title: "Escanea el QR de la tarjeta del cliente",
            placeholder: "«Mi código» en su tarjeta · vacío si es cliente nuevo",
        });
        if (!confirmed) return;
        const qr = (payload || "").trim();

        try {
            // Cliente nuevo: el QR de la encuesta sale en el ticket.
            if (!qr) {
                const r = await orm.call("pos.order", "gago_compra", datos);
                orden.gago_qr = r.qr_png;
                return;
            }
            let r = await orm.call("pos.order", "gago_compra_cliente", [qr, ...datos, false]);
            // Encuesta pendiente: si registra esta compra, pierde lo de la anterior.
            if (!r.registrada && r.aviso) {
                const pierde = r.aviso.puntos ? `${r.aviso.puntos} puntos` : "ese sello";
                const { confirmed: igual } = await popup.add(ConfirmPopup, {
                    title: "Tiene una encuesta sin responder",
                    body: `${r.nombre || "El cliente"} no ha respondido la encuesta de su compra anterior. Si registras esta compra, pierde ${pierde}. Lo mejor es que la responda ahora en su celular.`,
                    confirmText: "Registrar de todos modos",
                    cancelText: "No registrar",
                });
                if (!igual) return;
                r = await orm.call("pos.order", "gago_compra_cliente", [qr, ...datos, true]);
            }
            const gana = r.puntos ? `${r.puntos} puntos` : "su sello";
            await popup.add(ConfirmPopup, {
                title: "✅ Listo",
                body: `En el celular de ${r.nombre || "el cliente"} se abrió la encuesta. Al responderla gana ${gana}.`,
                confirmText: "Continuar",
                cancelText: "Cerrar",
            });
        } catch (e) {
            await popup.add(ErrorPopup, {
                title: "No se pudo registrar en Gago",
                body: `${mensajeError(e)} La venta sigue normal.`,
            });
        }
    },
});

// El QR de la encuesta (cliente nuevo) viaja con la orden hasta el ticket.
patch(Order.prototype, {
    export_for_printing() {
        const datos = super.export_for_printing(...arguments);
        datos.gago_qr = this.gago_qr || false;
        return datos;
    },
});

// ── Botón «Canjear Gago» (premios y cupones) ────────────────────────────
export class GagoCanjearButton extends Component {
    static template = "gago_pos.CanjearButton";

    setup() {
        this.pos = usePos();
        this.popup = useService("popup");
        this.orm = useService("orm");
    }

    async click() {
        const { confirmed, payload } = await this.popup.add(TextInputPopup, {
            title: "Canjear premio o cupón de Gago",
            placeholder: "Escanea o escribe el código",
        });
        if (!confirmed || !payload || !payload.trim()) return;
        try {
            const r = await this.orm.call("pos.order", "gago_canjear", [payload.trim()]);
            const detalle = r.tipo === "cupon" ? `Cupón: ${r.descripcion || ""}` : `Premio entregado${r.nombre ? " a " + r.nombre : ""}`;
            await this.popup.add(ConfirmPopup, { title: "✅ Canjeado en Gago", body: detalle });
        } catch (e) {
            await this.popup.add(ErrorPopup, { title: "No se pudo canjear", body: mensajeError(e) });
        }
    }
}

ProductScreen.addControlButton({ component: GagoCanjearButton, condition: () => true });

gago_pos/static/src/gago_pos.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- gago_pos/static/src/gago_pos.xml -->
<templates xml:space="preserve">

    <!-- Botón en la pantalla de venta -->
    <t t-name="gago_pos.CanjearButton">
        <button class="control-button btn btn-light rounded-0 fw-bolder" t-on-click="() => this.click()">
            <i class="fa fa-gift me-1"/> Canjear Gago
        </button>
    </t>

    <!-- QR de la encuesta al final del ticket -->
    <t t-name="gago_pos.OrderReceipt" t-inherit="point_of_sale.OrderReceipt" t-inherit-mode="extension">
        <xpath expr="//div[hasclass('pos-receipt')]" position="inside">
            <div t-if="props.data.gago_qr" style="text-align:center;margin-top:12px">
                <div style="font-weight:bold">¡Califícanos y gana tus puntos!</div>
                <img t-att-src="props.data.gago_qr" style="width:160px;height:160px"/>
                <div style="font-size:12px">Escanea con la cámara de tu celular</div>
            </div>
        </xpath>
    </t>

</templates>

Python

# Python 3 (pip install requests). Pon tu llave en una variable de entorno: GAGO_API_KEY=gago_…
import os
import requests

GAGO_URL = "https://www.getgago.com/api/v1"
LLAVE = os.environ["GAGO_API_KEY"]


def gago(metodo, ruta, datos=None, params=None):
    r = requests.request(metodo, GAGO_URL + ruta, json=datos, params=params,
                         headers={"Authorization": "Bearer " + LLAVE}, timeout=10)
    respuesta = r.json()
    if not respuesta.get("ok"):
        raise Exception(respuesta["error"]["mensaje"])
    return respuesta


# Al cobrar, «¿Acumula puntos?» → Sí → escanea el QR de la tarjeta del cliente:
venta = gago("POST", "/compras/cliente", {"qr": "QR_ESCANEADO", "factura": "A-1043", "monto": 125.50, "moneda": "GTQ"})
if not venta["registrada"]:
    # Tiene una encuesta sin responder (venta["aviso"]). Si el cajero confirma, se registra de todos modos:
    venta = gago("POST", "/compras/cliente", {"qr": "QR_ESCANEADO", "factura": "A-1043", "monto": 125.50, "moneda": "GTQ", "confirmado": True})

# Cliente nuevo (sin tarjeta): imprime nuevo["qr_png"] en el ticket.
nuevo = gago("POST", "/compras", {"factura": "A-1044", "monto": 80, "moneda": "GTQ"})

# Botón «Canjear»: el código del QR del premio o del cupón.
canje = gago("POST", "/canjes", {"codigo": "CUPON1"})

# Consultar al cliente.
cliente = gago("GET", "/clientes", params={"telefono": "50255551111"})

JavaScript (servidor, Node 18+)

// JavaScript en el servidor (Node 18 o más nuevo). Pon tu llave en una variable de entorno: GAGO_API_KEY=gago_…
// No la pongas en el navegador: quien la vea podría registrar compras en tu negocio.
const GAGO_URL = "https://www.getgago.com/api/v1";

async function gago(metodo, ruta, datos) {
  const r = await fetch(GAGO_URL + ruta, {
    method: metodo,
    headers: { Authorization: `Bearer ${process.env.GAGO_API_KEY}`, "Content-Type": "application/json" },
    body: datos ? JSON.stringify(datos) : undefined,
  });
  const respuesta = await r.json();
  if (!respuesta.ok) throw new Error(respuesta.error.mensaje);
  return respuesta;
}

// Al cobrar, «¿Acumula puntos?» → Sí → escanea el QR de la tarjeta del cliente:
const compra = { qr: "QR_ESCANEADO", factura: "A-1043", monto: 125.5, moneda: "GTQ" };
let venta = await gago("POST", "/compras/cliente", compra);
if (!venta.registrada) {
  // Tiene una encuesta sin responder (venta.aviso). Si el cajero confirma, se registra de todos modos:
  venta = await gago("POST", "/compras/cliente", { ...compra, confirmado: true });
}

// Cliente nuevo (sin tarjeta): imprime nuevo.qr_png en el ticket.
const nuevo = await gago("POST", "/compras", { factura: "A-1044", monto: 80, moneda: "GTQ" });

// Botón «Canjear»: el código del QR del premio o del cupón.
const canje = await gago("POST", "/canjes", { codigo: "CUPON1" });

// Consultar al cliente.
const cliente = await gago("GET", "/clientes?telefono=50255551111");

PHP 7.4+

<?php
// PHP 7.4 o más nuevo (con cURL). Pon tu llave en una variable de entorno: GAGO_API_KEY=gago_…
const GAGO_URL = "https://www.getgago.com/api/v1";

function gago(string $metodo, string $ruta, ?array $datos = null): array {
    $c = curl_init(GAGO_URL . $ruta);
    curl_setopt_array($c, [
        CURLOPT_CUSTOMREQUEST => $metodo,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("GAGO_API_KEY"), "Content-Type: application/json"],
        CURLOPT_POSTFIELDS => $datos ? json_encode($datos) : null,
    ]);
    $respuesta = json_decode(curl_exec($c), true);
    curl_close($c);
    if (empty($respuesta["ok"])) throw new Exception($respuesta["error"]["mensaje"] ?? "Error de Gago");
    return $respuesta;
}

// Al cobrar, «¿Acumula puntos?» → Sí → escanea el QR de la tarjeta del cliente:
$compra = ["qr" => "QR_ESCANEADO", "factura" => "A-1043", "monto" => 125.50, "moneda" => "GTQ"];
$venta = gago("POST", "/compras/cliente", $compra);
if (!$venta["registrada"]) {
    // Tiene una encuesta sin responder ($venta["aviso"]). Si el cajero confirma, se registra de todos modos:
    $venta = gago("POST", "/compras/cliente", $compra + ["confirmado" => true]);
}

// Cliente nuevo (sin tarjeta): imprime $nuevo["qr_png"] en el ticket.
$nuevo = gago("POST", "/compras", ["factura" => "A-1044", "monto" => 80, "moneda" => "GTQ"]);

// Botón «Canjear»: el código del QR del premio o del cupón.
$canje = gago("POST", "/canjes", ["codigo" => "CUPON1"]);

// Consultar al cliente.
$cliente = gago("GET", "/clientes?telefono=50255551111");

Para POS web que no son Odoo: pega esto en la pantalla de venta. Llama a tu servidor, que llama a Gago con la llave usando el ejemplo de Python, JavaScript o PHP.

«¿Acumula puntos?» al cobrar y botón «Canjear Gago» (HTML + JavaScript)

<!-- Para cualquier POS web. Los botones llaman a TU servidor (/gago/…), que a su vez llama a Gago con la llave
     (ver los ejemplos de Python, JavaScript o PHP). Así la llave nunca llega al navegador. -->

<!-- 1) Al cobrar: llama a gagoAlCobrar(factura, total) justo antes de cerrar la venta. -->
<script>
  async function gagoAlCobrar(factura, total, moneda = "GTQ") {
    if (!confirm("¿Acumula puntos?\n\nAceptar = Sí · Cancelar = No")) return; // No: la venta sigue normal
    const qr = prompt("Escanea el QR de la tarjeta del cliente (vacío si es cliente nuevo):");
    if (qr === null) return;
    const compra = { qr: qr.trim(), factura, monto: total, moneda };
    // Cliente nuevo: tu servidor llama a /compras e imprime qr_png en el ticket.
    let r = await (await fetch(qr.trim() ? "/gago/compra-cliente" : "/gago/compra", {
      method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(compra),
    })).json();
    if (r.ok && r.registrada === false && r.aviso) {
      const pierde = r.aviso.puntos ? r.aviso.puntos + " puntos" : "ese sello";
      if (!confirm("Tiene una encuesta sin responder. Si registras esta compra, pierde " + pierde + ". ¿Registrar de todos modos?")) return;
      r = await (await fetch("/gago/compra-cliente", {
        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ ...compra, confirmado: true }),
      })).json();
    }
    alert(r.ok ? "✅ Listo: en el celular del cliente se abrió la encuesta." : "❌ " + r.error.mensaje + " La venta sigue normal.");
    return r; // con cliente nuevo, r.qr_png es la imagen para el ticket
  }
</script>

<!-- 2) Botón «Canjear Gago» (premios y cupones) -->
<button type="button" id="gago-canjear" style="padding:10px 16px;border-radius:10px;background:#ea580c;color:#fff;font-weight:700;border:0">
  🎁 Canjear Gago
</button>
<script>
  document.getElementById("gago-canjear").addEventListener("click", async () => {
    const codigo = prompt("Escanea o escribe el código del premio o del cupón:");
    if (!codigo) return;
    const r = await (await fetch("/gago/canjear", {
      method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ codigo: codigo.trim() }),
    })).json();
    alert(r.ok ? "✅ Canjeado: " + (r.descripcion || "premio entregado") : "❌ " + r.error.mensaje);
  });
</script>
Referencia

Errores

{ "ok": false, "error": { "codigo": "documento_usado", "mensaje": "Esa factura ya generó su código." } }
HTTPcodigoQué pasa
401llave_invalidaFalta la llave, es incorrecta o fue revocada.
403api_inactivaEl negocio no tiene activo el módulo.
403usuario_inactivo, sin_permiso_canjeEl usuario de la llave fue desactivado o no puede canjear.
409documento_usadoEsa factura ya generó su código.
409cupon_usado, cupon_vencido, premio_vencidoYa no se puede canjear.
404codigo_invalido, compra_no_encontradaNo existe en este negocio.
422monto_invalido, moneda_invalida, documento_requerido, telefono_invalidoRevisa los datos enviados.
429demasiadas_llamadasMás de 300 llamadas por minuto.
Integración

Odoo POS

🐍Del lado del servidor

Guarda la llave en un parámetro del sistema (Ajustes → Técnico → Parámetros) y haz las llamadas desde Python (por ejemplo, un método RPC del modelo pos.order), no desde el navegador.

🧾En el ticket

Al validar la orden, guarda qr_png en la orden y agrégalo a la plantilla del recibo (OWL) con la leyenda «Califícanos y gana tus puntos».

🎟️Botón «Canjear»

Un botón en la pantalla de pago que lee el código (escáner o teclado), llama a /canjes y, si es un descuento, aplica la línea correspondiente.

💬¿Ayuda?

Escríbenos desde Gago → Novedades de Gago con el nombre del negocio y la llave (solo su inicio, gago_ab12…).

Gago · API para POS · v1