☰ Menú · Reglas y límites del local
Reglas y límites del local
Cómo controla un local lo que pueden hacer las cajas conectadas: niveles de cashback, categorías de productos, reservas, numeración de tickets, tickets enviados tarde, límites y escaneo de tarjetas.
Todo lo de esta página lo configura el propietario del local en Desarrolladores → Reglas para las cajas. Las reglas se aplican a todas las claves API del local; una clave concreta (una caja, un quiosco) puede tener sus propios valores para cualquiera de ellas. Tu integración lee las reglas con las que trabaja en GET /v1/account, dentro de settings.
"settings": {
"redemption": "hold",
"hold_minutes": 30,
"check_numbering": "per_register",
"offline_max_hours": 72,
"redeem_max_per_check": 50000,
"redeem_max_per_day": null,
"require_scan": true,
"scan_window_minutes": 30,
"allow_adjustments": false,
"adjustment_max": 50000,
"card_prefix": "2999"
}Niveles de cashback
Un programa de cashback puede tener niveles: por ejemplo, Base 5 %, Plata 7 % desde la segunda visita, Oro 10 % a partir de 1000,00 gastados. Los niveles se cuentan por visitas, por importe gastado o por lo que llegue antes. El propietario los configura en el programa de fidelización. En la caja no hace falta nada: cada ticket genera cashback según el nivel del cliente después de ese ticket, y cada objeto member te dice en qué nivel está el cliente.
"cashback": {
"balance": 10200,
"held": 0,
"available": 10200,
"currency": "MDL",
"earn_rate": 7,
"level": "Silver",
"level_basis": "any",
"levels": [
{ "name": "Base", "earn_rate": 5, "min_visits": null, "min_spent": null },
{ "name": "Silver", "earn_rate": 7, "min_visits": 2, "min_spent": null },
{ "name": "Gold", "earn_rate": 10, "min_visits": null, "min_spent": 100000 }
],
"next_level": { "name": "Gold", "earn_rate": 10, "visits_left": null, "spent_left": 80000 },
...
}next_level.visits_left y next_level.spent_left están listos para mostrarlos al cliente ("2 visitas más para Plata"). display.receipt_lines ya incluye esa línea en el idioma del cliente.
Categorías de productos
Sube tus productos con su categoría una vez y después envía los cambios. Las categorías aparecen en el panel del propietario, donde cada una se puede configurar para que no genere cashback (tabaco, alcohol), no se pueda pagar con cashback (artículos que ya están en promoción) o genere su propio porcentaje en lugar del nivel del cliente (café al 10 %). La API puede crear productos y categorías y cambiarles el nombre, pero solo el propietario cambia estas reglas.
curl https://loyaltyfy.io/api/v1/catalog/products/bulk \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"products": [
{ "sku": "4840001", "name": "Marlboro Gold", "category": "TOB", "category_name": "Tobacco", "price": 6500 },
{ "sku": "1001", "name": "Latte", "category": "COF", "category_name": "Coffee", "price": 4500 },
{ "sku": "2040", "name": "Zeama", "category": "KIT", "category_name": "Kitchen", "price": 6500 }
]
}'
# { "object": "catalog_sync", "upserted": 3 }Después envía line_items con cada ticket. Una línea puede llevar category o solo sku: buscamos la categoría en el catálogo. Los totales de las líneas se ajustan al importe del ticket, así que los descuentos hechos en la caja se reparten de forma proporcional. Las líneas de categorías sin reglas generan cashback según el nivel del cliente. Cada transacción y POST /v1/checks/calculate devuelven line_items con lo que acumuló cada línea, y una devolución puede nombrar las líneas devueltas. El propietario también puede anular la regla de una categoría en un solo producto, para siempre o solo entre dos fechas (promoción).
curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": "CHK-2026-000130",
"member": "2000111703779",
"amount": 17500,
"line_items": [
{ "sku": "4840001", "quantity": 1, "unit_price": 6500 },
{ "sku": "1001", "quantity": 1, "unit_price": 4500 },
{ "sku": "2040", "quantity": 1, "unit_price": 6500 }
]
}'
# Tobacco earns nothing, Coffee has its own 10%, Kitchen earns at the guest's level (5%):
# 0 + 450 + 325 = "cashback_earned": 775En los locales con el orden detallado de reglas activado, category también puede ser el nombre de la categoría tal como lo ve el propietario en el catálogo («Cerveza», no solo «106», sin importar mayúsculas): la línea sigue entonces las reglas de esa categoría. El nombre de una categoría nunca crea una categoría nueva. Un valor que el catálogo no conoce se sustituye por la categoría del producto según sku; solo si el producto no tiene categoría, el valor aparece como una categoría nueva. Gana la regla más concreta: el producto, luego su categoría, luego el programa o el nivel; un producto con su propio porcentaje lo recibe incluso en una categoría sin acumulación. En un ticket por debajo del mínimo del programa, o en un local sin acumulación, cada línea responde earn_percent: null y cashback_earned: 0, y por debajo del mínimo el ticket responde earn_rate: 0.
Pago con cashback mediante una reserva
Con En el ticket (la opción por defecto), la caja envía redeem_amount con el ticket cerrado. Con Con reserva, la caja aparta el importe cuando el cliente pide pagar con cashback, y el ticket cerrado lo confirma. Si el ticket no llega nunca (se cayó la red, se canceló la venta), la reserva se libera cuando pasa el tiempo que fijó el propietario, y el cliente conserva el dinero. Nunca se aplica un descuento sin descontarlo del saldo.
- 1Reserva
POST /v1/holdscon el socio, el importe y el total del ticket. Se aplican los mismos topes que a un ticket. La respuesta incluye elidde la reserva. - 2Captura
POST /v1/transactionsconhold_id. Si no envíasredeem_amount, se usa la reserva completa; también puedes enviar un importe menor. - 3O libera
POST /v1/holds/{id}/releasecuando se cancela la venta. Liberar dos veces no tiene efecto.
curl https://loyaltyfy.io/api/v1/holds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hold-R3-000131" \
-d '{ "member": "2000111703779", "amount": 3000, "check_amount": 20000, "register_id": "R3" }'
# at payment: the check captures it
curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "000131", "register_id": "R3", "member": "2000111703779",
"amount": 20000, "hold_id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19" }'cashback.available del socio, en los límites y en la propia app de caja del local, así que el mismo dinero no se puede gastar dos veces.Números de ticket por caja
Si cada caja numera los tickets desde 1, elige Cada caja numera los suyos. En ese caso register_id es obligatorio y guardamos el ticket como <register_id>:<external_id>, por ejemplo R3:15. Usa ese id combinado para leer, anular o devolver el ticket.
Prefijo del número de tarjeta
Las tarjetas que emitimos reciben un número de 13 dígitos. Si la caja reconoce las tarjetas de fidelidad por las primeras cifras, define un prefijo en Desarrolladores → Reglas para las cajas: las tarjetas nuevas empezarán por él. Los dígitos caben en los 13 caracteres (el prefijo 2999 da 2999 y 9 dígitos más), las letras se ponen delante. Las tarjetas ya emitidas conservan su número, y un card_number enviado con POST /v1/members siempre prevalece. El prefijo se devuelve en settings.card_prefix de GET /v1/account.
Tickets enviados tarde
Tras un corte, la caja envía su cola. Con un límite de, por ejemplo, 72 horas, los tickets cuyo closed_at sea más antiguo se rechazan con check_too_old, para que una caja restaurada desde una copia de seguridad antigua no llene el local de tickets viejos. Un closed_at más de 10 minutos en el futuro siempre se rechaza.
Límites de canje
Además del porcentaje del ticket que fija el programa, el propietario puede fijar el máximo de cashback por ticket y por cliente al día (todas las cajas juntas, según la zona horaria del local). Un ticket que pide más canjea lo permitido y la respuesta muestra el redeem_amount real; una reserva que pide más se rechaza con limited_by. Usa calcular para mostrar antes al cliente la cifra exacta.
Reglas por local
El propietario vincula los códigos de caja a un local en Locales. El código es el register_id que la caja envía con tickets, cálculos y reservas. Un local puede desactivar la acumulación, tener su propio porcentaje, prohibir el pago con cashback o tener su propia parte del ticket que se puede pagar con cashback. El propietario también elige qué gana cuando un producto (categoría), el local y el nivel del cliente tienen cada uno un porcentaje: producto, local, nivel; local, producto, nivel; o el nivel del cliente antes que el local (entonces el porcentaje del local reemplaza solo el nivel base). Una categoría sin acumulación sigue excluida en cualquier orden. Donde no se permite pagar con cashback, POST /v1/checks/calculate responde max_redeem: 0 con redeem_blocked_reason, y un ticket o una reserva con cashback se rechaza con 400 redeem_not_allowed_here. Un ticket sin register_id o con un código sin vincular sigue las reglas generales; los códigos desconocidos aparecen en una lista para que el propietario los vincule.
Orden de las reglas
Si el negocio usa excepciones por local, cada línea del ticket sigue la regla más específica: la excepción del local para el producto, luego la excepción del local para la categoría, luego la regla del producto, la de la categoría, el porcentaje propio del local y, por último, el nivel del cliente o el porcentaje del programa. Cada campo (porcentaje, acumula, se puede pagar con cashback) se toma de la primera regla que lo define. Ejemplo: programa 5%, categoría Alcohol 3%, en el local Ciocana para Alcohol 2%. En Ciocana una línea de alcohol gana 2%, en otros locales 3%, el resto de productos 5%. Las excepciones solo se aplican a tickets cuyo register_id está vinculado a un local. La acumulación o el canje desactivados en un local y el límite de canje del local se aplican siempre. Las excepciones se leen con GET /v1/catalog/location-rules.
Cashback como pago o como descuento
El contable del local elige en Desarrolladores → Reglas para cajas cómo registra la caja el pago con cashback. Como pago (por defecto): el cashback es una forma de pago, una suma junto al efectivo y la tarjeta; los precios y el IVA no cambian. Como descuento: el cashback baja el precio de los productos y el IVA se calcula sobre el precio tras el descuento. En este modo cada línea de POST /v1/checks/calculate y POST /v1/transactions lleva también redeem_allocated (unidades menores): la parte de redeem_amount que corresponde a la línea, en proporción a su importe. Las líneas que no se pueden pagar con cashback reciben 0 y las líneas siempre suman exactamente redeem_amount (los céntimos sobrantes van a la línea más grande). El modo está en settings.redeem_accounting de GET /v1/account (payment o discount). Sin line_items no se reparte nada.
{
"amount": 10000,
"redeem_amount": 1000,
"net_amount": 9000,
"line_items": [
{ "sku": "LATTE", "amount": 6000, "redeemable": true, "redeem_allocated": 600 },
{ "sku": "CAKE", "amount": 3000, "redeemable": true, "redeem_allocated": 300 },
{ "sku": "WATER", "amount": 1000, "redeemable": true, "redeem_allocated": 100 }
]
}Tipos de descuento
Envíe el descuento que aplicó la caja en discount_type, un código de hasta 64 caracteres como employee, discount_card o promo, en todo el ticket y, si hace falta, en líneas sueltas (line_items[].discount_type). Cada código nuevo aparece solo en Desarrolladores → Tipos de descuento, donde el propietario le pone nombre y decide si ese ticket acumula cashback y si se puede pagar con cashback. Un tipo nuevo acumula y permite el pago hasta que el propietario lo cambie. Un tipo de ticket sin acumulación da 0 de cashback en todo el ticket; un tipo de línea sin acumulación da 0 solo en esa línea. Donde no se permite pagar con cashback, POST /v1/checks/calculate responde max_redeem: 0 con limited_by: "discount_type" y redeem_blocked_reason: "discount_redeem_not_allowed", y POST /v1/transactions con redeem_amount o hold_id se rechaza con 400 discount_redeem_not_allowed. Las respuestas llevan entonces discount_type (el tipo y sus reglas) y cada línea su propio discount_type. Los locales sin tipos de descuento pueden enviar el campo: se ignora.
Artículos en promoción
Marque una línea del ticket como artículo en promoción con line_items[].promo: true en POST /v1/checks/calculate, POST /v1/transactions y POST /v1/holds. El propietario fija dos reglas para esas líneas en Desarrolladores → Reglas para cajas → Artículos en promoción: acumular cashback (activado por defecto) y pagar con cashback (desactivado por defecto). Una regla desactivada prevalece sobre cualquier regla del producto, la categoría y el local para esa línea: la línea no acumula nada (earn_percent: null, cashback_earned: 0) o no se puede pagar con cashback (redeemable: false). Una regla activada no cambia nada, la línea sigue sus reglas habituales. La parte del ticket que se puede pagar con cashback, max_redeem y, con el canje como descuento, redeem_allocated dejan fuera las líneas en promoción, así que reparta el cashback solo entre las líneas con redeemable: true. Cada línea de la respuesta lleva entonces promo (true o false), el ticket lo guarda y GET /v1/account devuelve las reglas en settings.promo_earn y settings.promo_redeem. Un valor distinto de true, false o null responde 400 parameter_invalid. Una devolución sigue lo que hizo la línea original, así que allí promo no hace falta. Los locales sin esta regla pueden enviar el campo: se ignora.
{
"member": "2000111703779",
"amount": 10000,
"line_items": [
{ "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "promo": true },
{ "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 3000 }
]
}{
"object": "check_calculation",
"amount": 10000,
"max_redeem": 900,
"cashback_earned": 500,
"earn_rate": 5,
"line_items": [
{ "sku": "4840001", "amount": 7000, "earn_percent": 5, "cashback_earned": 350, "redeemable": false, "promo": true },
{ "sku": "2040", "amount": 3000, "earn_percent": 5, "cashback_earned": 150, "redeemable": true, "promo": false }
],
...
}Regalos pendientes de entrega
El propietario fija las reglas en la página Regalos: un regalo por el total de compras (por ejemplo 5000 MDL, una botella de vino) o por alcanzar un nivel de cashback. Cuando un ticket supera el umbral o lleva al cliente a ese nivel, el regalo se abre y espera al cliente. Cada cliente recibe un regalo por regla, una sola vez; varios umbrales superados por un ticket abren varios regalos. Los clientes que ya habían superado el umbral antes de activar la regla no reciben nada, y una devolución no retira el regalo. Un regalo puede tener un plazo; después queda expired.
Flujo para la caja: 1) POST /v1/checks/calculate responde gifts.pending (ya esperando) y gifts.unlocks (lo que abrirá este ticket, con id: null), y la primera línea de display.cashier_text es el regalo: muéstrela al cajero. 2) POST /v1/transactions responde gifts.unlocked (abiertos por este ticket, con id) y gifts.pending. 3) El cajero entrega el regalo y pulsa Regalo entregado: llame a POST /v1/members/{member}/gifts/{gift_id}/give. El objeto member también lleva gifts.pending. Se envían los eventos gift.unlocked y gift.given. Los locales sin regalos nunca reciben el campo gifts, y las rutas de regalos responden 404 endpoint_not_found.
{
"object": "check_calculation",
"amount": 120000,
"cashback_earned": 6000,
"gifts": {
"pending": [],
"unlocks": [
{ "object": "gift", "id": null, "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "cashier_note": "From the shelf by the till", "status": "pending", "expires_at": "2026-12-16T10:00:00.000Z" }
]
},
"display": {
"cashier_text": "Gift: Bottle of wine (hand it to the guest) · Cashback earned: 60.00 MDL · Cashback balance: 210.00 MDL",
"receipt_lines": ["Gift: Bottle of wine (hand it to the guest)", "Cashback earned: 60.00 MDL", "..."]
},
...
}"gifts": {
"unlocked": [
{ "object": "gift", "id": "6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2", "title": "Bottle of wine", "source": "spend_threshold", "threshold": 500000, "level": null, "status": "pending", "unlocked_at": "2026-11-16T10:00:00.000Z", "expires_at": "2026-12-16T10:00:00.000Z", "given_at": null }
],
"pending": [ ... the same gift and any older ones still waiting ... ]
}curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/gifts/6f1c0b7e-3a2d-4b8e-9c55-0d2e7a91f4b2/give \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: give-6f1c0b7e" \
-H "Content-Type: application/json" \
-d '{ "register_id": "401", "cashier": "Ana" }'Modos de sellos
Por defecto un programa de sellos da 1 sello por ticket. El dueño de una tienda puede cambiarlo en la página Programa: 1 sello por ticket que tenga un producto de las categorías elegidas, o 1 sello por cada unidad de producto de las categorías elegidas (un producto pesado cuenta como una unidad), más un importe mínimo del ticket para un sello. Las categorías son los códigos category de tus line_items o de tu catálogo. Los modos por categoría necesitan line_items en POST /v1/transactions y POST /v1/checks/calculate; un ticket sin líneas da 1 sello y el importe mínimo se aplica a cualquier ticket. stamps_earned dice cuántos sellos dio el ticket; si pasan el umbral de la tarjeta más de una vez, se desbloquean varias recompensas a la vez y calculate también responde rewards_unlocked. Una anulación retira exactamente los sellos que quedan. En el modo por unidad un ticket se puede devolver por líneas con POST /v1/transactions/{external_id}/refunds: se retiran los sellos de las unidades devueltas (de recompensas sin usar si hace falta, nunca por debajo de cero) y la respuesta trae stamps_reversed. Los demás tickets de sellos se siguen devolviendo enteros con una anulación. Los locales sin modos de sellos mantienen 1 sello por ticket.
Hay que escanear la tarjeta
Con esta regla, un ticket, una visita, una reserva o una recompensa para una tarjeta solo se aceptan si la misma clave envió esa tarjeta a POST /v1/scans poco antes. Un número de tarjeta tecleado a mano en la caja se rechaza con scan_required. Envía la salida sin procesar del escáner a /v1/scans y luego sigue como siempre.
Ajustes manuales
Desactivados por defecto. Si el propietario los permite, una clave con el permiso members:adjust puede sumar o restar cashback indicando un motivo, hasta el límite por ajuste que fijó el propietario. Cada ajuste queda en el historial del socio y envía balance.adjusted.
curl https://loyaltyfy.io/api/v1/members/2000111703779/adjustments \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "ADJ-2026-0009", "amount": 2000, "reason": "Goodwill after a complaint" }'
# a negative amount takes cashback away