SUP × Flowshopper — Integration Flow

SKU	DésignationProduct name	CatégorieCategory	Description SEOSEO description	StatutStatus
RJ-CT-001	Caisse américaine simple cannelure 300×200×150 Single-wall shipping box 300×200×150	Carton / Caisses Cardboard / Boxes	— videempty —	À enrichirTo enrich
RJ-CT-002	Caisse double cannelure renforcée 400×300×200 Reinforced double-wall box 400×300×200	Carton / Caisses Cardboard / Boxes	— videempty —	À enrichirTo enrich
RJ-CT-003	Boîte postale carton kraft 250×175×100 Kraft paper postal box 250×175×100	Carton / Postal Cardboard / Postal	Boîte postale solide en carton kraft pour expéditions... Sturdy kraft paper postal box for shipping...	EnrichiEnriched
RJ-CT-004	Carton penderie 50 cm avec barre Wardrobe moving box 50 cm with bar	Carton / Déménagement Cardboard / Moving	— videempty —	À enrichirTo enrich

Prérequis techniques Technical specs

01 / CONTEXTE

Architecture cible

Flowshopper est un SaaS standalone avec authentification email + mot de passe. Chaque utilisateur RAJA dispose déjà d'un compte. L'intégration SUP n'introduit ni SSO, ni partage d'infrastructure : SUP appelle Flowshopper via deux endpoints HTTPS, Flowshopper appelle SUP en retour via un webhook. Chaque outil reste maître de son périmètre, de son stockage et de son authentification.

Principe directeur Aucun code partagé, aucune base de données partagée. Le couplage est limité à un contrat d'API et un secret HMAC partagé.

02 / ENDPOINT HANDOFF (SUP → Flowshopper)

Réception du fichier

Quand Marie clique sur "Enrich with Flowshopper" dans SUP, SUP appelle un endpoint Flowshopper avec l'identité de l'utilisatrice, le fichier (ou son URL signée), et les métadonnées de session. Flowshopper renvoie une URL de redirection contenant un handoff_token à usage unique.

// POST https://app.flowshopper.ai/api/v1/integrations/sup/handoff
// Header: X-SUP-Signature: hmac_sha256(body, shared_secret)
{
  "user_email": "marie.caron@raja.com",
  "file_format": "xlsx",
  "file_name": "catalogue_carton_q2_2026.xlsx",
  "file_transfer": { // option à arbitrer avec RAJA
    "mode": "signed_url", // ou "multipart"
    "url": "https://sup.raja.com/exports/4827?sig=...",
    "expires_at": "2026-05-08T14:32:18Z"
  },
  "sup_session_id": "sup_sess_8xK2...",
  "return_webhook": "https://sup.raja.com/api/flowshopper/import-ready",
  "requested_at": "2026-05-08T14:17:18Z"
}

// Réponse
{
  "redirect_url": "https://app.flowshopper.ai/handoff/8xK2.._signed",
  "handoff_token": "ho_8xK2...",
  "valid_until": "2026-05-08T14:18:18Z"
}

SUP exécute ensuite window.open(redirect_url) pour ouvrir Flowshopper en nouvel onglet.

03 / ARRIVÉE & AUTHENTIFICATION

Gestion du login standard

Sur la page /handoff/:token, Flowshopper consomme le token (à usage unique, expiration 60 secondes), récupère le fichier, et vérifie l'état de session de l'utilisatrice. Deux branches se présentent.

Cas A — session active. L'utilisatrice est déjà loggée dans Flowshopper (cookie de session valide). Elle est redirigée immédiatement vers /bulk-generation/job/:id avec son fichier déjà chargé sur l'écran de mapping.
Cas B — non loggée. Le contexte du handoff est stocké dans un pending_session (cookie ou DB, expiration 30 min). L'utilisatrice est redirigée vers la page de login Flowshopper, avec un bandeau contextuel "Vous arrivez depuis SUP". Après authentification, Flowshopper consulte le pending_session et redirige automatiquement vers le mapping. Aucune action manuelle requise.

04 / FORMAT FICHIER

XLSX uniquement

Pour s'aligner avec le format de référence LAGO et éviter la friction sur les conversions, la V1 supporte uniquement le format .xlsx. Les fichiers CSV et autres formats Excel pourront être ajoutés ultérieurement si nécessaire.

Critère	Spécification
Format	.xlsx (Office Open XML)
Encodage	UTF-8
Volumétrie max	~10 000 lignes / fichier
Taille max	50 MB
Première ligne	En-têtes de colonnes (obligatoire)
Feuilles	1ère feuille uniquement (V1)

À cadrer avec RAJA Mode de transfert du fichier (URL signée S3 / POST multipart / token de download SUP). Convention de nommage des colonnes (snake_case, pascalCase) pour optimiser l'auto-détection.

05 / WEBHOOK RETOUR (Flowshopper → SUP)

Réimport dans SUP

Quand Marie clique sur "Réimporter dans SUP" depuis l'historique, Flowshopper appelle le webhook de retour fourni par SUP. Le fichier enrichi est transmis via une URL signée Flowshopper (durée de vie 30 min, lecture seule).

// POST {return_webhook}
// Header: X-Flowshopper-Signature: hmac_sha256(body, shared_secret)
{
  "sup_session_id": "sup_sess_8xK2...",
  "job_id": "job_8xK2_4827",
  "user_email": "marie.caron@raja.com",
  "enriched_file": {
    "url": "https://app.flowshopper.ai/files/job_8xK2_4827?sig=...",
    "format": "xlsx",
    "expires_at": "2026-05-08T15:02:18Z"
  },
  "new_columns": ["description_seo", "titre_seo", "meta_description"],
  "row_count": 1247,
  "completed_at": "2026-05-08T14:31:42Z"
}

// Réponse SUP
{
  "received": true,
  "redirect_url": "https://sup.raja.com/imports/staging/8xK2"
}

Flowshopper redirige ensuite l'utilisatrice vers redirect_url. SUP fetch le fichier de son côté avant que l'URL signée n'expire.

06 / SÉCURITÉ

Garanties

Signature HMAC-SHA256. Toutes les requêtes entre SUP et Flowshopper sont signées avec un secret partagé (rotation prévue). Le signataire et le récepteur valident la signature et le timestamp (anti-replay, fenêtre 5 min).
Tokens à usage unique. Le handoff_token est invalidé après première consommation. Expiration 60 secondes après émission.
URLs signées courtes. Toutes les URLs de fichier ont une durée de vie limitée (15-30 min) et sont scopées en lecture seule.
Mapping email. Flowshopper résout l'email RAJA vers son compte interne. Si l'email n'existe pas dans Flowshopper, la session ne s'ouvre pas et un message clair s'affiche.
Aucune exposition publique. Les endpoints handoff et webhook sont scopés à des IP whitelistées (à confirmer avec RAJA) ou à des secrets validés.

07 / NOTIFICATIONS

Email transactionnel

L'utilisatrice reçoit un email Flowshopper à la fin de la génération, contenant un lien direct vers l'historique. Si la session SUP est encore valide quand elle clique sur "Réimporter dans SUP", le retour fonctionne. Sinon, SUP doit gérer la reconnexion (page de login SUP avec retour automatique sur la page d'import staging).

08 / DÉVELOPPEMENT

Périmètre & estimation

Côté Flowshopper :

Endpoint POST /api/v1/integrations/sup/handoff avec validation HMAC
Page /handoff/:token avec consommation du token et logique pending_session
Modification de la page de login pour gérer le bandeau contextuel et la redirection auto post-login
Bouton "Réimporter dans SUP" dans l'historique (visible uniquement pour les jobs source = "sup")
Worker d'appel webhook sortant avec retry exponentiel (3 tentatives)
Tag source sur les jobs pour distinction handoff / upload manuel

Côté SUP :

Bouton "Enrich with Flowshopper" sur la page d'export
Logique d'appel à l'endpoint handoff Flowshopper
Endpoint webhook POST /api/flowshopper/import-ready
Page d'import staging préchargeant le fichier reçu

Estimation 5 à 8 jours côté Flowshopper. Côté SUP : à dimensionner avec l'équipe RAJA selon l'architecture interne de SUP.

09 / POINTS À CADRER

À valider en réunion technique

Mode de transfert du fichier. URL signée (S3 ou équivalent) ou POST multipart ? La première option est plus propre pour les gros fichiers.
Convention des noms de colonnes dans les exports SUP, pour optimiser l'auto-détection côté Flowshopper.
Endpoint webhook côté SUP. Hébergement, authentification, gestion des retries.
Provisionnement des comptes Flowshopper. Liste d'utilisateurs RAJA à fournir une fois.
IP whitelist ou autre mécanisme de restriction des appels handoff.
Comportement en cas d'expiration de session SUP au moment du retour.
Gestion des erreurs côté Flowshopper (fichier corrompu, dépassement de volumétrie, mapping impossible) et UX du message d'erreur côté SUP.

01 / CONTEXT

Target architecture

Flowshopper is a standalone SaaS with email + password authentication. Each RAJA user already has an account. The SUP integration introduces neither SSO nor shared infrastructure: SUP calls Flowshopper through two HTTPS endpoints, and Flowshopper calls SUP back via a webhook. Each tool remains owner of its scope, storage and authentication.

Guiding principle No shared code, no shared database. Coupling is limited to an API contract and a shared HMAC secret.

02 / HANDOFF ENDPOINT (SUP → Flowshopper)

File reception

When Marie clicks "Enrich with Flowshopper" in SUP, SUP calls a Flowshopper endpoint with the user's identity, the file (or its signed URL), and session metadata. Flowshopper returns a redirect URL containing a single-use handoff_token.

// POST https://app.flowshopper.ai/api/v1/integrations/sup/handoff
// Header: X-SUP-Signature: hmac_sha256(body, shared_secret)
{
  "user_email": "marie.caron@raja.com",
  "file_format": "xlsx",
  "file_name": "catalogue_carton_q2_2026.xlsx",
  "file_transfer": { // to be agreed with RAJA
    "mode": "signed_url", // or "multipart"
    "url": "https://sup.raja.com/exports/4827?sig=...",
    "expires_at": "2026-05-08T14:32:18Z"
  },
  "sup_session_id": "sup_sess_8xK2...",
  "return_webhook": "https://sup.raja.com/api/flowshopper/import-ready",
  "requested_at": "2026-05-08T14:17:18Z"
}

// Response
{
  "redirect_url": "https://app.flowshopper.ai/handoff/8xK2.._signed",
  "handoff_token": "ho_8xK2...",
  "valid_until": "2026-05-08T14:18:18Z"
}

SUP then runs window.open(redirect_url) to open Flowshopper in a new tab.

03 / ARRIVAL & AUTHENTICATION

Standard login handling

On /handoff/:token, Flowshopper consumes the token (single-use, 60-second expiration), retrieves the file, and checks the user's session state. Two branches.

Case A — active session. The user is already logged in to Flowshopper (valid session cookie). She is redirected immediately to /bulk-generation/job/:id, file already loaded on the mapping screen.
Case B — not logged in. The handoff context is stored in a pending_session (cookie or DB, 30-minute expiration). The user is redirected to the Flowshopper login page, with a contextual banner "You're coming from SUP". After authentication, Flowshopper looks up the pending_session and auto-redirects to mapping. No manual action required.

04 / FILE FORMAT

XLSX only

To align with the LAGO reference format and avoid conversion friction, V1 supports only .xlsx. CSV and other Excel formats can be added later if needed.

Criterion	Specification
Format	.xlsx (Office Open XML)
Encoding	UTF-8
Max volume	~10,000 rows / file
Max size	50 MB
First row	Column headers (mandatory)
Sheets	First sheet only (V1)

To agree with RAJA File transfer mode (signed S3 URL / POST multipart / SUP download token). Column naming convention (snake_case, pascalCase) to optimize auto-detection.

05 / RETURN WEBHOOK (Flowshopper → SUP)

Re-import to SUP

When Marie clicks "Re-import to SUP" from history, Flowshopper calls the return webhook provided by SUP. The enriched file is transmitted via a Flowshopper signed URL (30-minute lifetime, read-only).

// POST {return_webhook}
// Header: X-Flowshopper-Signature: hmac_sha256(body, shared_secret)
{
  "sup_session_id": "sup_sess_8xK2...",
  "job_id": "job_8xK2_4827",
  "user_email": "marie.caron@raja.com",
  "enriched_file": {
    "url": "https://app.flowshopper.ai/files/job_8xK2_4827?sig=...",
    "format": "xlsx",
    "expires_at": "2026-05-08T15:02:18Z"
  },
  "new_columns": ["description_seo", "titre_seo", "meta_description"],
  "row_count": 1247,
  "completed_at": "2026-05-08T14:31:42Z"
}

// SUP response
{
  "received": true,
  "redirect_url": "https://sup.raja.com/imports/staging/8xK2"
}

Flowshopper then redirects the user to redirect_url. SUP fetches the file on its side before the signed URL expires.

06 / SECURITY

Guarantees

HMAC-SHA256 signature. All requests between SUP and Flowshopper are signed with a shared secret (rotation planned). Both sender and receiver validate signature and timestamp (anti-replay, 5-minute window).
Single-use tokens. The handoff_token is invalidated after first consumption. 60-second expiration after issuance.
Short signed URLs. All file URLs have a limited lifetime (15-30 min) and are scoped to read-only.
Email mapping. Flowshopper resolves the RAJA email to its internal account. If the email doesn't exist in Flowshopper, no session is opened and a clear error message is shown.
No public exposure. Handoff and webhook endpoints are scoped to whitelisted IPs (to confirm with RAJA) or validated secrets.

07 / NOTIFICATIONS

Transactional email

The user receives a Flowshopper email at the end of generation, with a direct link to history. If the SUP session is still valid when she clicks "Re-import to SUP", the return works. Otherwise, SUP must handle reconnection (SUP login page with auto-return to staging import page).

08 / DEVELOPMENT

Scope & estimation

Flowshopper side:

Endpoint POST /api/v1/integrations/sup/handoff with HMAC validation
Page /handoff/:token with token consumption and pending_session logic
Login page modification to handle the contextual banner and post-login auto-redirect
"Re-import to SUP" button in history (visible only for jobs with source = "sup")
Outbound webhook worker with exponential retry (3 attempts)
source tag on jobs to distinguish handoff vs manual upload

SUP side:

"Enrich with Flowshopper" button on the export page
Call logic to the Flowshopper handoff endpoint
Webhook endpoint POST /api/flowshopper/import-ready
Staging import page preloading the received file

Estimation 5 to 8 days on the Flowshopper side. SUP side: to be sized with the RAJA team based on internal SUP architecture.

09 / OPEN QUESTIONS

To validate in technical meeting

File transfer mode. Signed URL (S3 or equivalent) or POST multipart? The first option is cleaner for large files.
Column naming convention in SUP exports, to optimize Flowshopper auto-detection.
SUP-side webhook endpoint. Hosting, authentication, retry handling.
Flowshopper account provisioning. RAJA user list to provide once.
IP whitelist or other mechanism for restricting handoff calls.
Behavior on SUP session expiration at return time.
Error handling on Flowshopper side (corrupted file, volume exceeded, mapping impossible) and error message UX on SUP side.

Export #4827 — Catalogue Emballage Carton Export #4827 — Cardboard Packaging Catalog

Passage de relais Secure handoff

Configurer la génération en masse Configure bulk generation

Génération en cours Generation in progress

Historique des générations Generation history

Fichier enrichi reçu Enriched file received