Opérateurs de filtrage et de requête

Filtrez et paginez la liste des cartes à l’aide de conditions sur les champs, d’opérateurs sur les chaînes et les ensembles, et d’une pagination basée sur le décalage.

Opérateurs de filtre et de requête

Plusieurs points de terminaison liés aux cartes acceptent un filtre tableau qui restreint les résultats selon le champ de données de la carte. Utilisez les filtres avec la pagination pour récupérer exactement l’ensemble de cartes dont vous avez besoin.

Le filtrage est pris en charge sur ces points de terminaison :

GET /api/{tenantId}/passes — liste des cartes
POST /api/{tenantId}/passes/pushUpdate — déclencher une mise à jour push sur un ensemble filtré
POST /api/{tenantId}/passes/export/token — exporter un ensemble filtré

Retrieve passes with optional filtering, sorting, and pagination.

get

/api/{tenantId}/passes

Authorization: Requires Pass.Read scope.

Filtering: By identifiers (e.g., identifiers.email), metadata fields (e.g., metadata.loyaltyTier), pass type, or installation status (apple, google).

Sorting: By id, passType, creationDate, lastUpdateDate, apple, google, or any identifier/metadata field.

Pagination: Zero-based pageIndex and pageSize. Total count in x-pagination-total header.

Use Cases: Search passes by customer attributes; monitor installation status; filter by loyalty tier or campaign flag.

Example — list loyalty passes, page 0:

GET /api/{tenantId}/passes?pageIndex=0&pageSize=20
    &filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty
    &sortBy[0].field=creationDate&sortBy[0].direction=DESC

Example — passes installed on Apple Wallet:

GET /api/{tenantId}/passes?filter[0].field=installationStatus&filter[0].operator=contains&filter[0].value=apple

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Paramètres de requête

pageIndexinteger · int32Optionnel

Zero-based page index.

Default: 0

pageSizeinteger · int32Optionnel

Number of passes per page.

Default: 20

Réponses

200

Paged list of passes returned successfully.

Represents a pass returned by the API.

idstringOptionnel

Platform-assigned unique pass identifier. This is a random alphanumeric string generated at creation time and cannot be set by callers (e.g., xK9mP2nQr7sT).

secretstringOptionnel

Platform-generated opaque token used internally to authenticate pass delivery. Read-only; treat as confidential.

creationDateone ofOptionnel

Timestamp when the pass was created by the platform. Read-only. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings.

string · date-timeOptionnel

integer · int64Optionnel

lastUpdateDateone ofOptionnel

Timestamp of the most recent update. Equals CreationDate when no update has occurred. Read-only. Accepts ISO 8601 date-time string or Unix epoch seconds in request inputs. Responses are serialized as ISO 8601 date-time strings.

string · date-timeOptionnel

integer · int64Optionnel

passTypestringOptionnel

Type of pass, matching a file in the tenant server/passes/ configuration.

get/api/{tenantId}/passes

GET /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Paged list of passes returned successfully.

[
  {
    "id": "text",
    "secret": "text",
    "creationDate": "2026-08-09T00:02:10.091Z",
    "lastUpdateDate": "2026-08-09T00:02:10.091Z",
    "passType": "text",
    "identifiers": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": null
    },
    "additionalData": {
      "ANY_ADDITIONAL_PROPERTY": null
    },
    "providers": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Push update for passes matching the filter.

post

/api/{tenantId}/passes/pushUpdate

Authorization: Requires Pass.Write scope.

Filtering: Same as GetPasses�identifiers, metadata, pass type, installation status.

Async: Updates are queued. 200 response means scheduled, not complete. Monitor via statistics endpoint.

Data Merge: Merged into each matching pass. Set UpdateMetadata=true for recomputation (slower). Adjust Throughput for concurrency.

Bulk Operations: Ideal for campaigns, loyalty updates, seasonal offers. Use CorrelationId for tracking.

Use Cases: Campaign push; loyalty tier changes; offer refresh; bulk metadata updates.

Example — push a seasonal offer to all loyalty passes:

POST /api/{tenantId}/passes/pushUpdate
    ?filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty
            
{
  "additionalData": { "offer": "summer2025", "discount": "20%" },
  "options": {
    "updateMetadata": true,
    "throughput": 12,
    "correlationId": "campaign-summer-2025"
  }
}

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Paramètres de requête

Corps

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

Réponses

200

Passes scheduled for update; returns the count in the response body.

Result returned after scheduling a bulk push update operation.

passCountinteger · int32Optionnel

Count of passes scheduled for update.

post/api/{tenantId}/passes/pushUpdate

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

{
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null,
  "passType": null,
  "options": {
    "throughput": 1,
    "updateMetadata": true,
    "correlationId": null
  }
}

200

Passes scheduled for update; returns the count in the response body.

{
  "passCount": 1
}

Create a time-limited download token for exporting passes as Excel.

post

/api/{tenantId}/passes/export/token

Returns a short-lived signed URL (valid 5 minutes) that can be used to download the xlsx without an Authorization header. Filters are embedded in the token.

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Corpsobject · Neo.Web.Api.Controllers.FilterModel[]

Filter specification for pass queries.

fieldstringOptionnel

Field to filter by. Supported values: passType — pass type name (string).installationStatus — concatenation of installed wallet names (e.g. "apple", "google", "applegoogle"). Use contains to test for a single wallet.identifiers.{key} — an external identifier (string).metadata.{key} — a metadata field. The comparison type (string, number, boolean, datetime) is resolved automatically from the pass configuration.

operatorstring · enumOptionnel

Comparison operator to apply.

Valeurs possibles:

valuestring[] · nullableOptionnel

Filter value(s). Interpretation depends on Operator and the metadata field's configured type: String fields (identifiers.*, passType, installationStatus, or metadata.* configured as string) — plain string value for most operators; an array of strings for in / notIn.Numeric fields (metadata configured as number) — decimal number as a string, e.g. "42" or "3.14". Parsed using invariant culture (. as decimal separator).Boolean fields (metadata configured as boolean) — "true" or "false" (case-insensitive).Date fields (metadata configured as datetime) — ISO 8601 date-time string with timezone, e.g. "2024-06-01T00:00:00+00:00" or "2024-06-01T00:00:00Z". The value is converted to a unix timestamp (seconds) before comparison against the stored unix timestamp. The query parameter name is value (repeated for multiple values). Single value (equals, contains, startsWith, …):

GET /passes?filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding

Multiple values (in / notIn):

GET /passes?filter[0].field=passType&filter[0].operator=in&filter[0].value=boarding&filter[0].value=loyalty

Date comparison (metadata field configured as datetime):

GET /passes?filter[0].field=metadata.eventDate&filter[0].operator=greaterThan&filter[0].value=2024-01-01T00:00:00Z

Boolean comparison (metadata field configured as boolean):

GET /passes?filter[0].field=metadata.isVip&filter[0].operator=equals&filter[0].value=true
```</example>

Réponses

200

Download token created successfully.

downloadUrlstringOptionnel

post/api/{tenantId}/passes/export/token

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

[
  {
    "field": "text",
    "operator": "Contains",
    "value": [
      "text"
    ]
  }
]

200

Download token created successfully.

{
  "downloadUrl": "text"
}

Structure de la requête de filtre

Chaque condition de filtre est un FilterModel objet avec trois champs :

Champ

Type

Description

champ

string

Le champ de données de la carte sur lequel filtrer (p. ex. passType, loyaltyTier)

opérateur

string

L’opérateur de comparaison (voir ci-dessous)

valeur

string[]

Une ou plusieurs valeurs à comparer. Omettre pour isEmpty et isNotEmpty.

Les filtres sont transmis sous forme de paramètres de requête indexés :

filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding

Plusieurs conditions sont combinées avec un ET logique :

filter[0].field=passType&filter[0].operator=equals&filter[0].value=boarding
&filter[1].field=loyaltyTier&filter[1].operator=isNotEmpty

Opérateurs

Opérateurs de chaîne

Ces opérateurs comparent la valeur du champ à une seule chaîne.

Opérateur

Comportement

equals

Correspondance exacte

notEquals

Ne correspond pas

contains

Le champ contient la valeur comme sous-chaîne

startsWith

Le champ commence par la valeur

endsWith

Le champ se termine par la valeur

Exemple — cartes avec un niveau de fidélité qui contient « gold » :

filter[0].field=loyaltyTier&filter[0].operator=contains&filter[0].value=gold

Opérateurs de présence

Ces opérateurs vérifient si un champ a une valeur. Aucun valeur paramètre n’est requis.

Opérateur

Comportement

isEmpty

Le champ est absent ou nul

isNotEmpty

Le champ a une valeur non nulle

Exemple — cartes où externalId n’est pas défini :

filter[0].field=externalId&filter[0].operator=isEmpty

Opérateurs d’ensemble

Ces opérateurs correspondent à une liste de valeurs. Répétez le valeur paramètre pour fournir plusieurs entrées.

Opérateur

Comportement

in

Le champ correspond à n’importe quelle valeur de la liste

notIn

Le champ ne correspond à aucune des valeurs de la liste

Exemple — cartes de type boarding ou loyalty:

filter[0].field=passType&filter[0].operator=in&filter[0].value=boarding&filter[0].value=loyalty

in et notIn sont disponibles via l’API uniquement. La table des cartes du back-office n’expose pas ces opérateurs dans ses contrôles de filtre.

Pagination

Le point de terminaison de liste des cartes utilise une pagination par décalage.

Paramètre

Type

Par défaut

Description

pageIndex

integer

0

Index de page à base zéro

pageSize

integer

20

Nombre de résultats par page

La réponse inclut un x-pagination-total en-tête contenant le nombre total de cartes correspondantes sur toutes les pages.

Pour récupérer toutes les cartes par lots, incrémentez pageIndex jusqu’à ce que le nombre total soit consommé.

Combinaison des filtres et de la pagination

Les paramètres de filtre et de pagination sont indépendants et peuvent être librement combinés.

Mis à jour il y a 24 jours