i18n - docs translations (#15720)
Created by Github action <!-- CURSOR_SUMMARY --> --- > [!NOTE] > Adds a full French documentation set covering developers (API, webhooks, backend/frontend, self‑hosting) and user guide (CRM essentials, data model, workflows, settings, integrations, pricing, reporting). > > - **Docs (FR i18n)**: > - **Developers**: Add `API`, `Webhooks`, backend (best practices, custom objects, feature flags, architecture, commands, Zapier), frontend (best practices, architecture, commands, hotkeys, style guide, Storybook, Figma), self‑hosting (Docker Compose, upgrade guide, cloud providers), introduction. > - **User Guide**: Add getting started (what is Twenty, create/configure workspace, migration, import/export), CRM essentials (contacts/accounts, pipelines, views), data model (objects, fields, relations, table views), collaboration (emails/calendars, notes, tasks), integrations API (overview, integrations), workflows (getting started, features, credits, internal automations, services), settings (profile, permissions, members, domains, releases, email/calendar setup), pricing (billing/FAQ), reporting overview, resources (GitHub, glossary), introduction. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 9ba8c2457156e8d25bf41c055731acface4b5277. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Félix Malfait <felix@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
0fc538ac09
commit
154fb4665e
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: API
|
||||
image: /images/docs/getting-started/api.png
|
||||
info: Découvrez comment utiliser nos API.
|
||||
---
|
||||
|
||||
<Frame>
|
||||
<img src="/images/docs/getting-started/api.png" alt="Header" />
|
||||
</Frame>
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
L'API de Twenty permet aux développeurs d'interagir de manière programmée avec la plateforme CRM de Twenty. En utilisant l'API, vous pouvez intégrer Twenty avec d'autres systèmes, automatiser la synchronisation des données, et construire des solutions personnalisées autour de vos données clients. L'API fournit des points d'accès pour **créer, lire, mettre à jour et supprimer** des objets CRM principaux (comme les personnes et les entreprises) ainsi que pour accéder à la configuration des métadonnées.
|
||||
|
||||
**API Playground :** Vous pouvez désormais accéder à l'API Playground dans les paramètres de l'application. Pour essayer les appels API en temps réel, connectez-vous à votre espace de travail Twenty et naviguez vers **Paramètres → APIs & Webhooks**. Cela ouvre le API Playground intégré et les paramètres pour les clés API.
|
||||
**[Accédez aux paramètres de l'API](https://app.twenty.com/settings)**
|
||||
|
||||
## Authentification
|
||||
|
||||
L'API de Twenty utilise des clés API pour l'authentification. Chaque requête vers des points d'accès protégés doit inclure une clé API dans l'en-tête.
|
||||
|
||||
- **Clés API :** Vous pouvez générer une nouvelle clé API depuis la page de **paramètres de l'API** de votre application Twenty. Chaque clé API est un jeton secret qui accorde l'accès à vos données CRM, alors gardez-le en sécurité. Si une clé est compromise, révoquez-la dans les paramètres et générez-en une nouvelle.
|
||||
- **En-tête Auth :** Une fois que vous avez une clé API, incluez-la dans l'en-tête `Authorization` de vos requêtes HTTP. Utilisez le schéma de jeton Bearer. Par exemple :
|
||||
|
||||
```
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
```
|
||||
|
||||
Remplacez `VOTRE_CLÉ_API` par la clé que vous avez obtenue. Cet en-tête doit être présent sur **toutes les requêtes API**. Si le jeton est manquant ou invalide, l'API répondra avec une erreur d'authentification (HTTP 401 Non autorisé).
|
||||
|
||||
## Points d'accès API
|
||||
|
||||
Toutes les ressources peuvent être consultées via REST ou GraphQL.
|
||||
|
||||
- **Cloud :** `https://api.twenty.com/` ou votre domaine / sous-domaine personnalisé
|
||||
- **Instances auto-hébergées :** Si vous exécutez Twenty sur votre propre serveur, utilisez votre propre domaine à la place de `api.twenty.com` (par exemple, `https://<votre-domaine>/rest/`).
|
||||
|
||||
Les points d'accès sont groupés en deux catégories : **Core API** et **Metadata API**. L'**API principale** traite les données CRM primaires (personnes, entreprises, notes, tâches), tandis que l'**API des métadonnées** couvre les données de configuration (comme les champs personnalisés ou les définitions d'objets). La plupart des intégrations utiliseront principalement l'API principale.
|
||||
|
||||
### API principale
|
||||
|
||||
Accessible sur `/rest/` ou `/graphql/`.
|
||||
L'**API principale** sert de l'interface unifiée pour gérer les entités CRM principales (personnes, entreprises, notes, tâches) et leurs relations, offrant des modèles d'interaction **REST et GraphQL**.
|
||||
|
||||
### API de métadonnées
|
||||
|
||||
Accessible sur `/rest/metadata/` ou `/metadata/`.
|
||||
Les points d'accès de l'API de métadonnées permettent de récupérer des informations sur votre schéma et vos paramètres. Par exemple, vous pouvez récupérer les définitions des champs personnalisés, des schémas d'objets, etc.
|
||||
|
||||
- **Exemples de points d'accès :**
|
||||
|
||||
- `GET /rest/metadata/objects` – Liste tous les types d'objets et leurs métadonnées (champs, relations).
|
||||
- `GET /rest/metadata/objects/{objectName}` – Obtenez les métadonnées d'un objet spécifique (par exemple, `people`, `companies`).
|
||||
- `GET /rest/metadata/picklists` – Récupérer les options de champ de liste déroulante définies dans le CRM.
|
||||
|
||||
Typiquement, les points d'accès des métadonnées sont utilisés pour comprendre la structure des données (pour des intégrations dynamiques ou la création de formulaires) plutôt que pour gérer des enregistrements réels. Ils sont principalement en lecture seule dans la plupart des cas. Une authentification est également requise pour ceux-ci (utilisez votre clé API).
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Webhooks
|
||||
image: /images/docs/getting-started/webhooks.png
|
||||
info: Découvrez comment utiliser nos Webhooks.
|
||||
---
|
||||
|
||||
<Frame>
|
||||
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
||||
</Frame>
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Les Webhooks dans Twenty complètent l'API en permettant des **notifications en temps réel** à vos propres applications lors de certains événements dans votre CRM. Au lieu de sonder continuellement l'API pour les changements, vous pouvez configurer des webhooks pour que Twenty **pousse** des données vers votre système chaque fois que des événements spécifiques se produisent (par exemple, lorsqu'un nouvel enregistrement est créé ou qu'un enregistrement existant est mis à jour). Cela aide à synchroniser instantanément et efficacement les systèmes externes avec Twenty.
|
||||
|
||||
Avec les webhooks, Twenty enverra une requête HTTP POST à une URL que vous spécifiez, contenant des détails sur l'événement. Vous pouvez ensuite traiter ces données dans votre application (par exemple, pour mettre à jour votre base de données externe, déclencher des flux de travail ou envoyer des alertes).
|
||||
|
||||
## Configuration d'un Webhook
|
||||
|
||||
Pour créer un webhook dans Twenty, utilisez les paramètres **APIs & Webhooks** dans votre application Twenty :
|
||||
|
||||
1. **Naviguer vers les Paramètres :** Dans votre application Twenty, allez dans **Paramètres → APIs & Webhooks**.
|
||||
2. **Créer un Webhook :** Dans **Webhooks**, cliquez sur **+ Créer un webhook**.
|
||||
3. **Entrez l'URL :** Fournissez l'URL de l'endpoint sur votre serveur où vous souhaitez que Twenty envoie les requêtes webhook. Cela doit être une URL publiquement accessible qui peut gérer les requêtes POST.
|
||||
4. **Enregistrer :** Cliquez sur **Enregistrer** pour créer le webhook. Le nouveau webhook sera actif immédiatement.
|
||||
|
||||
Vous pouvez créer plusieurs webhooks si vous avez besoin d'envoyer différents événements vers différents endpoints. Chaque webhook est essentiellement un abonnement pour tous les événements pertinents (actuellement, Twenty envoie tous types d'événements à l'URL donnée ; filtrer des types d'événements spécifiques peut être configurable dans l'interface utilisateur). Si vous devez supprimer un webhook, vous pouvez le supprimer de la même page des paramètres (sélectionnez le webhook et choisissez supprimer).
|
||||
|
||||
## Événements et Charges utiles
|
||||
|
||||
Une fois qu'un webhook est configuré, Twenty enverra une requête HTTP POST à l'URL que vous avez spécifiée chaque fois qu'un événement déclencheur se produit dans vos données CRM. Les événements communs qui déclenchent les webhooks incluent :
|
||||
|
||||
- **Enregistrement Créé :** par exemple, une nouvelle personne est ajoutée (`person.created`), une nouvelle entreprise est créée (`company.created`), une note est créée (`note.created`), etc.
|
||||
- **Enregistrement Mis à Jour :** par exemple, les informations d'une personne existante sont mises à jour (`person.updated`), un enregistrement d'entreprise est édité (`company.updated`), etc.
|
||||
- **Enregistrement Supprimé :** par exemple, une personne ou une entreprise est supprimée (`person.deleted`, `company.deleted`).
|
||||
- **Autres Événements :** Si applicable, d'autres événements d'objet ou déclencheurs personnalisés (par exemple, si des tâches ou d'autres objets sont mis à jour, des types d'événements similaires seraient utilisés comme `task.created`, `note.updated`, etc.).
|
||||
|
||||
La requête POST du webhook contient une charge utile JSON dans son corps. La charge utile comprendra généralement au moins deux choses : le type d'événement et les données relatives à cet événement (souvent l'enregistrement qui a été créé/mise à jour). Par exemple, un webhook pour une nouvelle personne créée pourrait envoyer une charge utile comme :
|
||||
|
||||
```
|
||||
{
|
||||
"event": "person.created",
|
||||
"data": {
|
||||
"id": "abc12345",
|
||||
"firstName": "Alice",
|
||||
"lastName": "Doe",
|
||||
"email": "alice@example.com",
|
||||
"createdAt": "2025-02-10T15:30:45Z",
|
||||
"createdBy": "user_123"
|
||||
},
|
||||
"timestamp": "2025-02-10T15:30:50Z"
|
||||
}
|
||||
```
|
||||
|
||||
Dans cet exemple :
|
||||
|
||||
- `"event"` spécifie ce qui s'est passé (`person.created`).
|
||||
- `"data"` contient les détails du nouvel enregistrement (les mêmes informations que vous obtiendriez si vous demandiez cette personne via l'API).
|
||||
- `"timestamp"` est le moment où l'événement s'est produit (en UTC).
|
||||
|
||||
Votre endpoint devrait être prêt à recevoir de telles données JSON via POST. En général, vous allez analyser le JSON, regarder le type d'événement `"event"` pour comprendre ce qui s'est passé, et ensuite utiliser les `"data"` en conséquence (par exemple, créer un nouveau contact dans votre système ou mettre à jour un contact existant).
|
||||
|
||||
**Remarque :** Il est important de répondre avec un **statut HTTP 2xx** depuis votre endpoint webhook pour accuser réception avec succès. Si l'expéditeur du webhook de Twenty ne reçoit pas une réponse 2xx, il peut considérer que la livraison a échoué. (À l'avenir, une logique de réessai pourrait tenter de renvoyer les webhooks échoués, donc essayez toujours de retourner un 200 OK aussi rapidement que possible après le traitement des données.)
|
||||
|
||||
## Validation des Webhooks
|
||||
|
||||
Pour garantir la sécurité de vos endpoints webhook, Twenty inclut une signature dans l'en-tête `X-Twenty-Webhook-Signature`.
|
||||
|
||||
Cette signature est un hachage HMAC SHA256 de la charge utile de la requête, calculé en utilisant votre clé secrète.
|
||||
|
||||
Pour valider la signature, vous devrez :
|
||||
|
||||
1. Concaténer le timestamp (de l'en-tête `X-Twenty-Webhook-Timestamp`), un deux-points, et la chaîne JSON de la charge utile
|
||||
2. Calculer le hachage HMAC SHA256 en utilisant votre clé secrète comme clé ()
|
||||
3. Comparer le résultat de la somme de contrôle hexadécimale avec l'en-tête de signature
|
||||
|
||||
Voici un exemple en Node.js :
|
||||
|
||||
```javascript
|
||||
const crypto = require("crypto");
|
||||
const timestamp = "1735066639761";
|
||||
const payload = JSON.stringify({...});
|
||||
const secret = "your-secret";
|
||||
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
|
||||
const signature = crypto.createHmac("sha256", secret)
|
||||
.update(stringToSign)
|
||||
.digest("hex");
|
||||
```
|
||||
Reference in New Issue
Block a user