# API BeMyTalent : du contact au devis

> Clés API, droits, contrat OpenAPI et exemple JavaScript testé : recherchez un contact, créez un devis brouillon et vérifiez le résultat dans BeMyTalent.

Source : https://www.bemytalent.com/fr/documentation-api · mis à jour le 2026-11-07 · autres langues : [de](https://www.bemytalent.com/de/api-dokumentation.md) · [it](https://www.bemytalent.com/it/documentazione-api.md) · [en](https://www.bemytalent.com/en/api-documentation.md)

Pour les développeurs d’outils métier

## API BeMyTalent : du contact au devis

Cette première référence couvre le parcours contact → devis des API REST. Les contrats describe complètent la découverte des autres domaines. Les clés et les droits REST sont distincts de ceux du connecteur MCP.

### Démarrage rapide

- Dans un dossier de test, ouvrez Paramètres → Agents & API et créez une clé dédiée avec les quatre droits ci-dessous.

- Copiez les adresses CRM et Comptabilité affichées dans cet écran. Elles doivent partager la même base, terminée par /functions/v1.

- Gardez la clé dans l’environnement de votre serveur. Les exemples ne demandent jamais une clé de service Supabase ni un jeton de session du navigateur.

- Vérifiez l’exercice comptable et la facturation du dossier. L’exemple utilise des données fictives et une TVA de démonstration à zéro : adaptez le taux à votre cas réel.

- `crm:read`

- `crm:write`

- `invoicing:read`

- `invoicing:write`

### Accès et périmètre

- La clé bmt_… porte le dossier : ce parcours n’envoie pas de project_id. Les références doivent appartenir à ce même dossier.

- Une clé par application et par environnement facilite sa révocation dans Paramètres → Agents & API. Contrôlez sa date d’expiration et remplacez-la avant échéance.

- Envoyez Authorization: Bearer suivi de la clé, et Content-Type: application/json pour les écritures. La clé reste côté serveur, hors du code source, des URL et des journaux.

- Les droits d’écriture REST sont plus larges que ceux du MCP. Accordez seulement ceux nécessaires ; une description d’API n’accorde aucun droit supplémentaire.

### Contrats et opérations

Les chemins ci-dessous se placent après /functions/v1. Les quatre descriptions demandent une authentification valide. Les descriptions des mandats et de la planification exigent aussi, respectivement, les droits mandates:read et planning:read. Le contrat OpenAPI téléchargeable couvre uniquement les cinq opérations de ce parcours.

**CRM : ressources, filtres et références**

`GET /crm-api/describe`

**Comptabilité et facturation : actions**

`GET /accounting-api?action=describe`

**Mandats et temps : actions**

`GET /mandates-api?action=describe`

**Planification : schémas et actions**

`GET /planning-api?action=describe`

| Opération | Méthode | Adresse relative | Droit requis | Réponse |
|---|---|---|---|---|
| Rechercher par e-mail exact | `GET` | `/crm-api/contacts` | `crm:read` | 200 |
| Créer le contact | `POST` | `/crm-api/contacts` | `crm:write` | 201 |
| Relire le contact | `GET` | `/crm-api/contacts/{id}` | `crm:read` | 200 |
| Préparer le devis brouillon | `POST` | `/accounting-api?action=create_offer` | `invoicing:write` | 200 |
| Relire le devis et ses lignes | `GET` | `/accounting-api?action=quotes&id={id}` | `invoicing:read` | 200 |

[Télécharger le contrat OpenAPI (.json)](https://www.bemytalent.com/.well-known/bmt-api/openapi.json)

### Contact → devis, pas à pas

- 1. Rechercher avant de créer Le filtre email est une égalité exacte, sensible à la casse. count est le total des résultats filtrés du CRM. Avec limit=2, tout total supérieur à un arrête l’exemple ; une recherche n’est pas une garantie d’unicité en cas de créations concurrentes.

- 2. Créer et relire le contact Si aucun contact ne correspond, POST /contacts renvoie HTTP 201 et data.id. Conservez cet identifiant, puis relisez la fiche. Ne créez pas de société séparée pour ce premier essai.

- 3. Créer le devis POST accounting-api?action=create_offer reçoit contact_id et lines. Une ligne contient description, quantity et unit_price_excl_vat. La réponse HTTP 200 porte invoice_id, document_kind=quote et status=draft. Même un devis utilise le champ invoice_id.

- 4. Relire le document GET accounting-api?action=quotes&id=… renvoie un tableau quotes avec les lignes. Contrôlez le contact, le statut et les montants. Les listes comptables générales sont bornées et signalées non exhaustives ; count ne vaut pas un total global.

- 5. Relire dans BeMyTalent Ouvrez Facturation → Devis dans le dossier d’essai. L’exemple n’appelle aucune émission ni aucun envoi. Le reçu local conserve les identifiants de l’essai.

```
curl --fail-with-body --get "$BMT_API_BASE/crm-api/contacts" \
  -H "Authorization: Bearer $BMT_API_KEY" \
  --data-urlencode "filter.email=integration-demo@example.invalid" \
  --data-urlencode "limit=2" --data-urlencode "offset=0"
```

```
{
  "first_name": "Alex",
  "last_name": "Integration Demo",
  "email": "integration-demo@example.invalid",
  "language": "fr"
}
```

```
{
  "subject": "INTEGRATION TEST — DO NOT SEND",
  "language": "fr",
  "qr_bill_enabled": false,
  "reminders_enabled": false,
  "lines": [
    {
      "description": "Demonstration service",
      "quantity": 2,
      "unit": "h",
      "unit_price_excl_vat": 100
    }
  ],
  "contact_id": "11111111-2222-4333-8444-555555555555"
}
```

Exemple de réponse de création, avec des identifiants fictifs. Les montants réels dépendent des lignes et de la configuration du dossier.

```
{
  "ok": true,
  "invoice_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  "document_kind": "quote",
  "status": "draft",
  "lines_count": 1
}
```

L’exemple Node.js 22+ réalise ces étapes sans relance automatique. Les variables sont à fournir par votre environnement serveur ; remplacez la base fictive par celle copiée dans BeMyTalent. Le fichier téléchargé contient le même code que celui exercé par les tests.

- Téléchargez le fichier JavaScript dans un répertoire dédié à cet essai.

- Renseignez BMT_API_BASE et BMT_API_KEY dans votre environnement, puis confirmez que le dossier ne contient que des données de test.

- Le script réserve bmt-contact-quote-receipt.json avant tout appel. Il refuse une nouvelle exécution si ce fichier existe. Conservez-le pour examiner le résultat ; ne le supprimez pas pour relancer à l’aveugle.

[Télécharger l’exemple JavaScript (.mjs)](https://www.bemytalent.com/.well-known/bmt-api/contact-quote.mjs)

```
export BMT_API_BASE="https://your-api-host.example.invalid/functions/v1"
# BMT_API_KEY: server environment / secret manager
BMT_DEMO_CONFIRMED=yes node contact-quote.mjs
```

### Reprises et doublons

- POST /contacts et create_offer acceptent l’en-tête facultatif Idempotency-Key (1 à 200 caractères ASCII visibles, sans espace). Le script conserve une clé distincte par création dans son reçu. Après une réponse perdue, réutilisez cette clé, la même clé API et exactement le même corps JSON. Sans cet en-tête, chaque appel reste une nouvelle création.

- Le devis et toutes ses lignes sont créés dans une transaction : une erreur annule cette création entière. Une reprise réussie porte Idempotency-Replayed: true. Le contact conserve son identifiant et rend ses champs actuels ; le devis rend son reçu de création initial. Relisez le document pour connaître son état actuel.

- La clé de reprise est isolée par dossier, clé API et opération. Un contenu différent ou un objet supprimé renvoie 409, sans recréation. Les reçus sont conservés jusqu’à la suppression du dossier. Conservez le lien entre votre référence métier, la clé de reprise et les identifiants BMT ; changer de clé API change aussi le périmètre antidoublons.

### Comprendre les réponses

**400**

Paramètre ou référence refusé. Un échec SQL annule la création concernée ; le contact et le devis restent deux opérations distinctes.

**401 / 403**

Vérifiez la validité de la clé, les droits accordés et l’accès au dossier.

**402**

Un accès actif au dossier est nécessaire pour écrire. Vérifiez son abonnement ou sa période d’essai.

**404**

La ressource n’est pas accessible dans ce dossier. Vérifiez l’identifiant et le périmètre.

**409 / 422**

Conflit métier ou référence incompatible. Relisez l’objet avant de décider de la suite.

**429**

Respectez retry_after_seconds renvoyé dans le corps. Pour une création, contrôlez aussi le résultat avant de recommencer.

**5xx / réseau**

Résultat potentiellement incertain. Aucun renvoi automatique des créations dans l’exemple.

### Versions et validation

Version du guide : 1.1.0

Cette version date le guide et son contrat partiel, pas toutes les API de BMT. Les tests exercent les requêtes documentées contre les handlers REST avec une authentification et un stockage synthétiques, et vérifient les refus et réponses incertaines. Une recette sur votre dossier reste nécessaire avant la production.