Intégration API — guide technique¶

À qui s'adresse ce guide

À la personne qui réalise le raccordement informatique (service informatique du partenaire, éditeur, prestataire). Pour créer la clé depuis le portail, voir la procédure Générer un accès API.

1. Obtenir vos identifiants¶

Connectez-vous au portail (https://portail.lexi.pf) avec votre compte utilisateur.
Ouvrez l'onglet Accès API (visible dans votre espace, client ou fournisseur).
Cliquez sur Nouvelle clé, nommez-la selon son usage (« Réassort », « Comptabilité »…) et validez.
Copiez immédiatement le Client ID et le Secret : le secret n'est affiché qu'une seule fois et n'est stocké nulle part côté Lexi. En cas de perte, utilisez Régénérer le secret sur la ligne concernée (l'ancien est aussitôt invalidé).

Jusqu'à 2 clés par fiche : de quoi préparer une nouvelle clé avant de retirer l'ancienne (rotation sans coupure), ou faire tourner deux intégrations distinctes. Chacune se régénère et se révoque indépendamment.

Les identifiants sont propres à votre fiche partenaire : ils ne donnent accès qu'à vos propres données, en lecture seule. Les endpoints fournisseur (ventes-fournisseur, stocks-fournisseur) exigent une fiche fournisseur ; les endpoints client (factures, dossiers, activites, connaissements) sont ouverts à toute fiche.

2. Obtenir un jeton d'accès¶

Standard OAuth2 client_credentials :

curl -X POST 'https://login.lexi.ovh/realms/lexi/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<votre-client-id>' \
  -d 'client_secret=<votre-secret>'

Réponse :

{ "access_token": "eyJhbGciOi...", "expires_in": 300, "token_type": "Bearer" }

Le jeton est valable quelques minutes (expires_in, en secondes) : mettez-le en cache et renouvelez-le avant expiration — ne demandez pas un jeton par requête.

3. Appeler l'API¶

Base : https://portail.lexi.pf/api/portail/v1. Deux en-têtes obligatoires :

En-tête	Valeur
`Authorization`	`Bearer <access_token>`
`X-Tenant-Id`	L'identifiant du tenant, affiché dans l'onglet Accès API

L'identifiant de votre fiche partenaire ({partenaireId}) figure dans le Client ID (dernier segment) et dans les exemples de l'onglet Accès API.

Ventes agrégées — `GET /partenaires/{partenaireId}/ventes-fournisseur`¶

Quantités vendues/reprises par jour et par article, sur une plage de dates obligatoire.

Paramètre	Type	Description
`du`	date ISO 8601	Début de période (inclus) — obligatoire
`au`	date ISO 8601	Fin de période (incluse) — obligatoire, plage ≤ 366 jours

curl 'https://portail.lexi.pf/api/portail/v1/partenaires/889/ventes-fournisseur?du=2026-07-01T00:00:00Z&au=2026-07-31T23:59:59Z' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-Tenant-Id: <tenant-id>'

Réponse (extrait) :

{
  "du": "2026-07-01T00:00:00+00:00",
  "au": "2026-07-31T23:59:59+00:00",
  "lignes": [
    {
      "jour": "2026-07-15",
      "codeArticle": "6245920",
      "referenceFournisseur": "VOTRE-REF-123",
      "libelle": "T-shirt sport…",
      "quantiteFacturee": 4,
      "quantiteAvoiree": 0,
      "quantiteNette": 4
    }
  ],
  "totauxArticles": [ { "codeArticle": "6245920", "quantiteNette": 12, "...": "…" } ],
  "totalQuantiteNette": 145
}

quantiteFacturee = vendue, quantiteAvoiree = reprise (retours).
referenceFournisseur = votre référence interne, gérable depuis le portail (fiche article ou import de fichier) — utilisez-la pour croiser avec votre SI.

Stock — `GET /partenaires/{partenaireId}/stocks-fournisseur`¶

Quantités en stock par article, paginé.

Paramètre	Type	Description
`recherche`	texte	Optionnel (code, libellé, votre référence)
`pageNumber`	entier	Défaut 1
`pageSize`	entier	Défaut 50, max 500

Réponse : { items: [ { codeArticle, referenceFournisseur, libelle, quantiteEnStock } ], totalCount, pageNumber, pageSize }.

4. Bonnes pratiques et limites¶

Cadence : les données de ventes évoluent au fil de la journée — interroger une fois par heure suffit largement pour un réassort. Une limite de débit s'applique (HTTP 429 au-delà) : espacez vos appels et gérez le retry avec backoff.
Jeton en cache : un jeton par période de validité, pas par requête.
Codes d'erreur : 401 jeton absent/expiré, 403 partenaire hors de votre périmètre ou tenant incorrect, 429 débit dépassé, 400 paramètres invalides (message en français dans le corps).
Sécurité : le secret est l'équivalent d'un mot de passe machine — stockez-le dans un coffre, jamais dans un code source. Régénérez-le en cas de doute, révoquez l'accès si l'intégration est décommissionnée.