---
author: OOMOL
author_url: https://oomol.com/fr/about/
title: Appeler les API des fournisseurs avec SaaS Proxy
description: Appelez les API des fournisseurs avec une Project API key et le
  compte connecté de votre utilisateur via SaaS Proxy.
lang: fr
canonical_url: https://oomol.com/fr/docs/saas-proxy/
markdown_url: https://oomol.com/fr/docs/saas-proxy.md
---

# Appeler les API des fournisseurs avec SaaS Proxy

Utilisez SaaS Proxy pour un endpoint qui ne dispose pas encore d’une action Connector. Votre backend fournit le chemin, la méthode et les paramètres ; Connector sélectionne le compte connecté de l’utilisateur et ajoute ses identifiants. Le fournisseur doit prendre en charge le proxy et les permissions du compte restent applicables.

## Préparer le compte

Suivez d’abord le [guide Connector for SaaS](/fr/docs/connector-saas/). Gardez la Project API key sur votre backend et enregistrez l’association vérifiée entre utilisateur et compte. Utilisez une clé de projet oo_proj_…, pas une clé personnelle ou un token fournisseur. Déduisez userId et le compte de la session authentifiée ; ne faites pas confiance à un identifiant de compte arbitraire envoyé par le navigateur.

## Appeler avec HTTP

```http
POST https://connector.oomol.com/v1/saas/proxy/{service}
Authorization: Bearer <project-api-key>
Content-Type: application/json
```

Cet exemple Gmail en lecture seule récupère le profil du compte connecté. Remplacez les identifiants de configuration et de compte par ceux enregistrés sur votre backend. Le compte doit disposer des permissions de lecture du profil. La méthode HTTP externe est toujours POST ; la méthode du fournisseur se trouve dans request.

```bash
export PROJECT_API_KEY='oo_proj_...'
export PROVIDER_CONFIG_ID='<gmail-provider-config-id>'
export CONNECTED_ACCOUNT_ID='<connected-account-id>'

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/proxy/gmail' \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: req-saas-proxy-1' \
  --data @- <<JSON
{
  "providerConfigId": "$PROVIDER_CONFIG_ID",
  "userId": "customer-1",
  "connectedAccountId": "$CONNECTED_ACCOUNT_ID",
  "request": {
    "endpoint": "/users/me/profile",
    "method": "GET"
  }
}
JSON
```

## Champs de la requête

| Champ | Utilisation |
| --- | --- |
| `userId` | Obligatoire : identifiant de l’utilisateur de votre produit, associé au compte connecté. |
| `providerConfigId` | Facultatif, mais recommandé : ID de configuration dont le service correspond à l’URL. Sans cet ID, le projet doit avoir une seule configuration active pour ce service. |
| `connectedAccountId` / `alias` | Facultatifs : indiquez au maximum un sélecteur. Sans sélecteur, le compte active le plus récent de cet utilisateur et de cette configuration est choisi. |
| `request.endpoint` | Obligatoire : chemin commençant par /, ajouté à la Base URL du fournisseur, ou URL HTTPS absolue d’une origine autorisée. Base URL de Gmail : https://gmail.googleapis.com/gmail/v1. |
| `request.method` | Obligatoire : GET, POST, PUT, PATCH ou DELETE. |
| `request.query` | Facultatif : objet avec des valeurs chaîne, nombre, booléen ou null. Les valeurs null sont ignorées ; les tableaux et objets imbriqués sont refusés. |
| `request.headers` | Facultatif : en-têtes hors authentification. Connector ajoute les identifiants ; ne fournissez pas Authorization, Cookie, Host ou X-API-Key. |
| `request.body` | Facultatif : JSON ou texte pour une écriture chez le fournisseur. GET n’envoie pas de corps. |

## Appeler avec ProjectConnector

Utilisez une version de @oomol-lab/connector incluant ProjectConnector.proxy. Si votre version ne propose pas cette méthode, utilisez l’exemple HTTP. Le SDK convertit externalUserId et connectionName en userId et alias. connectedAccountId est prioritaire sur connectionName. Le type générique décrit la réponse attendue sans valider les données à l’exécution.

```sh
npm install @oomol-lab/connector
```

```ts
import { ProjectConnector } from "@oomol-lab/connector";

const project = new ProjectConnector({
  apiKey: process.env.PROJECT_API_KEY!,
});

const result = await project.proxy<{ emailAddress: string }>(
  "customer-1",
  "gmail",
  { endpoint: "/users/me/profile", method: "GET" },
  {
    providerConfigId: process.env.PROVIDER_CONFIG_ID!,
    connectedAccountId: process.env.CONNECTED_ACCOUNT_ID!,
    retries: 0,
  },
);

if (result.status < 200 || result.status >= 300) {
  throw new Error(`Provider returned HTTP ${result.status}`);
}
console.log(result.data.emailAddress);
```

Pour plusieurs appels du même utilisateur, liez-le une seule fois :

```ts
const user = project.forUser("customer-1");
const profile = await user.proxy<{ emailAddress: string }>(
  "gmail",
  { endpoint: "/users/me/profile", method: "GET" },
  {
    providerConfigId: process.env.PROVIDER_CONFIG_ID!,
    connectionName: "work",
    retries: 0,
  },
);
if (profile.status < 200 || profile.status >= 300) {
  throw new Error(`Provider returned HTTP ${profile.status}`);
}
console.log(profile.data.emailAddress);
```

## Lire les réponses et gérer les erreurs

L’enveloppe HTTP ci-dessous est un exemple. Le SDK renvoie directement son objet data : status, headers et data. Les clients HTTP peuvent conserver meta.executionId pour le diagnostic.

```json
{
  "success": true,
  "message": "OK",
  "data": {
    "status": 200,
    "headers": { "content-type": "application/json" },
    "data": {
      "emailAddress": "user@example.com",
      "messagesTotal": 120,
      "threadsTotal": 80,
      "historyId": "12345"
    }
  },
  "meta": {
    "executionId": "exec-example",
    "service": "gmail",
    "appId": "app-example"
  }
}
```

Vérifiez les deux niveaux. Une enveloppe Connector réussie peut contenir un statut fournisseur non 2xx dans data.status ; avec le SDK, vérifiez result.status et le corps du fournisseur. Les échecs Connector lèvent ConnectorError. Une Project API key invalide peut produire HTTP 401 avec le texte brut Unauthorized : ne supposez pas que toutes les erreurs sont en JSON.

## Limites et dépannage

- Le proxy renvoie du JSON analysé ou du texte, pas un flux ni un transfert binaire. Le délai amont par défaut est de 30 secondes et la réponse est limitée à 4 MiB ; chaque fournisseur peut modifier ces limites.

- Le proxy n’ajoute aucune permission OAuth. Si les scopes manquent, vérifiez la configuration et demandez une nouvelle autorisation à l’utilisateur. Seules les origines autorisées par le fournisseur sont acceptées.

- provider_config_not_found et multiple_provider_configs_found concernent le choix de configuration ; proxy_not_supported indique l’absence de prise en charge. Pour proxy_upstream_timeout ou proxy_response_too_large, réduisez si possible la portée de la requête ou de la réponse.

- Un délai dépassé ne prouve pas l’échec d’une écriture. Désactivez les tentatives automatiques si elles risquent de créer des doublons ; les exemples SDK fixent retries à zéro. Conservez l’ID de requête et HTTP meta.executionId lorsqu’il est présent, puis consultez les journaux d’exécution du projet dans OOMOL Console.

Consultez aussi [la connexion de comptes avec ProjectConnector](/fr/docs/project-connector/).