Pipeline

Lister les opportunités du pipeline

Retourne la liste paginée des deals (opportunités) du client (cursor v2). Tri stable created_at DESC, id DESC.

Un deal n'est PAS une entité distincte en base : c'est un client_contacts ayant pipeline_stage_id IS NOT NULL. Le sous-ensemble de champs exposé est volontairement réduit aux infos pertinentes pour la vue pipeline (coordonnées + stage + valeur + score). Pour le contact complet (custom_fields, tags, notes), utiliser GET /v1/contacts/{id}.

Filtres

• ?stage_id (uuid) — filtre exact sur la stage du pipeline.

Fiches fusionnées

Une fiche absorbée par une fusion n'apparaît plus dans la liste : son historique vit dans la fiche conservée, seule à être listée.

Pas de GET single

Aucun endpoint GET /v1/pipeline/deals/{id} n'est exposé — pour récupérer un deal individuel, utiliser GET /v1/contacts/{id} ou filtrer cette liste par ?stage_id.

curl -X GET 'https://api.capturia.io/v1/pipeline/deals' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

Placer un contact dans le pipeline

Place un contact existant dans une stage du pipeline (set pipeline_stage_id). Ne crée pas de contact — contact_id doit déjà exister et appartenir au client appelant (sinon 404 not_found). De même pour stage_id (404 not_found si la stage n'appartient pas au client).

Un contact_id qui désigne une fiche absorbée par une fusion répond 404 not_found : placer la fiche conservée à la place. Si la fusion est annulée depuis le tableau de bord, la fiche redevient accessible sous son ID.

Si le contact est déjà dans une stage du même pipeline, il y est déplacé. Le déplacement passe par le même moteur que le tableau de bord : il apparaît dans la chronologie du contact, déclenche les automatisations d'étape et le webhook, et compte comme une décision humaine (l'agent IA cesse de relancer ce lead).

Un contact rangé dans un autre pipeline que celui de la stage visée n'est pas déplacé : 422 business_rule_violation avec details.reason = other_pipeline (le transfert entre pipelines se fait depuis le tableau de bord). Un contact archivé n'est pas déplacé non plus (details.reason = contact_archived).

Un lead disqualifié ne change pas de stage tant que sa disqualification n'est pas levée : la requête retourne 409 lead_disqualified. Le déplacer vers une stage perdue, ou vers la stage de disqualification, reste accepté. La réouverture se fait depuis la fiche du lead dans le tableau de bord.

curl -X POST 'https://api.capturia.io/v1/pipeline/deals' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "contact_id": "8f3b1a2c-9d4e-4f5a-b6c7-d8e9f0a1b2c3",
  "stage_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}'

Déplacer un deal vers une autre stage

Déplace un deal (pipeline_stage_id) vers une nouvelle stage. Seul le déplacement de stage est exposé via cet endpoint — pour modifier les autres champs du deal (email, deal_value, etc.) utiliser PATCH /v1/contacts/{id}.

Préconditions

• Le deal cible doit exister, appartenir au client appelant, et avoir pipeline_stage_id IS NOT NULL, sinon 404 not_found. L'ID d'une fiche absorbée par une fusion répond aussi 404 not_found : déplacer la fiche conservée.
• La stage cible doit appartenir au client appelant, sinon 404 not_found.
• Le lead ne doit pas être disqualifié, sinon 409 lead_disqualified. Une stage perdue ou la stage de disqualification reste une cible acceptée ; sinon, rouvrir le lead depuis sa fiche dans le tableau de bord avant de rejouer la requête.
• La stage cible doit appartenir au pipeline du deal, et le contact ne doit pas être archivé, sinon 422 business_rule_violation (details.reason = other_pipeline ou contact_archived).

Le déplacement passe par le même moteur que le tableau de bord : il apparaît dans la chronologie du contact, déclenche les automatisations d'étape et le webhook, et compte comme une décision humaine (l'agent IA cesse de relancer ce lead).

curl -X PATCH 'https://api.capturia.io/v1/pipeline/deals/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "stage_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
}'

Retirer un deal du pipeline

Retire le deal du pipeline en mettant pipeline_stage_id = NULL. Le contact n'est PAS supprimé — il reste accessible via GET /v1/contacts/{id}. Pour supprimer définitivement le contact, utiliser DELETE /v1/contacts/{id}.

Le deal cible doit exister, appartenir au client appelant, et avoir pipeline_stage_id IS NOT NULL — sinon 404 not_found. L'ID d'une fiche absorbée par une fusion répond aussi 404 not_found : retirer la fiche conservée. Si la fusion est annulée depuis le tableau de bord, la fiche redevient accessible sous son ID. Un contact archivé reste dans son pipeline : 422 business_rule_violation (details.reason = contact_archived).

curl -X DELETE 'https://api.capturia.io/v1/pipeline/deals/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

Lister les stages du pipeline

Retourne la liste complète des stages des pipelines du client, triées par pipeline (dans l'ordre du dashboard), puis par stage_order ASC. Chaque stage nomme son pipeline (pipeline.name, pipeline.is_default) : un compte à plusieurs pipelines peut avoir deux stages du même nom. Chaque stage est enrichie d'un compteur contact_count calculé en temps réel (nombre de contacts du client actuellement positionnés sur cette stage, sans les contacts archivés ni fusionnés — utile pour les KPI de pipeline). Une stage masquée dans le dashboard reste listée, marquée is_hidden.

Réponse non-paginée

L'endpoint retourne toutes les stages du client en un seul appel (généralement < 20 par client, max 50). Le format de réponse reste compatible list V2 pour la cohérence des intégrations (pagination.next_cursor=null, pagination.has_more=false, pagination.limit et pagination.total_count égalent le nombre de stages retournées).

Lecture seule

Création / édition / réordonnancement des stages passe par le dashboard — aucun endpoint POST/PATCH/DELETE /v1/pipeline/stages n'est exposé.

curl -X GET 'https://api.capturia.io/v1/pipeline/stages' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'