Your AI Connector Docs

API des transactions

Une transaction est une opportunité de vente sur votre tableau de Pipeline de ventes — un titre, une valeur, l’étape dans laquelle elle se trouve, et éventuellement le contact auquel elle appartient et le membre de l’équipe auquel elle est assignée. Ce guide couvre la lecture et la gestion des transactions via l’API.

Tous les exemples ci-dessous utilisent le format de requête ?apiKey= en cURL et l’en-tête X-API-Key en JavaScript et Python — les deux fonctionnent sur chaque point de terminaison.

L’objet transaction 

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage est l’identifiant de l’une de vos étapes de pipeline — lisez-les avec GET /pipelines (voir Pipelines ci-dessous). Les identifiants d’étape sont uniques sur l’ensemble de vos pipelines, donc pipeline_id est dérivé de l’étape et est en lecture seule : default est votre pipeline principal, et il est null lorsque l’étape n’existe plus. Les horodatages sont au format ISO 8601.

Une affaire ne stocke que les champs indiqués ci-dessus. Lorsque vous en créez ou en mettez à jour une, tout autre champ est refusé avec une 400 qui le nomme, afin que rien de ce que vous envoyez ne soit perdu silencieusement. Conservez les données supplémentaires dans les champs personnalisés du contact associé.

Lister les transactions

GET /deals — renvoie les transactions de votre compte, de la plus récente à la plus ancienne.

Paramètres de requête (tous facultatifs) : stage (un identifiant d’étape), pipeline_id (uniquement les transactions sur ce pipeline), contact_id, limit (50 par défaut, 200 max), cursor (depuis le next_cursor de la page précédente).

cURL

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

Réponse (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Obtenir une transaction

GET /deals/{dealId}

curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Réponse (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

Une transaction qui n’existe pas, ou qui appartient à un autre compte, renvoie 404.

Créer une transaction

POST /deals — title et stage sont requis ; stage doit être l’un des identifiants d’étape de votre pipeline.

curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

Réponse (201)

{ "success": true, "deal_id": "deal_abc123" }

Mettre à jour une transaction

PUT /deals/{dealId} — envoyez uniquement les champs que vous souhaitez modifier (title, description, notes, value, stage, status, priority, contact_id, …). value doit être un nombre.

curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

Réponse (200) : { "success": true, "deal_id": "deal_abc123" }

Déplacer une affaire vers une autre étape

POST /deals/{dealId}/move — corps { "new_stage_id": "stage-3", "new_position": 0 }. La position 0 place la carte en haut de la colonne.

curl -X POST "https://api.youraiconnector.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'

Réponse (200) : { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Supprimer une affaire

DELETE /deals/{dealId} — supprime l’affaire. Cette action est irréversible.

curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Réponse (200) : { "success": true }

Pipelines

Chaque compte possède un pipeline principal (id: "default") ; vous pouvez en ajouter jusqu’à neuf autres, chacun avec ses propres étapes. Les identifiants d’étape et les balises de déclenchement doivent être uniques sur tous les pipelines du compte, et chaque pipeline peut marquer une étape comme son résultat won et une autre comme son résultat lost.

Lister les pipelines

GET /pipelines — tous les pipelines, le principal en premier, chacun avec ses étapes triées par position.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Réponse (200) :

{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}

Créer un pipeline

POST /pipelines — corps { "id"?, "name", "stages"?, "settings"? }. Laissez id vide pour en générer un. Chaque étape utilise les mêmes champs que la boîte de dialogue Étapes : id, name, color, position, trigger_tag facultatif (un chemin de balise, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (une étape du même pipeline) et outcome ("won" ou "lost").

curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'

Réponse (201) : { "success": true, "data": { "pipeline": { ... } } }. Un identifiant d’étape ou une balise de déclenchement déjà utilisé par un autre pipeline est une 400 nommant ce pipeline ; un identifiant qui existe déjà est une 409.

Mettre à jour un pipeline

PUT /pipelines/{pipelineId} — corps { "name"?, "stages"?, "settings"? }. stages remplace toute la liste, comme dans la boîte de dialogue Étapes. Utilisez default pour le pipeline principal. L’identifiant du pipeline lui-même ne peut pas être modifié.

Supprimer un pipeline

DELETE /pipelines/{pipelineId} — supprime un pipeline supplémentaire (le principal ne peut pas être supprimé). Si des transactions se trouvent encore dans ses étapes, l’appel répond 409 avec deal_count ; ajoutez ?delete_deals=true pour supprimer ces transactions en même temps que le pipeline. Cette action est irréversible.

Réponse (204).

Étapes suivantes

  • Pipeline de ventes — fonctionnement des étapes, des étiquettes d’étape, des pipelines multiples et du tableau.
  • API Tâches — les tâches peuvent être liées à une affaire avec deal_id.
  • Automatisations — les étapes Trouver des affaires et Trouver une affaire lisent les mêmes données au sein d’un flux de travail.