Le connecteur doit relire une opportunité Oracle CX Sales après un délai dépassé. Il reçoit une réponse 200, mais le numéro renvoyé diffère de celui du dossier en attente. Si le traitement accepte cette réponse, il peut ensuite modifier le responsable d’une autre opportunité.
Le risque augmente quand la même application lit les dossiers, les enrichit et rejoue les écritures. Décidez quelle référence chaque appel attend, quels champs il peut modifier et quel résultat le support doit retrouver après une coupure.
Pour une intégration Oracle CX Sales sous Symfony, commencez par vérifier une lecture par OptyNumber. Le lecteur ci-dessous contrôle la référence retournée. Vous pouvez ensuite décider comment traiter les accès refusés, les erreurs de format et une mise à jour concurrente.
Séparer la lecture et la décision de mise à jour
Le client HTTP s’occupe du transport et du contrat de réponse. Le mapping traduit les champs Oracle en valeurs utilisées par l’application. Le traitement métier décide ensuite s’il faut enrichir le dossier, l’envoyer en validation ou le laisser en attente. Un GET réussi donne une observation à ce traitement.
Par exemple, une intégration peut autoriser l’ERP à corriger la raison sociale d’un client et réserver le changement d’étape au CRM. Si le même message contient les deux changements, alors le traitement enregistre l’enrichissement autorisé et indique que la phase reste sous le contrôle du commerce.
Pour qui mettre en place ce lecteur Symfony
Le lecteur sert à une équipe qui ajoute Oracle CX Sales à un service Symfony ou qui fiabilise un traitement de reprise existant. Il donne un premier test en lecture seule avant d’ouvrir les droits d’écriture. Il sert aussi à relire une opportunité connue quand le support doute de l’état observé dans un export.
Choisissez une opportunité que le commercial peut retrouver dans le tenant de recette. Vérifiez son numéro, son identifiant interne et le périmètre du compte technique. Si la recette et la production utilisent des tenants différents, conservez leurs références avec l’origine de chaque appel.
Conserver les références Oracle et ERP
Pour lire une opportunité, Oracle documente /crmRestApi/resources/11.13.18.05/opportunities/{OptyNumber}. Dans la réponse, OptyNumber représente la référence utilisée par ce chemin et OptyId l’identifiant interne. Les comptes et contacts possèdent leurs propres ressources. Leurs numéros ne permettent pas d’appeler ce chemin. Contrat de lecture d’une opportunité.
Dans le registre du connecteur, associez l’origine Oracle, OptyNumber et OptyId à la référence de votre événement. Une commande ERP conserve sa propre référence. Après une fusion de comptes, l’équipe doit pouvoir relire l’association qui existait au moment de la vente avant de réappliquer un ancien message.
Configurer le client et ses droits
Injectez un client Symfony dédié avec l’origine HTTPS du tenant et le mode d’accès autorisé. Si le projet utilise OAuth client credentials, Oracle demande de configurer l’application, sa portée et les rôles autorisés pour la ressource. Validez le parcours d’obtention du token puis vérifiez la lecture métier avec ce même compte. Configuration OAuth Oracle.
Avec un 401, vérifiez le contexte d’authentification et l’expiration du jeton. Avec un 403, comparez les rôles et l’accès à l’opportunité. Après un 404, contrôlez l’origine, le chemin et la visibilité du dossier avant d’envisager une création. Les journaux conservent le statut, le service et la corrélation, en excluant les jetons et les corps de réponse.
Lire une opportunité avec Symfony HttpClient
Cette fonction effectue une lecture sans redirection avec un client dédié, sans politique automatique de retry. Le paramètre fields limite la réponse aux trois champs utiles pour cet exemple. Le filtre de saisie accepte les numéros alphanumériques avec tirets ou tirets bas du flux d’exemple. Adaptez ce filtre aux conventions de numérotation validées pour votre tenant.
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class OracleOpportunityReadFailure extends RuntimeException
{
public function __construct(int $status, public readonly ?string $retryAfter)
{
parent::__construct('Lecture Oracle indisponible ou refusée.', $status);
}
}
function readOracleOpportunity(HttpClientInterface $client, string $number): array
{
if (preg_match('/\A[A-Za-z0-9_-]{1,30}\z/', $number) !== 1) {
throw new InvalidArgumentException('Format du numéro non admis pour ce flux.');
}
$path = '/crmRestApi/resources/11.13.18.05/opportunities/';
$response = $client->request('GET', $path . rawurlencode($number), [
'headers' => ['Accept' => 'application/json'],
'query' => ['fields' => 'OptyId,OptyNumber,Name'],
'max_redirects' => 0,
'timeout' => 5.0,
'max_duration' => 10.0,
]);
$status = $response->getStatusCode();
if ($status !== 200) {
$retryAfter = $response->getHeaders(false)['retry-after'][0] ?? null;
throw new OracleOpportunityReadFailure($status, $retryAfter);
}
$data = $response->toArray(false);
$id = $data['OptyId'] ?? null;
$name = $data['Name'] ?? null;
if (($data['OptyNumber'] ?? null) !== $number
|| !is_int($id) || $id <= 0
|| !is_string($name) || trim($name) === ''
) {
throw new UnexpectedValueException('Réponse Oracle incohérente pour ce numéro.');
}
return ['id' => $id, 'number' => $number, 'name' => $name];
}
L’exemple suppose un PHP 64 bits pour l’identifiant Oracle. Les erreurs de transport et de décodage remontent à l’appelant. Sur une erreur HTTP, la fonction transmet le statut et la valeur brute de Retry-After lorsqu’elle existe. Le worker décide du délai et de la prochaine action, selon le budget du flux. Exceptions Symfony HttpClient.
Choisir entre PATCH, upsert et rapprochement
Oracle documente PATCH sur une opportunité identifiée par son OptyNumber. Pour le POST de création, Oracle documente aussi l’en-tête Upsert-Mode. Avec cette option, le service cherche une correspondance avec le payload et peut créer une ressource s’il n’en trouve pas. Testez les critères effectivement utilisés sur le tenant, y compris avec deux candidats proches. Mettre à jour une opportunité et Créer une opportunité.
Traiter une réponse perdue et une modification concurrente
Paradoxalement, un timeout après un POST peut demander d’arrêter la file d’écriture sur ce dossier. Si Oracle a accepté le premier envoi, alors la priorité est de retrouver son effet. Relisez par une référence que la cible permet d’interroger et comparez le compte, le périmètre et la version de l’événement. Dans ce cas, l’idempotence locale aide à identifier l’opération, avec un contrôle du résultat distant.
Sur une ressource qui prend en charge une écriture conditionnelle, conservez l’ETag obtenu en lecture puis vérifiez le comportement d’If-Match. Si le service répond 412, relisez l’état et réévaluez le changement. Confirmez la disponibilité de ce mécanisme sur la ressource et la version de votre tenant avant de l’utiliser. Mises à jour conditionnelles Oracle.
Tester les réponses et les reprises
| Résultat | Action attendue |
|---|---|
| GET 200 avec le bon numéro | Lire les trois champs et confirmer l’identifiant du dossier. |
| GET 200 avec un autre numéro | Bloquer le traitement et vérifier le chemin et les références. |
| GET 429 ou interruption réseau | Replanifier la lecture si l’erreur est transitoire et borner le délai. |
| Délai dépassé après un POST | Retrouver l’effet de l’opération avant toute nouvelle écriture. |
Avec MockHttpClient, vérifiez le chemin, le filtre de champs et le nombre d’appels. En recette Oracle, comparez ensuite un dossier connu, un refus attendu et une réponse dont le format change. Dans la file, gardez à l’entrée la référence de l’événement, puis en sortie le mapping, la décision et le statut. Le runbook indique qui peut libérer une écriture en attente.
Protéger une correction commerciale tardive
Dans un exemple fictif, l’opportunité CX-804 passe en proposition après validation par sa responsable. Un ancien export arrive ensuite et propose un autre propriétaire. Le connecteur compare l’origine et la version du changement, conserve la décision commerciale et trace l’écart avec le numéro de l’opportunité.
Le même principe vaut lorsqu’un ERP confirme la raison sociale pendant que le CRM modifie l’étape. Chaque source agit sur les champs convenus. Pour une comparaison sur un autre ERP, le parcours Sage et CRM sous Symfony traite aussi la répartition des écritures et la reprise.
Erreurs fréquentes lors des reprises
- Réutiliser un identifiant interne comme numéro d’opportunité. Vérifier le champ qui sert au chemin REST.
- Transformer un 404 en création immédiate. Revoir le tenant, le service et la visibilité du dossier.
- Confondre deux tentatives et deux opérations. Garder la même référence métier pour la même opération.
- Relancer le lot entier pour un seul conflit. Isoler l’événement concerné et vérifier ses dépendances avant la reprise.
Plan d’action avant la première écriture
- Commencer par lire une opportunité connue avec le client de recette.
- Documenter les champs écrits, leur source et les versions reconnues.
- Tester le refus d’accès, la réponse incohérente et la perte de réponse.
- Rejouer le dossier en attente et retrouver le même résultat avec le support.
Valider le premier flux avec le support
Choisissez un seuil d’alerte lié au délai dont dispose l’équipe. Par exemple, si une vente doit partir en gestion avant la clôture de journée, l’âge du plus ancien dossier incertain doit déclencher une vérification à temps. Présentez les blocages par cause, avec une action adaptée à la sécurité, au mapping ou au dossier commercial.
Avant d’élargir la synchronisation, vérifiez qu’un lot interrompu reprend à partir du dernier résultat confirmé et que les dossiers en attente restent visibles. Comparez la source, la cible et la trace de l’opération. L’équipe doit pouvoir retrouver la décision même quand le premier worker a disparu.
Relier le SDK au parcours Oracle CX Sales
Le pilier Oracle CX Sales et ERP présente les références commerciales à conserver depuis le compte jusqu’à la commande.
Le guide du transfert d’opportunité en commande détaille les validations et la preuve attendue côté ERP.
Conclusion sur la recette du connecteur
Partez d’un numéro d’opportunité connu, avec la projection des champs et les droits de lecture requis. Vérifiez la référence retournée avant de confier le dossier au traitement métier.
Avant une écriture, rejouez une réponse perdue et une correction concurrente. Le support doit savoir où relire la donnée et dans quel cas reprendre.
L’accompagnement Oracle CX Sales permet de cadrer cette recette avec les équipes CRM et ERP, puis de tester le flux Symfony sur le premier parcours choisi.