API y webhooks / Referencia / Añadir una visita
Añadir una visita
POST /v1/passages añade un sello o puntos a la tarjeta de un cliente desde tu TPV, e indica si se ha conseguido una recompensa.
POST
/v1/passagesEl equivalente a un escaneo en el mostrador, enviado por tu TPV: un sello (o varios), o puntos. Las reglas y los límites son los del mostrador, la tarjeta del cliente se actualiza en su Wallet y la visita cuenta como las demás (habituales, recordatorios, solicitud de reseña).
Cuerpo (JSON)
clientobjectobligatorio
Quién recibe la visita: uno de
id, carte (el código de la tarjeta), email o telephone.montantnumberopcional
Importe del ticket, en unidades (
12.5 para 12,50 €). Si el comercio tiene una regla «10 € = 1 sello», el importe prevalece sobre quantite; en modo puntos, se convierte con la regla de puntos por euro del comercio.quantiteintegeropcional
Modos tampons y paliers: número de sellos, 1 por defecto, 50 como máximo.
pointsintegeropcional
Modo points, sin importe: los puntos que poner. Por defecto, el valor del comercio.
referencestringopcional
El número del ticket. Una referencia solo sella una vez por comercio.
creer_si_absentbooleanopcional
true: un cliente desconocido, identificado por email o telephone, se crea (con prenom y nom si están en client). Por defecto false.conditions_accepteesbooleanopcional
Cuando el comercio exige sus condiciones y
creer_si_absent crea el cliente (en client o en la raíz).Ejemplo
curl https://app.stampywallet.com/v1/passages \
-H "Authorization: Bearer sw_live_votre_cle" \
-H "Content-Type: application/json" \
-d '{
"client": { "telephone": "+33612345678", "prenom": "Léa" },
"montant": 12.5,
"reference": "TICKET-4512",
"creer_si_absent": true
}'const r = await fetch('https://app.stampywallet.com/v1/passages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.STAMPY_CLE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
client: { telephone: '+33612345678', prenom: 'Léa' },
montant: 12.5,
reference: 'TICKET-4512',
creer_si_absent: true,
}),
});
const resultat = await r.json();
if (resultat.recompense_atteinte) console.log('¡Recompensa por entregar!');import os, requests
r = requests.post(
"https://app.stampywallet.com/v1/passages",
headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
json={"client": {"telephone": "+33612345678", "prenom": "Léa"},
"montant": 12.5, "reference": "TICKET-4512", "creer_si_absent": True},
)
print(r.json()["recompense_atteinte"])Respuesta
{
"passage": {
"id": "226fdea1-ba59-49fb-93e6-60a14a765134",
"client_id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7",
"valeur": 1,
"montant": 12.5,
"reference": "TICKET-4512",
"cree_le": "2026-10-22T09:20:00.000Z"
},
"rejoue": false,
"client_cree": false,
"recompense_atteinte": true,
"recompenses_gagnees": 1,
"plafonne": false,
"client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 0, "objectif": 10 } }
}| Campo | Significado |
|---|---|
passage.valeur | Los sellos o puntos puestos |
passage.montant | El importe registrado, o null |
rejoue | true cuando la reference ya se había usado: la respuesta es entonces 200 y devuelve la visita original, sin sellar una segunda vez |
client_cree | true si creer_si_absent ha creado el cliente |
recompense_atteinte, recompenses_gagnees | Esta visita hace ganar una recompensa (o varias): para entregar cuando el cliente la recoja |
plafonne | true si el valor se ha reducido al máximo del mostrador |
client | El objeto cliente después de la visita |
Los rechazos
| Estado | code | Cuándo |
|---|---|---|
404 | client_introuvable | Ningún cliente coincide y creer_si_absent no está a true |
409 | trop_tot | Hubo una visita del mismo cliente hace menos que el plazo antidoble visita del comercio (90 segundos por defecto) |
422 | montant_insuffisant | El importe no llega a un sello (o a un punto) |
422 | conditions_requises | El cliente se crearía, pero las condiciones del comercio no se han aceptado |
Atención : indica siempre una reference (el número de ticket): así, un TPV que reintenta tras un corte no pone dos sellos. Una referencia cuya visita se ha anulado no se vuelve a poner.
Actualizado el
¿Te ha sido útil esta página?Gracias por tu opinión.