Dawap développe son connecteur SDK pour l'API CRM Odoo sous Symfony

1. Pourquoi nous avons construit un SDK Odoo CRM interne
2. Ce qu attend un CTO d un connecteur CRM orienté production
3. Pourquoi Symfony est un socle solide pour Odoo CRM
4. Modèle Odoo CRM: crm.lead, res.partner, stages, activities
5. API Odoo: XML-RPC et JSON-RPC en pratique
6. Authentification et gouvernance des accès
7. Endpoints métier: exemples concrets de payloads
8. Contractuel vs illustratif: règle de documentation Dawap
9. Idempotence, replay et cohérence des transitions pipeline
10. Gestion des erreurs API et stratégie de retries
11. Tests d intégration: couverture et non-régression
12. Observabilité run, KPI et runbooks
13. Plan de mise en oeuvre en 6 semaines
14. Mini cas réel et conclusion stratégique

1. Pourquoi nous avons construit un SDK Odoo CRM interne

Odoo CRM est rarement isolé: il dialogue avec ventes, facturation, comptabilité, logistique et parfois outils tiers. Sans cadre d'intégration, les flux dérivent vite: leads dupliqués, partenaires incomplets, et statuts d'opportunité qui ne reflètent plus la réalité commerciale.

Le SDK Odoo CRM sous Symfony sert à stabiliser ce paysage: conventions de mapping, orchestration fiable, idempotence et observabilité. On transforme des scripts opportunistes en couche d'intégration durable.

2. Ce qu attend un CTO d un connecteur CRM orienté production

Un CTO attend d'un connecteur CRM qu'il soit prévisible: incidents rares, diagnostics rapides, reprises propres et gouvernance claire des évolutions.

L'objectif n'est pas de "faire passer un call", mais d'assurer un système fiable à long terme, même lorsque les flux et les règles métier évoluent.

3. Pourquoi Symfony est un socle solide pour Odoo CRM

Symfony fournit le cadre de référence: injection de dépendances, config par environnement, workers asynchrones, gestion de secrets, policies de retries/timeouts, monitoring instrumenté.

final class OdooCrmSdkKernel
{
    public function __construct(
        private OdooAuthProvider $auth,
        private OdooRpcClient $rpc,
        private OdooErrorMapper $errors,
        private OdooTelemetry $telemetry
    ) {}
}

4. Modèle Odoo CRM: crm.lead, res.partner, stages, activities

Les entités pivots sont `crm.lead` (lead/opportunity), `res.partner` (contacts/sociétés), les stages de pipeline et les activités associées.

La qualité d'intégration dépend de la cohérence entre ces entités: rattachement partner fiable, stage correct, et journal d'activités complet pour le suivi commercial.

5. API Odoo: XML-RPC et JSON-RPC en pratique

Selon version et contexte d'hébergement, Odoo expose XML-RPC et/ou JSON-RPC. Les deux reposent sur `execute_kw` mais diffèrent par le transport et les conventions d'appel.

Le SDK masque cette variabilité: les services métier appellent une API interne stable, quelle que soit la couche RPC effectivement utilisée.

6. Authentification et gouvernance des accès

L'auth Odoo s'appuie sur base, utilisateur, mot de passe (ou token), et contexte d'exécution. En production, nous imposons comptes techniques minimaux, séparation d'environnements, et rotation contrôlée des accès.

POST /jsonrpc HTTP/1.1
Host: [ODOO_HOST]
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "common",
    "method": "authenticate",
    "args": ["[DB]", "[LOGIN]", "[PASSWORD]", {}]
  },
  "id": 1
}

7. Endpoints métier: exemples concrets de payloads

Exemples illustratifs réalistes en JSON-RPC, à adapter à votre modèle Odoo.

7.1 Création d'un lead (`crm.lead`)

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute_kw",
    "args": [
      "[DB]",
      12,
      "[PASSWORD]",
      "crm.lead",
      "create",
      [
        {
          "name": "MKT-2026-0189",
          "type": "lead",
          "email_from": "lea.martin@acme.fr",
          "phone": "+33153402010"
        }
      ]
    ]
  },
  "id": 2
}

7.2 Upsert partner (`res.partner`)

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute_kw",
    "args": [
      "[DB]",
      12,
      "[PASSWORD]",
      "res.partner",
      "create",
      [
        {
          "name": "ACME Distribution",
          "email": "lea.martin@acme.fr",
          "phone": "+33153402010"
        }
      ]
    ]
  },
  "id": 3
}

7.3 Changement de stage opportunité

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute_kw",
    "args": [
      "[DB]",
      12,
      "[PASSWORD]",
      "crm.lead",
      "write",
      [[1457], {"stage_id": 23}]
    ]
  },
  "id": 4
}

8. Contractuel vs illustratif: règle de documentation Dawap

Nous distinguons systématiquement obligations techniques et exemples.

Contractuel:
- endpoint RPC, auth, méthode execute_kw
- modèles ciblés et champs requis

Illustratif:
- valeurs d'exemple
- mappings custom de démonstration
- scénarios simplifiés

9. Idempotence, replay et cohérence des transitions pipeline

Les événements peuvent être rejoués; sans idempotence, les transitions de stage dérivent. Le SDK impose des clés de déduplication et des règles de progression métier explicites.

Clé idempotente type:
crm:odoo:[model]:[external_id]:[source_timestamp]

10. Gestion des erreurs API et stratégie de retries

Les erreurs sont classées (`technical`, `contract`, `business`, `security`) et traitées selon une matrice claire.

- technical: retry borné + backoff
- contract: correction payload
- business: validation fonctionnelle
- security: rotation accès / escalade

11. Tests d intégration: couverture et non-régression

La couverture inclut création lead/partner, transition stage, erreurs de validation, timeout RPC, rejeu idempotent, et réconciliation des données CRM/SI.

Matrice minimale:
1) create lead + partner
2) transition stage nominale
3) erreur de stage/validation
4) timeout + retry borné
5) rejeu idempotent
6) resync lot et contrôle d'écarts

Références: Tests API et Postman.

12. Observabilité run, KPI et runbooks

Les KPI pilotent latence RPC, erreurs, reprises et écarts de réconciliation.

Métriques recommandées:
- odoo_rpc_call_duration_ms{model,method}
- odoo_error_total{class}
- odoo_retry_total{reason}
- replay_queue_size{flow}
- reconciliation_gap_total{model}

Les runbooks décrivent procédures de reprise, seuils d'alerte et escalade. Voir: Observabilité API et runbooks.

13. Plan de mise en oeuvre en 6 semaines

Semaine 1: cadrage flux, mapping champs, règles de pipeline.

Semaine 2: socle SDK + auth + gestion d'erreurs + tests initiaux.

Semaine 3: implémentation lead/partner + idempotence.

Semaine 4: transitions pipeline + activités + runbooks.

Semaine 5: non-régression, volumétrie, hardening.

Semaine 6: recette, déploiement progressif, monitoring renforcé.

14. Mini cas réel et conclusion stratégique

Cas type: lead entrant web enrichi ERP, création partner, qualification lead et passage en opportunité. Le SDK garantit ordre métier, traçabilité et reprise idempotente.

Un SDK Odoo CRM devient stratégique lorsqu'il combine fiabilité opérationnelle et vitesse de delivery, sans régression à chaque évolution métier.

Pour aller plus loin: Présentation des SDK API CRM développés par Dawap, Intégration API CRM Odoo CRM et Intégration API.