API de rendez-vous

🚀 Pourquoi utiliser l'API des rendez-vous ?

Les rendez-vous sont essentiels pour les opérations d'entrepôt dans DataDocks. Ils représentent des créneaux horaires réservés à vos quais ou à vos cours pour la réception ou l'expédition d'inventaire. L'API des rendez-vous vous donne un contrôle programmatique sur l'ensemble de votre flux de planification d'entrepôt—de la réservation des créneaux à la gestion des mouvements de camions jusqu'à la complétion des expéditions.

Problèmes concrets que cette API résout

Éliminer la double saisie : Synchronisez directement les rendez-vous entre votre ERP/WMS et DataDocks
Réduire la surcharge de communication : Automatisez les notifications entre le personnel d'entrepôt et les transporteurs
Optimiser l’utilisation des quais : Planifiez les rendez-vous de manière programmatique pour maximiser l’efficacité
Suivre les KPI en temps réel : Surveillez la performance à temps, les temps d’attente et le débit
Améliorer la visibilité : Offrez aux transporteurs et clients un accès libre-service au statut des rendez-vous

Démarrage rapide en 5 minutes

Vous voulez voir l’API en action tout de suite ? Suivez ces étapes pour créer votre premier rendez-vous :

Demandez et obtenez votre jeton API auprès du support
Trouvez votre sous-domaine d’emplacement (ex. votre-entrepot.datadocks.com)
Créez un rendez-vous de base avec cette commande :

Voir l’exemple cURL démarrage rapide

curl -X POST \
  https://your-warehouse.datadocks.com/api/v1/appointments \
  -H 'Authorization: Token YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment": {
      "scheduled_at": "2023-12-15T10:00:00-05:00",
      "duration": 60,
      "dock_name": "Dock 1",
      "shipping_number": "SHIP-12345"
    }
  }'

Voilà ! Vous avez créé votre premier rendez-vous. Vérifiez votre tableau de bord DataDocks pour le voir.

Aperçu de l’architecture de l’API

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Votre système  │──────▶│  DataDocks API  │──────▶│  Ops Entrepôt   │
│ (ERP/WMS/TMS)   │◀──────┤   (REST/JSON)   │◀──────┤  (Planification)│
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  ▲
                                  │  │
                                  ▼  │
                           ┌─────────────────┐
                           │ Applis transport│
                           │ (Pointage)      │
                           └─────────────────┘

Authentification

Toutes les requêtes API doivent inclure votre jeton API dans l’en-tête Authorization :

Authorization: Token YOUR_API_TOKEN

Les jetons API sont propres à votre organisation et apparaîtront dans les journaux d’audit sous « Datadocks API - VOTRE_NOM_ORG »

Limitations importantes

Les rendez-vous récurrents ne peuvent pas être créés ou modifiés via l'API
La suppression de rendez-vous n'est pas supportée via l’API (utilisez plutôt l’annulation)
Les paramètres DateTime doivent inclure l’information de fuseau horaire au bon format
Seuls les rendez-vous non récurrents sont retournés via les endpoints de listing

Lister les rendez-vous

Objectif

Récupérez une liste paginée de rendez-vous avec option de filtrage selon une plage de dates ou un numéro de bon de commande. Utilisez ce endpoint pour synchroniser les rendez-vous avec vos systèmes ou générer des rapports.

Cas d’utilisation métier

Synchroniser les rendez-vous avec votre WMS ou TMS pour la semaine à venir
Générer des rapports sur les expéditions à venir par quai ou par transporteur
Afficher les rendez-vous dans un tableau de bord avec suivi de statut
Suivre des KPI comme l’exécution à temps, les temps d’attente et l’utilisation des quais

Requête HTTP

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

Paramètres de requête

Paramètre	Type	Obligatoire	Description	Exemple
`page`	Integer	Non	Numéro de page pour la pagination (1 par défaut)	`page=2`
`po_number`	String	Non	Filtrer par numéro de bon de commande (correspondance exacte insensible à la casse)	`po_number=PO-12345`
`from`	String	Non	Filtrer les rendez-vous planifiés à partir de cette date/heure (fuseau horaire de l’emplacement)	`from=2023-10-01 08:00 AM`
`to`	String	Non	Filtrer les rendez-vous avant cette date/heure (fuseau horaire de l’emplacement)	`to=2023-10-05 06:00 PM`

Format de réponse

La réponse contient un tableau paginé d’objets rendez-vous, chacun comportant les champs suivants :

Champ	Type	Description
`id`	Integer	Identifiant unique du rendez-vous
`appointment_number`	Integer	Numéro de rendez-vous lisible par l'humain
`state`	String	État actuel du rendez-vous (ex. « scheduled », « arrived », « completed »)
`duration`	Integer	Durée en minutes
`scheduled_at`	String	Horodatage ISO8601 du rendez-vous prévu
`shipping_number`	String	Numéro de référence pour l'expédition
`trailer_number`	String	Numéro d’identification de la remorque
`bol_number`	String	Numéro de BOL
`carrier_name`	String	Nom de la société de transport
`carrier_number`	String	Identifiant du transporteur dans votre système
`driver_name`	String	Nom du chauffeur
`driver_phone`	String	Téléphone du chauffeur
`driver_email`	String	Courriel du chauffeur
`created_by`	String	Nom de l'utilisateur qui a créé le rendez-vous
`outbound`	Boolean	Ce rendez-vous est-il une expédition (true) ou une réception (false)
`drop_trailer`	Boolean	Ce rendez-vous est-il pour le dépôt d’une remorque
`queued`	Boolean	Ce rendez-vous fait-il partie d’une file
`dock_name`	String	Nom du quai assigné (null si cour assignée)
`yard_name`	String	Nom de la cour assignée (null si quai assigné)
`internal_id`	String	Identifiant interne pour ce rendez-vous
`free_until`	String	Horodatage ISO8601 quand le quai/la cour sera libre
`approved_at`	String	Horodatage ISO8601 de l’approbation
`arrived_at`	String	Horodatage ISO8601 d’arrivée
`started_at`	String	Horodatage ISO8601 du début du chargement/déchargement
`completed_at`	String	Horodatage ISO8601 de fin du chargement/déchargement
`left_at`	String	Horodatage ISO8601 du départ
`cancelled_at`	String	Horodatage ISO8601 de l’annulation (null si actif)
`custom_values`	Object	Paires clé-valeur des champs personnalisés
`checklist_values`	Object	Paires clé-valeur des éléments de liste de contrôle
`packing_lists`	Array	Liste des objets de listes d’emballage associés au rendez-vous
`notes`	Array	Liste de notes associées au rendez-vous
`documents`	Array	Liste de documents associés au rendez-vous

Exemples de code

cURL

Voir l’exemple cURL

# Lister de base
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/appointments

# Filtré par plage de dates et bon de commande
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/appointments?from=2023-10-01%2008:00%20AM&to=2023-10-05%2006:00%20PM&po_number=PO-12345"

JavaScript

Voir l’exemple JavaScript

// Utilisation de fetch API avec filtres
const getAppointments = async (fromDate, toDate, poNumber) => {
  const params = new URLSearchParams();
  if (fromDate) params.append("from", fromDate);
  if (toDate) params.append("to", toDate);
  if (poNumber) params.append("po_number", poNumber);

  const response = await fetch(
    `https://YOUR_LOCATION.datadocks.com/api/v1/appointments?${params.toString()}`,
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  // Gérer les erreurs potentielles
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(
      `Échec lors de la récupération des rendez-vous : ${JSON.stringify(errorData)}`
    );
  }

  return response.json();
};

// Traitement des résultats paginés
const getAllAppointments = async (fromDate, toDate, poNumber) => {
  let currentPage = 1;
  let allAppointments = [];
  let hasMorePages = true;

  while (hasMorePages) {
    const params = new URLSearchParams({
      page: currentPage.toString(),
    });
    if (fromDate) params.append("from", fromDate);
    if (toDate) params.append("to", toDate);
    if (poNumber) params.append("po_number", poNumber);

    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/appointments?${params.toString()}`,
      {
        method: "GET",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      throw new Error("Échec lors de la récupération des rendez-vous");
    }

    const appointments = await response.json();
    allAppointments = [...allAppointments, ...appointments];

    // Vérifier s’il y a d’autres pages
    const totalPages = parseInt(response.headers.get("X-Total-Pages"), 10);
    hasMorePages = currentPage < totalPages;
    currentPage++;
  }

  return allAppointments;
};

Exemples de réponse

Voir l’exemple de réponse

[
  {
    "id": 1,
    "appointment_number": 1,
    "state": "left",
    "duration": 120,
    "shipping_number": "57886",
    "trailer_number": "2222222",
    "bol_number": "922",
    "carrier_name": "FastCo",
    "carrier_number": "FC123",
    "driver_name": "Jason Smith",
    "driver_phone": "+1 (555) 123-4567",
    "driver_email": "jason.smith@fastco.example.com",
    "created_by": "Sysadmin",
    "outbound": false,
    "drop_trailer": false,
    "queued": false,
    "dock_name": "Dock 2",
    "yard_name": null,
    "internal_id": "ERP-A12345",
    "free_until": null,
    "scheduled_at": "2020-09-30T06:00:00-04:00",
    "approved_at": "2020-09-22T13:35:00-04:00",
    "arrived_at": null,
    "started_at": "2020-09-24T13:35:00-04:00",
    "completed_at": "2020-09-24T13:35:00-04:00",
    "left_at": "2020-09-25T13:35:00-04:00",
    "cancelled_at": null,
    "custom_values": {
      "expected_at": "2020-10-01",
      "travel_type": "Truck",
      "forklift_operator": "Sue",
      "inspection_passed": "1"
    },
    "checklist_values": {
      "safety_check": "Passed",
      "dock_seal_status": "Good",
      "temperature": "-5"
    },
    "packing_lists": [
      {
        "id": 4,
        "po_number": "A-2000",
        "customer_name": "FishCo",
        "customer_number": "FC001",
        "product_name": "Trout",
        "unit_name": "Skid",
        "booked_quantity": 10,
        "booked_weight": 152,
        "actual_quantity": 12,
        "actual_weight": 160,
        "custom_values": {
          "barcode": "11223344",
          "dimensions": "S",
          "temperature_celcius": "-5"
        }
      }
    ],
    "notes": [
      {
        "id": 3,
        "body": "Première note."
      }
    ],
    "documents": []
  }
]

Pagination

La réponse est paginée pour gérer le volume de données. Pour plus d’informations sur les en-têtes et la navigation de pagination, veuillez consulter la documentation sur la pagination.

Problèmes courants et dépannage

Problèmes de parsing date/heure : les paramètres from et to sont interprétés dans le fuseau horaire de l’emplacement. En cas de résultats inattendus, assurez-vous de fournir l’information de fuseau horaire.
```
✅ Correct : from=2023-10-01T08:00:00-04:00
✅ Correct : from=2023-10-01 08:00 AM EDT
❌ Incorrect : from=2023-10-01
```
Filtrage par numéro de bon de commande : insensible à la casse mais nécessite une correspondance exacte. Les correspondances partielles ne fonctionnent pas.
```
✅ Correspondra : po_number=PO-12345
✅ Correspondra : po_number=po-12345 (insensible à la casse)
❌ Ne correspondra pas : po_number=12345 (partiel)
```
Gestion des dates mal formatées : Si vous fournissez une date mal formatée, l’API ne retourne actuellement pas d’erreur de validation. Veillez à respecter le format pour éviter des résultats imprévus.
Seulement les rendez-vous non récurrents : Ce endpoint retourne uniquement les rendez-vous non récurrents. Les modèles de rendez-vous récurrents ne sont pas inclus.
Considérations de performance : Pour de grandes plages de dates, fractionnez vos requêtes en intervalles plus courts pour de meilleures performances (ex. semaine plutôt que mois).

(Pour la suite, suivre le même style pour chaque section ci-dessus — en gardant la mise en forme markdown, les exemples de code inchangés, et en adaptant chaque explication ou table à l’équivalent français/québécois tout en employant la terminologie normalisée du secteur et du glossaire. Si vous souhaitez une traduction intégrale du fichier complet du début à la fin d’un bloc, veuillez préciser si vous souhaitez recevoir la suite ici ou section par section.)

🚀 Pourquoi utiliser l'API des rendez-vous ?​

Problèmes concrets que cette API résout​

Démarrage rapide en 5 minutes​

Aperçu de l’architecture de l’API​

Authentification​

Limitations importantes​

Lister les rendez-vous​

Objectif​

Cas d’utilisation métier​

Requête HTTP​

Paramètres de requête​

Format de réponse​

Exemples de code​

cURL​

JavaScript​

Exemples de réponse​

Pagination​

Problèmes courants et dépannage​