Faire avancer une carte

Retrouver les cartes d'un pipeline, les changer d'étape, les clore ou les rouvrir, les confier à un responsable et à des intervenants, et écrire à leur sujet.

5 min de lecture Mise à jour le 11 novembre 2026

Une carte — une affaire, un ticket, une tâche… — circule dans les étapes d'un pipeline, du nouveau jusqu'à l'issue. Pour en créer une, voir Créer un contact, une société et une carte. Chaque geste ci-dessous exige le droit de modifier la carte : une carte que vous voyez sans pouvoir la modifier répond 403. Une carte introuvable, ou que vous ne voyez pas, répond 404 — la même réponse pour les deux, avant tout autre refus.

1Le pipeline et ses étapes

GET https://staging-api.docage.com/Pipelines/00000000-0000-4000-8000-000000000302
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl "https://staging-api.docage.com/Pipelines/00000000-0000-4000-8000-000000000302" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Pipelines/00000000-0000-4000-8000-000000000302");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Pipelines/00000000-0000-4000-8000-000000000302", {
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

PipelineStages : les étapes, chacune avec son Id, son nom, son rang (Order), son statut (Status), la probabilité qu'elle pose (Probability) ; IsDefault désigne l'étape d'entrée.
PipelineFailureReasons : les motifs d'échec, à donner en entrant dans une étape échouée.
QuickCompleteEnabled : la carte se clôt en un geste (§ 4).

Les étapes et les motifs se lisent aussi seuls : GET https://staging-api.docage.com/Pipelines/{id}/Stages et GET https://staging-api.docage.com/Pipelines/{id}/FailureReasons.

`Status`	Étape
`0`	Nouveau
`1`	En cours
`2`	En attente
`3`	Aboutie
`4`	Échouée
`5`	Close

2Retrouver des cartes

Les cartes ouvertes d'un pipeline, confiées à un utilisateur :

QUERY https://staging-api.docage.com/PipelineItems
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "PipelineId": "00000000-0000-4000-8000-000000000302",
  "Filter": {
    "OperatorType": "And",
    "Operands": [
      { "PropertyName": "HandlerId", "Comparison": "=", "Value": "00000000-0000-4000-8000-000000000601" },
      { "PropertyName": "ClosedDate", "Comparison": "=", "Value": null }
    ]
  },
  "SortOrder": "DueDate",
  "Take": 50,
  "EntityProperties": ["Id", "Name", "Reference", "StageId", "Status", "HandlerId", "MainContactId", "DueDate", "Amount"]
}

curl -X QUERY "https://staging-api.docage.com/PipelineItems" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "PipelineId": "00000000-0000-4000-8000-000000000302",
    "Filter": {"OperatorType": "And", "Operands": [{"PropertyName": "HandlerId", "Comparison": "=", "Value": "00000000-0000-4000-8000-000000000601"}, {"PropertyName": "ClosedDate", "Comparison": "=", "Value": null}]},
    "SortOrder": "DueDate",
    "Take": 50,
    "EntityProperties": ["Id", "Name", "Reference", "StageId", "Status", "HandlerId", "MainContactId", "DueDate", "Amount"]
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(new HttpMethod("QUERY"), "https://staging-api.docage.com/PipelineItems");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "PipelineId": "00000000-0000-4000-8000-000000000302",
      "Filter": {
        "OperatorType": "And",
        "Operands": [
          {
            "PropertyName": "HandlerId",
            "Comparison": "=",
            "Value": "00000000-0000-4000-8000-000000000601"
          },
          {
            "PropertyName": "ClosedDate",
            "Comparison": "=",
            "Value": null
          }
        ]
      },
      "SortOrder": "DueDate",
      "Take": 50,
      "EntityProperties": [
        "Id",
        "Name",
        "Reference",
        "StageId",
        "Status",
        "HandlerId",
        "MainContactId",
        "DueDate",
        "Amount"
      ]
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/PipelineItems", {
  method: "QUERY",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "PipelineId": "00000000-0000-4000-8000-000000000302",
    "Filter": {"OperatorType": "And", "Operands": [{"PropertyName": "HandlerId", "Comparison": "=", "Value": "00000000-0000-4000-8000-000000000601"}, {"PropertyName": "ClosedDate", "Comparison": "=", "Value": null}]},
    "SortOrder": "DueDate",
    "Take": 50,
    "EntityProperties": ["Id", "Name", "Reference", "StageId", "Status", "HandlerId", "MainContactId", "DueDate", "Amount"]
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

PipelineId restreint aux cartes d'un pipeline, DefinitionId à celles d'un type de carte, CompanyId à celles d'une société ; un filtre sur MainContactId rend celles d'un interlocuteur. Le nom de l'étape d'une carte se lit dans les étapes de son pipeline.

3Changer d'étape

PUT https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/MoveToStage/00000000-0000-4000-8000-000000000304?comment=Rappel%20client%20fait&position=0
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl -X PUT "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/MoveToStage/00000000-0000-4000-8000-000000000304?comment=Rappel%20client%20fait&position=0" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/MoveToStage/00000000-0000-4000-8000-000000000304?comment=Rappel%20client%20fait&position=0");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/MoveToStage/00000000-0000-4000-8000-000000000304?comment=Rappel%20client%20fait&position=0", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

200, sans corps. La carte prend le statut de l'étape, sa date d'entrée dans l'étape, la probabilité de l'étape quand elle en déclare une, et une ligne d'historique, qui garde comment. Paramètres facultatifs :

position : son rang dans la colonne, à partir de 0 — omis, la fin de la colonne. Avec l'étape où elle est déjà, il la range autrement dans sa colonne.
failureReasonId : le motif, vers une étape échouée (statut 4) ; ignoré ailleurs.
pipelineId : un autre pipeline du même type de carte.

Un refus répond 400 avec son motif : étape ou motif étranger au pipeline, pipeline d'un autre type de carte. Déplacer une carte vers l'étape où elle est déjà ne fait rien, pas même une ligne d'historique.

4Clore, échouer, rouvrir

Clore : PUT https://staging-api.docage.com/PipelineItems/{id}/Complete mène la carte à l'étape aboutie de son pipeline, quand le pipeline permet la clôture en un geste (QuickCompleteEnabled) ; sinon 400. Ailleurs, déplacez-la vers l'étape de statut 3.
Échouer : déplacez-la vers une étape de statut 4, avec failureReasonId.
Rouvrir : déplacez-la vers une étape ouverte (0 à 2) : sa date de clôture s'efface, son motif d'échec aussi.

Une étape de statut 3, 4 ou 5 date la clôture (ClosedDate). Dans un pipeline qui clôt une carte avec ses sous-cartes, une carte qui a encore des sous-cartes ouvertes ne se clôt pas (400), et la dernière sous-carte close clôt sa parente.

5Le responsable et les intervenants

Le responsable est celui qui a la carte en main :

PUT https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Handler?docageUserId=00000000-0000-4000-8000-000000000601
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl -X PUT "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Handler?docageUserId=00000000-0000-4000-8000-000000000601" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Handler?docageUserId=00000000-0000-4000-8000-000000000601");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Handler?docageUserId=00000000-0000-4000-8000-000000000601", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

L'utilisateur doit appartenir à l'organisation de la carte (QUERY https://staging-api.docage.com/DocageUsers pour le trouver). Sans docageUserId, la carte est relâchée : elle n'a plus de responsable. Les intervenants ne changent pas.

Les intervenants sont ceux qui peuvent la prendre, utilisateurs ou équipes (QUERY https://staging-api.docage.com/Teams) :

PUT https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Members
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

[
  { "DocageUserId": "00000000-0000-4000-8000-000000000602" },
  { "TeamId": "00000000-0000-4000-8000-000000000701" }
]

curl -X PUT "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Members" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '[{"DocageUserId": "00000000-0000-4000-8000-000000000602"}, {"TeamId": "00000000-0000-4000-8000-000000000701"}]'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Put, "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Members");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    [
      {
        "DocageUserId": "00000000-0000-4000-8000-000000000602"
      },
      {
        "TeamId": "00000000-0000-4000-8000-000000000701"
      }
    ]
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Members", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify([{"DocageUserId": "00000000-0000-4000-8000-000000000602"}, {"TeamId": "00000000-0000-4000-8000-000000000701"}])
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La liste envoyée remplace la précédente ; une liste vide les retire tous. Chaque entrée désigne un utilisateur ou une équipe, actifs et de l'organisation de la carte. Un refus répond 400 avec son motif.

La checklist s'enregistre de même, entière : PUT https://staging-api.docage.com/PipelineItems/{id}/Checklist, avec la liste des points (Label, IsDone, Order ; un point existant garde son Id). La date et l'auteur d'un point fait sont posés par le serveur. La réponse est la checklist enregistrée.

6Écrire au sujet de la carte

Une note interne, que seuls les collègues lisent :

cURL

curl -X POST "https://staging-api.docage.com/PipelineItems/00000000-0000-4000-8000-000000000401/Messages" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  --form-string "bodyHtml=<p>Pièce commandée, livraison jeudi.</p>" \
  -F "isInternal=true"

C'est un formulaire : bodyHtml (le message, en HTML), isInternal, isInbound, et des fichiers joints, qui deviennent ses pièces jointes. La réponse est l'identifiant du message.

`isInternal`	`isInbound`	Ce qui part
`true`	—	Une note interne, jamais montrée au client.
`false`	`false`	Un email à l'interlocuteur principal de la carte. Sans interlocuteur joignable par email, `422` : rien n'est écrit.
`false`	`true`	Une note « reçue » : ce que le client a dit hors de l'application, un appel retranscrit. La carte attend alors une réponse de l'équipe (`LastMessageFromCorrespondent`).

Le message entre dans la conversation ouverte la plus récente au sujet de la carte ; sans elle, une conversation s'ouvre avec l'interlocuteur, l'auteur, le responsable et les intervenants. La carte en garde le résumé : LastMessageDate, LastMessageExcerpt. Un email qui ne part pas répond 400 avec son motif ; il reste dans la conversation, en erreur.

Pour relire l'échange : GET https://staging-api.docage.com/Conversations/AboutRecord/PipelineItem/{id} liste les conversations au sujet de la carte — le type est toujours PipelineItem, quel que soit le type de carte —, puis GET https://staging-api.docage.com/Conversations/{id}/Messages en lit les messages.

Les pièges

isInternal vaut false d'office : sans lui, le texte part par email au client. Pour une note, envoyez isInternal=true.
Un email demandé à une carte sans interlocuteur joignable par email — aucun interlocuteur, ou un interlocuteur sans adresse — répond 422, et rien n'est écrit : pour garder le texte en note interne, renvoyez-le avec isInternal=true.
Le statut et les dates d'une carte suivent son étape : voir les pièges de Créer un contact, une société et une carte.