Tester l'API de bout en bout

Les adresses

Une seule adresse pour tout : https://preprod-api.satelica.com. On s'y connecte (/auth/v1/…) et on y appelle l'API (/api/v1/…). La production (api.satelica.com) porte des données réelles et vos comptes d'essai n'y existent pas : tout appel y est refusé (401).

Le contrat se télécharge et s'importe tel quel dans Postman, Insomnia ou un générateur de client. Il décrit les 193 opérations de l'API, les 5 opérations de connexion et les 29 événements envoyés par webhook. Pour chacune, il donne les champs attendus et un exemple de réponse réelle relevé en préproduction.

Les comptes d'essai

Trois comptes, un par profil. Chacun voit et fait exactement ce que son rôle permet en production.

La liste complète des rôles et de leurs permissions se lit avec GET /roles (compte CYBASTION). Chaque opération de la référence indique la permission qu'elle exige et ce que l'appelant peut voir.

Se connecter

Une connexion par e-mail et mot de passe donne un jeton d'accès. Ce jeton accompagne ensuite chaque appel.

1. Obtenir un jeton

curl -X POST 'https://preprod-api.satelica.com/auth/v1/token?grant_type=password' \
  -H 'apikey: <clé publique>' \
  -H 'Content-Type: application/json' \
  -d '{"email": "odoo.partenaire@preprod.satelica.test", "password": "<mot de passe>"}'

La réponse contient access_token (valable 3 600 secondes, soit une heure), expires_at et refresh_token.

2. Appeler l'API

curl 'https://preprod-api.satelica.com/api/v1/moi' \
  -H 'Authorization: Bearer <access_token>'

GET /moi rend le compte, son organisation, son rôle et la liste de ses permissions : c'est le premier appel à faire pour vérifier la connexion.

3. Renouveler sans redemander le mot de passe

curl -X POST 'https://preprod-api.satelica.com/auth/v1/token?grant_type=refresh_token' \
  -H 'apikey: <clé publique>' -H 'Content-Type: application/json' \
  -d '{"refresh_token": "<refresh_token>"}'

Chaque renouvellement rend un nouveau refresh_token : conservez le dernier reçu. Renouvelez un peu avant expires_at. Si l'API répond 401 jeton_invalide, renouvelez puis rejouez l'appel.

4. Se déconnecter

curl -X POST 'https://preprod-api.satelica.com/auth/v1/logout?scope=local' \
  -H 'apikey: <clé publique>' -H 'Authorization: Bearer <access_token>'

Réponse 204. Le jeton de renouvellement est révoqué. Le jeton d'accès déjà émis expire de lui-même dans l'heure (voir Comportements voulus).

Exemple en Python (Odoo)

import requests

AUTH = "https://preprod-api.satelica.com/auth/v1"
API = "https://preprod-api.satelica.com/api/v1"
CLE_PUBLIQUE = "<clé publique>"


def connecter(email, mot_de_passe):
    reponse = requests.post(f"{AUTH}/token", params={"grant_type": "password"},
                            headers={"apikey": CLE_PUBLIQUE},
                            json={"email": email, "password": mot_de_passe}, timeout=30)
    reponse.raise_for_status()
    return reponse.json()          # access_token, refresh_token, expires_at


def renouveler(refresh_token):
    reponse = requests.post(f"{AUTH}/token", params={"grant_type": "refresh_token"},
                            headers={"apikey": CLE_PUBLIQUE},
                            json={"refresh_token": refresh_token}, timeout=30)
    reponse.raise_for_status()
    return reponse.json()


session = connecter("odoo.partenaire@preprod.satelica.test", "<mot de passe>")
entetes = {"Authorization": f"Bearer {session['access_token']}"}

moi = requests.get(f"{API}/moi", headers=entetes, timeout=30).json()
clients = requests.get(f"{API}/clients", headers=entetes,
                       params={"page": 1, "taille": 50}, timeout=30).json()
print(moi["role"]["code"], clients["pagination"]["total"])

Essayer depuis la référence

La référence interactive envoie de vraies requêtes à la préproduction.

1. Ouvrez la référence de préproduction et remplissez l'encadré Obtenir un jeton d'accès, en haut de page. Sans jeton, chaque essai répond 401.
2. Saisissez l'e-mail et le mot de passe d'un compte d'essai. Le jeton obtenu reste dans l'onglet, s'efface à sa fermeture, et le mot de passe n'est jamais conservé.
3. Choisissez une opération puis Tester : le jeton est déjà placé dans Authorization. Pour une lecture, l'identifiant de l'adresse ({id}) est prérempli avec un objet réel de la préproduction : cliquez sur Send. Pour une écriture, il n'est pas prérempli, pour qu'un clic d'exploration n'annule ni ne supprime rien : l'identifiant à coller est donné dans la description du paramètre. Les champs du corps sont préremplis avec un exemple réel, à adapter.
4. Pour changer de profil, utilisez Oublier le jeton, puis connectez-vous avec un autre compte.

Les cinq opérations du groupe Authentification visent le service d'authentification, et non l'API. Leur clé publique apikey est déjà renseignée.

Conventions

Les mêmes règles valent pour toutes les opérations.

Erreurs

Toujours { "code", "message", "details"? } : un code stable, un message en français, et parfois des précisions par champ.

{
  "code": "requete_invalide",
  "message": "La demande de règlement est invalide.",
  "details": [
    { "code": "invalid_format", "format": "uuid", "path": ["commande_id"], "message": "Invalid UUID" },
    { "code": "custom", "path": [], "message": "Précisez la commande ou la facture à régler." }
  ]
}

Le service d'authentification a son propre format : { "code": 400, "error_code": "invalid_credentials", "msg": "…" }.

Parcours de A à Z : un nouveau client

L'enchaînement que nos recettes automatiques rejouent à chaque livraison. Chaque appel est décrit en détail dans la référence.

CYBASTION odoo.cybastion · Partenaire odoo.partenaire · Client odoo.client

1. Se connecter avec les trois comptes
   • POST/auth/v1/token?grant_type=passwordchacun
   • GET/moichacun
2. Le partenaire enregistre un client, avec ses pièces
   • GET/types-documents — les pièces marquées exigee_creation pour cible: clientPartenaire
   • POST/fichiers — une fois par pièce, bucket=kycPartenaire
   • POST/clients/controle-doublon puis POST /clients — entreprise, contact, premier site, piècesPartenaire
3. CYBASTION arbitre la réservation et examine les pièces
   • POST/reservations/{id}/decision — {"decision": "validee"} : le client entre au portefeuilleCYBASTION
   • GET/documents-kyc?statut=depose puis POST /documents-kyc/{id}/decisionCYBASTION
   • POST/clients/{id}/acces — ouvre le compte du contact principal et lui envoie sa bienvenuePartenaire
4. Le partenaire chiffre et envoie un devis

   Pour que le compte client d'essai puisse répondre, menez la vente sur l'Entreprise de démonstration Odoo.

   • POST/opportunites — type_transaction: "nouveau_besoin"Partenaire
   • GET/offres et GET /tarifs — une offre active et tariféePartenaire
   • POST/devis/simulation puis POST /devis — mêmes montants, devis brouillon numéroté DEVPartenaire
   • POST/devis/{id}/envoi — le PDF est produit, le devis passe envoyePartenaire
5. Le client accepte et signe
   • POST/devis/{id}/reponse — {"decision": "accepte"}Client
   • POST/signatures — {"objet": "devis", "objet_id": …} : un code à six chiffres part par e-mailClient
   • POST/signatures/{signature_id}/confirmer — le code et le tracé (image PNG ou JPEG en data URI)Client

   Autre voie : le partenaire dépose le devis signé sur papier (POST /fichiers avec bucket=devis, puis POST /devis/{id}/signature). Dans les deux cas naissent la commande (CMD), le contrat en projet (CTR), l'échéancier et la commission latente du partenaire.

6. Le règlement
   • POST/paiements/en-ligne — rend l'adresse de paiement Paystack (voir Paiements de test)Client
   • POST/paiements/{id}/verification — après le paiement : la plateforme interroge Paystack et constate le règlementClient

   Ou hors ligne : POST /paiements (virement, avec cle_idempotence) par le partenaire, puis POST /paiements/{id}/decision {"decision": "valide"} par CYBASTION. Soldée, la commande passe payee, sa commission devient realisee et l'ordre d'installation s'ouvre de lui-même.

7. La facture
   • POST/commandes/{id}/factures — corps facultatif, numéro FACCYBASTION
   • PATCH/factures/{id}/reference-fne — la référence de la facture normaliséeCYBASTION
8. L'installation et la mise en service
   • GET/ordres-installation?commande_id=…CYBASTION
   • POST/ordres-installation/{id}/technicien puis …/technicien/contact — un technicien du registre (GET /techniciens)CYBASTION
   • POST/ordres-installation/{id}/transmission — l'ordre part chez VIP NetCYBASTION
   • POST/fichiers (bucket=proces-verbaux), POST /proces-verbaux, POST /proces-verbaux/{id}/decisionCYBASTION
   • GET/activations puis POST /activations/{id}/decision — activee avec identifiant_connexionCYBASTION
9. La commission du partenaire
   • GET/commissions et GET /commissions/totauxPartenaire
   • POST/fichiers (bucket=versements, sa facture) puis POST /demandes-versementPartenaire
   • POST/demandes-versement/{id}/decision puis …/versement — commissions payeeCYBASTION

Et toutes les autres opérations

Corrections et suppressions, transferts de client entre partenaires, avoirs et remboursements, relances, support, notifications, catalogue, paramètres, tableaux de bord et journal d'audit : toutes s'essaient de la même façon. Avant la publication de ce guide, chacune a été appelée avec succès en préproduction, à deux exceptions près : la notification Paystack et son rejeu, réservés à Paystack. La référence décrit, opération par opération, les cas où elle refuse.

Webhooks : être prévenu de chaque événement

SATELICA prévient Odoo de lui-même, dans les secondes qui suivent chaque événement métier. Plus besoin d'interroger l'API en boucle.

1. Déclarer une adresse de réception
   • POST/webhooks — {"url": "https://…", "evenements": ["*"]} : le secret de signature est rendu une seule foisCYBASTION
   • GET/webhooks/evenements — les 29 événements, pour n'en choisir que certainsCYBASTION
2. Vérifier la réception
   • POST/webhooks/{id}/test — un événement webhook.test part aussitôt ; la réponse dit ce que votre adresse a réponduCYBASTION
3. Dérouler le parcours de A à Z

   Chaque étape produit son événement : client.cree, devis.signe, paiement.valide, facture.emise, ordre_installation.cree, pv.valide, activation.realisee, commission.realisee, versement.paye…

4. Suivre et rejouer
   • GET/webhooks/{id}/livraisons — statut, tentatives, code HTTP reçu, prochaine relanceCYBASTION
   • POST/webhook-livraisons/{id}/rejeu — renvoyer un envoi, par exemple après une panne de votre côtéCYBASTION

Le message reçu

import hashlib, hmac, time


def signature_valide(secret: str, entete: str, corps_brut: bytes, tolerance: int = 300) -> bool:
    elements = [partie.split("=", 1) for partie in entete.split(",") if "=" in partie]
    horodatage = int(next(valeur for cle, valeur in elements if cle == "t"))
    if abs(time.time() - horodatage) > tolerance:
        return False
    attendu = hmac.new(secret.encode(), f"{horodatage}.".encode() + corps_brut, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(attendu, valeur) for cle, valeur in elements if cle == "v1")

Paiements de test

La préproduction est reliée à Paystack en mode test : aucun argent ne circule.

POST /paiements/en-ligne rend adresse_paiement, une page de paiement Paystack de test. Les références de la préproduction commencent par PPAY-. Moyens de test publiés par Paystack (documentation Paystack) :

Après le paiement, Paystack renvoie vers une page de retour, qui ne fait qu'informer le payeur. C'est la vérification qui constate le règlement : le client ou CYBASTION appelle POST /paiements/{id}/verification, et la plateforme interroge Paystack. Tant que le paiement n'est pas fait, la réponse le dit (initie) sans rien modifier.

Courriels de test

La préproduction n'envoie aucun courriel à l'extérieur. Bienvenue, lien de mot de passe, code de signature et avis : tout est retenu dans une boîte de réception de test. Pour lire un code de signature ou suivre un lien d'accès, demandez à CYBASTION l'accès à cette boîte. Pour essayer la signature sans boîte de réception, utilisez la voie papier (POST /devis/{id}/signature).

Sécurité

Ce que la plateforme garantit, à éprouver en préproduction.

Authentification

• Jeton d'accès JWT signé (ES256) par le service d'authentification. L'API vérifie sa signature, son émetteur et son expiration à chaque appel.
• Durée de vie d'une heure, renouvelable par un jeton de renouvellement à usage unique.
• À chaque appel, l'API relit le compte : un compte désactivé est refusé sur-le-champ (403 compte_inactif), même avec un jeton encore valable.
• Les liens d'accès valent 20 minutes, ne servent qu'une fois, et seul le dernier demandé fonctionne. POST /public/mot-de-passe/lien répond de la même façon que l'adresse ait un compte ou non : elle ne révèle rien.

Autorisations et cloisonnement

• 12 rôles, 60 permissions. Chaque opération exige une permission précise, indiquée dans la référence ; sans elle : 403 permission_refusee.
• Un partenaire ne voit que son portefeuille, et un client que son propre dossier. Une ressource hors périmètre répond 404 et non 403, pour ne pas révéler qu'elle existe.
• Les données sont aussi protégées en base, par des politiques de sécurité au niveau des lignes (RLS).
• Un fichier ne peut être joint que par le compte qui l'a déposé.

Entrées et fichiers

• Chaque corps, paramètre et identifiant est validé avant tout traitement. Un champ manquant ou mal formé répond 400, un champ inconnu est ignoré, et un corps ne dépasse pas 1 Mo.
• Fichiers : 10 Mo au plus. Seuls sont admis PDF, JPEG, PNG, WebP et HEIC, et le contenu réel est contrôlé, pas seulement l'extension. Chaque fichier passe un antivirus avant de pouvoir être joint. Un compte dépose 60 fichiers par heure au plus ; un PDF compte 50 pages au plus, une image 50 mégapixels au plus.
• La lecture d'un fichier passe par une adresse signée, valable 5 minutes.
• Le montant d'un paiement en ligne est le reste dû, recalculé par la plateforme : l'appelant n'en transmet aucun. Un règlement déclaré hors ligne n'a d'effet qu'après validation par la Finance.

Débit et transport

• 300 requêtes par minute et par compte, ou par adresse IP sans jeton ; au-delà, 429 avec retry-after. La demande de lien de mot de passe est limitée à 10 par adresse IP et par quart d'heure.
• HTTPS seulement, avec HSTS, X-Content-Type-Options: nosniff et une politique de référent stricte.
• CORS : depuis un navigateur, seuls le back-office et ce portail sont admis. Un appel de serveur à serveur (Odoo) n'est pas concerné.

Traçabilité et paiements

• Les actions métier (créations, décisions, corrections, suppressions) sont inscrites au journal d'audit, qui n'accepte que des ajouts : GET /journal-audit (compte CYBASTION).
• Signature électronique : code à six chiffres envoyé par e-mail, valable 10 minutes, 3 essais au plus. La preuve (adresse IP, appareil, empreintes du document) est conservée et le PDF scellé.
• Notifications Paystack : signature HMAC SHA-512 et adresses d'expédition vérifiées, notification enregistrée avant traitement, traitement idempotent (une notification rejouée ne crédite rien de plus).
• Les messages d'erreur ne contiennent aucun détail technique interne.

Comportements voulus

Ces comportements surprennent parfois lors d'un audit. Ils sont délibérés.

Règles d'essai

Les tests de sécurité sont bienvenus, dans ce cadre.

Une faille trouvée se signale à CYBASTION, en privé, avec l'opération, la requête et l'heure. Elle n'est divulguée nulle part avant sa correction.

Données et assistance

• Les données de la préproduction sont fictives et partagées : nos recettes automatiques y créent aussi des objets, reconnaissables au préfixe « ZZ Recette » et effacés régulièrement.
• La préproduction peut être remise à neuf entre deux campagnes d'essai ; les comptes d'essai sont alors rouverts.
• Elle reçoit chaque nouvelle version avant la production : le contrat publié ici est toujours celui du code en service.

Pour une question, un compte supplémentaire, un exemplaire de document à rejouer ou un incident, adressez-vous à votre interlocuteur CYBASTION. Indiquez l'opération, l'heure, le compte employé et, en cas d'erreur, la réponse reçue.