> ## Documentation Index
> Fetch the complete documentation index at: https://docs-pos.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Faire des requêtes

> URL de base et préfixe /v1, forme des réponses en succès et en erreur, et pagination page / pageSize.

Toutes les opérations de l'API sont servies sous le préfixe **`/v1`**, à partir
de l'URL de base du backend POS.

```
https://<votre-backend-pos>/v1/...
```

L'URL de base dépend de votre environnement (l'application n'est pas encore
déployée à une adresse publique fixe). Le chemin d'une opération apparaît dans la
[Référence API](/fr/developers/overview), par exemple `GET /v1/products` ou
`POST /v1/checkout/finalize`.

## Forme des réponses

### Succès

Les routes de domaine renvoient leur **charge utile directement**, en JSON brut —
il n'y a **pas** d'enveloppe `{ "data": … }` sur ces routes. Selon l'opération,
c'est un objet (un modèle de lecture), un tableau, ou une page.

```json theme={null}
{
  "id": "prod_123",
  "name": "…",
  "price": { "amount": 1990, "currency": "EUR" }
}
```

<Note>
  L'unique exception est `GET /v1/auth/whoami`, une route récente qui renvoie
  `{ "data": { "effectivePermissions": [ … ] } }`. Unifier toutes les réponses de
  succès sous une enveloppe `{ data }` est un chantier transverse
  **volontairement non réalisé** ici, car il toucherait le client API et toutes
  les applications.
</Note>

### Erreur

Un échec renvoie l'enveloppe d'erreur partagée :

```json theme={null}
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "statusCode": 400,
    "fieldErrors": [{ "field": "quantity", "message": "must be positive" }]
  }
}
```

* `code` — un `ResultCode` du noyau (voir [Codes d'erreur](/fr/developers/error-codes)).
* `message` — un message lisible.
* `statusCode` — le statut HTTP, cohérent avec le code d'état de la réponse.
* `fieldErrors` — présent uniquement sur `VALIDATION_FAILED` : la liste des
  erreurs de champ `{ field, message }`.

Une erreur de validation de requête est normalisée dans **exactement la même**
enveloppe qu'un rejet de cas d'usage.

## Pagination

Les opérations de liste se paginent par les paramètres de requête **`page`** et
**`pageSize`** (`pageSize` plafonné, en pratique à **100**).

```http theme={null}
GET /v1/deposits?page=1&pageSize=20
```

La réponse d'une liste paginée porte les éléments et le comptage :

```json theme={null}
{
  "items": [ … ],
  "total": 1,
  "page": 1,
  "pageSize": 20,
  "pageCount": 1
}
```

## Validation

Les schémas qui valident une requête au runtime sont les **mêmes** que ceux qui
génèrent le spec OpenAPI : les paramètres, la querystring et le corps documentés
sont exactement ceux validés à l'exécution. Un corps ou un paramètre invalide
produit un `400 VALIDATION_FAILED` avec `fieldErrors`.