Premiers pas avec l’API

Effectuez un premier appel d’API limité à un locataire sur une carte existante dans The Wallet Crew.

Premiers pas avec l’API

L’API Wallet Crew offre aux développeurs un contrôle programmatique sur les cartes. La création de Carte est prise en charge via le SDK Cinto, les connecteurs et POST /passes. Utilisez POST /passes pour les flux pilotés par le backend. Voir Cycle de vie de la Carte → Création d’une carte.

Chaque point de terminaison de l’API est rattaché à un tenant. Tous les appels incluent un {tenantId} segment de chemin et une clé API émise pour ce tenant. Un tenant est un espace de travail isolé sur la plateforme, souvent une marque ou une région. Si le modèle de tenant ne vous est pas familier, commencez par Concepts clés.

Exemples concrets

Déclencher un rafraîchissement de carte après la modification d’un solde de fidélité dans un CRM.
Enregistrer un scan en magasin ou sur site depuis un système de caisse (POS) ou de contrôle d’accès.
Envoyer une notification push à un détenteur de carte spécifique après un événement opérationnel.

Prérequis

Avant d’effectuer un premier appel API, assurez-vous que ces éléments existent déjà :

Un modèle de carte configuré dans le back-office.
Au moins une Carte créée via le documentation du SDK Cinto, un connecteur ou POST /passes.
Une clé API pour le tenant.

Étape 1 — Obtenir la clé API

Dans le back-office, accédez à Paramètres → Clés API et secrets → Clés API.

Créez une nouvelle clé API. La clé est automatiquement rattachée au tenant actuellement sélectionné dans le back-office. Copiez la clé lorsqu’elle est créée. Elle ne sera plus affichée.

Les clés API comportent des permissions. Une clé sans les permissions requises renvoie 401 ou 403. Utilisez la référence de l’API pour confirmer les exigences spécifiques au point de terminaison. Une page dédiée aux permissions des clés API sera ajoutée séparément.

Étape 2 — Comprendre l’URL de base

Les opérations OpenAPI ci-dessous incluent l’URL de base de production. Remplacez {tenantId} par l’identifiant du tenant. Cet identifiant est le slug utilisé dans l’URL du back-office. Par exemple, si l’URL du back-office contient /tenant/my-brand/, le tenantId est my-brand.

Chaque point de terminaison de l’API est rattaché à un tenant. Une clé émise pour un tenant ne peut pas accéder aux données d’un autre tenant.

Étape 3 — S’authentifier

Incluez la clé API dans chaque requête à l’aide de l’en-tête X-API-KEY .

Si la clé est absente ou invalide, l’API renvoie 401.

Étape 4 — Comprendre les identifiants de carte

L’API identifie les cartes via des identifiants externes — des clés qui relient une carte aux systèmes sources tels qu’un ID CRM, un numéro de fidélité ou un ID de billet. La plupart des points de terminaison acceptent un identifiant externe pour cibler la carte correcte.

Certains points de terminaison utilisent également l’identifiant interne passId. C’est courant pour les opérations directes comme l’envoi d’une notification à une carte spécifique.

Premiers appels courants

Forcer la mise à jour d’une carte

Une mise à jour forcée est souvent le meilleur premier appel lorsque des cartes existent déjà. Elle valide le rattachement au tenant, l’authentification et l’actualisation du fournisseur sur une carte réelle.

Update a pass and optionally its type.

patch

/api/{tenantId}/passes

Authorization: Requires Pass.Write scope.

Identification: Use internal id (e.g., id=Ed34kg3oA47) or external identifiers with id. prefix (e.g., id.y2.customerId=1233332). Multiple identifiers must match exactly one pass.

Data: Merged with existing data. Empty/null removes fields; omitted fields unchanged.

Metadata: Set options.UpdateMetadata=true for recomputation (slower). Set options.BypassQueue=true for synchronous updates instead of queueing.

Type: Optionally convert pass to different type.

Use Cases: Update identifiers/metadata; push notifications; type conversion; bulk updates; urgent changes.

Example — update by platform pass ID:

PATCH /api/{tenantId}/passes?id=xK9mP2nQr7sT
            
{
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": true }
}

Example — update by external identifier:

PATCH /api/{tenantId}/passes?id.shopify.customerId=12345
            
{
  "identifiers": { "email": "[email protected]" },
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": false }
}

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Paramètres de requête

passTypestringOptionnel

type of the pass to update. type name should be one of the file in the server/passes/ tenant configuration.

Corps

Data payload for single pass update operations.

additionalDataobject · nullableOptionnel

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

passTypestring · nullableOptionnel

Optional pass type to convert the pass to.

updateMetadatabooleanOptionnelObsolète

Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update

Default: false

bypassQueuebooleanOptionnelObsolète

Indicates whether the push update should bypass the queue and run immediately. Queuing helps protect the system load and should only be bypassed when required.

Default: false

Réponses

200

Pass update enqueued or applied successfully.

Aucun contenu

404

No pass found matching the provided identifiers.

patch/api/{tenantId}/passes

PATCH /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null,
  "passType": null,
  "options": {
    "bypassQueue": false,
    "updateMetadata": true,
    "correlationId": null
  }
}

Aucun contenu

Cet appel indique à la plateforme de récupérer à nouveau les données auprès des fournisseurs configurés, de reconstruire la carte et de pousser la version mise à jour vers l’appareil.

Enregistrer un scan

Lorsqu’un code-barres de carte est scanné dans un point de vente ou un système de contrôle d’accès, enregistrez l’événement via l’API Scan.

Record a pass barcode scan event

post

/api/{tenantId}/scans

Records scan events when pass barcodes/QR codes are scanned. Scans are correlated to passes and generate scan completion events for downstream systems (redemption, attendance tracking, etc.).

Authorization

Requires PassScan.Scan scope

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Corps

datastring · min: 3 · max: 2048Requis

Raw Data of the scan value

typestring · enumRequis

Type of data

Valeurs possibles:

Réponses

201

Scan successfully recorded; pass identifier returned

passIdstringRequis

Identifier of the pass

400

Invalid scan request (data too short/long, missing type)

401

Not authorized or invalid credentials

404

No pass found with matching scan data

500

Processing error during scan event generation

post/api/{tenantId}/scans

POST /api/{tenantId}/scans HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "data": "text",
  "type": "manual"
}

{
  "passId": "text"
}

Envoyer une notification push

Utilisez le point de terminaison de notification pour envoyer une notification push à un détenteur de carte spécifique.

Send a notification to the pass identified by its pass identifier

put

/api/{tenantId}/passes/{passId}/notification

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

passIdstringRequis

The internal identifier of the pass

tenantIdstringRequis

Corps

contentstring · nullableOptionnel

Could be null if LocalizedContent is specified

localizedContentobject · nullableOptionnel

Localized notification content by language code. Key: ISO 639-1 code or "iso2-region" (e.g., "en", "en-US"). Value: The notification content for that language.

Réponses

200

Aucun contenu

404

Not Found

put/api/{tenantId}/passes/{passId}/notification

PUT /api/{tenantId}/passes/{passId}/notification HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 92

{
  "content": null,
  "localizedContent": null,
  "options": {
    "updateData": false,
    "correlationId": null
  }
}

Aucun contenu

Référence de l’API

La référence complète de l’API est disponible sous Développeurs → Référence de l’API.

Utilisez-la pour les détails des points de terminaison, les corps des requêtes, les schémas de réponse et les exigences de permission.

Ouvrir la référence de l’API

FAQ

L’API peut-elle créer une nouvelle carte ?

Oui. La création de Carte est prise en charge via le SDK Cinto, les connecteurs et POST /passes. Utilisez POST /passes pour les flux pilotés par le backend. Voir Cycle de vie de la Carte → Création d’une carte.

Quel est le meilleur premier appel API ?

Une mise à jour forcée sur une carte existante est généralement le meilleur premier appel. Elle valide le périmètre du tenant, l’authentification et le chemin de rendu sur une carte réelle.

Les intégrations doivent-elles commencer par passId ou des identifiants externes ?

La plupart des intégrations commencent par des identifiants externes parce qu’ils existent déjà dans les systèmes sources. Utilisez passId lorsqu’une opération directe sur une carte nécessite l’identifiant interne.

Mis à jour il y a 23 jours