API des États du flux de travail

🚀 Pourquoi utiliser l’API des États du flux de travail?

Chaque emplacement fait passer les rendez-vous à travers un flux de travail : les états principaux fournis d’emblée par DataDocks (réservé, arrivé, démarré, etc.), plus tout état personnalisé ajouté par l’entrepôt, comme « Documents récupérés » entre l’arrivée et le déchargement. L’API des États du flux de travail est en lecture seule : elle retourne le flux de travail de l’emplacement afin que votre intégration connaisse les états existants, leur ordre, et le champ de date/heure associé à chacun.

Problèmes réels résolus par cette API

• Faire correspondre les états à votre système : Traduisez le state retourné sur les rendez-vous, incluant les états personnalisés, vers vos propres statuts.
• Découvrir les champs de date/heure : Identifiez le champ <state>_at à transmettre ou lire pour chaque état personnalisé sans codage en dur des clés.
• Respecter l’ordre de l’entrepôt : Utilisez position pour afficher la progression de la même manière que DataDocks.

Cet endpoint ne permet pas de créer, modifier ou supprimer des états. Veuillez utiliser le logiciel DataDocks pour gérer votre flux de travail.

Démarrage rapide en 5 minutes

1. Obtenez un jeton d’API et le sous-domaine de votre emplacement (voir Authentification).
2. Appelez l’endpoint de consultation.

Voir un exemple cURL

curl -H "Authorization: Token VOTRE_JETON_API" \
  "https://VOTRE_EMPLACEMENT.datadocks.com/api/v1/workflow_states"

Authentification

Toutes les requêtes doivent transmettre votre jeton dans l’en-tête Authorization (identique aux autres APIs d’emplacement). Consultez Authentification pour plus de détails.

Authorization: Token VOTRE_JETON_API

Consultation des États du flux de travail

Objectif

Retourne chaque état du flux de travail de l’emplacement, dans l’ordre du flux de travail. La liste comprend les états principaux, les états personnalisés, ainsi que ceux que l’emplacement a masqués. Un emplacement sans flux de travail configuré retourne les états principaux par défaut.

Requête HTTP

GET https://[location_subdomain].datadocks.com/api/v1/workflow_states

Paramètres de requête

Aucun. La réponse n’est pas paginée.

Format de la réponse

La racine du JSON est un tableau d’objets état, ordonnés par position.

Champ	Type	Description
state	String	Clé d’état. Il s’agit de la valeur retournée dans le champ state d’un rendez-vous
timestamp_key	String/null	Champ du rendez-vous qui indique quand l’état a été atteint (p. ex. approved_at, unloading_at) ; null si aucun horodatage associé
name	String	Nom affiché de l’état
parent_state	String/null	Pour un état personnalisé, l’état principal auquel il appartient ; null pour les états principaux
position	Integer	Ordre dans le flux de travail ; les états ultérieurs ont un numéro plus élevé
hidden	Boolean	Indique si l’emplacement masque cet état dans DataDocks

États principaux

state	timestamp_key
needs_booking	null
pending	null
booked	approved_at
arrived	arrived_at
started	started_at
completed	completed_at
left	left_at
cancelled	cancelled_at

États personnalisés

Un état personnalisé appartient toujours à un état principal (parent_state) et le suit dans le flux de travail. Sa timestamp_key correspond à sa propre clé suivie de _at, et ce champ apparaît sur le rendez-vous une fois l’état atteint. Consultez États personnalisés de workflow pour savoir comment lire et renseigner ces dates/heures.

Les clés des états personnalisés sont générées à partir du nom de l’état lors de sa création et ne changent pas si le nom est modifié. Lisez les clés à partir de cet endpoint plutôt que de les calculer à partir du nom.

Exemples de code

cURL

Voir un exemple cURL

curl -H "Authorization: Token VOTRE_JETON_API" \
  "https://VOTRE_EMPLACEMENT.datadocks.com/api/v1/workflow_states"

JavaScript

Voir un exemple JavaScript

const getWorkflowStates = async () => {
  const response = await fetch(
    "https://YOUR_LOCATION.datadocks.com/api/v1/workflow_states",
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  if (!response.ok) {
    const errorData = await response.text();
    throw new Error(`Échec lors de la récupération des états du flux de travail : ${errorData}`);
  }

  return response.json();
};

// Trouver les champs de date/heure des états personnalisés
getWorkflowStates().then((states) => {
  const customTimestampKeys = states
    .filter((state) => state.parent_state && state.timestamp_key)
    .map((state) => state.timestamp_key);

  console.log(customTimestampKeys); // p. ex. : ["paperwork_collected_at"]
});

Exemple de réponse

Voir un exemple de réponse

[
  {
    "state": "needs_booking",
    "timestamp_key": null,
    "name": "Besoin de réservation",
    "parent_state": null,
    "position": 0,
    "hidden": false
  },
  {
    "state": "pending",
    "timestamp_key": null,
    "name": "En attente d'approbation",
    "parent_state": null,
    "position": 1,
    "hidden": false
  },
  {
    "state": "booked",
    "timestamp_key": "approved_at",
    "name": "Réservé",
    "parent_state": null,
    "position": 2,
    "hidden": false
  },
  {
    "state": "arrived",
    "timestamp_key": "arrived_at",
    "name": "Arrivé",
    "parent_state": null,
    "position": 3,
    "hidden": false
  },
  {
    "state": "paperwork_collected",
    "timestamp_key": "paperwork_collected_at",
    "name": "Documents récupérés",
    "parent_state": "arrived",
    "position": 4,
    "hidden": false
  },
  {
    "state": "started",
    "timestamp_key": "started_at",
    "name": "Démarré",
    "parent_state": null,
    "position": 5,
    "hidden": true
  },
  {
    "state": "completed",
    "timestamp_key": "completed_at",
    "name": "Terminé",
    "parent_state": null,
    "position": 6,
    "hidden": false
  },
  {
    "state": "left",
    "timestamp_key": "left_at",
    "name": "Parti",
    "parent_state": null,
    "position": 7,
    "hidden": false
  },
  {
    "state": "cancelled",
    "timestamp_key": "cancelled_at",
    "name": "Annulé",
    "parent_state": null,
    "position": 8,
    "hidden": false
  }
]

Erreurs

Code d’erreur	Description	Cause possible
401	Non autorisé	Jeton API invalide ou manquant

Endpoints connexes

• API Rendez-vous - Lire et modifier les dates/heures des états des rendez-vous
• Webhooks – Être notifié lorsqu’un rendez-vous change d’état