Krow-workspace/docs/api_specification.md

Spécification de l'API KROW Workforce (Migration GCP)

Version : 2.0 Date : 11/11/2025 Objectif : Ce document définit l'API RESTful à construire sur Google Cloud Platform (Cloud Functions, Cloud SQL) pour remplacer le backend Base44. Il est basé sur la documentation exhaustive de l'API Base44 (v2.0) et a pour but de guider le développement du nouveau backend.

---

Conventions Générales

• URL de base : /api/v1
• Authentification : Chaque requête (sauf POST /login et GET /health) doit inclure un header Authorization: Bearer <Firebase-Auth-Token>.
• Format des données : Toutes les requêtes et réponses seront au format application/json.
• Réponses d'erreur : Les erreurs utiliseront les codes de statut HTTP standards (400, 401, 403, 404, 500) et incluront un corps de réponse JSON de la forme { "error": "Description du problème" }.
• Champs Communs : Chaque entité aura les champs suivants, gérés automatiquement par le backend :
  • id: string (UUID, Clé primaire)
  • created_date: string (ISO 8601 Timestamp)
  • updated_date: string (ISO 8601 Timestamp)
  • created_by: string (Email de l'utilisateur créateur)

---

1. Authentification (/auth)

Basé sur Firebase Authentication. Le frontend gère l'inscription et la connexion avec le SDK Firebase. Notre backend a besoin d'un endpoint pour récupérer les informations étendues de l'utilisateur.

Entité User (Basée sur base44.auth.me)

Champ	Type	Description
id	string	ID Firebase de l'utilisateur
email	string	Email de l'utilisateur (non modifiable)
full_name	string	Nom complet
user_role	string	Rôle personnalisé dans l'application (admin, procurement, client...)
...autres	any	D'autres champs personnalisés peuvent être ajoutés.

Endpoints

GET /auth/me

• Description : Récupère les informations du profil de l'utilisateur actuellement authentifié.
• SDK d'origine : base44.auth.me()
• Réponse (200 OK) : L'objet User complet.

PUT /auth/me

• Description : Met à jour le profil de l'utilisateur actuel.
• SDK d'origine : base44.auth.updateMe(data)
• Corps de la requête : Un objet avec les champs de User à mettre à jour.
• Réponse (200 OK) : L'objet User mis à jour.

---

2. Entités (Endpoints CRUD)

Pour chaque entité ci-dessous, les endpoints standards suivants sont à implémenter.

• POST /{nom-entite}: Crée une nouvelle entrée.
• GET /{nom-entite}: Liste les entrées, avec support pour le filtrage et le tri via des query params.
• GET /{nom-entite}/{id}: Récupère une entrée par son ID.
• PUT /{nom-entite}/{id}: Met à jour une entrée par son ID.
• DELETE /{nom-entite}/{id}: Supprime une entrée par son ID.

2.1. Event (/events)

Description : Gère les événements et les commandes de main-d'œuvre.

Champ	Type	Description
event_name	string	Nom de l'événement (requis)
is_recurring	boolean	Indique si l'événement est récurrent
recurrence_type	string	single, date_range, scatter
recurrence_start_date	string	Date de début de récurrence (ISO 8601)
recurrence_end_date	string	Date de fin de récurrence (ISO 8601)
scatter_dates	array	Tableau de dates (ISO 8601) pour scatter
business_id	string	ID du client (Business)
business_name	string	Nom du client
vendor_id	string	ID du fournisseur (Vendor)
vendor_name	string	Nom du fournisseur
hub	string	Lieu/hub
contract_type	string	W2, 1099, Temp, Contract
po_reference	string	Référence de bon de commande
status	string	Draft, Active, Pending, Assigned, Confirmed, Completed, Canceled
date	string	Date de l'événement (ISO 8601)
shifts	array	Tableau d'objets Shift
addons	object	Services additionnels
total	number	Coût total
client_name	string	Nom du contact client
client_email	string	Email du contact client
client_phone	string	Téléphone du contact client
notes	string	Notes additionnelles
requested	number	Nombre total de personnel demandé
assigned_staff	array	Tableau d'objets de personnel assigné

2.2. Staff (/staff)

Description : Gère les membres du personnel.

Champ	Type	Description
employee_name	string	Nom complet (requis)
vendor_id	string	ID du fournisseur (Vendor)
vendor_name	string	Nom du fournisseur
manager	string	Nom du manager
contact_number	string	Numéro de contact principal
phone	string	Autre téléphone
email	string	Adresse email
department	string	Operations, Sales, HR, etc.
hub_location	string	Lieu/hub de rattachement
address	string	Adresse de l'employé
city	string	Ville
position	string	Poste/compétence principal(e)
position_2	string	Poste/compétence secondaire
profile_type	string	Skilled, Beginner, Cross-Trained
employment_type	string	Full Time, Part Time, On call, etc.
english	string	Fluent, Intermediate, Basic, None
rating	number	Note de performance (0-5)
shift_coverage_percentage	number	Pourcentage de shifts couverts (0-100)
cancellation_count	number	Nombre d'annulations
no_show_count	number	Nombre de non-présentations
total_shifts	number	Nombre total de shifts assignés
reliability_score	number	Score de fiabilité (0-100)
background_check_status	string	pending, cleared, failed, expired
background_check_date	string	Date du dernier contrôle (ISO 8601)
certifications	array	Liste des certifications

2.3. Vendor (/vendors)

Description : Gère les fournisseurs et leur onboarding.

Champ	Type	Description
vendor_number	string	Numéro de fournisseur (ex: VN-####)
legal_name	string	Nom légal de l'entreprise (requis)
doing_business_as	string	Nom commercial (DBA)
region	string	National, Bay Area, etc.
primary_contact_email	string	Email du contact principal (requis)
approval_status	string	pending, approved, suspended, terminated
is_active	boolean	Statut d'activité
tax_id	string	Numéro d'identification fiscale (EIN)
business_type	string	Corporation, LLC, etc.
insurance_certificate	string	URL du certificat d'assurance
insurance_expiry	string	Date d'expiration de l'assurance (ISO 8601)
w9_document	string	URL du document W9
coi_document	string	URL du document COI

2.4. VendorRate (/vendor-rates)

Description : Gère les grilles tarifaires des fournisseurs.

Champ	Type	Description
vendor_id	string	ID du fournisseur (Vendor)
vendor_name	string	Nom du fournisseur (requis)
category	string	Catégorie de service (Kitchen, etc.)
role_name	string	Nom du poste (requis)
employee_wage	number	Salaire horaire de l'employé (requis)
client_rate	number	Tarif horaire facturé au client (requis)
pricing_status	string	optimal, underpriced, overpriced
is_active	boolean	Statut d'activité

2.5. Invoice (/invoices)

Description : Gère les factures.

Champ	Type	Description
invoice_number	string	Numéro de facture (requis)
event_id	string	ID de l'événement (Event)
business_name	string	Nom du client (requis)
vendor_name	string	Nom du fournisseur
amount	number	Montant de la facture (requis)
status	string	Open, Paid, Overdue, Disputed, etc.
issue_date	string	Date d'émission (ISO 8601, requis)
due_date	string	Date d'échéance (ISO 8601, requis)
paid_date	string	Date de paiement (ISO 8601)

2.6. Business (/businesses)

Description : Gère les entreprises clientes.

Champ	Type	Description
business_name	string	Nom de l'entreprise (requis)
contact_name	string	Nom du contact principal (requis)
email	string	Email de l'entreprise
phone	string	Téléphone de l'entreprise
sector	string	Bon Appétit, Eurest, etc.
rate_group	string	Standard, Premium, etc. (requis)
status	string	Active, Inactive, Pending

---

Note : Pour la concision, seules les entités les plus critiques ont été entièrement détaillées. La même structure (Schéma + Endpoints) doit être appliquée pour : Certification, Team, Conversation, Message, ActivityLog, Enterprise, Sector, Partner, Order, et Shift en se basant sur API_documentation.md.

---

3. Services d'Intégration

POST /integrations/invoke-llm

• Description : Fait appel à un modèle de langage (Vertex AI).
• SDK d'origine : base44.integrations.Core.InvokeLLM(params)
• Body : { "prompt": "...", "response_json_schema": {...}, "file_urls": [...] }
• Réponse (200 OK) : { "result": "..." }

POST /integrations/send-email

• Description : Envoie un email.
• SDK d'origine : base44.integrations.Core.SendEmail(params)
• Body : { "to": "...", "subject": "...", "body": "..." }
• Réponse (200 OK) : { "status": "sent" }

POST /integrations/upload-file

• Description : Gère le téléversement de fichiers publics vers Google Cloud Storage.
• SDK d'origine : base44.integrations.Core.UploadFile({ file })
• Requête : multipart/form-data.
• Réponse (200 OK) : { "file_url": "https://..." }

POST /integrations/upload-private-file

• Description : Gère le téléversement de fichiers privés vers Google Cloud Storage.
• SDK d'origine : base44.integrations.Core.UploadPrivateFile({ file })
• Requête : multipart/form-data.
• Réponse (200 OK) : { "file_uri": "gs://..." }

POST /integrations/create-signed-url

• Description : Crée une URL d'accès temporaire pour un fichier privé.
• SDK d'origine : base44.integrations.Core.CreateFileSignedUrl(params)
• Body : { "file_uri": "...", "expires_in": 3600 }
• Réponse (200 OK) : { "signed_url": "https://..." }

POST /integrations/extract-data

• Description : Extrait des données structurées d'un fichier (CSV, PDF...).
• SDK d'origine : base44.integrations.Core.ExtractDataFromUploadedFile(params)
• Body : { "file_url": "...", "json_schema": {...} }
• Réponse (200 OK) : { "status": "success", "output": [...] }

POST /integrations/generate-image

• Description : Génère une image via une IA.
• SDK d'origine : base44.integrations.Core.GenerateImage(params)
• Body : { "prompt": "..." }
• Réponse (200 OK) : { "url": "https://..." }