> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.crowdchange.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Vue d'ensemble

> Apprenez à authentifier vos appels à l'API CrowdChange v2, les méthodes HTTP utilisées, les codes de réponse et les conventions de chaque endpoint.

L'API CrowdChange vous donne un accès programmatique à la plateforme de collecte de fonds : campagnes, équipes, pages personnelles, donateurs, transactions et webhooks. Elle est organisée en deux surfaces :

* **API côté serveur** (`/v2/private/...`) — pour les intégrations serveur à serveur de confiance. Elles retournent des données plus riches et prennent en charge les opérations d'écriture, comme les dons hors ligne et la gestion des webhooks. Ne les appelez jamais depuis un navigateur.
* **API côté client** (`/v2/client/...`) — des points de terminaison principalement en lecture (en plus du traitement des dons) qui peuvent être appelés en toute sécurité depuis des pages publiques, comme des widgets et des parcours de don personnalisés.

Toutes les requêtes et réponses utilisent le format JSON, et chaque requête doit être effectuée en HTTPS.

## URL de base

Utilisez l'URL de base qui correspond à la région où votre compte est hébergé :

| Environnement       | URL de base                   |
| :------------------ | :---------------------------- |
| Production (É.-U.)  | `https://api.crowdchange.co`  |
| Production (Canada) | `https://api.crowdchange.ca`  |
| Développement       | `https://api.crowdchange.dev` |

## Authentification

Chaque requête doit inclure votre **clé API** dans l'en-tête `Authorization`. Le préfixe `Bearer` est optionnel.

```http theme={null}
Authorization: Bearer {api-key}
```

Votre clé API identifie votre organisation (site). Les requêtes sans clé valide sont rejetées avec le code `403 Forbidden`. Gardez votre clé secrète et utilisez-la uniquement depuis des environnements serveur de confiance.

### Authentification de l'utilisateur

Un sous-ensemble des points de terminaison côté serveur agit au nom d'un utilisateur individuel (par exemple, pour gérer les campagnes, les équipes ou les pages personnelles qu'un utilisateur possède). Ceux-ci nécessitent un **jeton utilisateur** supplémentaire en plus de votre clé API.

1. Obtenez un jeton en appelant [Sign In](/api-reference/server-side/user-specific-apis/post_v2-private-user-login) avec les identifiants de l'utilisateur.
2. Envoyez le jeton retourné avec chaque requête spécifique à l'utilisateur, soit dans l'en-tête `auth-token`, soit comme paramètre de requête `token`.

```http theme={null}
Authorization: Bearer {api-key}
auth-token: {user-token}
```

Les jetons utilisateur expirent après 30 jours d'inactivité. Un utilisateur peut être connecté sur jusqu'à 10 appareils à la fois.

## Méthodes HTTP

L'API suit les conventions REST standards :

| Méthode | Utilisation                                                     |
| :------ | :-------------------------------------------------------------- |
| `GET`   | Récupère une ressource ou une liste de ressources.              |
| `POST`  | Crée une ressource, ou exécute une recherche ou une action.     |
| `PUT`   | Remplace une ressource existante par la représentation fournie. |

## Dates et heures

Toutes les valeurs de date et d'heure suivent la norme [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) et sont stockées et retournées en UTC. Les valeurs de date-heure sont formatées ainsi : `YYYY-MM-DD hh:mm:ss`.

## Codes de statut

L'API utilise les codes de statut HTTP habituels pour indiquer le résultat d'une requête :

| Code                       | Signification                                                           |
| :------------------------- | :---------------------------------------------------------------------- |
| `200 OK`                   | La requête a réussi.                                                    |
| `400 Bad Request`          | La requête était mal formée ou n'a pas pu être traitée.                 |
| `401 Unauthorized`         | L'authentification est manquante ou invalide.                           |
| `403 Forbidden`            | L'authentification a réussi, mais vous n'avez pas accès à la ressource. |
| `404 Not Found`            | La ressource demandée n'existe pas.                                     |
| `405 Method Not Allowed`   | La méthode HTTP n'est pas prise en charge pour ce point de terminaison. |
| `422 Unprocessable Entity` | Le corps de la requête a échoué à la validation.                        |
| `429 Too Many Requests`    | Vous avez dépassé la limite de requêtes; réessayez plus tard.           |

## Erreurs

Lorsque la validation échoue (`422`), la réponse liste chaque champ invalide et ses messages :

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "fieldname": [
      "Error message"
    ]
  }
}
```

Les autres erreurs retournent une enveloppe cohérente avec un `status` et un `message` :

```json theme={null}
{
  "status": "error",
  "message": {
    "error": [
      "A description of what went wrong."
    ]
  }
}
```