> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/readme.md).
# Guide du développeur
## Guide du développeur
Cette section se concentre sur les intégrations API avec The Wallet Crew. Elle couvre l'authentification, la référence API, une première requête et les principaux chemins à suivre ensuite.
Ouvrir la référence API Démarrer le quickstart
Exemples concrets
* Créer une Carte de fidélité après l'inscription ou le paiement.
* Mettre à jour les champs de la Carte après un événement CRM, billetterie ou POS.
* Transmettre les événements du cycle de vie du Wallet vers un backend, un CRM ou une pile d'analyse.
### Commencez ici
La plupart des projets développeur suivent le même chemin.
{% stepper %}
{% step %}
#### Obtenir des identifiants
Générez une clé API depuis la console d'administration dans **Paramètres → Sécurité → Clés API**.
Pour la plupart des premières intégrations, la clé API est envoyée dans le `X-API-KEY` .
{% endstep %}
{% step %}
#### Ouvrir la référence de l’API
Utilisez la référence API pour inspecter les points de terminaison, les corps de requête, les schémas de réponse et des exemples en direct.
[Ouvrir la référence API](https://docs.thewalletcrew.io/api-reference)
{% endstep %}
{% step %}
#### Faire une première requête
Commencez avec une Carte existante. C'est le moyen le plus rapide de valider l'accès au tenant, l'authentification et le comportement de mise à jour sans mêler la logique de création au premier test.
Continuer avec [Premiers pas avec l’API](/developers-guides/fr/integration-guides/getting-started-with-the-api.md).
{% endstep %}
{% step %}
#### Étendre l'intégration
Une fois que le premier appel de gestion fonctionne, passez aux flux de création, aux mises à jour, aux webhooks, aux scans et au reporting.
{% endstep %}
{% endstepper %}
### Authentification
Le principal point d'entrée développeur utilise une clé API. Générez la clé depuis la console d'administration, puis envoyez-la dans le `X-API-KEY` .
Certaines API à portée de tenant peuvent utiliser d'autres modèles d'authentification ou des scopes supplémentaires. Dans ce cas, le guide du point de terminaison ou la référence fait foi.
{% hint style="info" %}
Pour une première intégration, commencez avec les API documentées autour de `X-API-KEY`. C'est le chemin habituel pour la gestion des Cartes, les webhooks, les scans et la référence API interactive.
{% endhint %}
### Quickstart
Le flux de validation le plus rapide consiste à commencer avec une Carte déjà existante, à déclencher un appel de gestion, puis à confirmer le résultat sur cette Carte.
L'appel initial le plus courant est une actualisation de Carte :
## Update a pass and optionally its type.
> \*\*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": "" },\
> "additionalData": { "loyaltyTier": "gold" },\
> "options": { "updateMetadata": false }\
> }\
> \`\`\`
````json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Pass"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"SingleUpdatePassData":{"type":"object","allOf":[{"$ref":"#/components/schemas/SingleUpdatePassDataOptionsUpdatePassData"}],"properties":{"bypassQueue":{"type":"boolean","description":"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,"deprecated":true}},"additionalProperties":false,"description":"Data payload for single pass update operations."},"SingleUpdatePassDataOptionsUpdatePassData":{"type":"object","properties":{"identifiers":{"type":"object","additionalProperties":{"type":"string"},"description":"External identifiers of the customer for this pass. Keys must not start with `id.`; common examples are `y2.customerId` or `shopify.customerId`.\nUse an empty value to remove an identifier. Leave the collection empty to keep existing identifiers unchanged."},"additionalData":{"type":["null","object"],"additionalProperties":{"type":"null"},"description":"Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags)."},"passType":{"type":["null","string"],"description":"Optional pass type to convert the pass to."},"updateMetadata":{"type":"boolean","description":"Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update","default":false,"deprecated":true},"options":{"description":"Options for single pass update operations. Metadata recomputation is enabled by default.\nUse Neo.Web.Api.Controllers.PassController.SingleUpdatePassDataOptions.BypassQueue to apply the update synchronously instead of queueing.","$ref":"#/components/schemas/SingleUpdatePassDataOptions"}},"additionalProperties":false},"SingleUpdatePassDataOptions":{"type":"object","allOf":[{"description":"Options used when updating passes.","$ref":"#/components/schemas/UpdatePassDataOptions"}],"properties":{"bypassQueue":{"type":"boolean","description":"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}},"additionalProperties":false,"description":"Options for single pass update operations. Metadata recomputation is enabled by default.\nUse Neo.Web.Api.Controllers.PassController.SingleUpdatePassDataOptions.BypassQueue to apply the update synchronously instead of queueing."},"UpdatePassDataOptions":{"type":"object","properties":{"updateMetadata":{"type":"boolean","description":"When true, recompute and persist pass metadata. Updating metadata is slower and is usually unnecessary for notification-only updates."},"correlationId":{"type":["null","string"],"description":"Groups related updates under the same correlationId. Useful for batch updates (for example nightly jobs) to make retries and logs traceable."}},"additionalProperties":false,"description":"Options used when updating passes."},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/passes":{"patch":{"tags":["Pass"],"summary":"Update a pass and optionally its type.","description":"**Authorization:** Requires `Pass.Write` scope.\n\n**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.\n\n**Data:** Merged with existing data. Empty/null removes fields; omitted fields unchanged.\n\n**Metadata:** Set `options.UpdateMetadata=true` for recomputation (slower). Set `options.BypassQueue=true` for synchronous updates instead of queueing.\n\n**Type:** Optionally convert pass to different type.\n\n**Use Cases:** Update identifiers/metadata; push notifications; type conversion; bulk updates; urgent changes.\n\n**Example — update by platform pass ID:**\n```\nPATCH /api/{tenantId}/passes?id=xK9mP2nQr7sT\n \n{\n \"additionalData\": { \"loyaltyTier\": \"gold\" },\n \"options\": { \"updateMetadata\": true }\n}\n```\n**Example — update by external identifier:**\n```\nPATCH /api/{tenantId}/passes?id.shopify.customerId=12345\n \n{\n \"identifiers\": { \"email\": \"user@example.com\" },\n \"additionalData\": { \"loyaltyTier\": \"gold\" },\n \"options\": { \"updateMetadata\": false }\n}\n```","parameters":[{"name":"identifiers","in":"query","description":"identifier of the pass. To update a pass with a Wallet Crew internal id only specify `id` (example : `\"id\": \"Ed34kg3oA47\"`) to update a pass with external identifier prefix the key with `id.` (example : `\"id.y2.customerId\": \"1233332\"`) \n\nWhen multiple external identifiers is submitted all identifiers should be found. \nIf more than one pass is found an exception will be thrown.","schema":{"type":"object","additionalProperties":{"type":"string"}}},{"name":"passType","in":"query","description":"type of the pass to update. type name should be one of the file in the `server/passes/` tenant configuration.","schema":{"type":"string"}},{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"data related to this pass. This data will be merge with the existing data.","content":{"application/json":{"schema":{"description":"Data payload for single pass update operations.","$ref":"#/components/schemas/SingleUpdatePassData"}},"text/json":{"schema":{"description":"Data payload for single pass update operations.","$ref":"#/components/schemas/SingleUpdatePassData"}},"application/*+json":{"schema":{"description":"Data payload for single pass update operations.","$ref":"#/components/schemas/SingleUpdatePassData"}}}},"responses":{"200":{"description":"Pass update enqueued or applied successfully."},"404":{"description":"No pass found matching the provided identifiers.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
````
Cela valide la portée du tenant, l'authentification par clé API et le pipeline de mise à jour sur une vraie Carte. Utilisez [Premiers pas avec l’API](/developers-guides/fr/integration-guides/getting-started-with-the-api.md) pour la configuration de bout en bout.
S'il n'existe pas encore de Carte, commencez par [Flux d'inscription](/developers-guides/fr/integration-guides/wallet/enrolment-flows.md) ou [Création de Carte déclenchée par un connecteur](/developers-guides/fr/integration-guides/wallet/connector-triggered-pass-creation.md).
### Référence de l’API
Utilisez la référence API lorsque la forme exacte de la charge utile, le schéma de réponse ou le comportement du point de terminaison comptent.
#### Points d'entrée principaux
* [Référence de l’API](https://docs.thewalletcrew.io/api-reference)
* [Webhooks](/developers-guides/fr/integration-guides/webhooks.md)
### Guides du développeur
Ces pages couvrent les principaux modèles d'intégration.
* [Concepts clés](/developers-guides/fr/readme/key-concepts.md) pour la portée du tenant, les identifiants, les modèles et les bases du cycle de vie de la Carte.
* [Premiers pas avec l’API](/developers-guides/fr/integration-guides/getting-started-with-the-api.md) pour les premiers appels à portée de tenant sur des Cartes déjà existantes.
* [Flux d'inscription](/developers-guides/fr/integration-guides/wallet/enrolment-flows.md) pour la création de Carte pendant des parcours d'inscription hébergés ou personnalisés.
* [Création de Carte déclenchée par un connecteur](/developers-guides/fr/integration-guides/wallet/connector-triggered-pass-creation.md) pour l'émission pilotée par la source, basée sur les événements en amont.
* [Mettre à jour les données de Carte dans les modèles](/developers-guides/fr/integration-guides/wallet/update-pass-data-in-templates.md) pour mettre à jour les données de Carte et les afficher dans les modèles.
* [Moteur de templates](/developers-guides/fr/integration-guides/wallet/liquid-templating.md) pour la syntaxe DotLiquid prise en charge, les filtres personnalisés et la balise `minify` .
* [Webhooks](/developers-guides/fr/integration-guides/webhooks.md) pour la diffusion d'événements en temps réel.
* [API de scan](/developers-guides/fr/integration-guides/scan-api.md) pour l'ingestion des scans de codes-barres et de QR codes.
* [API Insights](/developers-guides/fr/integration-guides/insights-api.md) pour les requêtes sur les journaux, les événements et les métriques.
* [Connecteurs personnalisés](/developers-guides/fr/integration-guides/custom-connectors.md) pour la logique d'intégration côté tenant.
### Étapes suivantes courantes
Une fois la première requête réussie, l'étape suivante dépend généralement de l'objectif de l'intégration.
* Si des Cartes existent déjà, commencez par [Premiers pas avec l’API](/developers-guides/fr/integration-guides/getting-started-with-the-api.md).
* Si l'émission de Carte démarre dans une inscription, un paiement ou un formulaire hébergé, utilisez [Flux d'inscription](/developers-guides/fr/integration-guides/wallet/enrolment-flows.md).
* Si l'émission de Carte démarre à partir d'un événement du système source, utilisez [Création de Carte déclenchée par un connecteur](/developers-guides/fr/integration-guides/wallet/connector-triggered-pass-creation.md).
* Pour garder le contenu du Wallet à jour, poursuivez avec [Mettre à jour les données de Carte dans les modèles](/developers-guides/fr/integration-guides/wallet/update-pass-data-in-templates.md).
* Pour notifier d'autres systèmes en temps réel, utilisez [Webhooks](/developers-guides/fr/integration-guides/webhooks.md).
### FAQ
Comment l'authentification est-elle récupérée ?
Générez une clé API depuis la console d'administration, puis envoyez-la dans `X-API-KEY` pour les principales API de la plateforme documentées dans le flux de quickstart.
Où se trouve la référence API ?
Utilisez [Référence de l’API](https://docs.thewalletcrew.io/api-reference) pour le principal point d'entrée API.
Quel est le meilleur premier appel API ?
Une mise à jour forcée sur une Carte existante est généralement le meilleur premier appel, car elle valide l'accès au tenant, l'authentification et le chemin de mise à jour sans dépendre d'un flux de création.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.thewalletcrew.io/developers-guides/fr/readme.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.