Emite tarjetas de fidelidad/cashback que tu cliente agrega a Apple Wallet con un tap — sin instalar ninguna app. Un Program es el diseño de tu tarjeta (una marca, un tipo de recompensa); un Pass es la tarjeta ya emitida para un cliente concreto, con su saldo.
Google Wallet todavía no existe — googleUrl siempre vuelve null.
Creas un Program por diseño de tarjeta (ej. "Cashback Café Aroma"). Cada cliente final recibe un Pass dentro de ese program, con su propio saldo de puntos/cashback/sellos. La autenticación normal (Authorization: Bearer, ver Autenticación) aplica a todo lo de esta página excepto las dos rutas marcadas públicas más abajo.
/wallet/programsname es lo único obligatorio — el resto trae valores por defecto razonables. → { program }/wallet/programs/:id/wallet/programs · /wallet/programs/:idcertificateMode:'own'.Campos de POST/PATCH — todo lo que Apple deja personalizar en un pase storeCard lo expone esta API, es el mismo motor que usa el editor visual del Dashboard:
| Campo | Tipo | Notas |
|---|---|---|
name | string | Solo en POST, obligatorio. |
type | 'cashback'|'points'|'stamps' | Solo en POST (default 'cashback') — inmutable, PATCH lo ignora si lo mandas. |
certificateMode | 'shared'|'own' | Solo en POST (default 'shared') — inmutable. Ver certificado propio abajo. |
label | string | Nombre del negocio en el pase (organizationName). Si lo omites, usa name. |
primaryColor | hex, #0F172A | Fondo de la tarjeta (default un azul oscuro). |
foregroundColor | hex | Texto principal (default #FFFFFF). |
labelColor | hex | Etiquetas pequeñas de cada campo (default #C8C8C8). |
secondaryColor | hex o '' | Activa un degradado vertical (franja detrás del valor). '' quita un degradado ya guardado. Ver nota sobre el degradado. |
logoUrl | URL https | Se descarga y se convierte a los tamaños que exige Apple al vuelo. Debe ser https:// (no http). Si falla la descarga, el pase se genera igual con un placeholder de color sólido. |
headerText | string | Texto pequeño arriba de todo (ej. "Gracias por tu visita"). |
primaryLabel | string | Label bajo el valor grande. Si lo omites: "CASHBACK"/"PUNTOS"/"SELLOS" según type. |
secondaryLabel | string | Solo relevante con type:'cashback' — label del campo secundario de puntos. |
auxiliaryLabel / auxiliaryValue | string | Campo extra opcional (ej. "Nivel" / "Oro"). Los dos juntos o ninguno. |
backText | string | Mensaje en el reverso de la tarjeta (ej. términos, "válido en todas las sucursales"). |
valueFormat | 'number'|'money' | Cómo se lee el valor grande. Si lo omites: 'money' para cashback, 'number' para points/stamps. |
currency | 'MXN'|'USD'|'EUR' | Solo aplica con valueFormat:'money' (default 'MXN'). |
storeCard — solo admite imagen en la franja superior (strip.png), el resto del pase es siempre un color sólido. Con secondaryColor activo, esa franja lleva un degradado vertical de primaryColor a secondaryColor, y el color sólido del resto de la tarjeta pasa a ser secondaryColor — así el borde inferior de la franja se funde con el resto de la tarjeta (queda una sola costura, arriba, en vez de dos).certificateMode:'shared' (default) usa el certificado de Zoosial — el program nace appleStatus:'active' de una vez, sin pasos extra. 'own' es para negocios que quieren su propia marca Apple (Pass Type ID propio):
/wallet/programs/:id/apple/connect{ csr, instructions[] } — el CSR se sube en tu cuenta Apple Developer./wallet/programs/:id/apple/certificate.cer que te dio Apple. → { status, expiresAt } (fecha real leída del certificado)./wallet/programs/:id/apple/status{ status('pending_connection'|'csr_generated'|'active'), passTypeId?, expiresAt? }/wallet/passes{ pass, appleUrl, googleUrl }. appleUrl ya trae el token de descarga (?t=) — es el link completo para "Agregar a Apple Wallet", listo para mandar por WhatsApp/SMS o convertir en QR. 409 si customerId ya tiene un pase en ese program./wallet/programs/:id/passes{ passes: [{ pass, appleUrl }] } — todos los pases del program, con el link de descarga ya armado./wallet/passes/:id/wallet/passes/:id/download?t=… público.pkpass firmado. La abre el teléfono del cliente final, sin cuenta de Zoosial — es el link que le mandas (o su QR). El ?t= es obligatorio y solo lo tiene la respuesta de creación.appleUrl es una URL normal, genera el QR del lado de tu app (cualquier librería de QR sirve, es solo texto). El Dashboard de Zoosial lo hace así mismo, en el navegador./wallet/passes/:id/transactions{ transaction }. amount negativo para descontar/redimir; 400 si el movimiento deja el saldo en negativo. El pase instalado se refresca solo en el iPhone del cliente en segundo plano (no bloquea la respuesta)./wallet/passes/:id/transactions[?limit=]# 1. Crea el program (diseño de la tarjeta) curl -X POST https://zoosial.com/wallet/programs \ -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \ -d '{ "name": "Café Aroma", "type": "cashback", "primaryColor": "#3E2723", "secondaryColor": "#6D4C41", "foregroundColor": "#FFFFFF", "logoUrl": "https://cafearoma.mx/logo.png", "primaryLabel": "CASHBACK", "valueFormat": "money", "currency": "MXN" }' # -> { "program": { "id": "prog_…", … } } # 2. Emite un pase para un cliente curl -X POST https://zoosial.com/wallet/passes \ -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \ -d '{ "programId": "prog_…", "customerId": "cli-102", "customerName": "Ana López", "cashback": 0 }' # -> { "pass": {...}, "appleUrl": "https://zoosial.com/wallet/passes/pass_…/download?t=…", "googleUrl": null } # 3. Entrega appleUrl al cliente (QR, WhatsApp, SMS) -- al abrirlo en su iPhone, # Safari ofrece "Agregar a Apple Wallet" solo, sin cuenta de Zoosial. # 4. Más tarde, registra una compra curl -X POST https://zoosial.com/wallet/passes/pass_…/transactions \ -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \ -d '{ "type": "cashback", "amount": 45.50, "reason": "compra en tienda" }' # El pase instalado en el iPhone de Ana se actualiza solo, sin que vuelva a escanear nada.
/wallet/apple-service/v1/* es el protocolo de Apple que hace que el saldo se refresque solo en el Wallet del cliente. No lo llama tu integración — lo llama Apple Wallet directo, con la credencial que ya trae incrustada cada pase. No hace falta implementar nada de esto: basta con llamar a POST .../transactions o PATCH /wallet/programs/:id y el push sale solo.