# Concepts

> Comptes, applications, environnements, entreprises connectées, numéros, messages et événements : le vocabulaire de Bref Point Inbox.

## Le modèle en un coup d'œil

```text title="Qui possède quoi"
Compte (votre société)
 └─ Application (« Mon CRM »)
     ├─ Environnement sandbox ──┐
     └─ Environnement production┤  chacun contient, strictement séparés :
                                │
                                ├─ Clés API
                                ├─ Destinations de webhooks
                                └─ Entreprises connectées (vos clients)
                                    └─ Compte WhatsApp Business (WABA)
                                        ├─ Templates
                                        └─ Numéros
                                            └─ Messages et événements
```

| Terme | Signification |
|---|---|
| **Compte** | Vous : le développeur ou l'éditeur qui utilise Bref Point Inbox. C'est l'unité d'isolation : aucune donnée n'est jamais visible d'un compte à l'autre. |
| **Application** | Un projet de votre côté. Elle regroupe vos environnements et vos clés. |
| **Environnement** | `sandbox` (test, gratuit, illimité) ou `production`. Deux univers étanches. |
| **Entreprise connectée** | **Votre client**, propriétaire d'un compte WhatsApp Business. Vous en créez autant que vous avez de clients. |
| **Compte WhatsApp (WABA)** | Le compte WhatsApp Business de votre client chez Meta. Il porte les templates. |
| **Numéro** | Un numéro WhatsApp d'envoi et de réception, rattaché à un compte WhatsApp. C'est lui que vous désignez par `phoneNumberId` pour envoyer. |
| **Message** | Un message envoyé (`outbound`) ou reçu (`inbound`) par un numéro. |
| **Événement** | Une notification envoyée à vos webhooks : message reçu, délivré, lu, échoué… |

<Callout type="note" title="Trois identifiants à ne pas confondre">
`phoneNumberId` dans l'API Bref Point Inbox est **notre** identifiant du numéro (un UUID). L'identifiant que Meta donne au numéro (chiffres seulement) n'apparaît que lors de la [connexion du compte](/docs/guides/connect-whatsapp), sous le même nom de champ dans le corps de cette requête.
</Callout>

## Le cycle de vie d'un message sortant

```text
queued ──► sent ──► delivered ──► read
   │         │          │
   └─────────┴──────────┴──► failed
```

| Statut | Signification |
|---|---|
| `queued` | Accepté par l'API, en attente d'envoi. La réponse `202` signifie exactement cela. |
| `sent` | Remis à Meta. |
| `delivered` | Meta a remis le message à l'appareil du destinataire. |
| `read` | Le destinataire a lu le message (si ses paramètres de confirmation de lecture le permettent). |
| `failed` | Refusé ou non remis ; `error.code` et `error.message` expliquent pourquoi. |
| `received` | (messages `inbound` uniquement) message reçu d'un client. |

Un statut **ne recule jamais** : si Meta nous livre les événements dans le désordre ou en double, un message `read` ne redevient pas `delivered`, et un échec n'écrase pas un message déjà lu.

## Les principes de l'API

- **Asynchrone** : `POST /messages` répond tout de suite ; l'envoi réel et ses reprises se font en arrière-plan. Suivez l'avancement par [webhooks](/docs/guides/webhooks).
- **Idempotente** : l'en-tête `Idempotency-Key` garantit qu'un envoi rejoué n'est jamais exécuté deux fois. Voir [Fiabilité](/docs/guides/reliability).
- **Isolée** : une ressource d'un autre compte ou d'un autre environnement répond `404`, comme si elle n'existait pas.
- **Observable** : chaque réponse porte un en-tête `X-Request-Id`, repris dans les erreurs et dans le [journal des appels](/docs/api/logs).