Construire des intégrations

Certaines des apps les plus précieuses connectent une app SOIS existante à un service extérieur. Un exemple courant : synchroniser des factures depuis l'app de comptabilité SOIS vers QuickBooks. Ce guide explique comment une app d'intégration lit les données SOIS en toute sécurité et se connecte à un service externe.

Les apps d'intégration sont une catégorie de premier plan. Elles lisent les données d'une autre app via un contrat gouverné, jamais directement sa base de données, et seulement avec le consentement du tenant.

Deux faces d'une intégration

Une app d'intégration parle à deux choses :

  1. Une app SOIS (par exemple comptabilité, entrepôt ou contacts). Vous lisez ou écrivez ses données via son contrat publié.
  2. Un service externe (par exemple QuickBooks). Vous l'appelez avec les propres identifiants du tenant.

Déclarez avec quoi vous vous intégrez

Votre projet déclare les apps SOIS dont il dépend. Cette déclaration fait deux choses : elle indique à SOIS quels contrats votre app peut utiliser, et elle permet au tenant de voir et d'approuver l'accès quand il installe votre app.

Lire les données SOIS via le contrat

Votre app ne touche pas les tables d'une autre app. Elle lit via le contrat de cette app, un ensemble stable d'opérations et de formes de données. Votre agent construit votre mappage par rapport à ces formes. Pendant le développement, vous travaillez avec des données d'exemple représentatives, vous pouvez donc construire et prévisualiser tout le flux sans connexion en direct.

À l'exécution, l'accès est gouverné :

  • Le tenant approuve l'accès inter-apps quand il installe votre app. Cela fait partie des scopes demandés par votre app.
  • Le contrat applique ce que votre app peut lire ou écrire. L'isolation du tenant n'est jamais affaiblie.

Connecter le service externe

Les identifiants externes appartiennent au tenant, pas à vous. Votre app déclare les identifiants dont elle a besoin (par exemple une connexion OAuth), et chaque tenant qui installe fournit les siens. Vous ne détenez jamais les identifiants d'un autre tenant.

Exemple : synchroniser des factures vers QuickBooks

  1. Déclarez que votre app s'intègre avec l'app de comptabilité.
  2. Demandez à votre agent de lire la forme de la facture de comptabilité et de construire un mappage d'une facture SOIS vers une facture QuickBooks. Construisez et prévisualisez par rapport à des factures d'exemple.
  3. Déclarez les identifiants OAuth QuickBooks dont votre app a besoin.
  4. Quand un tenant installe votre app, il approuve l'accès à la comptabilité et connecte son propre compte QuickBooks.
  5. À l'exécution, votre app lit les factures via le contrat de comptabilité et les pousse vers QuickBooks avec les identifiants du tenant, généralement selon un planning ou un déclencheur.

Bonnes pratiques

  • Mappez les champs explicitement et gérez les cas où un service externe attend des données que votre source n'a pas.
  • Échouez en douceur. Si le service externe est indisponible, réessayez plutôt que de perdre des données.
  • Demandez uniquement les scopes dont vous avez besoin. Les tenants approuvent un accès restreint plus vite et lui font davantage confiance.

Étapes suivantes