Un traitement Symfony doit relire l’opportunité Insightly 7841 avant de transmettre le dossier à l’équipe projet. L’API renvoie un statut 429 alors que des exports et des traitements commerciaux utilisent la même instance.
Le risque est de retarder le démarrage du projet pendant que le traitement répète une lecture qui ne peut pas encore aboutir. Le code HTTP identifie la limitation. La décision dépend du budget restant, de la dernière lecture confirmée et du délai accepté pour transmettre le dossier.
Le lecteur ci-dessous appelle un seul endpoint, contrôle l’identifiant reçu et laisse au traitement la décision de reprise. Le dossier 7841 est fictif et les exemples se testent avec des réponses simulées.
Pour cadrer les accès et le traitement d’un premier dossier réel, partez de votre projet d’intégration Insightly et des décisions que le commerce doit pouvoir retrouver dans le journal.
Pour qui écrire un lecteur Insightly
Les développeurs Symfony peuvent réutiliser le même lecteur pour alimenter un système tiers, rapprocher ses références et recetter les accès. Les trois parcours vérifient alors l’origine de la réponse et l’identité de la fiche de la même façon.
Répartir les décisions entre le client et le traitement
Le client HTTP vérifie l’origine, le statut et la forme de la réponse. Le traitement décide quand relire l’opportunité, quand différer un lot et si le dossier peut avancer. Après une interruption, le support doit retrouver ces décisions à partir du même identifiant de dossier.
Commencez par une lecture utilisée par le transfert de projet. Ajoutez ensuite le rapprochement des contacts et des organisations avec des opérations distinctes. Si plusieurs consommateurs ont besoin de la même fiche, décidez avec le métier combien de temps une lecture reste exploitable avant de la partager.
Configurer HTTP Basic pour la bonne instance
Relevez l’URL d’API dans les paramètres de l’utilisateur Insightly. Elle contient le pod de son instance et se termine par /v3.1/. Avec HTTP Basic, Symfony reçoit la clé API en identifiant et un mot de passe vide. Les droits effectifs sont ceux de l’utilisateur associé à la clé. Documentation Insightly sur l’accès à l’API.
En recette, utilisez une clé et un dossier dédiés à cet environnement. Vérifiez que le compte de lecture voit l’opportunité et ses relations utiles, puis consignez les champs réellement accessibles. Ne journalisez ni la clé ni l’en-tête d’autorisation.
Injecter les deux paramètres dans Symfony
Dans un projet Symfony qui utilise le namespace App, placez la classe au chemin src/Integration/InsightlyReader.php et injectez les valeurs de déploiement. La barre oblique finale de l’URL permet de résoudre le chemin relatif sous /v3.1/. Authentification avec Symfony HttpClient.
Faites approuver le couple environnement et instance avant d’activer le traitement. Si l’instance de recette répond avec la clé de recette, alors confirmez aussi l’identifiant du dossier témoin. Deux comptes peuvent partager le même pod et exposer des fiches différentes.
# config/services.yaml
services:
App\Integration\InsightlyReader:
arguments:
$httpClient: '@http_client'
$baseUri: '%env(INSIGHTLY_API_BASE_URL)%'
$apiKey: '%env(INSIGHTLY_API_KEY)%'
Lire une opportunité avec Symfony
Le lecteur construit GET /v3.1/Opportunities/7841 à partir de l’identifiant. Il exige HTTP 200 et vérifie OPPORTUNITY_ID dans le JSON. Une réponse qui contient une autre opportunité doit être examinée avant toute transmission de données. Référence des ressources Insightly v3.1.
Les délais de 5 et 12 secondes sont des valeurs de recette. Le premier borne l’attente pendant une période d’inactivité et le second borne la durée totale. Les redirections sont désactivées. Utilisez le client HTTP standard pour cet exemple et programmez les relances de lecture dans le traitement qui connaît l’état du dossier. Délais réseau de Symfony HttpClient.
<?php
declare(strict_types=1);
namespace App\Integration;
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class InsightlyReader
{
private HttpClientInterface $client;
public function __construct(
HttpClientInterface $httpClient,
string $baseUri,
#[\SensitiveParameter] string $apiKey,
) {
if (!preg_match('~\Ahttps://api\.[a-z0-9-]+\.insightly\.com/v3\.1/\z~', $baseUri)) {
throw new \InvalidArgumentException('URL Insightly v3.1 invalide.');
}
if ($apiKey === '' || preg_match('/[:\x00-\x20\x7f]/', $apiKey)) {
throw new \InvalidArgumentException('Clé API Insightly invalide.');
}
$this->client = $httpClient->withOptions([
'base_uri' => $baseUri,
'auth_basic' => [$apiKey, ''],
'headers' => ['Accept' => 'application/json'],
'max_redirects' => 0,
'timeout' => 5,
'max_duration' => 12,
]);
}
public function readOpportunity(int $id): array
{
if ($id < 1) {
throw new \InvalidArgumentException('Identifiant d’opportunité invalide.');
}
$response = $this->client->request('GET', 'Opportunities/' . $id);
$status = $response->getStatusCode();
if ($status !== 200) {
throw new \RuntimeException('Lecture Insightly refusée ou indisponible.', $status);
}
$record = $response->toArray(false);
if (($record['OPPORTUNITY_ID'] ?? null) !== $id) {
throw new \UnexpectedValueException('L’opportunité reçue ne correspond pas à la demande.');
}
return $record;
}
}
Le code retourne le document brut au traitement. Symfony signale séparément une erreur de transport ou un JSON illisible. Pour suivre le quota, relevez X-RateLimit-Remaining dans l’instrumentation du client, y compris sur les réponses 429, sans consigner les données de la fiche.
Injectez ce lecteur dans le service qui prépare le transfert. Validez l’ID au retour, traduisez les données vers votre modèle, puis consignez la version lue et la décision avant de soumettre la transmission. Si la lecture échoue, alors le dossier garde son état et la file conserve l’identifiant à relire.
Vérifier les identifiants et les relations
Conservez l’identifiant Insightly avec l’instance et le type de ressource. Dans le dossier fictif, le traitement associe l’opportunité 7841 à l’organisation 320, puis transmet cette référence à l’équipe projet. Vérifiez les relations sur la fiche ou sur la ressource dédiée avec les droits du compte exécutant.
Traiter un rapprochement qui attend une décision
Si deux organisations restent candidates après une recherche, consignez les deux identifiants et demandez un arbitrage. Un nom commun ou un domaine partagé ne suffit pas à choisir le compte. Une fois le choix validé, conservez la correspondance pour les prochains traitements et la référence de la décision.
Pour relire un lot, les endpoints qui les documentent acceptent top et skip. La pagination par décalage peut bouger si les fiches sont modifiées entre deux appels. Conservez les identifiants traités et contrôlez la couverture du périmètre avant de déclarer la lecture complète. Pagination et filtres Insightly.
Si une opportunité réapparaît pendant le rattrapage, alors comparez sa version avec celle déjà traitée. Vous pouvez éviter un second transfert si la lecture correspond à la même version. Si les valeurs ont changé, reprenez la décision pour les champs que le flux gère.
Erreurs fréquentes et décisions de reprise
Pour chaque réponse, notez le statut, l’identifiant demandé et la prochaine décision. Une lecture interrompue peut être reprogrammée dans la limite du délai métier. En cas d’écriture interrompue dans un autre flux, vérifiez d’abord l’état de la cible et la clé métier.
| Réponse | Contrôle et décision |
|---|---|
| 200, ID 7841 | Confirmer la lecture. Vérifier les relations avant le transfert. |
| 200, autre ID | Isoler la réponse et vérifier la correspondance avant de transmettre. |
| 401 ou 403 | Contrôler la clé, l’instance et les droits du compte. Attendre la correction. |
| 404 | Confirmer l’instance, la visibilité et la référence avant de clore le dossier. |
| 429, budget à zéro | Différer les appels de cette instance et conserver le point de reprise. |
| 429, budget encore positif | Réduire le débit partagé et espacer les nouvelles lectures. |
| 503 ou délai dépassé | Planifier une nouvelle lecture dans la fenêtre autorisée. Alerter si elle expire. |
Insightly applique des limites à l’instance, dont un débit et un quota dépendant de l’offre. Faites partager la même limite de débit à vos traitements. Sur 429, si l’en-tête est absent ou invalide, différez le dossier et faites vérifier le budget avant de relancer le lot. Limites et en-têtes de quota Insightly.
En réalité, un import qui répond encore en HTTP 200 peut déjà priver les ventes d’appels. Dans un exemple fictif, le quota restant est de 240 appels et les transferts prioritaires en réservent 40. Un lot de 220 lectures unitaires peut dépasser de 20 appels le budget qui lui est disponible. Fractionnez-le avec un plafond de 200 lectures au moment du calcul. Revérifiez le budget en cours de traitement, car les autres consommateurs peuvent l’entamer.
Protéger une mise à jour concurrente
Pour un PUT soumis au contrôle de concurrence documenté, relisez l’objet et reprenez la valeur du champ JSON ETag dans l’en-tête If-Match. Un statut 412 indique que la version utilisée a changé. Relisez alors la fiche et réévaluez les champs concernés avant de décider si l’écriture reste justifiée. Contrôle de concurrence dans Insightly v3.1.
Supposons que le lot ait lu 7841 avant que le commerce corrige son responsable. Après le 412, le traitement peut conserver cette correction et appliquer seulement la référence ERP dont il est responsable, si la nouvelle fiche satisfait encore les préconditions. Si le lot devait aussi écrire le responsable, l’écart doit passer par la règle d’arbitrage convenue avec le commerce.
Gardez l’ETag comme preuve de version. Pour une création, conservez en plus la clé métier et le résultat du rapprochement après une réponse perdue. Ce suivi permet de rechercher l’objet cible avant d’autoriser une seconde tentative.
Par exemple, conservez deux tentatives pour 7841. La première porte la version lue et aboutit au 412. La seconde doit citer la nouvelle version et la décision de conserver le responsable saisi par le commerce. Si la référence ERP est déjà présente après la relecture, clôturez l’opération avec cette preuve.
Plan d’action pour tester le premier flux
- Avec
MockHttpClient, vérifier l’URL résolue, la méthode GET et l’en-tête Basic pour une clé fictive. - Simuler une fiche correcte, une fiche différente, un JSON illisible, un refus d’accès, une limitation et une coupure réseau.
- En recette, confirmer que le compte lit le dossier et les relations nécessaires. Tester avec le quota partagé de l’environnement.
- Si le flux écrit, modifier la fiche entre lecture et mise à jour, puis vérifier la décision prise à la réception du 412.
Donner au support une preuve de reprise
Pour chaque tentative, conservez l’identifiant de corrélation, le pod, le type de ressource, l’identifiant de fiche, le statut et la décision. Sur une 429, ajoutez le budget restant quand il est disponible. Sur 412, le support doit pouvoir retrouver les champs à arbitrer sans avoir accès au secret.
Après une limite de débit, réouvrez progressivement les lectures en fonction de leur échéance métier. Une lecture attendue pour un démarrage de projet passe avant un export qui peut reprendre plus tard. Comptez les appels par instance pour que deux équipes ne relancent pas chacune leur propre lot au même moment.
Mesurez l’âge du plus ancien dossier différé et le nombre de projets en attente d’une lecture CRM. Si 7841 approche de son échéance, le support doit pouvoir confirmer le compte concerné, la raison de l’attente et le prochain contrôle prévu.
Approfondir le parcours CRM et projet
Avant d’implémenter la création, choisissez qui ouvre le projet et comment le retrouver après une réponse perdue. Intégrer Insightly du CRM au projet.
Au transfert, vérifiez que le projet retrouve la bonne organisation et les contacts attendus. Relations entre les objets Insightly.
Conclusion sur la reprise du flux
Le premier contrôle consiste à retrouver l’opportunité attendue avec les droits du compte qui exécutera le flux. Faites ensuite expliquer au support une lecture bloquée à partir de l’identifiant et du dernier statut reçu.
Avant d’ouvrir les écritures, vérifiez la décision après un changement de version et le rapprochement après une réponse perdue. Fixez qui peut autoriser une relance quand la fiche a changé.
Dawap accompagne le développement et la recette d’un connecteur Insightly avec les équipes responsables du CRM et du système cible.