Rappel et bonnes pratiques du Portail Intégrateurs

Cette charte définit les conventions et bonnes pratiques communes à l’ensemble des API Sydev (Tarifeo, Tamzag, Optima, Sesame). Elle sert de référence pour assurer la cohérence, la sécurité et la maintenabilité des intégrations.

1. Objectif

  • Garantir une homogénéité dans les échanges avec les différents produits Sydev.
  • Faciliter l’intégration par les éditeurs et intégrateurs tiers.
  • Prévenir les incohérences entre les environnements (préprod et prod).

2. Principes généraux

  • Les APIs Sydev sont basées sur REST/HTTPS et retournent du JSON.
  • L’authentification repose sur un token temporaire (valide 2 heures) obtenu via une API Login spécifique à chaque produit.
  • Toute nouvelle intégration doit être d’abord validée dans l’environnement préprod avant passage en production.

3. Structure des endpoints

  • Les endpoints sont organisés par domaine fonctionnel : /catalogs, /products, /orders, etc.
  • Le versionnement se fait dans l’URL : /v1/..., /v2/....
  • Les URL utilisent le format kebab-case (ex : /product-families/, /supplier-prices/).
  • Les champs JSON utilisent le format camelCase.

4. Paramètres et filtres

  • Pagination standard : ?page=1&limit=100.
  • Filtrage : ?status=active&createdAt[gte]=2025-01-01.
  • Tri : ?sort=-createdAt (le préfixe - indique un ordre décroissant).
  • Les dates sont au format ISO 8601 UTC : 2025-10-16T08:21:37Z.

5. Identifiants et référentiels

  • Les identifiants (ID) sont uniques à chaque environnement et ne doivent pas être partagés entre préprod et prod

6. Réponses et erreurs

Les APIs renvoient des statuts HTTP standards :

CodeSignification
200Succès
201Ressource créée
400Requête invalide
401Authentification requise
403Accès refusé
404Ressource introuvable
409Conflit de données
422Données invalides
429Trop de requêtes
500Erreur interne serveur

Format d’erreur standard

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Le champ 'email' est requis",
    "requestId": "abc123"
  }
}

7. Sécurité et conformité

  • Accès uniquement via HTTPS (TLS 1.2+).
  • Les tokens ne doivent pas être transmis dans les URLs.
  • Respect du RGPD : aucune donnée personnelle ne doit être stockée hors des serveurs Sydev sans autorisation.
  • Gestion des accès via conventions d’utilisation signées avec chaque partenaire.

8. Bonnes pratiques d’intégration

  • Toujours tester en préprod avant la mise en production.
  • Limiter la fréquence des appels (respect des quotas par clé API).
  • Mettre en cache les données de référence (catalogues, familles, unités) pour éviter les appels inutiles.
  • Utiliser les statuts HTTP pour piloter les traitements.
  • Documenter vos connecteurs internes.

9. Exemple multi-langages

Exemple d’appel pour récupérer la liste des produits (Tamzag) :

cURL

curl -X GET https://api.mytamzag.com/v1/products \
  -H "Authorization: Token abc123xyz456"

JavaScript

fetch('https://api.mytamzag.com/v1/products', {
  headers: { Authorization: 'Token abc123xyz456' }
}).then(res => res.json()).then(console.log)

Python

import requests
r = requests.get('https://api.mytamzag.com/v1/products', headers={'Authorization': 'Token abc123xyz456'})
print(r.json())

Retour en haut