Le connecteur reçoit HTTP 200 après une écriture dans monday CRM. La réponse contient pourtant une erreur GraphQL. Si le worker valide le dossier à partir du code HTTP, la mise à jour disparaît du suivi. Si le worker relance la création avec une nouvelle clé, le tableau peut recevoir un deuxième item.
Sous Symfony, faites remonter séparément le résultat HTTP, le résultat GraphQL et la preuve métier. Une lecture réussie doit fournir la page attendue. Une mutation doit fournir l’identifiant que le worker vérifiera avant de clôturer l’opération.
Prenez le dossier fictif R-7841. Si la page expire, reprenez l’inventaire. Si une notification arrive deux fois, retrouvez la première réception. Si l’écriture perd sa réponse, gardez l’opération ouverte jusqu’à la lecture de l’item.
Pour adapter le connecteur à vos tableaux, à vos règles commerciales et à l’ERP, retrouvez notre accompagnement en intégration monday CRM.
Faire remonter une erreur GraphQL malgré HTTP 200
Commencez par traiter la présence d’erreurs dans la réponse. GraphQL peut retourner des données partielles et une erreur dans le même corps. Pour une page d’inventaire, avancer avec ces seules données peut faire disparaître des items du rapprochement.
Conserver l’état avant de renvoyer la requête
Stockez l’identifiant de l’opération et le contexte avant l’appel. À la réception, rattachez au dossier le statut HTTP et le code d’erreur GraphQL disponible. Pour une mutation à l’issue incertaine, faites une lecture de contrôle avant de décider qu’elle doit être relancée. Erreurs de l’API monday.
Choisir une opération technique à tester sur un tableau pilote
Ouvrez une lecture des colonnes et des items sur un seul tableau. Ajoutez ensuite une écriture limitée à un champ dont le connecteur est propriétaire. Le guide du pilote monday CRM détaille la répartition entre formulaire, commerciaux et ERP.
Sur R-7841, le worker peut modifier la référence de demande pendant la recette. La date de relance reste attribuée à la commerciale. Si l’équipe veut aussi automatiser une transition, elle valide d’abord la règle et ses effets sur les notifications et sur la transmission à l’ERP.
Définir ce que le worker peut reprendre
- Lecture de tableau. Conservez le curseur uniquement pour la fenêtre de lecture en cours et reprenez avec les mêmes critères.
- Écriture à confirmer. Conservez la clé, l’item et les colonnes attendues. Une réponse perdue déclenche un rapprochement.
- Refus d’accès ou de schéma. Suspendez l’écriture touchée et indiquez la permission ou la colonne à vérifier.
Le journal de réception des webhooks a une autre fonction. Il protège le traitement d’une livraison reçue deux fois. La clé d’idempotence de l’API protège les tentatives d’une même mutation. L’index qui relie la référence externe à l’item sert à retrouver le dossier lorsque les deux fenêtres techniques ont expiré.
Écrire un transport GraphQL avec Symfony HttpClient
Le transport ci-dessous effectue un seul appel par tentative. Le worker programme les reprises et fournit la clé déjà conservée lorsqu’il demande une mutation. Il vérifie ensuite les champs propres à son opération dans les données retournées.
<?php
declare(strict_types=1);
use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class MondayRequestFailed extends RuntimeException
{
public function __construct(
public readonly string $reason,
public readonly ?string $retryAfter = null,
) {
parent::__construct($reason);
}
}
final class MondayGraphQlTransport
{
public function __construct(
private readonly HttpClientInterface $http,
private readonly string $token,
private readonly string $apiVersion,
) {
}
public function request(string $query, array $variables, ?string $operationKey = null): array
{
$headers = [
'Authorization' => $this->token,
'API-Version' => $this->apiVersion,
'Accept' => 'application/json',
];
if ($operationKey !== null) {
if (trim($operationKey) === '') {
throw new InvalidArgumentException('La clé d’écriture doit être enregistrée avant l’appel.');
}
$headers['Idempotency-Key'] = $operationKey;
}
try {
$response = $this->http->request('POST', 'https://api.monday.com/v2', [
'headers' => $headers,
'json' => ['query' => $query, 'variables' => (object) $variables],
'timeout' => 4,
'max_duration' => 12,
'max_redirects' => 0,
]);
$status = $response->getStatusCode();
$responseHeaders = $response->getHeaders(false);
$retryAfter = $responseHeaders['retry-after'][0] ?? null;
if ($status === 429) {
$response->cancel();
throw new MondayRequestFailed('quota', $retryAfter);
}
if ($status === 408 || $status >= 500) {
$response->cancel();
throw new MondayRequestFailed('resultat_inconnu');
}
if ($status !== 200 && ($status !== 409 || $operationKey === null)) {
$response->cancel();
throw new MondayRequestFailed('refus_http');
}
$body = $response->toArray(false);
if ($status === 409) {
$code = $body['errors'][0]['extensions']['code'] ?? null;
if ($code === 'IDEMPOTENCY_CONFLICT') {
throw new MondayRequestFailed('ecriture_en_cours', $retryAfter);
}
throw new MondayRequestFailed('refus_http');
}
if (($responseHeaders['api-version'][0] ?? null) !== $this->apiVersion) {
throw new MondayRequestFailed('version_inattendue');
}
if (($body['errors'] ?? []) !== []) {
throw new MondayRequestFailed('erreur_graphql');
}
if (!is_array($body['data'] ?? null) || array_is_list($body['data'])) {
throw new MondayRequestFailed('resultat_inconnu');
}
return $body['data'];
} catch (TransportExceptionInterface | DecodingExceptionInterface) {
throw new MondayRequestFailed('resultat_inconnu');
}
}
}
Configurez une version testée dans Symfony. En novembre 2026, la documentation indique 2026-10 comme version courante. Une divergence de l’en-tête de réponse bloque la clôture. Si la requête était une écriture, vérifiez l’item avant de lancer une autre opération. Versions de l’API monday.
Encoder les valeurs de colonne dans les variables de mutation
Sur le tableau de recette, préparez column_values avec json_encode($valeurs, JSON_THROW_ON_ERROR). La variable GraphQL contient la chaîne JSON des valeurs par identifiant de colonne. Le corps de la requête reste un objet JSON avec query et variables. Pour un statut, utilisez le libellé validé par le responsable du tableau, puis vérifiez l’identifiant renvoyé. Écriture des valeurs de colonne dans monday.
Contrôler les identifiants et les types de colonnes
Associez à chaque champ écrit l’identifiant du tableau, l’identifiant de la colonne, son type et la transformation attendue. Un libellé peut rester identique après recréation. Comparez les identifiants et les types au démarrage du lot avant toute mutation.
Pour un statut, validez aussi la valeur autorisée par le tableau pilote. Laisser le connecteur créer automatiquement un nouveau libellé peut masquer une divergence de mapping. Si le statut reçu n’appartient pas au contrat, isolez l’item et faites confirmer la correspondance par son responsable.
Isoler le jeton et les permissions de recette
Envoyez le jeton dans l’en-tête Authorization. Un jeton personnel hérite des accès de son titulaire. Vérifiez ces droits dans le tableau de recette et séparez les identifiants de recette et de production. Avec une application OAuth, choisissez les portées nécessaires aux lectures, écritures et abonnements retenus. Authentification de l’API monday.
Gardez le jeton dans la configuration privée du worker. Les traces peuvent contenir un identifiant de corrélation, l’ID de l’item et le code de refus. Évitez d’y placer l’en-tête d’authentification ou le formulaire complet. Un refus 403 se traite en vérifiant les droits du compte, du tableau et de la colonne.
Paginer sans changer de tableau ni avancer sur une page partielle
Interrogez items_page sous boards pour la première page. Utilisez ensuite next_items_page à la racine avec le curseur retourné. Contrôlez l’identifiant du tableau au départ et vérifiez que la réponse suivante contient bien la liste d’items et un curseur explicite, même lorsqu’il vaut null.
query PremierePage($tableaux: [ID!]!, $limite: Int!) {
boards(ids: $tableaux) {
id
items_page(limit: $limite) {
cursor
items { id name }
}
}
}
query PageSuivante($curseur: String!, $limite: Int!) {
next_items_page(cursor: $curseur, limit: $limite) {
cursor
items { id name }
}
}
Le curseur expire 60 minutes après la première requête. En cas d’expiration, recommencez l’inventaire et rapprochez les items par identifiant. Écartez les résultats de la passe incomplète du calcul des éléments absents. Les lectures d’items archivés demandent un traitement distinct. Pagination des items monday.
Éviter les doublons après une réponse perdue
Réutiliser la clé pour la même mutation
Enregistrez la clé avant l’envoi et conservez les variables qui décrivent l’intention. Un conflit IDEMPOTENCY_CONFLICT signale une tentative en cours pour cette clé. Lisez Retry-After avant de reprogrammer exactement la même requête. Une modification des colonnes à écrire constitue une autre opération et doit être validée comme telle.
Une réponse mémorisée peut être rejouée pendant 30 minutes. Certaines réponses et situations de quota du cache sortent de ce mécanisme. Le worker doit donc savoir rechercher l’item par sa référence et vérifier les valeurs écrites. Après expiration de la fenêtre, une ancienne clé ne suffit plus à protéger une création. Conditions d’idempotence de monday.
Pour R-7841, un HTTP 200 contenant une erreur et un fragment de données garde l’opération ouverte. Relisez l’item attendu. S’il porte la référence et la valeur prévues, enregistrez cette preuve. S’il manque, laissez le support arbitrer le dossier lorsqu’une nouvelle création pourrait doubler un item existant.
Erreurs fréquentes lors d’une reprise
Lorsque la file reprend après une interruption, vérifiez l’âge de l’opération originale avant de renvoyer une création. Le délai de la dernière tentative ne donne pas l’âge de la clé dans le cache. Si deux items portent la même référence, bloquez la création et gardez les deux identifiants à disposition du support pour qu’il vérifie leurs relations.
Accuser réception du webhook avant son traitement métier
La vérification initiale de l’URL demande de renvoyer le champ challenge reçu dans la réponse JSON. Ce chemin sert à configurer l’abonnement. Pour les notifications, vérifiez le contexte de l’abonnement et du tableau puis journalisez l’événement accepté avant de le transmettre au worker. Configuration des webhooks monday.
Quand la notification décrit un changement d’étape, relisez l’item et comparez son état au champ que l’opération est autorisée à modifier. Un ancien événement Nouveau n’a aucune raison de repasser sur une étape Qualifié confirmée depuis. Le support doit retrouver la décision dans la trace de traitement.
Rejouer les réponses dégradées avec un client simulé
Le client de recette doit pouvoir injecter un HTTP 200 avec des erreurs GraphQL, un 429 avec un délai, un 409 d’idempotence et une exception réseau. Pour chaque scénario, vérifiez le nombre d’appels, l’état retourné et la clé envoyée. Un test de transport n’établit pas que la mutation produit le bon état métier.
Dans le tableau de recette, vérifiez séparément que la mutation attendue retourne l’item visé et que la lecture suivante expose la bonne valeur. Rejouez ensuite la notification après une modification commerciale. La validation est terminée quand le rapprochement retrouve l’écriture et que le changement manuel reste visible.
Déclencher des actions distinctes selon le refus
- Quota. Réduisez la concurrence et différez les appels concernés. L’exemple remonte l’en-tête
Retry-After. Si votre transport conserve aussi le corps du refus, utilisez le délairetry_in_secondsfourni par l’API. - Colonne absente. Fermez les écritures sur le mapping concerné et continuez les lectures utiles au diagnostic.
- Issue inconnue. Placez l’opération dans la file de rapprochement avant de l’autoriser à repasser en écriture.
Suivez l’âge des opérations encore ouvertes et le nombre de dossiers qui exigent une lecture de contrôle. Le plus ancien dossier en attente a plus de valeur pour le support que le seul taux moyen de réponses HTTP. Limites de l’API monday.
Vérifier les dépendances avant d’ouvrir une autre mutation
Faites valider le mapping par la personne responsable du tableau et les règles de transition par les commerciaux. Les exercices de tests API aident à isoler les refus et le guide de rapprochement source-cible aide à qualifier les écarts après une reprise.
Ajoutez un deuxième tableau quand la lecture complète, l’écriture de recette et l’alerte de reprise fonctionnent indépendamment. Conservez les mêmes preuves par tableau. Ainsi une dérive de colonnes bloque le flux touché et le support garde accès aux autres diagnostics.
Conclusion — prouver chaque opération avant de clôturer le dossier
Figez la version de l’API et les colonnes écrites. Vérifiez le contenu GraphQL et l’identifiant retourné avant de marquer la demande comme traitée.
Testez la fin d’une pagination, la reprise d’une réponse perdue et une notification reçue après changement d’étape. Chaque scénario doit laisser une trace que le support peut retrouver à partir de la référence métier.
Ouvrez les écritures suivantes après avoir testé leurs effets sur le tableau, les automatisations et la commande. Gardez le rapprochement accessible pour les opérations qui restent en attente.
Notre équipe peut vous accompagner dans l’intégration de monday CRM sous Symfony, de la recette du transport aux contrôles de reprise sur vos tableaux.