PDF : dans le navigateur, menu Fichier → Imprimer (ou Ctrl+P), choisir Enregistrer au format PDF comme imprimante, puis Enregistrer.

Try&Tell — Guide pour les organisations (marques & partenaires)

Document à destination des équipes marque, éditeur ou intégrateur — aligné sur le portail web et l’API Try&Tell. Pour le détail des webhooks et de l’attribution hors-plateforme, voir le document technique partner-off-platform-attribution-spec.md dans le dépôt.

1. Rôle d’une organisation sur Try&Tell

Une organisation est le compte « entreprise » rattaché à votre activité (fabricant, marque, éditeur logiciel, etc.). Elle permet notamment de :

publier et gérer un catalogue produits ;
proposer des promotions (liens de tracking, commissions) aux influenceurs ;
gérer la flotte (influenceurs invités, demandes de partenariat) ;
recevoir des signaux de conversion depuis votre site ou votre back-office (webhook partenaire), lorsque cette intégration est activée.

Chaque organisation possède une fiche (raison sociale, marque, contact, site, description, logo) et un type (ex. fabricant / éditeur logiciel selon les options du portail).

2. Création d’un compte organisme

2.1 Inscription initiale (compte utilisateur + organisation)

Élément	Détail
Méthode	POST /api/auth/organization
Corps	JSON OrganizationRegistrationRequest : email, mot de passe, identité utilisateur (username, prénom, nom, téléphone optionnel), pays (countryCode, ex. CA), puis champs entreprise : companyName, brandName, contactEmail, website, description, et organizationType (MANUFACTURER par défaut ou SOFTWARE_VENDOR).
Réponse	Message de succès ; connexion ensuite via POST /api/auth/login pour obtenir un JWT (Bearer).

L’ancien alias POST /api/auth/manufacturer peut encore exister pour compatibilité ; privilégiez POST /api/auth/organization.

2.2 Création d’une organisation supplémentaire (compte déjà existant)

Si l’utilisateur connecté est déjà au rôle approprié (ex. fabricant), il peut créer une autre organisation liée à son compte depuis le portail ou via l’API :

Élément	Détail
Méthode	POST /api/organizations/mine
Auth	Header Authorization: Bearer <token>
Corps	CreateMyOrganizationRequest : companyName (obligatoire), contactEmail (obligatoire, email), brandName, website, description, logoUrl, et optionnellement partnerWebhookSecret (voir §5).

3. Consulter et mettre à jour sa fiche organisme

Toutes les routes ci-dessous exigent un JWT valide et un utilisateur propriétaire de l’organisation.

Action	Méthode & chemin
Lister mes organisations	GET /api/organizations/mine
Détail d’une organisation	GET /api/organizations/mine/{id}
Mettre à jour	PUT /api/organizations/mine/{id} (même schéma que la création : CreateMyOrganizationRequest)
Tableau de bord (indicateurs)	GET /api/organizations/mine/{id}/dashboard — retourne notamment le nombre de produits et de campagnes liés à l’organisation.

Champs utiles côté intégration partenaire

Identité : companyName, brandName, contactEmail, website, description, logoUrl.
Webhook : le corps de mise à jour peut inclure partnerWebhookSecret. Absent ou null = ne pas modifier ; chaîne vide = supprimer le secret dédié (repli sur la configuration globale si définie).
En lecture, l’API expose partnerWebhookSecretPresent (booléen), jamais la valeur du secret.

4. Annuaire public (référence)

Méthode	GET /api/organizations
Auth	Selon la politique du déploiement (souvent utilisateurs authentifiés pour la découverte).

Détail public par identifiant : GET /api/organizations/{id}

5. Attribution des ventes / conversions (aperçu partenaire)

5.1 L’organisme n’a pas besoin de l’ID promotion en amont

La promotion est créée dans Try&Tell par l’influenceur, sur un produit déjà rattaché à votre organisation : le lien promotion ↔ produit ↔ organisme est géré côté plateforme. L’influenceur ne vous transmet pas l’identifiant technique de la promotion.

Le lien court partagé au public est du type …/p/{publicSlug} : l’URL contient un slug public, pas l’identifiant interne promotionId.

5.2 Ce que reçoit votre site au clic

Au clic, Try&Tell enregistre le clic puis redirige vers votre URL cible en ajoutant notamment :

Paramètre	Rôle
tt_ref	Égal au publicSlug de la promotion ou de la participation campagne — à conserver jusqu’à la conversion.
tt_track	Code métier optionnel sur une promotion ; pour une participation campagne, identifiant de campagne. Omis s’il n’y a pas de valeur à transmettre.
tt_sub	Jeton opaque pour l’acheteur déjà connecté sur Try&Tell (portail web ou boutique). Absent pour un visiteur non authentifié : ne pas inventer ni reconstruire cette valeur côté organisme.

Vous stockez tt_ref (et idéalement tt_track) avec la session ou la commande, sans recevoir promotionId par un autre canal. Si tt_sub est présent sur l’URL d’arrivée, conservez la même valeur jusqu’à la conversion.

5.3 Webhook : exemple HTTP

En pratique : publicSlug = valeur de tt_ref. promotionId est optionnel.

Exemple côté organisme

POST /api/webhooks/partner/conversions
X-Partner-Webhook-Secret: {secret_organisme}
Content-Type: application/json

{
  "publicSlug": "2n5O1qTX",
  "externalOrderId": "order-12345",
  "amount": 99.99,
  "currency": "CAD",
  "signature": "<sha1_hex calculé>"
}

URL complète (production) : https://partner.tryandtell.ca/api/webhooks/partner/conversions

Votre intégration utilise partner.tryandtell.ca uniquement (passerelle dédiée aux webhooks de conversion).

5.3 bis Architecture et sécurité

Hôte partenaire : surface API minimale (webhook conversions + limite de débit).
Secret + signature + IP : protection serveur à serveur.
Intégration validée par Try & Tell avant production.
Pas de broker requis : POST HTTPS direct depuis votre backend.

Important : l’intégration doit toujours être validée (partner_integration_verified = true) et le secret organisme configuré avant qu’un appel réel soit accepté (hors sandbox admin avec les bons réglages).

Signature : SHA-1 hex de publicSlug + externalOrderId + amount + currency + secret_organisme (sans séparateur). Pour amount, utilisez un décimal plain avec un point et sans zéros finaux après la virgule : ex. 50.9 pour 50,90 € (pas 50.90).

Liste blanche IP optionnelle sur la fiche organisme. Corps optionnel : buyerToken (= tt_sub).

Les règles détaillées (idempotence, ledger) figurent dans la spécification partner-off-platform-attribution.

5.4 Acheteur connecté et cashback (hors checkout plateforme)

Lorsque le webhook inclut un buyerToken valide (même valeur que tt_sub) et que le produit prévoit un pool cashback acheteur au-delà de la commission influenceur sur la promotion, Try&Tell peut créditer le portefeuille de l’acheteur après règlement de la commission créateur. La part acheteur est calculée sur le montant de vente déclaré : taux cashback produit moins taux commission promotion (si la marge restante est positive). Le débit correspondant est imputé au portefeuille organisme ; l’acheteur retrouve le mouvement dans son historique portefeuille sur Try&Tell.

Sans buyerToken, seule la commission influenceur (et le suivi de conversion) est traitée selon les règles habituelles du webhook.

6. Flotte & partenariats (aperçu)

Les endpoints sous /api/organizations/{organizationId}/... couvrent flotte, découverte d’influenceurs et partenariats. Le détail est exposé dans Swagger.

7. Documentation API interactive

Swagger UI : https://<hôte-api>/api/swagger-ui.html
OpenAPI : typiquement https://<hôte-api>/api/v3/api-docs
Base locale courante : http://localhost:7106/api

8. Bonnes pratiques

Utiliser HTTPS ; ne pas journaliser les JWT en clair.
Traiter le secret webhook comme un mot de passe ; prévoir une procédure de rotation.
Ne pas modifier, régénérer ni inventer tt_sub / buyerToken ; les relayer tels quels de l’URL d’arrivée jusqu’au webhook si présents.
Réutiliser la même externalOrderId pour une même transaction (idempotence).
Valider sur un environnement de recette avant la production.

9. Contact & support

À compléter selon votre contrat (équipe Try&Tell ou revendeur).

Document fourni pour partage avec un partenaire — les chemins d’API peuvent évoluer selon la version déployée.