{ "openapi": "3.0.0", "info": { "title": "Scell.io API", "description": "API Scell.io — facturation électronique (Factur-X / UBL / CII / EN16931) et signatures simples (eIDAS EU-SES).\n\n## Authentification (3 mécanismes)\n\n| Mécanisme | Header(s) | Préfixe clé | Usage |\n|-----------|-----------|-------------|-------|\n| **Sanctum Bearer JWT** | `Authorization: Bearer ` | (JWT) | Dashboard utilisateur connecté |\n| **Secret API Key** | `X-API-Key` *(ou alias historique `X-Tenant-Key`)* | `sk_live_*` / `sk_test_*` | Server-to-server (factures, signatures, webhooks…) |\n| **Publishable Key** | `X-Publishable-Key` | `pk_live_*` / `pk_test_*` | Widget public d'onboarding partenaire (browser-safe) |\n\n> ℹ️ **`X-API-Key` et `X-Tenant-Key` sont strictement équivalents** côté serveur — les deux headers acceptent la **même** clé secrète `sk_live_*` / `sk_test_*` (cf. `TenantApiKeyMiddleware` qui lit `X-Tenant-Key ?? X-API-Key` et valide la même regex). `X-Tenant-Key` est conservé pour la rétro-compatibilité ; **utiliser `X-API-Key`** dans le code nouveau. Il n'existe **PAS** de format de clé `tk_*` distinct.\n\n## SDKs officiels\n\n- **TypeScript/JavaScript** : [`@scell/sdk`](https://www.npmjs.com/package/@scell/sdk) v2.25.0+\n- **PHP** : [`scell/sdk`](https://packagist.org/packages/scell/sdk) v2.25.0+\n- **MCP Agent** : [`@scell/mcp-client`](https://www.npmjs.com/package/@scell/mcp-client) v2.25.0+\n\n## Documentation\n\n- [Guide SDKs](https://scell.io/fr/sdk)\n- [Webhooks](https://scell.io/fr/webhooks)\n- [Changelog](https://scell.io/fr/changelog)", "contact": { "name": "Support Scell.io", "url": "https://scell.io", "email": "support@scell.io" }, "license": { "name": "Proprietary", "url": "https://scell.io/fr/legal/cgv" }, "version": "1.2.1", "x-generated-at": "2026-05-28T20:23:27+00:00", "x-build-sha": "9847b86" }, "paths": { "/v1/admin/quotes": { "get": { "tags": [ "Admin – Quotes" ], "summary": "[Admin] Lister tous les devis (cross-tenant)", "operationId": "8033392757b23f9d99de91c8c4866b0d", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "sub_tenant_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "today", "week", "month", "quarter", "year" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "Liste paginée" }, "401": { "description": "Non authentifié" }, "403": { "description": "Réservé aux administrateurs" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/admin/quotes/{quote}": { "get": { "tags": [ "Admin – Quotes" ], "summary": "[Admin] Récupérer un devis (cross-tenant)", "operationId": "a37054edb188037252347a975719a488", "responses": { "200": { "description": "Devis trouvé" }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/admin/quotes/stats": { "get": { "tags": [ "Admin – Quotes" ], "summary": "[Admin] Statistiques globales des devis", "operationId": "57c16dd628e0dbfdb1ca86e041f95fdb", "responses": { "200": { "description": "Statistiques" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/admin/quotes/integrity-check": { "get": { "tags": [ "Admin – Quotes" ], "summary": "[Admin] Vérification d'intégrité des devis", "description": "Détecte les devis orphelins, les conversions incohérentes, et les statuts bloqués.", "operationId": "c360a63dc17a951b75662ba9ee3130cd", "responses": { "200": { "description": "Rapport d'intégrité" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/admin/quotes/audit-export": { "get": { "tags": [ "Admin – Quotes" ], "summary": "[Admin] Export CSV de l'audit des devis", "description": "Retourne un CSV de toutes les actions d'audit sur les devis dans la période donnée.", "operationId": "e52ff6729c0544b5447ecaca459abc19", "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Fichier CSV" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/admin/sub-tenants": { "get": { "tags": [ "Admin" ], "summary": "Liste arborescente des Tenants + leurs SubTenants (admin)", "description": "Retourne tous les Tenants de la plateforme (paginees) avec leurs SubTenants charges en eager. Reserve aux administrateurs Scell.io (`can:admin access`).", "operationId": "61a92b1760560c682e55c1bcdbbf09db", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "search", "in": "query", "description": "Recherche sur tenant + sub-tenants (nom, SIRET, email, external_id).", "schema": { "type": "string" } }, { "name": "onboarding_status", "in": "query", "description": "Filtre les tenants ayant au moins un sub-tenant avec ce statut.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Liste paginee", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legal_name": { "type": "string", "nullable": true }, "siret": { "type": "string", "nullable": true }, "billing_email": { "type": "string", "format": "email", "nullable": true }, "kyb_status": { "type": "string" }, "sub_tenants_count": { "type": "integer" }, "sub_tenants": { "type": "array", "items": { "$ref": "#/components/schemas/SubTenantResource" } } }, "type": "object" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Auth manquante." }, "403": { "description": "Permission admin requise." } }, "security": [ { "cookieAuth": [] } ] } }, "/admin/sub-tenants/{id}": { "get": { "tags": [ "Admin" ], "summary": "Detail cross-tenant d'un SubTenant (admin)", "description": "Retourne le sub-tenant + son tenant parent + ses statistiques (companies/invoices/credit_notes).", "operationId": "841a7b549d05538be5ba00701811c5c1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail.", "content": { "application/json": { "schema": { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/SubTenantResource" }, { "properties": { "tenant": { "type": "object" }, "stats": { "properties": { "companies_count": { "type": "integer" }, "invoices_count": { "type": "integer" }, "credit_notes_count": { "type": "integer" } }, "type": "object" } }, "type": "object" } ] } }, "type": "object" } } } }, "404": { "description": "Non trouve." } }, "security": [ { "cookieAuth": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Supprimer un SubTenant cross-tenant (admin)", "description": "Meme politique ISCA que `/v1/tenant/sub-tenants/{id}` mais sans scope tenant (admin global). Voir cette doc pour le detail des codes 422 (SUB_TENANT_HAS_COMPANIES + SUB_TENANT_HAS_FISCAL_ENTRIES).", "operationId": "686b63ee39822f9de0f22fc319e904ad", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cascade", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Supprime.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "companies_deleted": { "type": "integer" } }, "type": "object" } } } }, "422": { "description": "Refus (cf payload code)." }, "404": { "description": "Non trouve." } }, "security": [ { "cookieAuth": [] } ] } }, "/admin/sub-tenants/status-options": { "get": { "tags": [ "Admin" ], "summary": "Enumeration des onboarding_status (admin)", "description": "Liste les valeurs autorisees pour `SubTenant.onboarding_status`. Utile pour peupler des dropdowns.", "operationId": "313c7ca1389c69b84d3816341c01fde9", "responses": { "200": { "description": "Liste.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Etat de sante de l'API", "description": "Verifie que l'API repond correctement. Utilise par les load balancers et systemes de monitoring.", "operationId": "87f4c9ca64325201142de5963bf08c5c", "responses": { "200": { "description": "API operationnelle", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time" } }, "type": "object" } } } } }, "security": [], "servers": [ { "url": "http://localhost:8000/api/v1", "description": "Serveur de développement" }, { "url": "https://api.scell.io/api/v1", "description": "Serveur de production" } ] } }, "/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "Lister les clés API", "description": "Retourne la liste des clés API générées pour le compte.", "operationId": "b35df5b76a65bb259446547c3fd61f45", "parameters": [ { "name": "company_id", "in": "query", "description": "Filtrer par entreprise", "schema": { "type": "string", "format": "uuid" } }, { "name": "environment", "in": "query", "description": "sandbox ou production", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Liste des clés API", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "API Keys" ], "summary": "Créer une clé API", "description": "Génère une nouvelle clé API. ⚠️ La clé complète n'est retournée qu'une seule fois.", "operationId": "00e1dccc554b23180adddc619a8b3c0d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "environment" ], "properties": { "name": { "type": "string", "example": "Clé Production Server 1" }, "company_id": { "description": "Optionnel. Si non fourni, la clé ne sera liée à aucune entreprise.", "type": "string", "format": "uuid", "nullable": true }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "invoices", "signatures" ] }, "example": [ "invoices", "signatures" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Clé API créée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "properties": { "key": { "description": "Clé complète (affichée une seule fois)", "type": "string", "example": "sk_live_x8z..." } }, "type": "object" } ] }, "warning": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api-keys/{id}": { "get": { "tags": [ "API Keys" ], "summary": "Détails d'une clé", "description": "Récupère les informations d'une clé API.", "operationId": "d5cef035c257888bb7d2afa9a7b5728f", "parameters": [ { "name": "id", "in": "path", "description": "ID de la clé", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Détails de la clé", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } }, "type": "object" } } } }, "404": { "description": "Clé non trouvée", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "API Keys" ], "summary": "Révoquer une clé", "description": "Révoque une clé API. Elle ne sera plus utilisable immédiatement.", "operationId": "1b44437ad6aa6798d9edc858c6ee98bc", "parameters": [ { "name": "id", "in": "path", "description": "ID de la clé", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "reason", "in": "query", "description": "Raison de la révocation", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Clé révoquée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Clé non trouvée", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Inscription d'un nouvel utilisateur", "description": "Crée un nouveau compte utilisateur et ouvre une session sécurisée via cookie HttpOnly.\n\n### Prérequis SPA\n\nAvant d'appeler cet endpoint, récupérer le cookie CSRF :\n```bash\nGET /sanctum/csrf-cookie\n```\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/auth/register \\\n -H \"Content-Type: application/json\" \\\n -H \"X-XSRF-TOKEN: {csrf_token}\" \\\n --cookie-jar cookies.txt \\\n --cookie cookies.txt \\\n -d '{\n \"email\": \"user@example.com\",\n \"password\": \"secret123\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Dupont\",\n \"phone\": \"+33612345678\"\n }'\n```\n\n**JavaScript (SPA)**\n```javascript\n// 1. Récupérer le cookie CSRF\nawait fetch('https://api.scell.io/sanctum/csrf-cookie', { credentials: 'include' });\n\n// 2. S'inscrire\nconst response = await fetch('https://api.scell.io/api/v1/auth/register', {\n method: 'POST',\n credentials: 'include',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n email: 'user@example.com',\n password: 'secret123',\n first_name: 'Jean',\n last_name: 'Dupont',\n phone: '+33612345678'\n })\n});\nconst data = await response.json();\nconsole.log(data);\n```", "operationId": "08136088c4862c313b35d6518bab8d3a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password", "first_name", "last_name", "accept_dpa", "accept_terms" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" }, "first_name": { "type": "string", "example": "Jean" }, "last_name": { "type": "string", "example": "Dupont" }, "phone": { "type": "string", "example": "+33612345678" }, "accept_dpa": { "description": "Acceptation du DPA (RGPD Art. 28) — obligatoire", "type": "boolean", "example": true }, "accept_terms": { "description": "Acceptation des CGV, CGU et politique de confidentialité — obligatoire", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Inscription réussie — session ouverte via cookie HttpOnly", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Inscription réussie" }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Connexion utilisateur", "description": "Authentifie un utilisateur et ouvre une session sécurisée via cookie HttpOnly.\n\n### Prérequis SPA\n\nAvant d'appeler cet endpoint, récupérer le cookie CSRF :\n```bash\nGET /sanctum/csrf-cookie\n```\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/auth/login \\\n -H \"Content-Type: application/json\" \\\n -H \"X-XSRF-TOKEN: {csrf_token}\" \\\n --cookie-jar cookies.txt \\\n --cookie cookies.txt \\\n -d '{\n \"email\": \"user@example.com\",\n \"password\": \"secret123\"\n }'\n```\n\n**JavaScript (SPA)**\n```javascript\n// 1. Récupérer le cookie CSRF\nawait fetch('https://api.scell.io/sanctum/csrf-cookie', { credentials: 'include' });\n\n// 2. Se connecter\nconst response = await fetch('https://api.scell.io/api/v1/auth/login', {\n method: 'POST',\n credentials: 'include',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ email: 'user@example.com', password: 'secret123' })\n});\n```", "operationId": "99d66635c4992aeaa6aa44ff653d0563", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Connexion réussie — session ouverte via cookie HttpOnly", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Connexion réussie" }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" } } } }, "422": { "description": "Identifiants invalides", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/google": { "get": { "tags": [ "Auth" ], "summary": "Redirection Google OAuth", "description": "Redirige le navigateur vers la page de consentement Google OAuth.", "operationId": "4bed7d26e340ea5910b8a2a7556da5f5", "responses": { "302": { "description": "Redirection vers Google OAuth" } } } }, "/auth/google/callback": { "get": { "tags": [ "Auth" ], "summary": "Callback Google OAuth", "description": "Gère le retour de Google, crée ou connecte l'utilisateur, ouvre une session cookie et redirige vers le frontend.", "operationId": "135c7e29ea84003206abd244e8c924da", "responses": { "302": { "description": "Redirection vers le frontend (dashboard en cas de succès, login avec erreur sinon)" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Déconnexion", "description": "Invalide la session courante et supprime le cookie de session.", "operationId": "6abf3b64a4bc7838d56346f05a5153af", "responses": { "200": { "description": "Déconnexion réussie", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Déconnexion réussie" } }, "type": "object" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Profil utilisateur", "description": "Récupère les informations de l'utilisateur connecté et son solde.", "operationId": "7edae2cdbaafc10dff8c9c4198b320a2", "responses": { "200": { "description": "Informations utilisateur", "content": { "application/json": { "schema": { "properties": { "user": { "$ref": "#/components/schemas/User" }, "balance": { "oneOf": [ { "$ref": "#/components/schemas/Balance" } ], "nullable": true } }, "type": "object" } } } } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/auth/tenant/keys/publishable": { "post": { "tags": [ "Auth" ], "summary": "Generer une cle publishable (dashboard)", "description": "Genere ou renouvelle la cle publishable (pk_*) du tenant associe a l'utilisateur connecte via session. Reservee aux tenants partenaires.", "operationId": "0bf9622c23ace489adb5aab0aa87d35a", "responses": { "201": { "description": "Cle publishable generee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "publishable_key": { "type": "string" }, "prefix": { "type": "string" }, "environment": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Tenant non partenaire" }, "404": { "description": "Aucun tenant associe" } }, "security": [ { "cookieAuth": [] } ] } }, "/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Mot de passe oublié", "description": "Envoie un email avec un lien de réinitialisation.", "operationId": "fea89d2766defe4ad877001920e3f289", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email envoyé", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Un email de réinitialisation a été envoyé." } }, "type": "object" } } } } } } }, "/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Réinitialiser le mot de passe", "description": "Définit un nouveau mot de passe à l'aide du token reçu par email.", "operationId": "b8d03d5b689dcb65d3771f62d4f90a24", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "token", "email", "password", "password_confirmation" ], "properties": { "token": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "password_confirmation": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Mot de passe réinitialisé", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Mot de passe réinitialisé avec succès." } }, "type": "object" } } } } } } }, "/v1/auth/tenant/profile": { "put": { "tags": [ "Auth" ], "summary": "Mettre a jour le profil tenant", "description": "Met a jour les informations du tenant associe a l'utilisateur connecte.\n\n### Champs modifiables\n- `name` (obligatoire) : Nom commercial\n- `legal_name` : Raison sociale\n- `siret` : Numero SIRET (14 chiffres)\n- `vat_number` : Numero de TVA intracommunautaire\n- `billing_email` (obligatoire) : Email de facturation\n- `technical_email` : Email technique\n- `address` : Adresse (objet JSON avec line1/street, city, postal_code, country)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X PUT https://api.scell.io/api/v1/auth/tenant/profile \\\n -H \"Content-Type: application/json\" \\\n -H \"X-XSRF-TOKEN: {csrf_token}\" \\\n --cookie cookies.txt \\\n -d '{\n \"name\": \"Ma Societe SAS\",\n \"legal_name\": \"Ma Societe SAS\",\n \"siret\": \"12345678901234\",\n \"vat_number\": \"FR12345678901\",\n \"billing_email\": \"facturation@masociete.fr\",\n \"address\": {\n \"line1\": \"10 rue de la Paix\",\n \"city\": \"Paris\",\n \"postal_code\": \"75002\",\n \"country\": \"FR\"\n }\n }'\n```", "operationId": "2f496486c63fe42420911e5cf02c10b8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "billing_email" ], "properties": { "name": { "type": "string", "example": "Ma Societe SAS" }, "legal_name": { "type": "string", "example": "Ma Societe SAS", "nullable": true }, "siret": { "type": "string", "example": "12345678901234", "nullable": true }, "vat_number": { "type": "string", "example": "FR12345678901", "nullable": true }, "billing_email": { "type": "string", "format": "email", "example": "facturation@masociete.fr" }, "technical_email": { "type": "string", "format": "email", "nullable": true }, "address": { "properties": { "line1": { "type": "string", "example": "10 rue de la Paix" }, "street": { "type": "string", "example": "10 rue de la Paix" }, "city": { "type": "string", "example": "Paris" }, "postal_code": { "type": "string", "example": "75002" }, "country": { "type": "string", "example": "FR" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Profil tenant mis a jour", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profil mis a jour avec succes" }, "tenant": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Aucun tenant associe" }, "422": { "description": "Erreur de validation" } }, "security": [ { "cookieAuth": [] } ] } }, "/auth/me/api-key/rotate": { "post": { "tags": [ "Auth" ], "summary": "Régénérer sa clé API (Sanctum + re-auth password)", "description": "Endpoint BFF (Backend For Frontend) : génère une nouvelle clé API pour le tenant du user authentifié Sanctum. Re-auth password obligatoire (defense-in-depth contre cookie volé). La nouvelle clé est retournée UNE SEULE FOIS — stockez-la immédiatement dans un secret manager. L'ancienne clé est invalidée instantanément.", "operationId": "20c6fc309ca924b1143598c6bcd59573", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "password" ], "properties": { "password": { "description": "Mot de passe utilisateur (re-auth)", "type": "string", "format": "password" }, "environment": { "description": "Environnement de la nouvelle clé (défaut : environnement courant du tenant)", "type": "string", "enum": [ "sandbox", "production" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Clé régénérée avec succès", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "properties": { "api_key": { "type": "string", "example": "sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }, "prefix": { "type": "string", "example": "sk_live_" }, "last4": { "type": "string", "example": "XYZW" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } }, "type": "object" }, "warning": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Non authentifié (cookie Sanctum manquant)" }, "422": { "description": "Mot de passe invalide ou validation échouée" }, "404": { "description": "Aucun tenant associé au compte" }, "429": { "description": "Trop de tentatives (throttle auth-password : 3/15min)" } }, "security": [ { "cookieAuth": [] } ] } }, "/companies": { "get": { "tags": [ "Companies" ], "summary": "Lister les entreprises", "description": "Retourne la liste de toutes les entreprises associées à l'utilisateur connecté.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET https://api.scell.io/api/v1/companies \\\n -H \"Authorization: Bearer \" \\\n -H \"Accept: application/json\"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/companies', [\n 'headers' => ['Authorization' => 'Bearer ']\n]);\n```", "operationId": "08ed2ae55723c6a9506353eab8145498", "responses": { "200": { "description": "Liste des entreprises", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Companies" ], "summary": "Créer une entreprise", "description": "Crée une nouvelle entreprise.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/companies \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Ma Société\",\n \"siret\": \"12345678901234\",\n \"address_line1\": \"1 Rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"country\": \"FR\"\n }'\n```", "operationId": "d80b2e6cabac7670e3a925121bfb870f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "siret", "address_line1", "postal_code", "city" ], "properties": { "name": { "type": "string" }, "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "vat_number": { "type": "string", "nullable": true }, "legal_form": { "type": "string", "nullable": true }, "address_line1": { "type": "string" }, "address_line2": { "type": "string", "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "example": "FR" }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "website": { "type": "string", "format": "uri", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Entreprise créée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Entreprise créée avec succès" }, "data": { "$ref": "#/components/schemas/Company" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/companies/{id}": { "get": { "tags": [ "Companies" ], "summary": "Voir une entreprise", "description": "Récupère les détails d'une entreprise spécifique.", "operationId": "04de43b30ed21f7c223d9faba2342427", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'entreprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Détails de l'entreprise", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Company" } }, "type": "object" } } } }, "404": { "description": "Entreprise non trouvée", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Companies" ], "summary": "Mettre à jour une entreprise", "description": "Modifie les informations d'une entreprise existante.", "operationId": "64045036ab84b92fcff8aa9d82256f68", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'entreprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "vat_number": { "type": "string", "nullable": true }, "legal_form": { "type": "string", "nullable": true }, "address_line1": { "type": "string" }, "address_line2": { "type": "string", "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "example": "FR" }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "website": { "type": "string", "format": "uri", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Entreprise mise à jour", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Entreprise mise à jour" }, "data": { "$ref": "#/components/schemas/Company" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Companies" ], "summary": "Supprimer une entreprise", "description": "Supprime définitivement une entreprise.", "operationId": "988db2c604e42e9fd332d321f1e84f47", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'entreprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entreprise supprimée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Entreprise supprimée" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/companies/{id}/kyc": { "post": { "tags": [ "Companies" ], "summary": "Initier KYC", "description": "Démarre le processus de vérification KYC pour une entreprise.", "operationId": "a8ba01f2cb5e1db2eef25fcd3f17c594", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'entreprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "KYC initié", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Vérification KYC initiée" }, "kyc_reference": { "type": "string" }, "redirect_url": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Déjà vérifié", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/companies/{id}/kyc/status": { "get": { "tags": [ "Companies" ], "summary": "Statut KYC", "description": "Vérifie l'état actuel du processus KYC.", "operationId": "21a69abd8b7301f962931e108fd0973e", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'entreprise", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Statut KYC", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "pending_kyc" }, "kyc_reference": { "type": "string", "nullable": true }, "kyc_completed_at": { "type": "string", "format": "date-time", "nullable": true }, "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices": { "get": { "tags": [ "Invoices" ], "summary": "Lister les factures", "description": "Retourne la liste des factures avec filtrage optionnel.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/invoices?direction=outgoing&status=validated\" \\\n -H \"Authorization: Bearer \"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/invoices', [\n 'headers' => ['Authorization' => 'Bearer '],\n 'query' => [\n 'direction' => 'outgoing',\n 'status' => 'validated'\n ]\n]);\n```", "operationId": "f8d7532e5c37f7bb14d3570cb83e7a3f", "parameters": [ { "name": "direction", "in": "query", "description": "outgoing (vente) ou incoming (achat)", "schema": { "type": "string", "enum": [ "outgoing", "incoming" ] } }, { "name": "status", "in": "query", "description": "Filtrer par statut", "schema": { "type": "string" } }, { "name": "environment", "in": "query", "description": "sandbox ou production", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Date de début (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Nombre d'éléments par page", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Liste des factures", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Invoices" ], "summary": "Créer une facture", "description": "Crée une nouvelle facture. En production, cette action débite un crédit.\n\n### Identification de l'acheteur\n\nDeux stratégies mutuellement exclusives :\n\n1. **`buyer_id`** — UUID d'une entrée du registre des acheteurs (scope tenant/sub_tenant). L'API snapshote l'acheteur sur la facture (anti-IDOR : 404 si hors scope).\n2. **Champs `buyer_*` à plat** — l'API upsert un acheteur dans le registre (par SIRET en B2B, par email en B2C / fallback) puis snapshote.\n\n### SIRET acheteur — non obligatoire dans tous les cas\n\n`buyer_siret` est requis **uniquement** pour une entreprise française (`buyer_is_individual` absent/false ET `buyer_country` = `FR`). Pour un particulier (`buyer_is_individual: true`) ou une entreprise hors France (`buyer_vat_number` ou `buyer_legal_id` alors requis), il est optionnel.\n\n### Acompte / solde sans devis\n\nUtilisez `invoice_type` (`deposit` / `balance`) + `deposit_group_id` / `deposit_total_ht` / `deposit_reference_text` pour émettre directement un acompte ou un solde. Pour partir d'un devis, préférez les endpoints `/quotes/{id}/convert-to-deposit` ou `/convert-to-balance`.\n\n### Exemples\n\n**cURL (B2B FR)**\n```bash\ncurl -X POST https://api.scell.io/api/v1/invoices \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"direction\": \"outgoing\",\n \"output_format\": \"facturx\",\n \"issue_date\": \"2026-05-28\",\n \"total_ht\": 100.00,\n \"total_tax\": 20.00,\n \"total_ttc\": 120.00,\n \"seller_siret\": \"12345678901234\",\n \"seller_name\": \"Ma Societe SAS\",\n \"seller_address\": { \"line1\": \"1 rue Test\", \"postal_code\": \"75001\", \"city\": \"Paris\", \"country\": \"FR\" },\n \"buyer_name\": \"ACME SARL\",\n \"buyer_siret\": \"98765432109876\",\n \"buyer_address\": { \"line1\": \"10 rue de la Paix\", \"postal_code\": \"75002\", \"city\": \"Paris\", \"country\": \"FR\" },\n \"lines\": [\n { \"description\": \"Prestation de service\", \"quantity\": 1, \"unit_price\": 100.00, \"tax_rate\": 20.00, \"total_ht\": 100.00, \"total_tax\": 20.00, \"total_ttc\": 120.00 }\n ]\n }'\n```\n\n**cURL (B2C particulier — pas de SIRET)**\n```bash\ncurl -X POST https://api.scell.io/api/v1/invoices \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"direction\": \"outgoing\", \"output_format\": \"facturx\", \"issue_date\": \"2026-05-28\",\n \"total_ht\": 100.00, \"total_tax\": 20.00, \"total_ttc\": 120.00,\n \"seller_siret\": \"12345678901234\", \"seller_name\": \"Ma Societe SAS\",\n \"seller_address\": { \"line1\": \"1 rue Test\", \"postal_code\": \"75001\", \"city\": \"Paris\", \"country\": \"FR\" },\n \"buyer_is_individual\": true,\n \"buyer_name\": \"Jean Dupont\",\n \"buyer_address\": { \"line1\": \"5 av des Fleurs\", \"postal_code\": \"69001\", \"city\": \"Lyon\", \"country\": \"FR\" },\n \"lines\": [ { \"description\": \"Prestation\", \"quantity\": 1, \"unit_price\": 100.00, \"tax_rate\": 20.00, \"total_ht\": 100.00, \"total_tax\": 20.00, \"total_ttc\": 120.00 } ]\n }'\n```", "operationId": "b22372f77704d157104e4a6061b135d0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "direction", "output_format", "issue_date", "total_ht", "total_tax", "total_ttc", "seller_siret", "seller_name", "seller_address", "buyer_name", "buyer_address", "lines" ], "properties": { "external_id": { "description": "Référence métier externe.", "type": "string", "maxLength": 100 }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "output_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "description": "Doit être >= issue_date.", "type": "string", "format": "date" }, "currency": { "type": "string", "maxLength": 3, "minLength": 3, "example": "EUR" }, "total_ht": { "type": "number" }, "total_tax": { "type": "number" }, "total_ttc": { "type": "number" }, "seller_siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "seller_name": { "type": "string", "maxLength": 255 }, "seller_address": { "$ref": "#/components/schemas/BuyerAddress" }, "buyer_id": { "description": "UUID du registre acheteurs (alternative aux champs buyer_* à plat). Anti-IDOR : 404 si hors scope.", "type": "string", "format": "uuid", "nullable": true }, "buyer_name": { "type": "string", "maxLength": 255 }, "buyer_siret": { "description": "Requis seulement pour une entreprise FR (buyer_is_individual=false + buyer_country=FR). Optionnel sinon.", "type": "string", "maxLength": 14, "minLength": 14, "nullable": true }, "buyer_country": { "description": "Code pays acheteur ISO 3166-1 alpha-2 (défaut: buyer_address.country ou FR).", "type": "string", "maxLength": 2, "minLength": 2, "nullable": true }, "buyer_vat_number": { "description": "Requis pour une entreprise hors FR si buyer_legal_id absent.", "type": "string", "maxLength": 20, "nullable": true }, "buyer_legal_id": { "description": "Identifiant légal alternatif (entreprise hors FR).", "type": "string", "maxLength": 50, "nullable": true }, "buyer_legal_id_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "buyer_is_individual": { "description": "true = particulier B2C (siret/vat optionnels, mentions L441-10 et BT-46/47/48 omises).", "type": "boolean", "nullable": true }, "buyer_address": { "$ref": "#/components/schemas/BuyerAddress" }, "buyer_shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true, "description": "Adresse de livraison (BG-13). Si absente ou identique à buyer_address, BG-13 est omis (ship=bill)." }, "invoice_template_id": { "description": "Modèle de facture à appliquer (doit exister).", "type": "string", "format": "uuid", "nullable": true }, "sub_tenant_id": { "description": "Émettre au nom d'un sous-locataire du tenant courant (anti-IDOR : 404 si hors scope).", "type": "string", "format": "uuid", "nullable": true }, "archive_enabled": { "description": "Activer l'archivage légal.", "type": "boolean", "nullable": true }, "invoice_type": { "description": "Type de facture. deposit = acompte (TVA exigible), balance = solde.", "type": "string", "enum": [ "standard", "deposit", "balance" ], "nullable": true }, "deposit_group_id": { "description": "Groupe acompte/solde reliant les factures partielles.", "type": "string", "format": "uuid", "nullable": true }, "deposit_total_ht": { "description": "Montant HT total de référence pour le groupe acompte/solde.", "type": "number", "minimum": 0.01, "nullable": true }, "deposit_reference_text": { "description": "Mention référençant les acomptes déjà émis.", "type": "string", "maxLength": 1000, "nullable": true }, "parent_quote_id": { "description": "Devis source (factures standard uniquement ; pour acompte/solde utiliser les endpoints de conversion de devis).", "type": "string", "format": "uuid", "nullable": true }, "lines": { "type": "array", "items": { "required": [ "description", "quantity", "unit_price", "tax_rate", "total_ht", "total_tax", "total_ttc" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "tax_rate": { "type": "number", "maximum": 100, "minimum": 0 }, "total_ht": { "description": "Calculé automatiquement si omis.", "type": "number" }, "total_tax": { "description": "Calculé automatiquement si omis.", "type": "number" }, "total_ttc": { "description": "Calculé automatiquement si omis.", "type": "number" } }, "type": "object" }, "minItems": 1 } }, "type": "object" }, "example": { "direction": "outgoing", "output_format": "facturx", "issue_date": "2026-05-28", "currency": "EUR", "total_ht": 100, "total_tax": 20, "total_ttc": 120, "seller_siret": "12345678901234", "seller_name": "Ma Societe SAS", "seller_address": { "line1": "1 rue Test", "postal_code": "75001", "city": "Paris", "country": "FR" }, "buyer_name": "ACME SARL", "buyer_siret": "98765432109876", "buyer_address": { "line1": "10 rue de la Paix", "postal_code": "75002", "city": "Paris", "country": "FR" }, "lines": [ { "description": "Prestation de service", "quantity": 1, "unit_price": 100, "tax_rate": 20, "total_ht": 100, "total_tax": 20, "total_ttc": 120 } ] } } } }, "responses": { "201": { "description": "Facture créée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture créée avec succès" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" }, "example": { "message": "Facture créée avec succès", "data": { "id": "019df46f-1234-7000-aaaa-000000000001", "invoice_number": "DRAFT-2026-0001", "direction": "outgoing", "output_format": "facturx", "status": "draft", "seller_name": "Ma Societe SAS", "seller_siret": "12345678901234", "buyer_name": "ACME SARL", "buyer_siret": "98765432109876", "total_ht": 100, "total_tva": 20, "total_ttc": 120, "currency": "EUR", "environment": "production" } } } } }, "401": { "description": "Tenant non résolu" }, "403": { "description": "KYB/KYC requis ou sub-tenant non prêt (production)" }, "404": { "description": "buyer_id / sub_tenant_id / parent_quote_id introuvable ou hors scope" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Voir une facture", "description": "Récupère les détails complets d'une facture.", "operationId": "93cb2b87637ce1c8b34f4d784d8b8820", "parameters": [ { "name": "id", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Détails de la facture", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvée", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Invoices" ], "summary": "Supprimer un brouillon", "description": "Supprime une facture en brouillon. Compliance fiscale ISCA : seules les factures avec status `draft` peuvent etre supprimees.", "operationId": "ad79fd4aee964cd008bc746e724544f6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Brouillon supprime" }, "403": { "description": "Suppression refusee : facture non-draft" }, "404": { "description": "Facture introuvable" } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices/{id}/download/{type}": { "get": { "tags": [ "Invoices" ], "summary": "Télécharger une facture", "description": "Génère un lien de téléchargement temporaire pour le fichier de la facture.\n\n### Types de fichiers\n* `original` : Fichier original uploadé ou généré\n* `converted` : Version convertie (ex: Factur-X)\n* `pdf` : Version PDF visible", "operationId": "8cfb9e3038b0ee3503fb246d97cae4e7", "parameters": [ { "name": "id", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "path", "description": "Type de fichier", "required": true, "schema": { "type": "string", "enum": [ "original", "converted", "pdf" ] } } ], "responses": { "200": { "description": "Lien de téléchargement généré", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "example": "https://storage.scell.io/..." }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Fichier non trouvé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices/{id}/audit-trail": { "get": { "tags": [ "Invoices" ], "summary": "Piste d'audit", "description": "Récupère l'historique complet des actions sur une facture (Piste d'Audit Fiable).", "operationId": "5b0ff540f799bc374adb77a9a8bc3f49", "parameters": [ { "name": "id", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Piste d'audit", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "action": { "type": "string" }, "details": { "type": "string" }, "actor_ip": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "integrity_valid": { "description": "True si la chaîne de hash est valide", "type": "boolean" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices/convert": { "post": { "tags": [ "Invoices" ], "summary": "Convertir une facture", "description": "Demande la conversion d'une facture vers un autre format (ex: UBL vers Factur-X). Non disponible en Sandbox.", "operationId": "8da5d6d082898664d6ba1edc18ed2484", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_id", "target_format" ], "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "target_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Conversion initiée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "invoice_id": { "type": "string" }, "target_format": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices/{id}/submit": { "post": { "tags": [ "Invoices" ], "summary": "Soumettre une facture", "description": "Soumet une facture au Portail Public de Facturation (PPF) via SuperPDP.\n\n### Statuts autorises\nSeules les factures avec le statut `draft` ou `validated` peuvent etre soumises.\n\n### Statuts de la facture\n- `draft` : Brouillon (peut etre soumise)\n- `validated` : Validee (peut etre soumise)\n- `transmitted` : En cours de transmission\n- `completed` : Acceptee par le PPF\n- `rejected` : Rejetee par le PPF\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/submit\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```\n\n**PHP**\n```php\n$response = $client->post('https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/submit', [\n 'headers' => ['X-API-Key' => 'sk_live_xxxxxx']\n]);\n```", "operationId": "183bc7847ce06663a0a3d1c819dadde2", "parameters": [ { "name": "id", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Facture soumise avec succes", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture soumise avec succes" }, "invoice_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "transmitted" }, "superpdp_id": { "type": "string", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Facture non soumissible", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Cette facture ne peut pas etre soumise" }, "current_status": { "type": "string", "example": "completed" } }, "type": "object" } } } }, "500": { "description": "Erreur lors de la soumission", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "details": { "type": "string", "nullable": true } }, "type": "object" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/public/quotes/{token}": { "get": { "tags": [ "Quotes Public" ], "summary": "Afficher le devis (lien signé public, REST)", "description": "Forme REST moderne utilisée par le viewer SPA. `token` = public_token (UUID 36 chars) du devis. La signature HMAC (`signature` + `expires`) est portée par l'URL signée Laravel. Pas d'authentification. Marque le devis VIEWED si actuellement SENT.", "operationId": "a967bc160f96fec5d1682321d8ddab17", "parameters": [ { "name": "token", "in": "path", "description": "public_token du devis (UUID)", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "description": "Signature HMAC de l'URL", "required": true, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Données publiques du devis" }, "403": { "description": "Lien invalide ou expiré" }, "404": { "description": "Devis introuvable" } } } }, "/v1/public/quotes/view": { "get": { "tags": [ "Quotes Public" ], "summary": "Afficher le devis (lien signé public, query legacy)", "description": "Forme query-string legacy (retrocompat). Requiert `token` en query. Identique à la forme REST.", "operationId": "48580cd74174542476bcf06f18bd24b6", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Données publiques du devis" }, "403": { "description": "Lien invalide ou expiré" }, "404": { "description": "Devis introuvable" } } } }, "/v1/public/quotes/{token}/accept": { "post": { "tags": [ "Quotes Public" ], "summary": "Accepter le devis (lien signé public, REST)", "description": "Le buyer soumet sa signature électronique (canvas SVG + nom tapé + consentement). Requiert une URL signée. Forme query legacy disponible sur `POST /v1/public/quotes/accept`.", "operationId": "573324945ae9c7c58d4bf6ca0464f105", "parameters": [ { "name": "token", "in": "path", "description": "public_token du devis (UUID)", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "canvas_svg_b64", "typed_name", "consent_accepted" ], "properties": { "canvas_svg_b64": { "description": "Signature manuscrite (SVG encodé en base64).", "type": "string", "maxLength": 300000 }, "typed_name": { "description": "Nom complet tapé par le signataire.", "type": "string", "maxLength": 255, "minLength": 2 }, "signed_by_email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "consent_accepted": { "description": "Doit être true (acceptation explicite eIDAS).", "type": "boolean" } }, "type": "object" }, "example": { "canvas_svg_b64": "PHN2Zz4uLi48L3N2Zz4=", "typed_name": "Jean Dupont", "signed_by_email": "jean.dupont@acme.fr", "consent_accepted": true } } } }, "responses": { "200": { "description": "Devis accepté, signature enregistrée" }, "403": { "description": "Lien invalide / expiré / devis non signable" }, "422": { "description": "Erreur de validation de la signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/public/quotes/{token}/refuse": { "post": { "tags": [ "Quotes Public" ], "summary": "Refuser le devis (lien signé public, REST)", "description": "Le buyer refuse le devis avec un motif obligatoire. Forme query legacy disponible sur `POST /v1/public/quotes/refuse`.", "operationId": "8a97fa8c45cf6ff86c0974ee2f9b6bea", "parameters": [ { "name": "token", "in": "path", "description": "public_token du devis (UUID)", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Motif du refus.", "type": "string", "maxLength": 1000, "minLength": 5 } }, "type": "object" }, "example": { "reason": "Tarif au-dessus de notre budget." } } } }, "responses": { "200": { "description": "Devis refusé" }, "403": { "description": "Lien invalide / devis non refusable" }, "422": { "description": "Raison manquante", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/public/quotes/{token}/pdf": { "get": { "tags": [ "Quotes Public" ], "summary": "Télécharger le PDF du devis (lien signé public, REST)", "description": "Forme query legacy disponible sur `GET /v1/public/quotes/pdf`.", "operationId": "7090508021db3b9058b39d064878865f", "parameters": [ { "name": "token", "in": "path", "description": "public_token du devis (UUID)", "required": true, "schema": { "type": "string" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "expires", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fichier PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Lien invalide ou expiré" }, "404": { "description": "Devis introuvable" } } } }, "/signatures/convert-document": { "post": { "tags": [ "Signatures" ], "summary": "Convertir un .docx en PDF", "description": "Convertit un document Word (.docx) en PDF fidèle (moteur LibreOffice). Utilisé par le wizard de signature avant l'envoi. Limite 20 Mo.", "operationId": "21f54fc992d3f70b54c608101edbcefc", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "document" ], "properties": { "document": { "description": "Fichier .docx (max 20 Mo)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "PDF généré", "content": { "application/pdf": [] } }, "422": { "description": "Document invalide ou échec de conversion" } }, "security": [ { "bearerAuth": [] }, { "apiKey": [] } ] } }, "/signatures": { "get": { "tags": [ "Signatures" ], "summary": "Lister les signatures", "description": "Retourne la liste des demandes de signature avec filtrage optionnel.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/signatures?status=pending\" \\\n -H \"Authorization: Bearer \"\n```", "operationId": "fbcd44bbdf3504f30f16c3682b4ec670", "parameters": [ { "name": "status", "in": "query", "description": "Filtrer par statut", "schema": { "type": "string", "enum": [ "pending", "completed", "refused", "expired" ] } }, { "name": "environment", "in": "query", "description": "sandbox ou production", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "Filtrer sur une company precise du tenant", "schema": { "type": "string", "format": "uuid" } }, { "name": "sub_tenant_id", "in": "query", "description": "Restreindre aux signatures d'un sub-tenant du tenant courant (anti-IDOR)", "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "description": "Nombre d'éléments par page (max 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste des signatures", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signature" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Signatures" ], "summary": "Créer une demande de signature", "description": "Crée une demande de signature électronique simple eIDAS **EU-SES** (le seul niveau exposé par Scell.io). En production, cette action débite le solde tenant.\n\n### Page wrapper sign.scell.io\n\nLe `signing_url` retourné dans `signers[]` ne pointe **plus** directement vers le service de signature. Chaque signataire reçoit une URL HMAC-signée de la forme :\n\n```\nhttps://sign.scell.io/sign/{signature_id}/{signer_id}?expires=...&signature=HMAC\n```\n\nCette page Scell.io embed le page de signature upstream dans une iframe, avec branding Scell.io par défaut. Le lien expire avec la signature (default +30 jours). L'URL upstream brute est accessible sur `signers[].upstream_signing_url` pour debug.\n\n### Branding par défaut\n\nSi vous omettez `ui_config`, le backend applique automatiquement la palette Scell.io (logo + 16 couleurs). Si vous fournissez un `ui_config` partiel, **seuls les champs absents** sont remplis avec les défauts — vos overrides sont préservés. `iframe_ancestors` est automatiquement étendu avec `https://sign.scell.io` et `https://scell.io` (cap 20, dédupliqué).\n\n### Exemples\n\n**cURL minimal (branding Scell par défaut)**\n```bash\ncurl -X POST https://api.scell.io/api/v1/signatures \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"title\": \"Contrat de prestation\",\n \"document_name\": \"contrat.pdf\",\n \"document\": \"\",\n \"signers\": [\n {\n \"first_name\": \"Jean\",\n \"last_name\": \"Dupont\",\n \"email\": \"jean.dupont@example.com\",\n \"auth_method\": \"email\",\n \"message\": \"Bonjour Jean, votre contrat. Code OTP: {OTP}\"\n }\n ],\n \"signature_positions\": [\n { \"page\": 1, \"x\": 70, \"y\": 80, \"unit\": \"percent\" }\n ]\n }'\n```\n\n**cURL avec override partiel UI + signature_options**\n```bash\ncurl -X POST https://api.scell.io/api/v1/signatures \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"title\": \"Contrat\",\n \"document_name\": \"contrat.pdf\",\n \"document\": \"\",\n \"signers\": [\n { \"first_name\": \"Marie\", \"last_name\": \"Dupont\", \"phone\": \"+33612345678\", \"auth_method\": \"sms\" }\n ],\n \"ui_config\": {\n \"sign_button_background_color\": \"#10B981\",\n \"hide_download_validated\": true,\n \"iframe_ancestors\": [\"https://app.acme.com\"]\n },\n \"signature_options\": {\n \"signature_mode\": \"both\",\n \"signer_must_read\": true,\n \"timezone\": \"Europe/Paris\"\n },\n \"redirect_complete_url\": \"https://app.acme.com/contracts/done\",\n \"archive_enabled\": true\n }'\n```", "operationId": "c7d984fb7c5db6b09629b9fe25946d3a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "document", "document_name", "signers" ], "properties": { "external_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "document": { "description": "Contenu du fichier en Base64", "type": "string" }, "document_name": { "type": "string" }, "signers": { "type": "array", "items": { "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "email", "sms", "both" ] }, "order": { "type": "integer" }, "message": { "description": "Message personnalisé pour le signataire (max 500 caractères)", "type": "string" } }, "type": "object" } }, "signature_positions": { "type": "array", "items": { "properties": { "page": { "description": "Numéro de page (1-indexé)", "type": "integer" }, "unit": { "description": "Unité des coordonnées (défaut: percent)", "type": "string", "enum": [ "percent", "pixel" ] }, "x": { "description": "Position X. Unité définie par `unit`.", "type": "number" }, "y": { "description": "Position Y. Unité définie par `unit`.", "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "page_width_px": { "description": "Largeur de la page en pixels @72dpi. Si absent, détection auto via parser PDF (fallback A4 595px).", "type": "integer" }, "page_height_px": { "description": "Hauteur de la page en pixels @72dpi. Si absent, détection auto via parser PDF (fallback A4 842px).", "type": "integer" }, "document_index": { "description": "Index du document ciblé (0 = document principal, 1+ = pièces jointes dans l'ordre d'envoi). Défaut: 0.", "type": "integer", "maximum": 10, "minimum": 0, "example": 0 }, "signer_index": { "description": "Index 0-based du signataire (référence sa position dans le tableau `signers`). OpenAPI EU-SES autorise PLUSIEURS positions de signature par signataire : répéter une entrée avec le même `signer_index` pour placer N champs de signature pour ce signataire. Si omis sur toutes les positions, comportement legacy positionnel (1 position par signataire dans l'ordre).", "type": "integer", "maximum": 9, "minimum": 0, "example": 0 } }, "type": "object" } }, "ui_config": { "description": "Personnalisation white-label (21 champs spec EU-SES eIDAS v1.0.17)", "properties": { "sidebar_logo": { "type": "string", "format": "uri" }, "sidebar_background_color": { "type": "string" }, "sidebar_title_color": { "type": "string" }, "sidebar_text_color": { "type": "string" }, "header_background_color": { "type": "string" }, "header_title_color": { "type": "string" }, "header_subtitle_color": { "type": "string" }, "footer_background_color": { "type": "string" }, "button_text_color": { "type": "string" }, "button_text_color_hover": { "type": "string" }, "button_background_color": { "type": "string" }, "button_background_color_hover": { "type": "string" }, "sign_button_text_color": { "type": "string" }, "sign_button_text_color_hover": { "type": "string" }, "sign_button_background_color": { "type": "string" }, "sign_button_background_color_hover": { "type": "string" }, "hide_sidebar": { "type": "boolean" }, "hide_header": { "type": "boolean" }, "hide_download_validated": { "type": "boolean" }, "hide_download_signed": { "type": "boolean" }, "iframe_ancestors": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "type": "object" }, "signature_options": { "description": "Options de comportement (non-UI) de la signature", "properties": { "signature_mode": { "type": "string", "enum": [ "typed", "drawn", "both" ] }, "signer_must_read": { "type": "boolean" }, "user_editable_data": { "properties": { "name": { "type": "boolean" }, "mobile": { "type": "boolean" }, "email": { "type": "boolean" } }, "type": "object" }, "timezone": { "description": "Identifiant IANA (ex: Europe/Paris)", "type": "string" } }, "type": "object" }, "initials_block": { "description": "Bloc paraphe (initiales) grave automatiquement sur le PDF.\n\n**Deux formats acceptes :**\n\n1. **Nouveau (recommande, depuis v2.15.0)** — `positions[]` avec une entree par page.\n Chaque entree peut surcharger x, y, font_size, color, bold.\n\n2. **Legacy (retrocompat)** — `position` (UNE position commune) + `pages`\n (`'all'`, `'except_last'` ou tableau d'entiers).\n\nSi les deux formats sont fournis, `positions[]` previaut.", "properties": { "enabled": { "description": "Active ou desactive le bloc paraphe.", "type": "boolean" }, "mode": { "description": "'auto' = depuis nom du 1er signataire ; 'custom' = utilise custom_text.", "type": "string", "enum": [ "auto", "custom" ] }, "source": { "type": "string", "enum": [ "signer_name", "custom" ] }, "custom_text": { "description": "Texte personnalise (max 8 chars). Utilise quand source=custom.", "type": "string", "maxLength": 8 }, "font_size": { "description": "Defaut applique a toutes les positions sans override.", "type": "number", "maximum": 20, "minimum": 6 }, "color": { "description": "Defaut applique a toutes les positions sans override.", "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "bold": { "description": "Defaut applique a toutes les positions sans override.", "type": "boolean" }, "positions": { "description": "Liste de positions, une entree par page. Recommande pour multi-pages. Si fourni, prevaut sur `position` + `pages`.", "type": "array", "items": { "required": [ "page", "x", "y" ], "properties": { "page": { "description": "Numero de page (1-indexed).", "type": "integer", "maximum": 500, "minimum": 1 }, "x": { "type": "number", "maximum": 5000, "minimum": 0 }, "y": { "type": "number", "maximum": 5000, "minimum": 0 }, "unit": { "description": "Defaut: 'percent' (0-100 relatif a la page).", "type": "string", "enum": [ "percent", "pixel" ] }, "page_width_px": { "description": "Utilise quand unit=pixel pour la conversion.", "type": "integer", "maximum": 5000, "minimum": 1 }, "page_height_px": { "type": "integer", "maximum": 5000, "minimum": 1 }, "font_size": { "description": "Override per-page.", "type": "number", "maximum": 20, "minimum": 6 }, "color": { "description": "Override per-page.", "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "bold": { "description": "Override per-page.", "type": "boolean" } }, "type": "object" }, "maxItems": 500 }, "pages": { "description": "Legacy. 'all' | 'except_last' | tableau d'entiers (1-indexed). Ignore si `positions` est fourni.", "oneOf": [ { "type": "string", "enum": [ "all", "except_last" ] }, { "type": "array", "items": { "type": "integer", "minimum": 1 } } ] }, "position": { "description": "Legacy. Position commune appliquee aux pages choisies par `pages`. Ignore si `positions` est fourni.", "properties": { "x": { "type": "number", "maximum": 5000, "minimum": 0 }, "y": { "type": "number", "maximum": 5000, "minimum": 0 }, "unit": { "type": "string", "enum": [ "percent", "pixel" ] }, "page_width_px": { "type": "integer", "maximum": 5000, "minimum": 1 }, "page_height_px": { "type": "integer", "maximum": 5000, "minimum": 1 } }, "type": "object" } }, "type": "object" }, "mentions": { "description": "Mentions juridiques gravees sur le PDF (ex: \"Lu et approuve\"). L'infrastructure de signature EU-SES ne supportant pas nativement les mentions manuscrites, Scell les grave en pre-process.", "type": "array", "items": { "required": [ "label", "position" ], "properties": { "label": { "description": "Libelle de la mention", "type": "string", "maxLength": 255 }, "required": { "description": "La mention doit-elle etre recopiee ou simplement affichee", "type": "boolean" }, "signer_index": { "description": "Index du signataire concerne (0-based)", "type": "integer", "maximum": 9, "minimum": 0 }, "position": { "required": [ "page", "x", "y" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" }, "unit": { "type": "string", "enum": [ "percent", "pixel" ] } }, "type": "object" }, "fallback_text": { "description": "Texte effectivement grave (defaut: meme que label)", "type": "string", "maxLength": 500 }, "font_size": { "type": "number", "maximum": 20, "minimum": 6 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "type": "object" }, "maxItems": 20 }, "date_block": { "description": "Bloc date du jour pre-rempli, grave par Scell avant envoi.", "properties": { "enabled": { "type": "boolean" }, "format": { "description": "Format PHP date() (ex: d/m/Y)", "type": "string", "maxLength": 50 }, "timezone": { "description": "Identifiant IANA (defaut: Europe/Paris)", "type": "string" }, "position": { "properties": { "page": { "description": "Numero de page (1-indexed) ou 'last'", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "enum": [ "last" ] } ] }, "x": { "type": "number" }, "y": { "type": "number" }, "unit": { "type": "string", "enum": [ "percent", "pixel" ] } }, "type": "object" }, "font_size": { "type": "number", "maximum": 20, "minimum": 6 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "type": "object" }, "redirect_complete_url": { "type": "string", "format": "uri" }, "redirect_cancel_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "archive_enabled": { "type": "boolean" } }, "type": "object" }, "example": { "title": "Contrat de prestation", "document_name": "contrat.pdf", "document": "", "signers": [ { "first_name": "Jean", "last_name": "Dupont", "email": "jean.dupont@example.com", "auth_method": "email", "message": "Bonjour Jean, votre contrat. Code OTP: {OTP}" } ], "signature_positions": [ { "page": 1, "x": 70, "y": 80, "unit": "percent" } ], "archive_enabled": true } } } }, "responses": { "201": { "description": "Signature créée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Signature" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/signatures/{id}": { "get": { "tags": [ "Signatures" ], "summary": "Voir une signature", "description": "Récupère les détails d'une demande de signature.", "operationId": "e104a626ac65ba66ace48f291fd9ba18", "parameters": [ { "name": "id", "in": "path", "description": "ID de la signature", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Détails de la signature", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Signature" } }, "type": "object" } } } }, "404": { "description": "Signature non trouvée", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/signatures/{id}/download/{type}": { "get": { "tags": [ "Signatures" ], "summary": "Télécharger les fichiers", "description": "Génère un lien temporaire pour télécharger les documents.\n\n### Types de fichiers\n* `original` : Document original\n* `signed` : Document signé (si terminé)\n* `audit_trail` : Dossier de preuve (si terminé)", "operationId": "2654cfeb496e6d9bc1d82985814c32ff", "parameters": [ { "name": "id", "in": "path", "description": "ID de la signature", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "path", "description": "Type de fichier", "required": true, "schema": { "type": "string", "enum": [ "original", "signed", "audit_trail" ] } } ], "responses": { "200": { "description": "Lien de téléchargement", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Fichier non trouvé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/signatures/{id}/remind": { "post": { "tags": [ "Signatures" ], "summary": "Envoyer un rappel", "description": "Renvoie le lien de signature à un signataire (ou à tous les signataires en attente).\n\nOptions du body :\n- `signer_id` : UUID d'un signataire précis. Si omis, tous les signataires en attente sont notifiés.\n- `channel` : `'email'` | `'sms'` | `'both'`. Si omis, l'`auth_method` du signataire est utilisé.", "operationId": "4dc8d235b871224129541edd47923cbe", "parameters": [ { "name": "id", "in": "path", "description": "ID de la signature", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "signer_id": { "description": "Cible un signataire précis. Si omis, tous les signataires en attente.", "type": "string", "format": "uuid" }, "channel": { "description": "Canal d'envoi. Si omis, l'auth_method du signataire est utilisé.", "type": "string", "enum": [ "email", "sms", "both" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Rappels envoyés", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "signers_reminded": { "type": "integer" }, "channel_used": { "description": "Canal effectivement utilisé (email | sms | both).", "type": "string" } }, "type": "object" } } } }, "404": { "description": "SIGNER_NOT_FOUND — signer_id ne correspond à aucun signataire de cette signature." } }, "security": [ { "bearerAuth": [] } ] } }, "/signatures/{id}/cancel": { "post": { "tags": [ "Signatures" ], "summary": "Annuler la signature", "description": "Annule une demande de signature en cours. Impossible si déjà signée.", "operationId": "6a5e1e60ba8061e5faa4f10e0e18ec82", "parameters": [ { "name": "id", "in": "path", "description": "ID de la signature", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signature annulée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/sirene/{siret}": { "get": { "tags": [ "Sirene" ], "summary": "Lookup SIRENE (Etalab -> INSEE -> manual fallback)", "description": "Pipeline triple (decision 2026-05-08, widget v3) :\n\n1. **Etalab** (recherche-entreprises.api.gouv.fr) — gratuit, pas d'auth, ~7 req/sec/IP\n2. Si Etalab 404/503 -> fallback **INSEE V3.11** (cle API requise cote serveur)\n3. Si les 2 providers sont DOWN -> retourne 200 avec `sirene_lookup_failed=true` pour **debloquer la saisie manuelle**\n\nCache 24h par SIRET. Le widget v3 ne BLOQUE jamais l'utilisateur sur un SIRET introuvable : il bascule en saisie manuelle et marque le SubTenant pour retry async.", "operationId": "412ce674b60254c139b23152cb83fe36", "parameters": [ { "name": "siret", "in": "path", "description": "SIRET 14 chiffres (Luhn valide).", "required": true, "schema": { "type": "string", "maxLength": 14, "minLength": 14, "example": "12345678901234" } }, { "name": "force_manual", "in": "query", "description": "Skip Etalab+INSEE et retourne direct le mode saisie manuelle (debug widget).", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Entreprise trouvee OU saisie manuelle debloquee (verifier `sirene_lookup_failed`).", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SireneCompanyData" }, "code": { "description": "Present uniquement quand `data.sirene_lookup_failed=true`. Valeur: SIRENE_MANUAL_ENTRY_REQUIRED.", "type": "string", "example": "SIRENE_MANUAL_ENTRY_REQUIRED", "nullable": true } }, "type": "object" } } } }, "400": { "description": "SIRET invalide (pas 14 chiffres ou Luhn KO).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SIRET inexistant chez les 2 providers (siret bien forme mais pas en base SIRENE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/api/v1/admin/tenants/{tenant}/branding": { "get": { "tags": [ "Branding", "Admin" ], "summary": "[Admin] Lire le branding d'un tenant", "description": "Lecture admin du branding de la Company par défaut d'un tenant.", "operationId": "adminGetTenantBranding", "parameters": [ { "name": "tenant", "in": "path", "description": "UUID du tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branding du tenant", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès admin requis" }, "404": { "description": "Tenant introuvable ou sans Company par défaut" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Branding", "Admin" ], "summary": "[Admin] Remplacer le branding d'un tenant (PUT)", "description": "Remplacement complet admin du branding de la Company par défaut d'un tenant.", "operationId": "adminUpdateTenantBrandingPut", "parameters": [ { "name": "tenant", "in": "path", "description": "UUID du tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès admin requis" }, "404": { "description": "Tenant sans Company par défaut" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Branding", "Admin" ], "summary": "[Admin] Mise à jour partielle du branding d'un tenant (PATCH)", "operationId": "adminUpdateTenantBrandingPatch", "parameters": [ { "name": "tenant", "in": "path", "description": "UUID du tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès admin requis" }, "404": { "description": "Tenant sans Company par défaut" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/admin/sub-tenants/{subTenant}/branding": { "get": { "tags": [ "Branding", "Admin" ], "summary": "[Admin] Lire le branding d'un sub-tenant", "description": "Lecture admin du branding de la première Company d'un sub-tenant.", "operationId": "adminGetSubTenantBranding", "parameters": [ { "name": "subTenant", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branding du sub-tenant", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès admin requis" }, "404": { "description": "Sub-tenant introuvable ou sans Company" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Branding", "Admin" ], "summary": "[Admin] Remplacer le branding d'un sub-tenant (PUT)", "description": "Met à jour le branding de la première Company d'un SubTenant.", "operationId": "adminUpdateSubTenantBrandingPut", "parameters": [ { "name": "subTenant", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès admin requis" }, "404": { "description": "Sub-tenant sans Company" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Branding", "Admin" ], "summary": "[Admin] Mise à jour partielle du branding d'un sub-tenant (PATCH)", "operationId": "adminUpdateSubTenantBrandingPatch", "parameters": [ { "name": "subTenant", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès admin requis" }, "404": { "description": "Sub-tenant sans Company" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/buyers": { "get": { "tags": [ "Buyers" ], "summary": "Lister les acheteurs (scope tenant/sub_tenant)", "description": "Pagination par defaut 25, max 100. Recherche full-text sur name / siret / email via le parametre `q`.", "operationId": "5cce3a0b2f1ed02e682dbb72ae91a547", "parameters": [ { "name": "q", "in": "query", "description": "Recherche partielle sur name/siret/email", "required": false, "schema": { "type": "string" } }, { "name": "is_individual", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginée", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Buyer" } } }, "type": "object" } } } }, "401": { "description": "Non authentifié" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "tags": [ "Buyers" ], "summary": "Creer un acheteur", "description": "Crée une entrée dans le registre des acheteurs, scopée au (tenant, sub_tenant) courant.\n\nLe `siret` est obligatoire uniquement pour une entreprise (`is_individual` absent/false) française (`country = FR`). Pour un particulier (`is_individual: true`) ou un acheteur hors France, il est optionnel. Si `shipping_address` est identique à `billing_address`, elle est stockée en NULL (règle ship=bill du Factur-X BG-13).", "operationId": "2ef6c39d6c117e60d1ea20bd416e4844", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "country", "billing_address" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "ACME SARL" }, "is_individual": { "description": "Acheteur particulier (B2C). Rend siret/vat_number optionnels.", "type": "boolean", "example": false }, "siret": { "description": "Obligatoire seulement pour une entreprise FR.", "type": "string", "maxLength": 14, "minLength": 14, "example": "98765432109876", "nullable": true }, "vat_number": { "type": "string", "maxLength": 20, "example": "FR12345678901", "nullable": true }, "legal_id": { "type": "string", "maxLength": 50, "nullable": true }, "legal_id_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "email": { "type": "string", "format": "email", "maxLength": 255, "example": "compta@acme.fr", "nullable": true }, "phone": { "type": "string", "maxLength": 50, "example": "+33145678900", "nullable": true }, "country": { "description": "Code pays ISO 3166-1 alpha-2.", "type": "string", "maxLength": 2, "minLength": 2, "example": "FR" }, "billing_address": { "$ref": "#/components/schemas/BuyerAddress" }, "shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true }, "metadata": { "type": "object", "nullable": true }, "notes": { "type": "string", "maxLength": 5000, "nullable": true } }, "type": "object" }, "example": { "name": "ACME SARL", "is_individual": false, "siret": "98765432109876", "vat_number": "FR12345678901", "email": "compta@acme.fr", "country": "FR", "billing_address": { "line1": "10 rue de la Paix", "postal_code": "75002", "city": "Paris", "country": "FR" } } } } }, "responses": { "201": { "description": "Acheteur créé", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Buyer" } }, "type": "object" } } } }, "403": { "description": "Interdit (scope tenant)" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/buyers/{buyer}": { "get": { "tags": [ "Buyers" ], "summary": "Recuperer un acheteur", "operationId": "448a0a1d01f12b6a295c7a3749dc8eee", "parameters": [ { "name": "buyer", "in": "path", "description": "UUID de l'acheteur", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Acheteur trouvé", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Buyer" } }, "type": "object" } } } }, "404": { "description": "Acheteur introuvable ou hors scope" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "tags": [ "Buyers" ], "summary": "Supprimer un acheteur (soft delete)", "operationId": "c46071d0f6ab5978c1bca9e88c318993", "parameters": [ { "name": "buyer", "in": "path", "description": "UUID de l'acheteur", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Supprimé (soft delete)" }, "404": { "description": "Acheteur introuvable ou hors scope" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "tags": [ "Buyers" ], "summary": "Mettre a jour un acheteur", "description": "Mise à jour partielle. Tous les champs sont optionnels (seuls ceux présents sont modifiés). Le même endpoint est exposé en `PUT` (remplacement total des champs fournis). Ne modifie jamais les factures déjà émises (snapshots immuables).", "operationId": "7b0724f49fc53aedefc8b25cda226ba2", "parameters": [ { "name": "buyer", "in": "path", "description": "UUID de l'acheteur", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "is_individual": { "type": "boolean" }, "siret": { "type": "string", "maxLength": 14, "minLength": 14, "nullable": true }, "vat_number": { "type": "string", "maxLength": 20, "nullable": true }, "legal_id": { "type": "string", "maxLength": 50, "nullable": true }, "legal_id_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "phone": { "type": "string", "maxLength": 50, "nullable": true }, "country": { "type": "string", "maxLength": 2, "minLength": 2 }, "billing_address": { "$ref": "#/components/schemas/BuyerAddress" }, "shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true }, "metadata": { "type": "object", "nullable": true }, "notes": { "type": "string", "maxLength": 5000, "nullable": true } }, "type": "object" }, "example": { "email": "nouvelle-compta@acme.fr", "notes": "Contact comptable mis à jour." } } } }, "responses": { "200": { "description": "Acheteur mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Buyer" } }, "type": "object" } } } }, "404": { "description": "Acheteur introuvable ou hors scope" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/tenant/buyers/vat-context": { "post": { "tags": [ "Buyers" ], "summary": "Pré-résoudre le contexte TVA d'une ligne de facture", "description": "Résout le contexte TVA (taux, catégorie EN16931, exemption_reason, justification CGI)\nd'une future ligne de facture **avant** émission, en fonction de :\n\n- le pays et le statut (B2B/B2C) de l'acheteur\n- la validité du numéro de TVA intracommunautaire (B2B UE)\n- le pays du vendeur (défaut : `tenant->defaultCompany` ou Company du sub-tenant)\n- le `place_of_supply` éventuel (override art. 259 A CGI pour services immobiliers,\n restauration, événementiel, etc.)\n\n### Règles appliquées (cascade)\n\n| Règle | Condition | Résultat |\n|-------|-----------|----------|\n| `R1_fr_domestic` | FR → FR | TVA française selon catégorie (art. 278+ CGI) |\n| `R2_eu_b2b_vat_valid` | FR → UE B2B + `vat_number_valid=true` | REVERSE_CHARGE / `AE` (art. 259-1 CGI) |\n| `R3_eu_b2c_no_vat` | FR → UE B2C, ou UE B2B sans vat_number | TVA française (art. 259-2 CGI) |\n| `R4_export` | FR → hors UE | OUT_OF_SCOPE / `O` (export) |\n| `R6_place_of_supply_override` | `place_of_supply` ≠ pays buyer | TVA du pays lieu de prestation (art. 259 A CGI) |\n\n### Modes d'usage\n\n- **Mode 1 — `buyer_id`** : référence un acheteur du registre. L'API vérifie\n le scope (anti-IDOR) puis lit `country`, `is_individual`, `vat_number` depuis le buyer.\n- **Mode 2 — `buyer` inline** : utile pour valider un contexte sans persister\n d'acheteur (devis, simulation, prévisualisation).\n\n### Warnings\n\nSi `line.tax_rate` est fourni, l'API compare le taux saisi avec le taux résolu\net retourne une liste de `warnings` de cohérence (mismatch, catégorie incohérente,\nnuméro de TVA manquant pour un B2B UE, etc.). Tableau vide si tout est cohérent.\n\nVoir aussi : [llms.txt référence VAT_CONTEXT_RESOLUTION](/docs/scell-api-llms.txt).", "operationId": "7b2ff53e144745d474af2fd383fc4f83", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveVatContextRequest" }, "examples": { "b2b_eu_reverse_charge": { "summary": "B2B UE — autoliquidation (vat_number valide)", "value": { "buyer": { "country": "DE", "is_individual": false, "vat_number": "DE123456789", "vat_number_valid": true }, "line": { "category": "STANDARD" } } }, "b2b_fr_domestic": { "summary": "FR → FR — TVA française standard", "value": { "buyer_id": "019cb416-b6db-730c-b3a5-f8b7a4512eb1", "line": { "category": "STANDARD", "place_of_supply": "FR" } } }, "place_of_supply_override": { "summary": "Override 259 A — service immobilier en FR pour client DE", "value": { "buyer": { "country": "DE", "is_individual": false, "vat_number": "DE123456789", "vat_number_valid": true }, "line": { "category": "STANDARD", "place_of_supply": "FR", "service_nature": "real_estate_service" } } } } } } }, "responses": { "200": { "description": "Contexte TVA résolu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveVatContextResponse" } } } }, "401": { "description": "TENANT_NOT_RESOLVED — clé API sans tenant rattaché" }, "404": { "description": "BUYER_NOT_FOUND — `buyer_id` hors scope tenant/sub_tenant (anti-IDOR) — ou SUB_TENANT_NOT_FOUND" }, "422": { "description": "Validation — `buyer_id` OU `buyer.*` requis, codes pays ISO non-conformes, etc." } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/consent": { "post": { "tags": [ "RGPD", "Public" ], "summary": "Enregistrer un consentement CNIL", "description": "Journalise le choix de consentement de l'utilisateur depuis le bandeau cookies du site. Pas d'authentification. Idempotent : un meme `consent_id` + `version` dans une fenetre de 5 minutes retourne l'enregistrement existant (200) sans creer de doublon.", "operationId": "e6f6dfe48e4e7e061bb966fc336feb6b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "consent_id", "status", "preferences", "version" ], "properties": { "consent_id": { "description": "Identifiant unique du consentement (genere cote client).", "type": "string", "format": "uuid" }, "status": { "description": "Statut global du consentement.", "type": "string", "enum": [ "accepted", "refused", "partial" ], "example": "partial" }, "preferences": { "required": [ "functional", "analytics", "marketing" ], "properties": { "functional": { "type": "boolean", "example": true }, "analytics": { "type": "boolean", "example": false }, "marketing": { "type": "boolean", "example": false } }, "type": "object" }, "version": { "description": "Version de la politique de consentement.", "type": "string", "pattern": "^v\\d+\\.\\d+$", "example": "v1.0" }, "language": { "description": "Langue du bandeau (defaut: fr).", "type": "string", "enum": [ "fr", "en" ], "example": "fr" } }, "type": "object" } } } }, "responses": { "201": { "description": "Consentement enregistre", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string", "format": "uuid" }, "already_logged": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "200": { "description": "Consentement deja enregistre (idempotence, fenetre 5 min)", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string", "format": "uuid" }, "already_logged": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/contact": { "post": { "tags": [ "Public" ], "summary": "Soumettre le formulaire de contact", "description": "Enregistre un lead depuis le formulaire de contact public. Pas d'authentification. Protection anti-spam : rate-limit 3/min + 20/h par IP, honeypot (`hp_token` doit rester vide), reCAPTCHA v3 (score >= 0.5, requis en production via `captcha_token`).", "operationId": "ba1af6af5736110884ce545e41032199", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "message", "hp_token" ], "properties": { "name": { "description": "Nom du contact", "type": "string", "maxLength": 255, "example": "Marie Dupont" }, "email": { "description": "Email du contact (valide RFC + DNS)", "type": "string", "format": "email", "maxLength": 255, "example": "marie@example.com" }, "company": { "description": "Societe (optionnel)", "type": "string", "maxLength": 255, "nullable": true }, "phone": { "description": "Telephone (optionnel)", "type": "string", "maxLength": 50, "nullable": true }, "subject": { "description": "Sujet (optionnel)", "type": "string", "maxLength": 100, "nullable": true }, "message": { "description": "Message", "type": "string", "maxLength": 5000, "minLength": 10, "example": "Bonjour, j'aimerais en savoir plus sur l'API de facturation." }, "consent_marketing": { "description": "Consentement marketing", "type": "boolean", "example": false }, "hp_token": { "description": "Honeypot anti-spam : DOIT rester vide. Tout remplissage = bot rejete.", "type": "string", "maxLength": 0, "example": "" }, "captcha_token": { "description": "Token reCAPTCHA v3 (requis en production uniquement).", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Lead enregistre, notifications mises en file", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "Message envoye, vous recevrez une reponse sous 24h." } }, "type": "object" } } } }, "422": { "description": "Erreur de validation ou verification anti-robot echouee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Trop de requetes (rate-limit depasse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/credit-notes": { "get": { "tags": [ "Credit Notes" ], "summary": "Lister les avoirs", "description": "Retourne la liste paginee des avoirs de l'entreprise.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/credit-notes?status=sent\" \\\n -H \"Authorization: Bearer \"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/credit-notes', [\n 'headers' => ['Authorization' => 'Bearer '],\n 'query' => ['status' => 'sent']\n]);\n```", "operationId": "6384a014a2dc239c84019d39324ecfda", "parameters": [ { "name": "status", "in": "query", "description": "Filtrer par statut (draft, sent)", "schema": { "type": "string", "enum": [ "draft", "sent" ] } }, { "name": "invoice_id", "in": "query", "description": "Filtrer par facture d'origine", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "description": "Filtrer par type (partial, total)", "schema": { "type": "string", "enum": [ "partial", "total" ] } }, { "name": "per_page", "in": "query", "description": "Nombre d'elements par page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Liste des avoirs", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Credit Notes" ], "summary": "Creer un avoir", "description": "Cree un avoir a partir d'une facture existante.\n\n### Types d'avoirs\n* `total` : Avoir pour la totalite de la facture\n* `partial` : Avoir partiel (lignes specifiques)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/credit-notes \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reason\": \"Erreur de facturation\",\n \"type\": \"partial\",\n \"items\": [\n { \"invoice_line_id\": \"uuid\", \"quantity\": 2 }\n ]\n }'\n```", "operationId": "7ee977984917a620835d0875a43b52f0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_id", "reason", "type" ], "properties": { "invoice_id": { "description": "ID de la facture d'origine", "type": "string", "format": "uuid" }, "reason": { "description": "Motif de l'avoir", "type": "string", "maxLength": 1000 }, "type": { "description": "Type d'avoir", "type": "string", "enum": [ "partial", "total" ] }, "items": { "description": "Lignes a crediter (requis pour avoir partiel)", "type": "array", "items": { "properties": { "invoice_line_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "minimum": 0.0001 } }, "type": "object" } } }, "type": "object" }, "example": { "invoice_id": "550e8400-e29b-41d4-a716-446655440000", "reason": "Erreur de facturation", "type": "partial", "items": [ { "invoice_line_id": "019df46f-1234-7000-bbbb-000000000001", "quantity": 2 } ] } } } }, "responses": { "201": { "description": "Avoir cree en brouillon", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Avoir cree en brouillon." }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/credit-notes/{id}": { "get": { "tags": [ "Credit Notes" ], "summary": "Voir un avoir", "description": "Recupere les details complets d'un avoir.", "operationId": "a35894366c6ef94af78821f7f149e6e9", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Details de l'avoir", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "404": { "description": "Avoir non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Credit Notes" ], "summary": "Supprimer un avoir", "description": "Supprime un avoir en brouillon. Les avoirs envoyes ne peuvent pas etre supprimes.", "operationId": "27b364fbfacd4ff6395b4bb1bc0c6938", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Avoir supprime", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Avoir supprime." } }, "type": "object" } } } }, "422": { "description": "L'avoir ne peut pas etre supprime", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/credit-notes/{id}/send": { "post": { "tags": [ "Credit Notes" ], "summary": "Valider et envoyer un avoir", "description": "Valide l'avoir, genere le numero definitif et le PDF Factur-X.", "operationId": "742c1aa23b682edf9e1f2a919f9b5022", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Avoir valide et envoye", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Avoir valide et envoye." }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "422": { "description": "L'avoir ne peut pas etre envoye", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/credit-notes/{id}/download": { "get": { "tags": [ "Credit Notes" ], "summary": "Telecharger le PDF Factur-X", "description": "Telecharge le PDF Factur-X de l'avoir. L'avoir doit etre envoye.", "operationId": "f612abb65083a063e57205ff18789bbb", "parameters": [ { "name": "id", "in": "path", "description": "ID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fichier PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "422": { "description": "L'avoir n'a pas encore ete envoye", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/invoices/{invoiceId}/remaining-creditable": { "get": { "tags": [ "Credit Notes" ], "summary": "Montants restants a crediter", "description": "Calcule les montants restants a crediter sur chaque ligne d'une facture.", "operationId": "616fc043936a2f425a09042d58bb0add", "parameters": [ { "name": "invoiceId", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Montants restants", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "items": { "type": "array", "items": { "properties": { "invoice_line_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "original_quantity": { "type": "number" }, "credited_quantity": { "type": "number" }, "remaining_quantity": { "type": "number" }, "unit_price": { "type": "number" }, "remaining_amount_ht": { "type": "number" } }, "type": "object" } }, "total_remaining": { "type": "number" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tenant/fiscal/anchors": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Liste des ancrages blockchain", "description": "Retourne la liste des ancrages (preuves d'existence) des clotures fiscales sur la blockchain ou un service de timestamping. Chaque ancrage lie un hash de cloture a une preuve horodatee immuable.", "operationId": "554fc4c99add9103954a0f7f30636397", "parameters": [ { "name": "limit", "in": "query", "description": "Nombre maximum d'ancrages a retourner", "required": false, "schema": { "type": "integer", "default": 30, "example": 30 } } ], "responses": { "200": { "description": "Liste des ancrages", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "description": "Ancrage blockchain", "type": "object" } } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/api/v1/admin/fiscal/archive-health": { "get": { "tags": [ "Fiscal", "Admin" ], "summary": "Vérification santé du bucket fiscal S3 Object Lock", "description": "Vérifie versioning + Object Lock COMPLIANCE + audite un échantillon des derniers objets archivés.", "operationId": "e8c150048ae3b24148be5be480c56624", "parameters": [ { "name": "sample_size", "in": "query", "description": "Nombre d'objets à auditer (défaut: 10, max: 50)", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Bucket conforme", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "bucket_config": { "type": "object" }, "objects_audit": { "type": "object" }, "status": { "type": "string", "example": "healthy" } }, "type": "object" } }, "type": "object" } } } }, "503": { "description": "Bucket non conforme Object Lock", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/v1/tenant/fiscal/closings": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Historique des clotures journalieres", "description": "Retourne l'historique des clotures journalieres du grand-livre fiscal. Chaque cloture contient le cumul des montants, le hash de chaine et le nombre d'ecritures traitees pour la journee.", "operationId": "157d2767034cdd5b53e806beefbf8fa6", "parameters": [ { "name": "limit", "in": "query", "description": "Nombre maximum de clotures a retourner", "required": false, "schema": { "type": "integer", "default": 30, "example": 30 } } ], "responses": { "200": { "description": "Liste des clotures journalieres", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "description": "Cloture journaliere", "type": "object" } } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/closings/daily": { "post": { "tags": [ "Fiscal Compliance" ], "summary": "Effectuer une cloture journaliere", "description": "Declenche manuellement la cloture journaliere pour une date donnee (par defaut la veille). La cloture calcule le cumul des ecritures, genere un hash de chaine et scelle la journee. Une journee deja cloturee ne peut pas etre cloturee a nouveau.", "operationId": "39fab1a5a01aa49f86730a3420d250ac", "requestBody": { "description": "Date de cloture (optionnel, defaut = veille)", "content": { "application/json": { "schema": { "properties": { "date": { "description": "Date de la cloture (format Y-m-d)", "type": "string", "format": "date", "example": "2026-01-15" } }, "type": "object" } } } }, "responses": { "201": { "description": "Cloture journaliere effectuee avec succes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Cloture journaliere effectuee avec succes." }, "data": { "description": "Details de la cloture effectuee", "type": "object" } }, "type": "object" } } } }, "409": { "description": "Cloture deja effectuee pour cette date", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cloture deja effectuee pour cette date." } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/attestation/{year}": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Attestation de conformite fiscale", "description": "Genere l'attestation de conformite fiscale pour l'annee specifiee. Cette attestation certifie que le systeme de caisse respecte les exigences de la loi de finances (inalterabilite, securisation, conservation, archivage).", "operationId": "f23be9ee748c493abfbe89605322dd8a", "parameters": [ { "name": "year", "in": "path", "description": "Annee de l'attestation", "required": true, "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Donnees de l'attestation de conformite", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Contenu de l'attestation de conformite fiscale", "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/attestation/{year}/download": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Telecharger l'attestation de conformite fiscale", "description": "Telecharge l'attestation de conformite fiscale au format PDF/texte pour l'annee specifiee. Ce document peut etre presente lors d'un controle fiscal.", "operationId": "86bd4eb89ef21c3dfa9db46ed84f47bf", "parameters": [ { "name": "year", "in": "path", "description": "Annee de l'attestation", "required": true, "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Fichier de l'attestation (binary download)", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "description": "Erreur lors de la generation de l'attestation", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Erreur lors de la generation de l'attestation." } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/compliance": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Indicateurs de conformite fiscale temps reel", "description": "Retourne un tableau de bord agrege de conformite ISCA incluant le pourcentage de periodes cloturees, le pourcentage de chaines intactes, les incidents ouverts et le statut de conformite global.", "operationId": "263101c34f8111ed71b81382827d73da", "responses": { "200": { "description": "Indicateurs de conformite", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Metriques de conformite agregees", "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/entries": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Consultation du grand-livre fiscal", "description": "Retourne les ecritures du grand-livre fiscal (ledger) du tenant avec pagination. Permet de filtrer par plage de dates, type d'ecriture et environnement (production/sandbox).", "operationId": "55af6b63692a171db8e3ad8551aedcca", "parameters": [ { "name": "date_from", "in": "query", "description": "Date de debut (format Y-m-d)", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "description": "Date de fin (format Y-m-d)", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-12-31" } }, { "name": "entry_type", "in": "query", "description": "Type d'ecriture (ex: invoice_created, credit_note_issued, kill_switch_activated)", "required": false, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "description": "Environnement : production ou sandbox", "required": false, "schema": { "type": "string", "enum": [ "production", "sandbox" ] } }, { "name": "per_page", "in": "query", "description": "Nombre d'elements par page", "required": false, "schema": { "type": "integer", "default": 20, "example": 20 } } ], "responses": { "200": { "description": "Liste paginee des ecritures du grand-livre fiscal", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "description": "Ecriture fiscale", "type": "object" } }, "meta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 10 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 200 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/fec": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Export du Fichier des Ecritures Comptables (FEC) — chaine isolee", "description": "Genere le Fichier des Ecritures Comptables (FEC) conforme a l'article A.47 A-1 du LPF pour une SEULE chaine fiscale ISCA (tenant master ou sub_tenant donne). Le format de sortie peut etre pipe (|) ou tabulation. Si le parametre download est passe, le fichier est telecharge directement. Les sequence_number du fichier sont garantis contigus (une seule chaine ISCA).", "operationId": "b4ca5ada6f0517a123990dcbbf2e585c", "parameters": [ { "name": "start_date", "in": "query", "description": "Date de debut de la periode (obligatoire)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "end_date", "in": "query", "description": "Date de fin de la periode (obligatoire)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-12-31" } }, { "name": "format", "in": "query", "description": "Format du separateur : pipe ou tab", "required": false, "schema": { "type": "string", "default": "pipe", "enum": [ "pipe", "tab" ] } }, { "name": "sub_tenant_id", "in": "query", "description": "UUID du sub_tenant (optionnel). Si absent : export de la chaine master tenant (sub_tenant_id IS NULL). Si fourni : export de la chaine isolee du sub_tenant specifie. Le sub_tenant doit appartenir au tenant courant.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "019d5ea8-0000-7000-8000-000000000001" } }, { "name": "download", "in": "query", "description": "Telecharger le fichier directement", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "FEC genere avec succes (JSON ou fichier binaire si download=true)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "FEC genere avec succes." }, "data": { "properties": { "period": { "properties": { "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-12-31" } }, "type": "object" }, "format": { "type": "string", "example": "pipe" }, "sub_tenant_id": { "type": "string", "example": null, "nullable": true }, "file_path": { "type": "string", "example": "/tmp/fec_2026.txt" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "sub_tenant_id fourni mais introuvable ou hors scope du tenant courant", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Sub-tenant introuvable." } }, "type": "object" } } } }, "422": { "description": "Erreur de validation des parametres", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/fec/all": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Export ZIP de tous les FEC (toutes les chaines ISCA du tenant)", "description": "Genere un fichier ZIP contenant un FEC par chaine fiscale ISCA active du tenant : 1 FEC pour la chaine master tenant + 1 FEC par sub_tenant actif sur la periode. Chaque FEC a des sequence_number contigus (une seule chaine par fichier). Conforme DGFiP : chaque entite comptable est isolee dans son propre fichier.", "operationId": "c27f032133ee843120e2ec4ccfb3beb7", "parameters": [ { "name": "start_date", "in": "query", "description": "Date de debut de la periode (obligatoire)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "end_date", "in": "query", "description": "Date de fin de la periode (obligatoire)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-12-31" } }, { "name": "format", "in": "query", "description": "Format du separateur pour chaque FEC : pipe ou tab", "required": false, "schema": { "type": "string", "default": "pipe", "enum": [ "pipe", "tab" ] } } ], "responses": { "200": { "description": "ZIP genere (JSON metadata) ou fichier binaire", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "ZIP FEC genere avec succes." }, "data": { "properties": { "period": { "properties": { "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-12-31" } }, "type": "object" }, "format": { "type": "string", "example": "pipe" }, "file_path": { "type": "string", "example": "/tmp/fec_all_2026.zip" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation des parametres", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/forensic-export": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Export judiciaire avance (chronologie certifiee, graphe de dependances, rapport expert)", "description": "Genere un export forensique complet du grand-livre fiscal. Trois types sont disponibles :\n- **chronology** : Enregistrement chronologique certifie avec preuves de hachage en ligne. Chaque ecriture inclut data_hash, chain_hash et previous_hash pour une verification independante.\n- **graph** : Graphe de dependances cartographiant les relations entre ecritures fiscales, clotures et ancrages. Utile pour l'analyse visuelle des liens entre entites.\n- **report** (defaut) : Rapport d'expertise consolide incluant la chronologie, le graphe, l'historique des verifications d'integrite et une conclusion de conformite ISCA.\n\nL'export est enregistre dans le grand-livre fiscal comme evenement de type 'forensic_export' avec statut 'preuve_legale'.", "operationId": "cac8766adfaabe9eea39823dde0b15a2", "parameters": [ { "name": "type", "in": "query", "description": "Type d'export : chronology (chronologie certifiee), graph (graphe de dependances), report (rapport expert complet)", "required": false, "schema": { "type": "string", "default": "report", "enum": [ "chronology", "graph", "report" ] } }, { "name": "start_date", "in": "query", "description": "Date de debut de la periode (obligatoire, format Y-m-d)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "end_date", "in": "query", "description": "Date de fin de la periode (obligatoire, format Y-m-d)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-12-31" } } ], "responses": { "200": { "description": "Export forensique genere avec succes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Contenu de l'export forensique selon le type demande", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation des parametres", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/integrity": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Verification d'integrite de la chaine fiscale", "description": "Verifie l'integrite de la chaine de hachage du grand-livre fiscal pour le tenant courant. Permet de filtrer par plage de dates pour cibler une periode specifique. Retourne un rapport detaille avec le nombre d'ecritures verifiees et les eventuelles ruptures de chaine.", "operationId": "a4d3e64d14fce4d34474ce0635120de5", "parameters": [ { "name": "date_from", "in": "query", "description": "Date de debut de la periode (format Y-m-d)", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "description": "Date de fin de la periode (format Y-m-d)", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-12-31" } } ], "responses": { "200": { "description": "Rapport d'integrite de la chaine fiscale", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Rapport d'integrite avec details des verifications", "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/integrity/{date}": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Verification d'integrite pour une date specifique", "description": "Verifie l'integrite de la chaine de hachage du grand-livre fiscal pour une date donnee. Utile pour diagnostiquer une rupture de chaine sur un jour precis.", "operationId": "8e2b7661785142b5a914c4f30c8767bc", "parameters": [ { "name": "date", "in": "path", "description": "Date a verifier (format Y-m-d)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-01-15" } } ], "responses": { "200": { "description": "Rapport d'integrite pour la date donnee", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Rapport d'integrite pour la date demandee", "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/integrity/history": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Historique des verifications d'integrite", "description": "Retourne l'historique pagine des verifications d'integrite effectuees sur la chaine fiscale du tenant. Chaque entree correspond a une verification automatique ou manuelle avec son resultat.", "operationId": "77c6d6fc1ae6441506e777f21a838b84", "parameters": [ { "name": "per_page", "in": "query", "description": "Nombre d'elements par page", "required": false, "schema": { "type": "integer", "default": 20, "example": 20 } } ], "responses": { "200": { "description": "Liste paginee des verifications d'integrite", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "description": "Verification d'integrite", "type": "object" } }, "meta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 5 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 95 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/integrity-status": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Dashboard d'etat de sante du grand-livre fiscal", "description": "Retourne un snapshot complet de l'etat de sante du ledger ISCA du tenant : integrite de la chaine de hashes, gaps de sequence par sub_tenant, orphelins (invoices/credit_notes non-draft sans fiscal_entry). Utile pour le dashboard admin et pour declencher un fiscal:backfill-entries.", "operationId": "62919cf096ecda27d9f2d820fe7a3b34", "responses": { "200": { "description": "Snapshot complet de l'etat de sante du ledger", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/kill-switch/status": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Statut du kill-switch fiscal", "description": "Retourne l'etat actuel du kill-switch fiscal. Lorsque le kill-switch est actif, les nouvelles ecritures fiscales sont suspendues. Ce mecanisme est prevu pour les situations d'urgence (maintenance critique, migration).", "operationId": "48dd80b289994ac300ac1516af1ee37e", "responses": { "200": { "description": "Statut actuel du kill-switch", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "is_active": { "type": "boolean", "example": false }, "kill_switch": { "description": "Details du kill-switch actif (null si inactif)", "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/kill-switch/activate": { "post": { "tags": [ "Fiscal Compliance" ], "summary": "Activer le kill-switch fiscal", "description": "Active le kill-switch fiscal pour suspendre temporairement l'enregistrement des ecritures fiscales. Une raison obligatoire est enregistree dans le grand-livre a des fins de tracabilite. Si le kill-switch est deja actif, une erreur 409 est retournee.", "operationId": "7039c68dc4c45072f767be9a14d0252d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "description": "Raison de l'activation du kill-switch", "type": "string", "maxLength": 1000, "example": "Maintenance critique du systeme de facturation" } }, "type": "object" } } } }, "responses": { "201": { "description": "Kill-switch active avec succes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Kill-switch active. Les ecritures fiscales sont suspendues." }, "data": { "description": "Details du kill-switch cree", "type": "object" } }, "type": "object" } } } }, "409": { "description": "Le kill-switch est deja actif", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Le kill-switch est deja actif." } }, "type": "object" } } } }, "422": { "description": "Erreur de validation (raison manquante)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/kill-switch/deactivate": { "post": { "tags": [ "Fiscal Compliance" ], "summary": "Desactiver le kill-switch fiscal", "description": "Desactive le kill-switch fiscal et reprend l'enregistrement normal des ecritures fiscales. L'evenement de desactivation est egalement enregistre dans le grand-livre pour tracabilite. Retourne 404 si aucun kill-switch n'est actuellement actif.", "operationId": "574a8df21feb3d1cd7ad73bf679c4881", "responses": { "200": { "description": "Kill-switch desactive avec succes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Kill-switch desactive. Les ecritures fiscales reprennent." } }, "type": "object" } } } }, "404": { "description": "Aucun kill-switch actif", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Aucun kill-switch actif." } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/rules": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Liste des regles fiscales applicables", "description": "Retourne les regles fiscales applicables au tenant a une date donnee. Les regles peuvent etre globales (definies par la plateforme) ou specifiques au tenant. Filtrage optionnel par categorie (TVA, facturation, avoirs, cloture, export).", "operationId": "4bf5b22fb3b3e0f94d75918eca7181bd", "parameters": [ { "name": "date", "in": "query", "description": "Date de reference pour les regles applicables (format Y-m-d, defaut = aujourd'hui)", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-01-15" } }, { "name": "category", "in": "query", "description": "Categorie de regles a filtrer", "required": false, "schema": { "type": "string", "enum": [ "vat", "invoicing", "credit_note", "closing", "export" ] } } ], "responses": { "200": { "description": "Liste des regles fiscales applicables", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "description": "Regle fiscale", "type": "object" } } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] }, "post": { "tags": [ "Fiscal Compliance" ], "summary": "Creer une regle fiscale", "description": "Cree une nouvelle regle fiscale specifique au tenant. La definition de la regle est validee avant creation. Les regles ont un systeme de versioning : une mise a jour cree une nouvelle version plutot que de modifier l'existante.", "operationId": "196de4c61fc361fd8488be990eff9f07", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rule_key", "name", "category", "rule_definition", "effective_from" ], "properties": { "rule_key": { "description": "Cle unique de la regle", "type": "string", "maxLength": 100, "example": "vat_reduced_rate" }, "name": { "description": "Nom de la regle", "type": "string", "maxLength": 200, "example": "Taux de TVA reduit" }, "category": { "description": "Categorie de la regle", "type": "string", "enum": [ "vat", "invoicing", "credit_note", "closing", "export" ], "example": "vat" }, "rule_definition": { "description": "Definition de la regle (structure JSON libre)", "type": "object", "example": "{\"rate\": 5.5, \"applies_to\": [\"food\", \"books\"]}" }, "effective_from": { "description": "Date d'effet de la regle", "type": "string", "format": "date", "example": "2026-01-01" }, "effective_until": { "description": "Date de fin d'effet (optionnel)", "type": "string", "format": "date", "example": "2026-12-31", "nullable": true }, "legal_reference": { "description": "Reference legale (article de loi)", "type": "string", "maxLength": 200, "example": "Art. 278-0 bis CGI", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Regle creee avec succes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Regle creee avec succes." }, "data": { "description": "Regle fiscale creee", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation ou definition de regle invalide", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Definition de regle invalide." } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/rules/{key}": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Detail d'une regle fiscale", "description": "Retourne le detail de la derniere version active d'une regle fiscale identifiee par sa cle unique. Inclut la definition de la regle, sa categorie, ses dates d'effet et la reference legale associee.", "operationId": "a39eb2e74af396b8ddbeaca522971b8a", "parameters": [ { "name": "key", "in": "path", "description": "Cle unique de la regle fiscale", "required": true, "schema": { "type": "string", "example": "vat_standard_rate" } } ], "responses": { "200": { "description": "Detail de la regle fiscale", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Regle fiscale avec definition complete", "type": "object" } }, "type": "object" } } } }, "404": { "description": "Regle non trouvee", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Regle non trouvee." } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/rules/{key}/history": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Historique des versions d'une regle fiscale", "description": "Retourne l'historique complet des versions d'une regle fiscale identifiee par sa cle. Permet de tracer l'evolution des parametres fiscaux dans le temps (ex: changements de taux de TVA).", "operationId": "7ee4d2a0f55b05c552fd15cace541c04", "parameters": [ { "name": "key", "in": "path", "description": "Cle unique de la regle fiscale", "required": true, "schema": { "type": "string", "example": "vat_standard_rate" } } ], "responses": { "200": { "description": "Historique des versions de la regle", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "description": "Version de la regle fiscale", "type": "object" } } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/rules/{id}": { "put": { "tags": [ "Fiscal Compliance" ], "summary": "Mettre a jour une regle fiscale", "description": "Met a jour une regle fiscale en creant une nouvelle version. Les regles globales (sans tenant_id) ne peuvent pas etre modifiees par un tenant. Seules les regles specifiques au tenant sont modifiables.", "operationId": "ca725199f9f0c2bfda1282355b151107", "parameters": [ { "name": "id", "in": "path", "description": "Identifiant UUID de la regle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rule_definition" ], "properties": { "rule_definition": { "description": "Nouvelle definition de la regle (structure JSON)", "type": "object", "example": "{\"rate\": 20.0}" }, "effective_from": { "description": "Nouvelle date d'effet", "type": "string", "format": "date", "example": "2026-07-01", "nullable": true }, "effective_until": { "description": "Nouvelle date de fin d'effet", "type": "string", "format": "date", "nullable": true }, "legal_reference": { "description": "Reference legale mise a jour", "type": "string", "maxLength": 200, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Regle mise a jour (nouvelle version creee)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Regle mise a jour (nouvelle version creee)." }, "data": { "description": "Nouvelle version de la regle", "type": "object" } }, "type": "object" } } } }, "403": { "description": "Modification interdite (regle globale)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Les regles globales ne peuvent pas etre modifiees par un tenant." } }, "type": "object" } } } }, "404": { "description": "Regle non trouvee", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Regle non trouvee." } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/rules/export": { "get": { "tags": [ "Fiscal Compliance" ], "summary": "Exporter les regles fiscales pour une periode", "description": "Exporte l'ensemble des regles fiscales applicables sur une periode donnee. Utile pour l'archivage reglementaire ou la transmission aux auditeurs lors d'un controle fiscal.", "operationId": "93473f7ccd4900e476979d847880dd56", "parameters": [ { "name": "start_date", "in": "query", "description": "Date de debut de la periode (obligatoire)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "end_date", "in": "query", "description": "Date de fin de la periode (obligatoire)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-12-31" } } ], "responses": { "200": { "description": "Export des regles fiscales pour la periode", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Export des regles avec metadata de la periode", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation des dates", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/fiscal/rules/replay": { "post": { "tags": [ "Fiscal Compliance" ], "summary": "Rejouer les regles fiscales sur une periode", "description": "Rejoue (simule) l'application des regles fiscales sur une periode passee. Permet de verifier retroactivement si les regles ont ete correctement appliquees ou de simuler l'impact d'un changement de regle. Retourne un rapport de conformite.", "operationId": "755a39c723d8a4dca9adcfd311395f34", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "start_date", "end_date" ], "properties": { "start_date": { "description": "Date de debut de la periode a rejouer", "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "description": "Date de fin de la periode a rejouer", "type": "string", "format": "date", "example": "2026-06-30" } }, "type": "object" } } } }, "responses": { "200": { "description": "Rapport de rejeu des regles fiscales", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Rapport de simulation avec ecarts detectes", "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation des dates", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/invoices/incoming": { "get": { "tags": [ "Incoming Invoices" ], "summary": "Lister les factures entrantes", "description": "Retourne la liste paginee des factures fournisseurs (direction = incoming).\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/invoices/incoming?status=validated\" \\\n -H \"Authorization: Bearer \"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/invoices/incoming', [\n 'headers' => ['Authorization' => 'Bearer '],\n 'query' => ['status' => 'validated', 'seller_siret' => '12345678901234']\n]);\n```", "operationId": "40d3859251a8c19c460c1d8dd93b24d3", "parameters": [ { "name": "status", "in": "query", "description": "Filtrer par statut", "schema": { "type": "string", "enum": [ "draft", "validated", "accepted", "rejected", "disputed" ] } }, { "name": "seller_siret", "in": "query", "description": "Filtrer par SIRET du fournisseur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "from", "in": "query", "description": "Date de debut (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "description": "Montant TTC minimum", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "description": "Montant TTC maximum", "schema": { "type": "number" } }, { "name": "per_page", "in": "query", "description": "Nombre d'elements par page", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Liste des factures entrantes", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncomingInvoice" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/{invoice}/accept": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Accepter une facture entrante", "description": "Accepte une facture fournisseur. La facture passe au statut 'accepted'.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/accept \\\n -H \"Authorization: Bearer \"\n```", "operationId": "331ea9db0abce22471fbb968e8575c9a", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Facture acceptee", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Facture acceptee avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "La facture ne peut pas etre acceptee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/{invoice}/reject": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Rejeter une facture entrante", "description": "Rejette une facture fournisseur avec un motif obligatoire.\n\n### Codes de rejet\n* `incorrect_amount` : Montant incorrect\n* `duplicate` : Facture en double\n* `unknown_order` : Commande inconnue\n* `incorrect_vat` : TVA incorrecte\n* `other` : Autre motif\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/reject \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reason\": \"La facture ne correspond pas a notre commande\",\n \"reason_code\": \"unknown_order\"\n }'\n```", "operationId": "d2e3eeebdc2db7036ebfa364a20251e6", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason", "reason_code" ], "properties": { "reason": { "description": "Motif detaille du rejet", "type": "string", "maxLength": 500 }, "reason_code": { "description": "Code de rejet", "type": "string", "enum": [ "incorrect_amount", "duplicate", "unknown_order", "incorrect_vat", "other" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Facture rejetee", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Facture rejetee avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erreur de validation ou facture non rejectable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/{invoice}/dispute": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Contester une facture entrante", "description": "Conteste une facture fournisseur. Contrairement au rejet, la contestation permet de negocier avec le fournisseur.\n\n### Types de contestation\n* `amount_discrepancy` : Ecart de montant\n* `missing_goods` : Marchandises manquantes\n* `quality_issue` : Probleme de qualite\n* `contract_breach` : Non-respect du contrat\n* `pricing_error` : Erreur de prix\n* `other` : Autre motif\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/dispute \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reason\": \"Le montant facture ne correspond pas au devis accepte\",\n \"dispute_type\": \"amount_discrepancy\",\n \"expected_amount\": 1500.00\n }'\n```", "operationId": "2bc12ee45f73377b843d2e12a314e41d", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason", "dispute_type" ], "properties": { "reason": { "description": "Motif detaille de la contestation", "type": "string", "maxLength": 1000 }, "dispute_type": { "description": "Type de contestation", "type": "string", "enum": [ "amount_discrepancy", "missing_goods", "quality_issue", "contract_breach", "pricing_error", "other" ] }, "expected_amount": { "description": "Montant attendu (optionnel)", "type": "number" } }, "type": "object" } } } }, "responses": { "200": { "description": "Contestation enregistree", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Contestation enregistree avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erreur de validation ou facture non contestable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/incoming/{invoice}": { "get": { "tags": [ "Incoming Invoices" ], "summary": "Recuperer une facture entrante", "description": "Retourne le detail d'une facture fournisseur (direction = incoming) avec ses lignes.", "operationId": "e9a90636955ae6d239312bc5fda2abc0", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail de la facture entrante", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/incoming/{invoice}/mark-read": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Marquer une facture entrante comme lue", "description": "Marque une facture fournisseur comme lue par l'utilisateur courant. Operation idempotente : un second appel ne reecrit pas le timestamp.", "operationId": "e55d129b2ca6cbeee836a3b63981d371", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Facture marquee comme lue (ou deja lue)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "read_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/{invoice}/mark-paid": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Marquer une facture entrante comme payee", "description": "Marque une facture fournisseur comme payee. Seules les factures acceptees peuvent etre marquees comme payees.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/mark-paid \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"payment_reference\": \"VIR-2026-001234\",\n \"paid_at\": \"2026-01-24T10:30:00Z\",\n \"note\": \"Paiement par virement bancaire\"\n }'\n```\n\n**PHP**\n```php\n$response = $client->post('https://api.scell.io/api/v1/invoices/{invoice_id}/mark-paid', [\n 'headers' => ['Authorization' => 'Bearer '],\n 'json' => [\n 'payment_reference' => 'VIR-2026-001234',\n 'paid_at' => '2026-01-24T10:30:00Z'\n ]\n]);\n```", "operationId": "b3525f5d029888f61999e5a97b90105e", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_means_code" ], "properties": { "payment_means_code": { "description": "Code BT-81 EN16931 UN/ECE 4461 (OBLIGATOIRE). 10=especes, 20=cheque, 30=virement, 42=versement bancaire, 48=CB, 49=prelevement, 57=mandat, 58=SEPA CT, 59=SEPA DD, 97=compensation, 1=non specifie", "type": "string", "enum": [ "1", "10", "20", "30", "42", "48", "49", "57", "58", "59", "97" ], "example": "58" }, "payment_means_text": { "description": "Libelle BT-82 du moyen de paiement (ex: \"Compte Credit Mutuel ...4567\")", "type": "string", "maxLength": 100 }, "payment_reference": { "description": "Reference du paiement (virement, cheque, etc.)", "type": "string", "maxLength": 100 }, "paid_at": { "description": "Date du paiement (defaut: maintenant)", "type": "string", "format": "date-time" }, "note": { "description": "Note interne sur le paiement", "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Facture marquee comme payee", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Facture marquee comme payee avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "La facture ne peut pas etre marquee comme payee (statut incorrect)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/invoices/{invoice}/download": { "get": { "tags": [ "Incoming Invoices" ], "summary": "Telecharger le fichier source de la facture", "description": "Telecharge le fichier PDF ou XML de la facture entrante.\n\n### Formats disponibles\n* `pdf` : Document PDF avec la facture visuelle\n* `xml` : Fichier XML source (Factur-X, UBL, CII)\n\n### Exemples\n\n**cURL**\n```bash\n# Telecharger le PDF\ncurl -X GET \"https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/download?format=pdf\" \\\n -H \"Authorization: Bearer \" \\\n -o facture.pdf\n\n# Telecharger le XML\ncurl -X GET \"https://api.scell.io/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/download?format=xml\" \\\n -H \"Authorization: Bearer \" \\\n -o facture.xml\n```", "operationId": "4de181b34ab11a90397beb375c132b02", "parameters": [ { "name": "invoice", "in": "path", "description": "ID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "Format du fichier (pdf ou xml)", "schema": { "type": "string", "default": "pdf", "enum": [ "pdf", "xml" ] } } ], "responses": { "200": { "description": "Fichier telecharge", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Facture ou fichier non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v1/invoices/{invoice}/send-by-email": { "post": { "tags": [ "Invoices" ], "summary": "Envoyer une facture par email à l'acheteur", "description": "Envoie la facture par email à l'acheteur. Si la facture est en statut `draft`, elle passe automatiquement à `validated`. L'email réel de l'acheteur est résolu dans cet ordre : (1) `recipient_email` du payload, (2) `buyer_email` de la facture. Retourne 422 `BUYER_HAS_NO_EMAIL` si aucun email n'est résolvable.", "operationId": "sendInvoiceByEmail", "parameters": [ { "name": "invoice", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInvoiceByEmailRequest" } } } }, "responses": { "200": { "description": "Facture envoyée par email", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SendInvoiceByEmailResponse" }, "message": { "type": "string", "example": "Facture envoyée par email." } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé (facture d'un autre tenant)" }, "404": { "description": "Facture introuvable" }, "422": { "description": "Aucun email destinataire résolvable", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Aucun email n'est renseigné pour cet acheteur. Fournissez recipient_email dans la requête." }, "code": { "type": "string", "example": "BUYER_HAS_NO_EMAIL" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/v1/invoice-templates": { "get": { "tags": [ "Invoice Templates" ], "summary": "Lister les templates de factures", "description": "Retourne les templates accessibles au tenant courant (templates system + templates du tenant). Trie par defaut puis par nom.", "operationId": "3e08067c63359fe7731735c847df4afe", "parameters": [ { "name": "per_page", "in": "query", "description": "Nombre de resultats par page (1-100, defaut 25).", "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Liste paginee des templates", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] }, "post": { "tags": [ "Invoice Templates" ], "summary": "Creer un template de facture", "description": "Cree un template de personnalisation. Le scope `system` est interdit cote API (reserve a Scell). `sub_tenant_id` est obligatoire si `scope=sub_tenant`.", "operationId": "a8bb98bfe01ac4928466c29ccd4227b4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "scope", "name" ], "properties": { "scope": { "description": "Portee du template (`system` interdit cote API).", "type": "string", "enum": [ "tenant", "sub_tenant" ] }, "sub_tenant_id": { "description": "Obligatoire si scope=sub_tenant.", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "is_default": { "type": "boolean", "nullable": true }, "is_available_to_subtenants": { "type": "boolean", "nullable": true }, "logo_url": { "type": "string", "maxLength": 2048, "nullable": true }, "logo_position": { "type": "string", "enum": [ "top-left", "top-center", "top-right" ], "nullable": true }, "primary_color": { "description": "Hex ou 'transparent'.", "type": "string", "example": "#6366F1", "nullable": true }, "accent_color": { "type": "string", "nullable": true }, "text_color": { "type": "string", "nullable": true }, "background_color": { "type": "string", "nullable": true }, "header_text": { "type": "string", "maxLength": 500, "nullable": true }, "footer_text": { "type": "string", "maxLength": 500, "nullable": true }, "custom_mentions": { "type": "string", "maxLength": 2000, "nullable": true }, "advanced_options": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Template cree", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operation interdite (scope ou propriete)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] } }, "/v1/invoice-templates/{template}": { "get": { "tags": [ "Invoice Templates" ], "summary": "Recuperer un template de facture", "operationId": "ef88e2c6b20303fc4970c3f50b9f868e", "parameters": [ { "name": "template", "in": "path", "description": "ID du template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Acces interdit a ce template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] }, "put": { "tags": [ "Invoice Templates" ], "summary": "Mettre a jour un template de facture (alias de PATCH)", "operationId": "689575335c232a13f5cd9879b8a742b8", "parameters": [ { "name": "template", "in": "path", "description": "ID du template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "is_default": { "type": "boolean" }, "is_available_to_subtenants": { "type": "boolean" }, "logo_url": { "type": "string", "maxLength": 2048, "nullable": true }, "logo_position": { "type": "string", "enum": [ "top-left", "top-center", "top-right" ], "nullable": true }, "primary_color": { "type": "string", "nullable": true }, "accent_color": { "type": "string", "nullable": true }, "text_color": { "type": "string", "nullable": true }, "background_color": { "type": "string", "nullable": true }, "header_text": { "type": "string", "maxLength": 500, "nullable": true }, "footer_text": { "type": "string", "maxLength": 500, "nullable": true }, "custom_mentions": { "type": "string", "maxLength": 2000, "nullable": true }, "advanced_options": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Template mis a jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Modification interdite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] }, "delete": { "tags": [ "Invoice Templates" ], "summary": "Supprimer un template de facture", "operationId": "927f17b98f9b5c5f02f5d50892b76da3", "parameters": [ { "name": "template", "in": "path", "description": "ID du template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Template supprime" }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Suppression interdite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] }, "patch": { "tags": [ "Invoice Templates" ], "summary": "Mettre a jour un template de facture", "description": "Met a jour partiellement un template. Disponible aussi en PUT (`/v1/invoice-templates/{template}`).", "operationId": "74be4bfbc53be2194f99466eb9f05dd5", "parameters": [ { "name": "template", "in": "path", "description": "ID du template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "is_default": { "type": "boolean" }, "is_available_to_subtenants": { "type": "boolean" }, "logo_url": { "type": "string", "maxLength": 2048, "nullable": true }, "logo_position": { "type": "string", "enum": [ "top-left", "top-center", "top-right" ], "nullable": true }, "primary_color": { "description": "Hex ou 'transparent'.", "type": "string", "nullable": true }, "accent_color": { "type": "string", "nullable": true }, "text_color": { "type": "string", "nullable": true }, "background_color": { "type": "string", "nullable": true }, "header_text": { "type": "string", "maxLength": 500, "nullable": true }, "footer_text": { "type": "string", "maxLength": 500, "nullable": true }, "custom_mentions": { "type": "string", "maxLength": 2000, "nullable": true }, "advanced_options": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Template mis a jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Modification interdite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] } }, "/v1/invoice-templates/{template}/default": { "put": { "tags": [ "Invoice Templates" ], "summary": "Definir un template comme defaut", "description": "Marque le template comme defaut pour son owner et retire le flag des autres templates du meme scope.", "operationId": "f7f1489a323e8bf7fbf9865f99cee643", "parameters": [ { "name": "template", "in": "path", "description": "ID du template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template marque comme defaut", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operation interdite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] } }, "/v1/invoice-templates/{template}/logo": { "post": { "tags": [ "Invoice Templates" ], "summary": "Uploader le logo d'un template", "description": "Upload d'un logo (multipart) stocke sur S3 et associe au template. Formats : jpeg, png, webp, svg/svgz. Taille max : 2 Mo.", "operationId": "14a971443192bcab12f8af052d10ee19", "parameters": [ { "name": "template", "in": "path", "description": "ID du template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "logo" ], "properties": { "logo": { "description": "Fichier logo (jpeg, png, webp, svg, svgz — max 2 Mo).", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Logo uploade, template mis a jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InvoiceTemplate" } }, "type": "object" } } } }, "401": { "description": "Non authentifie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Operation interdite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Fichier invalide", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] }, { "bearerAuth": [] } ] } }, "/v1/legal/{slug}": { "get": { "tags": [ "Legal" ], "summary": "Document légal versionné (public)", "description": "Retourne la version publiée courante d'un document légal (dpa, cgv, cgu, confidentialite, cookies, mentions-legales) avec son contenu localisé et sa date d'entrée en vigueur.", "operationId": "eb34deb5865bc47e089cdd7cde70f750", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "dpa" }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fr", "en" ] }, "example": "fr" } ], "responses": { "200": { "description": "Document légal" }, "404": { "description": "Document légal introuvable" } } } }, "/api/v1/payment-schedule-presets": { "get": { "tags": [ "Misc", "Payment Schedule" ], "summary": "Lister les préréglages de plans de paiement", "description": "Retourne la liste des préréglages prédéfinis de plans de paiement. Ces préréglages sont définis en code (pas en DB) et représentent des combinaisons courantes de conditions de paiement. À utiliser avec `POST /api/v1/quotes/{quote}/payment-schedule` pour appliquer un plan.", "operationId": "listPaymentSchedulePresets", "responses": { "200": { "description": "Liste des préréglages disponibles", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentSchedulePreset" } }, "message": { "type": "string", "example": "Préréglages disponibles." } }, "type": "object" } } } }, "401": { "description": "Authentification requise" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/v1/newsletter/subscribe": { "post": { "tags": [ "Public" ], "summary": "S'abonner a la newsletter", "description": "Inscrit une adresse email a la newsletter du blog (double opt-in : un email de confirmation est ensuite envoye). Pas d'authentification. Rate-limit : 5/min par IP.", "operationId": "d4af1b74b599e6f9006444eb51bc6773", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "description": "Adresse email a abonner.", "type": "string", "format": "email", "maxLength": 255, "example": "lecteur@example.com" }, "locale": { "description": "Langue de la newsletter (defaut: fr).", "type": "string", "enum": [ "fr", "en" ], "example": "fr", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Email de confirmation envoye (ou deja abonne)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Un email de confirmation vous a ete envoye." }, "email": { "type": "string", "format": "email", "example": "lecteur@example.com" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Trop de requetes (rate-limit depasse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/newsletter/confirm/{token}": { "get": { "tags": [ "Public" ], "summary": "Confirmer l'abonnement newsletter", "description": "Confirme l'abonnement via le token recu par email (double opt-in). Pas d'authentification.", "operationId": "e1a106d9e096caef3bd5d83d3c49e4b7", "parameters": [ { "name": "token", "in": "path", "description": "Token de confirmation recu par email.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Abonnement confirme (ou deja confirme)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Votre abonnement a ete confirme." } }, "type": "object" } } } }, "404": { "description": "Token invalide ou expire", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Token invalide ou expire." } }, "type": "object" } } } } }, "security": [] } }, "/v1/newsletter/unsubscribe/{token}": { "get": { "tags": [ "Public" ], "summary": "Se desabonner de la newsletter", "description": "Desabonne via le token de desinscription. Pas d'authentification.", "operationId": "3a32810594f13e436bc52a779bf31a57", "parameters": [ { "name": "token", "in": "path", "description": "Token de desinscription.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Desabonnement effectue", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Vous avez ete desabonne." } }, "type": "object" } } } }, "404": { "description": "Lien de desinscription invalide", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Lien de desinscription invalide." } }, "type": "object" } } } } }, "security": [] } }, "/v1/onboarding/sessions": { "post": { "tags": [ "Onboarding" ], "summary": "Creer une session d'onboarding", "description": "Initialise une nouvelle session d'onboarding pour un tenant parent.\n\n### Modes disponibles\n- `api` : Integration full API\n- `redirect` : Redirection vers interface Scell.io\n- `embedded` : Integration iframe\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/onboarding/sessions\" \\\n -H \"X-Publishable-Key: pk_test_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"mode\": \"redirect\", \"callback_url\": \"https://myapp.com/callback\", \"external_id\": \"user_123\"}'\n```", "operationId": "5b2b160d8d1a41d07006bf52049969d2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "api", "redirect", "embedded" ] }, "external_id": { "type": "string", "nullable": true }, "callback_url": { "type": "string", "format": "uri", "nullable": true }, "state": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Session creee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/OnboardingSession" } }, "type": "object" } } } }, "401": { "description": "Tenant parent non authentifie" }, "422": { "description": "Erreur de validation" } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/v1/onboarding/sessions/{id}": { "get": { "tags": [ "Onboarding" ], "summary": "Statut d'une session", "description": "Retourne le statut et les details d'une session d'onboarding.", "operationId": "e73b14816a0b5f5debdc7f5a23b93237", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Details de la session", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/OnboardingSession" } }, "type": "object" } } } }, "404": { "description": "Session non trouvee" } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/v1/onboarding/exchange": { "post": { "tags": [ "Onboarding" ], "summary": "Echanger le code d'autorisation (mode redirect)", "description": "Echange le code d'autorisation obtenu apres le redirect contre les credentials du tenant.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/onboarding/exchange\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"authorization_code\": \"obc_xxxx\",\n \"parent_tenant_key\": \"sk_test_xxxx\"\n }'\n```", "operationId": "e925491238c7bcffa3c133ede3a1e4e3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "authorization_code", "parent_tenant_key" ], "properties": { "authorization_code": { "type": "string" }, "parent_tenant_key": { "description": "Secret API key (sk_*) of parent tenant", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Credentials du tenant", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "400": { "description": "Code invalide ou expire" }, "401": { "description": "Tenant non authentifie" } }, "security": [] } }, "/v1/onboarding/superpdp/authorize": { "post": { "tags": [ "Onboarding" ], "summary": "Obtenir l'URL d'autorisation SuperPDP", "description": "Genere l'URL de redirection vers le tunnel OAuth2 SuperPDP pour la creation de compte KYB/identite. Stocke un state CSRF dans les metadata de la session.", "operationId": "ed8d4c0a4466364532baa9f3a7af68cd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "URL d'autorisation SuperPDP", "content": { "application/json": { "schema": { "properties": { "authorize_url": { "type": "string", "format": "uri" }, "state": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Session inactive ou introuvable" }, "422": { "description": "Erreur de validation" } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/v1/onboarding/superpdp/callback": { "post": { "tags": [ "Onboarding" ], "summary": "Callback OAuth2 SuperPDP", "description": "Echange le code d'autorisation SuperPDP, recupere les informations entreprise et cree le tenant.", "operationId": "fa2310a6361cd98fab1135327e2dda9b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "session_id", "code", "state" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "code": { "description": "Code d'autorisation retourne par SuperPDP", "type": "string" }, "state": { "description": "State CSRF a verifier", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tenant cree via SuperPDP", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "authorization_code": { "type": "string" }, "tenant": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "siret": { "type": "string", "nullable": true }, "environment": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "State invalide, session inactive ou code invalide" }, "503": { "description": "SuperPDP indisponible" } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/v1/pricing/public": { "get": { "tags": [ "Pricing" ], "summary": "Tarifs publics", "description": "Retourne les tarifs globaux de la plateforme sans authentification. N'inclut pas les overrides specifiques aux tenants.", "operationId": "8fc56cd4ddb39c7e3e85f20f56262b77", "responses": { "200": { "description": "Tarifs publics", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoice_rate": { "type": "number", "format": "float", "example": 0.04 }, "signature_rate": { "type": "number", "format": "float", "example": 0.1 }, "currency": { "type": "string", "example": "EUR" } }, "type": "object" } }, "type": "object" } } } } }, "security": [] } }, "/v1/packs/public": { "get": { "tags": [ "Pricing" ], "summary": "Packs prepayes publics", "description": "Retourne les paliers prepayes actifs visibles depuis le site marketing. Pas d'authentification.", "operationId": "d40fb29f13f7706fe9b0bdbf8f5bac65", "responses": { "200": { "description": "Packs actifs ordonnes par position", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "example": "pro" }, "name": { "type": "string", "example": "Pro" }, "description": { "type": "string", "nullable": true }, "amount_eur": { "description": "Prix en centimes", "type": "integer", "example": 20000 }, "amount_euros": { "type": "number", "format": "float", "example": 200 }, "credits_eur": { "description": "Credits en centimes", "type": "integer", "example": 21000 }, "credits_euros": { "type": "number", "format": "float", "example": 210 }, "bonus_eur": { "description": "Bonus en centimes", "type": "integer", "example": 1000 }, "bonus_euros": { "type": "number", "format": "float", "example": 10 }, "bonus_percent": { "type": "number", "format": "float", "example": 5 }, "currency": { "type": "string", "example": "EUR" }, "position": { "type": "integer", "example": 2 }, "is_recommended": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } } }, "security": [] } }, "/v1/pricing": { "get": { "tags": [ "Pricing" ], "summary": "Tarifs de l'utilisateur connecte (dashboard)", "description": "Retourne les tarifs applicables a l'utilisateur connecte via session (dashboard). Inclut les overrides tenant si presents.", "operationId": "1cd8a93c213aaf7f911673ef9e59d3ec", "responses": { "200": { "description": "Tarifs effectifs", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoice_rate": { "type": "number", "format": "float", "example": 0.04 }, "signature_rate": { "type": "number", "format": "float", "example": 0.1 }, "currency": { "type": "string", "example": "EUR" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/tenant/pricing": { "get": { "tags": [ "Pricing" ], "summary": "Tarifs du tenant (API key)", "description": "Retourne les tarifs applicables au tenant authentifie via sa cle API secrete. Inclut les overrides tenant si presents.", "operationId": "fd1cbb0a2326cfb62ba653c9802b9cf1", "responses": { "200": { "description": "Tarifs effectifs du tenant", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoice_rate": { "type": "number", "format": "float", "example": 0.04 }, "signature_rate": { "type": "number", "format": "float", "example": 0.1 }, "currency": { "type": "string", "example": "EUR" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/quotes": { "get": { "tags": [ "Quotes" ], "summary": "Lister les devis (scope tenant/sub_tenant)", "operationId": "b0c63e69415e32c4897aa117090524dc", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginée des devis", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } }, "type": "object" } } } }, "401": { "description": "Non authentifié" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "tags": [ "Quotes" ], "summary": "Créer un devis", "description": "Crée un devis (statut `draft`).\n\n### Identification de l'acheteur (2 stratégies mutuellement exclusives)\n\n1. **`buyer_id`** — UUID d'une entrée du registre des acheteurs (scope tenant/sub_tenant). Le contrôleur snapshote l'entrée sur le devis.\n2. **Champs `buyer_*` à plat** — le contrôleur upsert/crée un acheteur. `buyer_name`, `buyer_country` et `buyer_address` deviennent alors obligatoires ; `buyer_siret` n'est requis que pour une entreprise FR (`buyer_is_individual` absent/false + `buyer_country=FR`).\n\nPassez `sub_tenant_id` pour émettre au nom d'un sous-locataire (anti-IDOR : 404 si hors scope).", "operationId": "4cdf887a54c147e041b99ebb03f8777e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "issue_date", "currency", "lines" ], "properties": { "sub_tenant_id": { "description": "Émettre au nom d'un sous-locataire du tenant courant.", "type": "string", "format": "uuid", "nullable": true }, "issue_date": { "type": "string", "format": "date", "example": "2026-05-28" }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "currency": { "type": "string", "maxLength": 3, "minLength": 3, "example": "EUR" }, "title": { "type": "string", "maxLength": 255, "nullable": true }, "description": { "type": "string", "maxLength": 5000, "nullable": true }, "internal_notes": { "type": "string", "maxLength": 5000, "nullable": true }, "external_id": { "type": "string", "maxLength": 100, "nullable": true }, "invoice_template_id": { "type": "string", "format": "uuid", "nullable": true }, "callback_url": { "type": "string", "format": "uri", "maxLength": 500, "nullable": true }, "signature_required": { "type": "boolean", "nullable": true }, "auto_convert_on_accept": { "type": "boolean", "nullable": true }, "buyer_id": { "description": "UUID du registre acheteurs (alternative aux champs buyer_* à plat).", "type": "string", "format": "uuid", "nullable": true }, "buyer_name": { "type": "string", "maxLength": 255, "nullable": true }, "buyer_country": { "type": "string", "maxLength": 2, "minLength": 2, "example": "FR", "nullable": true }, "buyer_is_individual": { "type": "boolean", "nullable": true }, "buyer_siret": { "description": "Requis seulement pour une entreprise FR.", "type": "string", "maxLength": 14, "minLength": 14, "nullable": true }, "buyer_vat_number": { "type": "string", "maxLength": 20, "nullable": true }, "buyer_legal_id": { "type": "string", "maxLength": 50, "nullable": true }, "buyer_legal_id_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "buyer_email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "buyer_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true }, "buyer_shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true }, "lines": { "type": "array", "items": { "required": [ "description", "quantity", "unit_price_ht", "tax_rate" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "detail": { "type": "string", "maxLength": 1000, "nullable": true }, "quantity": { "type": "number", "format": "float", "minimum": 0.001 }, "unit": { "type": "string", "maxLength": 50, "nullable": true }, "unit_price_ht": { "type": "number", "format": "float", "minimum": 0 }, "tax_rate": { "type": "number", "format": "float", "maximum": 100, "minimum": 0 }, "reference": { "type": "string", "maxLength": 100, "nullable": true }, "position": { "type": "integer", "minimum": 1, "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" }, "minItems": 1 }, "metadata": { "type": "object", "nullable": true } }, "type": "object" }, "example": { "issue_date": "2026-05-28", "expiration_date": "2026-06-28", "currency": "EUR", "title": "Devis prestation de conseil", "buyer_name": "ACME SARL", "buyer_country": "FR", "buyer_siret": "98765432109876", "buyer_email": "compta@acme.fr", "buyer_address": { "line1": "10 rue de la Paix", "postal_code": "75002", "city": "Paris", "country": "FR" }, "lines": [ { "description": "Audit technique", "quantity": 2, "unit": "jour", "unit_price_ht": 500, "tax_rate": 20 } ] } } } }, "responses": { "201": { "description": "Devis créé", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "401": { "description": "Non authentifié" }, "403": { "description": "Interdit (KYB/KYC/sub-tenant non prêt)" }, "404": { "description": "Acheteur (buyer_id) ou sub-tenant introuvable / hors scope" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}": { "get": { "tags": [ "Quotes" ], "summary": "Récupérer un devis", "operationId": "338ea0baa6a0f28f8379fa005bf6e3f9", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Devis trouvé", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "404": { "description": "Devis introuvable ou hors scope" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "tags": [ "Quotes" ], "summary": "Supprimer un devis", "operationId": "43c944bf48915d19f19b092deb5f71af", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Supprimé" }, "403": { "description": "Interdit — statut non supprimable" }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "tags": [ "Quotes" ], "summary": "Mettre à jour un devis (DRAFT uniquement)", "description": "Mise à jour partielle d'un devis en statut `draft`. Tous les champs sont optionnels. Le même endpoint est exposé en `PUT`. Si `lines` est fourni, il remplace entièrement les lignes (min 1).", "operationId": "121553b2cda7067889cede66d1aec2f3", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "issue_date": { "type": "string", "format": "date" }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "currency": { "type": "string", "maxLength": 3, "minLength": 3 }, "title": { "type": "string", "maxLength": 255, "nullable": true }, "description": { "type": "string", "maxLength": 5000, "nullable": true }, "internal_notes": { "type": "string", "maxLength": 5000, "nullable": true }, "external_id": { "type": "string", "maxLength": 100, "nullable": true }, "invoice_template_id": { "type": "string", "format": "uuid", "nullable": true }, "callback_url": { "type": "string", "format": "uri", "maxLength": 500, "nullable": true }, "signature_required": { "type": "boolean" }, "auto_convert_on_accept": { "type": "boolean" }, "buyer_id": { "type": "string", "format": "uuid", "nullable": true }, "buyer_name": { "type": "string", "maxLength": 255, "nullable": true }, "buyer_country": { "type": "string", "maxLength": 2, "minLength": 2 }, "buyer_is_individual": { "type": "boolean" }, "buyer_siret": { "type": "string", "maxLength": 14, "minLength": 14, "nullable": true }, "buyer_vat_number": { "type": "string", "maxLength": 20, "nullable": true }, "buyer_legal_id": { "type": "string", "maxLength": 50, "nullable": true }, "buyer_legal_id_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "buyer_email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "buyer_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true }, "buyer_shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteLine" }, "minItems": 1 }, "metadata": { "type": "object", "nullable": true } }, "type": "object" }, "example": { "title": "Devis prestation de conseil (révisé)", "expiration_date": "2026-07-15" } } } }, "responses": { "200": { "description": "Devis mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "403": { "description": "Interdit — statut non modifiable" }, "404": { "description": "Introuvable" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/preview": { "post": { "tags": [ "Quotes" ], "summary": "Prévisualiser un devis en PDF (sans persistance)", "operationId": "629d6ab120bbae914e617b9a6f99ea63", "responses": { "200": { "description": "PDF généré (application/pdf)" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/send": { "post": { "tags": [ "Quotes" ], "summary": "Envoyer le devis par email au destinataire", "description": "Envoie le devis par email. À défaut de `recipient_email`, l'email de l'acheteur du devis est utilisé.", "operationId": "781090b4ce45823914789dc0155aed29", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "recipient_email": { "description": "Override du destinataire (défaut: buyer_email du devis).", "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "send_now": { "type": "boolean", "nullable": true }, "message": { "description": "Message personnalisé inclus dans l'email.", "type": "string", "maxLength": 2000, "nullable": true } }, "type": "object" }, "example": { "recipient_email": "compta@acme.fr", "message": "Bonjour, veuillez trouver notre devis ci-joint." } } } }, "responses": { "200": { "description": "Devis envoyé" }, "403": { "description": "Interdit" }, "404": { "description": "Introuvable" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/cancel": { "post": { "tags": [ "Quotes" ], "summary": "Annuler le devis", "operationId": "163c9483cd6ddbf48bf797755fca36de", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Motif d'annulation (tracé dans l'audit log).", "type": "string", "maxLength": 1000, "nullable": true } }, "type": "object" }, "example": { "reason": "Projet abandonné par le client." } } } }, "responses": { "200": { "description": "Devis annulé" }, "403": { "description": "Interdit" }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/duplicate": { "post": { "tags": [ "Quotes" ], "summary": "Dupliquer le devis (crée un brouillon)", "operationId": "e7f9fd0555c995e0774a740bb8b25202", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis source", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "issue_date": { "description": "Date d'émission du doublon (défaut: aujourd'hui).", "type": "string", "format": "date", "nullable": true }, "expiration_date": { "type": "string", "format": "date", "nullable": true } }, "type": "object" }, "example": { "issue_date": "2026-05-28", "expiration_date": "2026-06-28" } } } }, "responses": { "201": { "description": "Doublon créé", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Quote" } }, "type": "object" } } } }, "403": { "description": "Interdit" }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/convert-to-deposit": { "post": { "tags": [ "Quotes" ], "summary": "Convertir le devis accepté en facture d'acompte", "description": "Crée une facture d'acompte (type 386, TVA immédiatement exigible — CGI art. 289) depuis un devis accepté. Peut être appelé N fois.", "operationId": "0a4fb5e72c4019c28cefd83fbdf45c42", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis accepté", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "value", "due_date" ], "properties": { "type": { "description": "Mode de calcul de l'acompte.", "type": "string", "enum": [ "percent", "amount" ] }, "value": { "description": "Pourcentage (si type=percent) ou montant HT (si type=amount).", "type": "number", "format": "float", "minimum": 0.01 }, "label": { "type": "string", "maxLength": 200, "nullable": true }, "due_date": { "description": "Échéance (>= aujourd'hui).", "type": "string", "format": "date" } }, "type": "object" }, "example": { "type": "percent", "value": 30, "label": "Acompte 30 %", "due_date": "2026-06-15" } } } }, "responses": { "201": { "description": "Facture d'acompte créée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Interdit — devis non accepté ou solde déjà émis" }, "404": { "description": "Introuvable" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/convert-to-balance": { "post": { "tags": [ "Quotes" ], "summary": "Convertir le devis accepté en facture de solde", "description": "Crée la facture de solde (type 380, finale). La TVA déjà collectée sur les acomptes est déduite automatiquement (BG-22 code 80). Appelable une seule fois.", "operationId": "ec305531eef2a7e5a974ab6c7ea9504c", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis accepté", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "due_date" ], "properties": { "due_date": { "description": "Échéance (>= aujourd'hui).", "type": "string", "format": "date" }, "label": { "type": "string", "maxLength": 200, "nullable": true } }, "type": "object" }, "example": { "due_date": "2026-07-15", "label": "Solde" } } } }, "responses": { "201": { "description": "Facture de solde créée", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Interdit" }, "404": { "description": "Introuvable" }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/audit-log": { "get": { "tags": [ "Quotes" ], "summary": "Journal d'audit du devis", "description": "Retourne la chaîne d'audit (SHA-256, distincte du ledger fiscal ISCA) du devis : création, envoi, vue, acceptation/refus, conversions.", "operationId": "de54c6e886664119353e006bdbe8c35c", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Logs d'audit", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "ip_address": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/regenerate-public-link": { "post": { "tags": [ "Quotes" ], "summary": "Régénérer le lien public signé du devis", "description": "Invalide l'ancien lien et génère une nouvelle URL signée (HMAC) avec un nouveau `public_token`.", "operationId": "4c76fa2fe77a56051deced0e6edecd95", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "ttl_days": { "description": "Durée de validité du lien en jours (défaut: 30).", "type": "integer", "maximum": 365, "minimum": 1, "example": 30 } }, "type": "object" } } } }, "responses": { "200": { "description": "Nouveau lien généré", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "public_url": { "type": "string", "format": "uri" } }, "type": "object" } } } }, "403": { "description": "Interdit" }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/revoke-public-link": { "post": { "tags": [ "Quotes" ], "summary": "Révoquer le lien public du devis", "operationId": "fc7e9548a49335c3294cd04a50863fb0", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lien révoqué" }, "403": { "description": "Interdit" }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/quotes/{quote}/pdf": { "get": { "tags": [ "Quotes" ], "summary": "Télécharger le PDF du devis", "operationId": "6c1fd46733177f218c8d931064a34ee3", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fichier PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Introuvable" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/v1/branding/sub-tenants/{subTenant}": { "get": { "tags": [ "Branding" ], "summary": "Lire le branding email d'un sub-tenant", "description": "Retourne le branding de la Company du sub-tenant. Anti-IDOR : le sub-tenant doit appartenir au tenant courant.", "operationId": "getSubTenantBranding", "parameters": [ { "name": "subTenant", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Branding du sub-tenant", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Sub-tenant hors scope du tenant courant" }, "404": { "description": "Sub-tenant sans Company" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "put": { "tags": [ "Branding" ], "summary": "Remplacer le branding email d'un sub-tenant (PUT)", "description": "Remplacement complet du branding du sub-tenant. Les champs absents sont mis à null.", "operationId": "updateSubTenantBrandingPut", "parameters": [ { "name": "subTenant", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Sub-tenant hors scope" }, "404": { "description": "Sub-tenant sans Company" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "patch": { "tags": [ "Branding" ], "summary": "Mise à jour partielle du branding d'un sub-tenant (PATCH)", "description": "Seuls les champs présents dans le payload sont mis à jour.", "operationId": "updateSubTenantBrandingPatch", "parameters": [ { "name": "subTenant", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Sub-tenant hors scope" }, "404": { "description": "Sub-tenant sans Company" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants": { "get": { "tags": [ "Sub-Tenants" ], "summary": "Liste des sub-tenants", "description": "Retourne la liste paginee des sub-tenants du tenant.\n\n### Filtres disponibles\n- `search` : Recherche par nom, external_id ou SIRET\n- `is_active` : Filtrer par statut actif/inactif\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants?search=acme&is_active=true\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/tenant/sub-tenants', [\n 'headers' => ['X-API-Key' => 'sk_live_xxxxxx'],\n 'query' => ['search' => 'acme', 'is_active' => true]\n]);\n```", "operationId": "70d9fb8cba052148682f05ea4e0ab5ad", "parameters": [ { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "search", "in": "query", "description": "Recherche par nom, external_id ou SIRET", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filtrer par statut actif", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Liste paginee", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubTenant" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Sub-Tenants" ], "summary": "Creer un sub-tenant", "description": "Cree un nouveau sub-tenant (client final) pour le tenant.\n\n### external_id\nL'`external_id` est un identifiant unique dans votre systeme. Il permet de referencer\nvos clients sans avoir a stocker les UUIDs Scell.io.\n\n### Onboarding (refonte 2026-05-08, widget v3)\nLe SubTenant cree manuellement via cet endpoint a `onboarding_status='active'`\npar defaut (le tenant master assume la verification). Pour un onboarding\ncomplet KYB SuperPDP, preferer le widget v3 (`POST /widget/onboarding/sub-tenant`).\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/sub-tenants\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"external_id\": \"client_123\",\n \"name\": \"ACME Corp\",\n \"siret\": \"12345678901234\",\n \"contact_email\": \"contact@acme.com\"\n }'\n```", "operationId": "550e0295e095bb3c29ac30d177c39893", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "external_id", "name" ], "properties": { "external_id": { "description": "ID unique dans votre systeme", "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "vat_number": { "type": "string", "maxLength": 50 }, "address": { "properties": { "line1": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "maxLength": 2, "minLength": 2 } }, "type": "object" }, "contact_email": { "type": "string", "format": "email" }, "contact_phone": { "type": "string" }, "onboarding_status": { "description": "Defaut \"active\" pour creation manuelle (Bearer). Widget v3 utilise des autres statuts.", "type": "string", "default": "active", "enum": [ "pending_superpdp", "superpdp_redirected", "superpdp_authorized", "superpdp_pending_review", "active", "superpdp_failed" ] }, "settings": { "type": "object" }, "metadata": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Sub-tenant cree", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Sub-tenant cree avec succes" }, "data": { "$ref": "#/components/schemas/SubTenant" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{id}": { "get": { "tags": [ "Sub-Tenants" ], "summary": "Detail sub-tenant", "description": "Retourne les details complets d'un sub-tenant avec ses statistiques.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "597aa81c157a15a0d0502766d7ba9aef", "parameters": [ { "name": "id", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/SubTenant" }, { "properties": { "stats": { "properties": { "companies_count": { "type": "integer" }, "invoices_count": { "type": "integer" }, "signatures_count": { "type": "integer" } }, "type": "object" } }, "type": "object" } ] } }, "type": "object" } } } }, "404": { "description": "Non trouve" } }, "security": [ { "apiKeyAuth": [] } ] }, "put": { "tags": [ "Sub-Tenants" ], "summary": "Modifier sub-tenant", "description": "Met a jour les informations d'un sub-tenant.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X PUT \"https://api.scell.io/api/v1/tenant/sub-tenants/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"ACME Corp - Nouveau nom\",\n \"is_active\": false\n }'\n```", "operationId": "9017f6e4e4beb2c13795a12d49adf210", "parameters": [ { "name": "id", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "siret": { "type": "string", "maxLength": 14, "minLength": 14, "nullable": true }, "vat_number": { "type": "string", "maxLength": 50, "nullable": true }, "address": { "type": "object", "nullable": true }, "contact_email": { "type": "string", "format": "email", "nullable": true }, "contact_phone": { "type": "string", "nullable": true }, "settings": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Modifie", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Sub-tenant mis a jour" }, "data": { "$ref": "#/components/schemas/SubTenant" } }, "type": "object" } } } }, "404": { "description": "Non trouve" }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] }, "delete": { "tags": [ "Sub-Tenants" ], "summary": "Supprimer sub-tenant", "description": "Supprime un sub-tenant (soft delete) et optionnellement ses entreprises rattachees.\n\n### Politique (compliance ISCA)\n\n- Sans Companies rattachees -> 200 OK direct\n- Avec Companies sans facture emise + ?cascade=true -> cascade delete + 200 OK\n- Avec Companies sans facture emise (cascade non passe) -> 422 + code=SUB_TENANT_HAS_COMPANIES + companies_count\n- Avec au moins une Invoice ou CreditNote emise -> 422 + code=SUB_TENANT_HAS_FISCAL_ENTRIES (REFUS systematique, autocertification fiscale)\n\nPour les sub-tenants avec factures emises, preferez PUT is_active=false plutot que delete.\n\n### Exemples\n\n**cURL**\n```bash\n# Delete simple (echoue avec 422 si Companies presentes)\ncurl -X DELETE \"https://api.scell.io/api/v1/tenant/sub-tenants/550e8400-...\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n\n# Delete avec cascade des Companies orphelines\ncurl -X DELETE \"https://api.scell.io/api/v1/tenant/sub-tenants/550e8400-...?cascade=true\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "3fe8f1987627a3992fc39f564ad0095d", "parameters": [ { "name": "id", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cascade", "in": "query", "description": "Si true, supprime aussi les Companies orphelines (sans factures).", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Supprime", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Sub-tenant supprime" }, "companies_deleted": { "description": "Nombre de Companies supprimees par la cascade", "type": "integer", "example": 0 } }, "type": "object" } } } }, "404": { "description": "Non trouve" }, "422": { "description": "Impossible de supprimer (deux scenarios distincts via le champ code)", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "SUB_TENANT_HAS_COMPANIES" ], "example": "SUB_TENANT_HAS_COMPANIES" }, "companies_count": { "description": "Nombre de Companies rattachees. Relancer avec ?cascade=true pour autoriser la suppression.", "type": "integer", "example": 1 } }, "type": "object" }, { "properties": { "error": { "type": "string" }, "code": { "description": "Au moins une Invoice ou CreditNote emise. Suppression refusee (compliance ISCA).", "type": "string", "enum": [ "SUB_TENANT_HAS_FISCAL_ENTRIES" ], "example": "SUB_TENANT_HAS_FISCAL_ENTRIES" } }, "type": "object" } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/tenant/sub-tenants/by-external-id/{externalId}": { "get": { "tags": [ "Sub-Tenants" ], "summary": "Rechercher par external_id", "description": "Recherche un sub-tenant par son identifiant externe.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/by-external-id/client_123\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "3fc0f738434a1f463bf805078955ae47", "parameters": [ { "name": "externalId", "in": "path", "description": "Identifiant externe", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trouve", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SubTenant" } }, "type": "object" } } } }, "404": { "description": "Non trouve" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/tenant/sub-tenants/{id}/superpdp-status": { "get": { "tags": [ "Sub-Tenants" ], "summary": "Statut SuperPDP d'un SubTenant", "description": "Retourne le SubTenant courant en base, sans appel reseau a SuperPDP. Utilise `last_polled_at` pour savoir quand a eu lieu le dernier refresh distant.\n\nPour forcer un refresh, utiliser POST `/superpdp-status/refresh` (rate-limited 1/min).", "operationId": "08ff946093c4bb192259f0ff16971c03", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SubTenant a jour.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SubTenantResource" } }, "type": "object" } } } }, "401": { "description": "Auth manquante ou invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SubTenant introuvable ou non scope sur ce tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/tenant/sub-tenants/{id}/superpdp-status/refresh": { "post": { "tags": [ "Sub-Tenants" ], "summary": "Force un refresh distant SuperPDP (rate-limited)", "description": "Force un appel `GET /oauth2_sessions/me` chez SuperPDP pour mettre a jour les statuts KYB et identite. Met a jour `last_polled_at` et `onboarding_status`.\n\n**Rate limit** : 1 appel par minute par SubTenant. Au-dela retourne 429 + `code=RATE_LIMITED`.\n\n### Cas du sub-tenant sans access_token SuperPDP\n\nSi le sub-tenant n'a jamais connecte SuperPDP (cree manuellement via API Bearer/Sanctum, sans passer par le widget v3), la reponse 422 inclut `code=MISSING_ACCESS_TOKEN` et un `authorize_url` fraichement genere. Ouvrez cette URL dans le navigateur de l'utilisateur final pour lancer le tunnel OAuth (le state CSRF + PKCE sont persistes en cache cote serveur pour validation au callback).", "operationId": "9cd2e7f3c6eb1f2d75a359bb42e5da30", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SubTenant rafraichi.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SubTenantResource" } }, "type": "object" } } } }, "401": { "description": "Auth manquante ou invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SubTenant introuvable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Refresh impossible — 2 scenarios distincts via le champ code.", "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "MISSING_ACCESS_TOKEN" ], "example": "MISSING_ACCESS_TOKEN" }, "authorize_url": { "description": "URL OAuth SuperPDP a ouvrir dans le navigateur de l'utilisateur final pour connecter le sub-tenant.", "type": "string", "format": "uri" }, "state": { "description": "State CSRF lie a l'authorize_url (persiste en cache 1h).", "type": "string" }, "message": { "description": "Message user-friendly explique pourquoi le refresh est impossible.", "type": "string" } }, "type": "object" }, { "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "REFRESH_FAILED" ], "example": "REFRESH_FAILED" } }, "type": "object" } ] } } } }, "429": { "description": "Rate limit (1 appel par minute par SubTenant).", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Trop de demandes. Reessayez dans 1 minute." }, "code": { "type": "string", "example": "RATE_LIMITED" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/tenant/sub-tenants/{id}/superpdp-authorize": { "post": { "tags": [ "Sub-Tenants" ], "summary": "Genere une URL d'authorize SuperPDP pour un sub-tenant", "description": "Construit une URL OAuth SuperPDP avec prefill (login_hint=email, superpdp_company_number=SIREN, PKCE S256). Persiste le state CSRF + code_verifier en cache (TTL 1h) pour validation au callback.\n\nCas d'usage :\n- Sub-tenant cree manuellement (sans widget v3) qui veut connecter SuperPDP\n- Re-authorize apres expiration des tokens\n- Equivalent Bearer/Sanctum de POST `/widget/onboarding/superpdp/authorize`\n\nLe frontend doit ouvrir l'`authorize_url` dans le navigateur de l'utilisateur final (typiquement `window.open(url, '_blank')`).", "operationId": "099425992f201b6ee6f63693997fd0df", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "URL d'authorize generee.", "content": { "application/json": { "schema": { "properties": { "authorize_url": { "description": "URL OAuth SuperPDP prefilled.", "type": "string", "format": "uri" }, "state": { "description": "State CSRF a valider au callback.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Auth manquante ou invalide." }, "404": { "description": "SubTenant introuvable." } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/tenant/sub-tenants/{id}/resume-url": { "post": { "tags": [ "Sub-Tenants" ], "summary": "Genere une signed URL de reprise SuperPDP (Bearer)", "description": "Equivalent Bearer de `GET /widget/onboarding/sub-tenant/{id}/resume-url` (publishable key). Permet aux integrations server-to-server (cron, dashboard admin) de generer des URLs de reprise SuperPDP a envoyer par email aux clients.\n\nSigned URL HMAC APP_KEY, TTL 7 jours. Retourne 422 si onboarding deja final.", "operationId": "1275800ace038c0e56727c8281b426f3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "URL generee.", "content": { "application/json": { "schema": { "properties": { "resume_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Auth manquante ou invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SubTenant introuvable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Onboarding deja final (active ou superpdp_failed).", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "ONBOARDING_ALREADY_FINAL" }, "onboarding_status": { "$ref": "#/components/schemas/OnboardingStatus" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/suppliers": { "get": { "tags": [ "Suppliers" ], "summary": "Lister les fournisseurs (scope tenant/sub_tenant)", "description": "Pagination par defaut 25, max 100. Recherche full-text sur name / siret / email via le parametre `q`.", "operationId": "9ecdacd31b01411d71b4082fec58b598", "parameters": [ { "name": "q", "in": "query", "description": "Recherche partielle sur name/siret/email", "required": false, "schema": { "type": "string" } }, { "name": "is_individual", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "post": { "tags": [ "Suppliers" ], "summary": "Creer un fournisseur", "operationId": "4cac2a9183d02b7967708ed1a636c0be", "responses": { "201": { "description": "Cree" }, "422": { "description": "Validation" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/suppliers/{supplier}": { "get": { "tags": [ "Suppliers" ], "summary": "Recuperer un fournisseur", "operationId": "92cfdee28d6c06ff9bb0e673f2d0d721", "responses": { "200": { "description": "Fournisseur trouve" }, "404": { "description": "Fournisseur introuvable ou hors scope" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "delete": { "tags": [ "Suppliers" ], "summary": "Supprimer un fournisseur (soft delete)", "operationId": "021e301e3fdede5e31fda176c69dfeb5", "responses": { "204": { "description": "Supprime" }, "404": { "description": "Fournisseur introuvable ou hors scope" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }, "patch": { "tags": [ "Suppliers" ], "summary": "Mettre a jour un fournisseur", "operationId": "bb2a98382a36b531b5361e8ca2095c41", "responses": { "200": { "description": "Mis a jour" }, "404": { "description": "Fournisseur introuvable ou hors scope" }, "422": { "description": "Validation" } }, "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] } }, "/api/v1/quotes/{quote}/payment-schedule": { "get": { "tags": [ "Payment Schedule" ], "summary": "Lister les lignes de l'échéancier d'un devis", "description": "Retourne toutes les lignes de l'échéancier de paiement d'un devis, triées par ordre d'affichage.", "operationId": "getQuotePaymentSchedule", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Liste des lignes de l'échéancier", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentScheduleLine" } } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé (devis d'un autre tenant)" }, "404": { "description": "Devis introuvable" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Payment Schedule" ], "summary": "Créer/remplacer l'échéancier d'un devis", "description": "Opération atomique : supprime les lignes pending/cancelled existantes et crée les nouvelles lignes. Les lignes déjà facturées (status=invoiced) sont préservées.", "operationId": "storeQuotePaymentSchedule", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "lines" ], "properties": { "lines": { "description": "Tableau de lignes à créer (remplace l'existant)", "type": "array", "items": { "$ref": "#/components/schemas/PaymentScheduleLineInput" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Échéancier créé avec succès", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentScheduleLine" } }, "message": { "type": "string", "example": "Échéancier créé avec succès." } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé ou devis verrouillé" }, "404": { "description": "Devis introuvable" }, "422": { "description": "Données invalides (montants, dates, total != 100% si percent)" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "delete": { "tags": [ "Payment Schedule" ], "summary": "Supprimer l'échéancier d'un devis", "description": "Supprime toutes les lignes pending/cancelled de l'échéancier. Échoue avec 422 si des lignes sont déjà facturées (compliance ISCA — la chaîne de hachage est immuable).", "operationId": "destroyQuotePaymentSchedule", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Échéancier supprimé (No Content)" }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé" }, "404": { "description": "Devis introuvable" }, "422": { "description": "L'échéancier contient des lignes déjà facturées", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "L'échéancier contient des lignes déjà facturées." }, "code": { "type": "string", "example": "SCHEDULE_HAS_INVOICED_LINES" }, "invoiced_count": { "type": "integer", "example": 2 } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "patch": { "tags": [ "Payment Schedule" ], "summary": "Modifier l'échéancier de façon chirurgicale", "description": "Modifie l'échéancier d'un devis de manière atomique avec les opérations `add`, `update` et `remove`. Seules les lignes non verrouillées (status=pending) peuvent être modifiées ou supprimées.", "operationId": "patchQuotePaymentSchedule", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "add": { "description": "Nouvelles lignes à ajouter", "type": "array", "items": { "$ref": "#/components/schemas/PaymentScheduleLineInput" }, "nullable": true }, "update": { "description": "Lignes existantes à mettre à jour (par leur id)", "type": "array", "items": { "required": [ "id" ], "properties": { "id": { "description": "UUID de la ligne à mettre à jour", "type": "string", "format": "uuid" }, "amount_type": { "type": "string", "enum": [ "percent", "fixed" ], "nullable": true }, "amount_value": { "type": "number", "format": "float", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "milestone_label": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "auto_generate": { "type": "boolean", "nullable": true } }, "type": "object" }, "nullable": true }, "remove": { "description": "UUIDs des lignes à supprimer (uniquement lignes pending)", "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Échéancier mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentScheduleLine" } }, "message": { "type": "string", "example": "Échéancier mis à jour." } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé ou devis verrouillé" }, "404": { "description": "Devis introuvable" }, "422": { "description": "Données invalides ou tentative de modifier une ligne verrouillée" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/quotes/{quote}/payment-summary": { "get": { "tags": [ "Payment Schedule" ], "summary": "Récapitulatif de paiement d'un devis", "description": "Retourne le tracker de paiement calculé : montants planifiés, facturés, solde restant, prochaine échéance, lignes en retard et statut SuperPDP des factures émises.", "operationId": "getQuotePaymentSummary", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Récapitulatif de paiement", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PaymentSummary" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé" }, "404": { "description": "Devis introuvable" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/quotes/{quote}/payment-schedule/lines/{line}/convert": { "post": { "tags": [ "Payment Schedule" ], "summary": "Convertir une ligne d'échéancier en facture d'acompte", "description": "Génère une facture d'acompte (type 386) depuis une ligne d'échéancier pending. La ligne passe en status=invoiced et est verrouillée. La facture est soumise à SuperPDP selon la configuration du tenant.", "operationId": "convertQuoteScheduleLine", "parameters": [ { "name": "quote", "in": "path", "description": "UUID du devis", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "line", "in": "path", "description": "UUID de la ligne d'échéancier", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "invoice_date": { "description": "Date de la facture (défaut : aujourd'hui, YYYY-MM-DD)", "type": "string", "format": "date", "nullable": true }, "due_date": { "description": "Date d'échéance de la facture (>= invoice_date)", "type": "string", "format": "date", "nullable": true }, "amount_override": { "description": "Montant TTC override (si non fourni, utilise amount_ttc_snapshot de la ligne)", "type": "number", "format": "float", "nullable": true }, "template_id": { "description": "UUID du template de facture à utiliser (optionnel)", "type": "string", "format": "uuid", "nullable": true }, "notes": { "description": "Notes internes (max 2000 car., BT-22 Factur-X)", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Facture d'acompte créée", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string", "example": "FA-2026-0001" }, "invoice_type": { "type": "string", "example": "deposit" }, "status": { "type": "string", "example": "validated" }, "total_ht": { "type": "number", "format": "float" }, "total_ttc": { "type": "number", "format": "float" }, "parent_quote_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "message": { "type": "string", "example": "Facture d'acompte créée depuis la ligne d'échéancier." } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "403": { "description": "Accès refusé ou ligne verrouillée" }, "404": { "description": "Devis ou ligne introuvable" }, "422": { "description": "La ligne est déjà facturée ou annulée" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/v1/tenant/auth/register": { "post": { "tags": [ "Tenant Auth" ], "summary": "Inscription d'un nouveau tenant", "description": "Cree un nouveau compte tenant avec email/mot de passe et retourne un token Bearer.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/auth/register\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"legal_name\": \"Mon Entreprise SAS\",\n \"auth_email\": \"contact@monentreprise.fr\",\n \"password\": \"motdepasse123\",\n \"siret\": \"12345678901234\"\n }'\n```", "operationId": "712ac92795ae1a0ef093720858d5543b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "legal_name", "auth_email", "password" ], "properties": { "legal_name": { "type": "string", "example": "Mon Entreprise SAS" }, "auth_email": { "type": "string", "format": "email", "example": "contact@monentreprise.fr" }, "password": { "type": "string", "format": "password", "minLength": 8 }, "siret": { "type": "string", "maxLength": 14, "minLength": 14, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Compte tenant cree", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Compte créé avec succès." }, "tenant": { "properties": { "id": { "type": "string", "format": "uuid" }, "legal_name": { "type": "string" }, "auth_email": { "type": "string", "format": "email" }, "siret": { "type": "string", "nullable": true }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } }, "type": "object" }, "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation" } }, "security": [] } }, "/v1/tenant/auth/login": { "post": { "tags": [ "Tenant Auth" ], "summary": "Connexion d'un tenant", "description": "Authentifie un tenant avec email/mot de passe et retourne un token Bearer.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/auth/login\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"auth_email\": \"contact@monentreprise.fr\", \"password\": \"motdepasse123\"}'\n```", "operationId": "bd5568ef6a759266ab330c504df75877", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "auth_email", "password" ], "properties": { "auth_email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Connexion reussie", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Connexion réussie." }, "tenant": { "type": "object" }, "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } } } }, "401": { "description": "Identifiants invalides" }, "403": { "description": "Compte desactive" } }, "security": [] } }, "/v1/tenant/auth/logout": { "post": { "tags": [ "Tenant Auth" ], "summary": "Deconnexion du tenant", "description": "Revoque tous les tokens Bearer du tenant courant.", "operationId": "dda80ca2306400f2155e1e8f72f89a9a", "responses": { "200": { "description": "Deconnexion reussie", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Déconnexion réussie." } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tenant/auth/me": { "get": { "tags": [ "Tenant Auth" ], "summary": "Profil du tenant connecte", "description": "Retourne les informations du tenant authentifie via son token Bearer.", "operationId": "5152f07491d45d4100d8be4646084345", "responses": { "200": { "description": "Profil tenant", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "format": "uuid" }, "legal_name": { "type": "string" }, "auth_email": { "type": "string", "format": "email" }, "siret": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true }, "billing_email": { "type": "string", "format": "email" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "kyb_status": { "type": "string" }, "balance": { "type": "number", "format": "float" }, "is_active": { "type": "boolean" }, "is_partner": { "type": "boolean" }, "publishable_key": { "type": "string", "nullable": true }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tenant/auth/keys/secret": { "post": { "tags": [ "Tenant Auth" ], "summary": "Generer une nouvelle cle secrete", "description": "Genere une nouvelle cle secrete (sk_*) pour le tenant. L'ancienne cle est immediatement invalidee. La nouvelle cle est affichee une seule fois.", "operationId": "25899758ca5bb59042e4e26a36a91384", "responses": { "201": { "description": "Cle secrete generee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "secret_key": { "description": "Affichee une seule fois", "type": "string" }, "prefix": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tenant/auth/keys/publishable": { "post": { "tags": [ "Tenant Auth" ], "summary": "Generer une cle publishable", "description": "Genere une cle publishable (pk_*) pour le tenant partenaire. Utilisee cote client pour le widget d'onboarding. Reservee aux tenants partenaires.", "operationId": "41ec77832d43457652d15b3a6711a6b0", "responses": { "201": { "description": "Cle publishable generee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "publishable_key": { "type": "string" }, "prefix": { "type": "string" }, "environment": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Tenant non partenaire" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tenant/auth/keys": { "get": { "tags": [ "Tenant Auth" ], "summary": "Lister les cles du tenant", "description": "Retourne les cles du tenant (prefix masque uniquement, sans le secret complet).", "operationId": "f7a9d4138b7cbf110930440436b6627b", "responses": { "200": { "description": "Liste des cles", "content": { "application/json": { "schema": { "properties": { "keys": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "secret", "publishable" ] }, "prefix": { "type": "string" }, "hint": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/tenant/billing/invoices": { "get": { "tags": [ "Tenant Billing" ], "summary": "Liste des factures", "description": "Retourne l'historique des factures mensuelles du tenant.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/billing/invoices\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "eefe045579fb0b15396a275a5d2f192c", "parameters": [ { "name": "limit", "in": "query", "description": "Nombre maximum de factures", "schema": { "type": "integer", "default": 12 } } ], "responses": { "200": { "description": "Liste des factures", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string", "example": "TENANT-202601-0001" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "total_ht": { "type": "number", "example": 100 }, "total_vat": { "type": "number", "example": 20 }, "total_ttc": { "type": "number", "example": 120 }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled" ] } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/invoices/{invoiceId}": { "get": { "tags": [ "Tenant Billing" ], "summary": "Detail facture", "description": "Retourne les details complets d'une facture.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/billing/invoices/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "1e4192de32ff4fffe6c313a5354713bf", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail de la facture", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/invoices/{invoiceId}/download": { "get": { "tags": [ "Tenant Billing" ], "summary": "Telecharger facture PDF", "description": "Telecharge la facture au format PDF.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/billing/invoices/550e8400-e29b-41d4-a716-446655440000/download\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -o facture.pdf\n```", "operationId": "898789bc2f992c7024e33fd32d6f3eba", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fichier PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Facture non trouvee" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/usage": { "get": { "tags": [ "Tenant Billing" ], "summary": "Consommation courante", "description": "Retourne la consommation du mois en cours avec projections.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/billing/usage\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "c66cb21a67db789ad75192d37cf404c0", "responses": { "200": { "description": "Consommation du mois", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoices_count": { "type": "integer" }, "invoices_amount": { "type": "number" }, "signatures_count": { "type": "integer" }, "signatures_amount": { "type": "number" }, "total_amount": { "type": "number" }, "projected": { "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/top-up": { "post": { "tags": [ "Tenant Billing" ], "summary": "Recharger la balance", "description": "Cree un PaymentIntent Stripe pour recharger la balance du tenant.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/billing/top-up\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"amount\": 100}'\n```", "operationId": "b0be2117d6815167a9fceff44356b595", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "description": "Montant a crediter en EUR", "type": "number", "maximum": 10000, "minimum": 10 }, "payment_method_id": { "description": "ID de la methode de paiement Stripe", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "PaymentIntent cree", "content": { "application/json": { "schema": { "properties": { "client_secret": { "description": "Client secret pour finaliser le paiement", "type": "string" }, "payment_intent_id": { "description": "ID du PaymentIntent", "type": "string" }, "amount": { "description": "Montant en centimes", "type": "integer" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation" }, "500": { "description": "Erreur Stripe" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/top-up/confirm": { "post": { "tags": [ "Tenant Billing" ], "summary": "Confirmer une recharge", "description": "Verifie et confirme une recharge apres paiement Stripe.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/billing/top-up/confirm\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"payment_intent_id\": \"pi_xxx\"}'\n```", "operationId": "85987f87d85b6ced7255c0fb5c4a8a7c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_intent_id" ], "properties": { "payment_intent_id": { "description": "ID du PaymentIntent Stripe", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Recharge confirmee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "transaction_id": { "type": "string" }, "amount": { "type": "number" }, "new_balance": { "type": "number" } }, "type": "object" } } } }, "400": { "description": "Paiement non complete" }, "404": { "description": "PaymentIntent non trouve" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/transactions": { "get": { "tags": [ "Tenant Billing" ], "summary": "Historique des transactions", "description": "Retourne l'historique des transactions (debits et credits).\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/billing/transactions?page=1&per_page=20\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "6265c44200ccbd508502db5c1596dd29", "parameters": [ { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "type", "in": "query", "description": "Filtrer par type", "schema": { "type": "string", "enum": [ "debit", "credit" ] } }, { "name": "service", "in": "query", "description": "Filtrer par service", "schema": { "type": "string", "enum": [ "invoice", "signature", "credit_note", "manual", "stripe" ] } } ], "responses": { "200": { "description": "Liste paginee des transactions", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object" }, "links": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/invoices/{invoiceId}/pay": { "post": { "tags": [ "Tenant Billing" ], "summary": "Initier le paiement d'une facture Scell.io", "description": "Crée un PaymentIntent Stripe pour payer une TenantInvoice en statut sent ou overdue.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/billing/invoices/550e8400-e29b-41d4-a716-446655440000/pay\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "fbe82d69dfbfa4a2385e97aace7e1263", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PaymentIntent créé ou récupéré", "content": { "application/json": { "schema": { "properties": { "client_secret": { "type": "string" }, "payment_intent_id": { "type": "string" }, "amount": { "description": "Montant en centimes", "type": "integer" }, "currency": { "type": "string", "example": "eur" }, "status": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvée" }, "422": { "description": "Facture non payable" }, "500": { "description": "Erreur Stripe" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/packs": { "get": { "tags": [ "Tenant Billing" ], "summary": "Liste des packs de crédits prépayés", "description": "Retourne les paliers de packs disponibles à l'achat (Découverte, Pro, Business, Enterprise...). Le bonus est inclus dans `credits_eur`.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/billing/packs\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "350ddc9d1d05fb7eeaa135e08ceb20a4", "responses": { "200": { "description": "Liste des packs actifs", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "example": "pro" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "amount_eur": { "description": "Prix payé (en centimes)", "type": "integer" }, "amount_euros": { "description": "Prix payé (en euros)", "type": "number" }, "credits_eur": { "description": "Crédits reçus (en centimes, bonus inclus)", "type": "integer" }, "credits_euros": { "description": "Crédits reçus (en euros)", "type": "number" }, "bonus_eur": { "description": "Bonus (en centimes)", "type": "integer" }, "bonus_percent": { "description": "Bonus en %", "type": "number" }, "currency": { "type": "string", "example": "EUR" }, "position": { "type": "integer" }, "is_recommended": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/billing/packs/{packSlug}/checkout": { "post": { "tags": [ "Tenant Billing" ], "summary": "Acheter un pack de crédits", "description": "Initie l'achat d'un pack prépayé. En sandbox, le crédit est appliqué immédiatement. En production, retourne un `client_secret` Stripe à confirmer côté frontend.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/billing/packs/pro/checkout\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "bb093b9e994370adce078cd3d993bf41", "parameters": [ { "name": "packSlug", "in": "path", "description": "Slug du pack (ex: starter, pro, business)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PaymentIntent réutilisé (idempotence)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "mode": { "type": "string", "example": "live_existing" }, "client_secret": { "type": "string" }, "payment_intent_id": { "type": "string" } }, "type": "object" } } } }, "201": { "description": "Pack acheté (sandbox bypass ou nouveau PaymentIntent live)", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "sandbox_bypass", "live" ] } }, "type": "object" } } } }, "401": { "description": "Tenant non résolu" }, "404": { "description": "Pack inconnu ou inactif" }, "500": { "description": "Erreur Stripe" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/v1/branding/tenant": { "get": { "tags": [ "Branding" ], "summary": "Lire le branding email du master tenant", "description": "Retourne la configuration branding (logo, couleur principale, pied de page, signature) de la Company par défaut du master tenant.", "operationId": "getTenantBranding", "responses": { "200": { "description": "Branding du tenant", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "404": { "description": "Tenant sans Company par défaut" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "put": { "tags": [ "Branding" ], "summary": "Remplacer le branding email du master tenant (PUT)", "description": "Remplacement complet du branding : les champs absents du payload sont mis à null.", "operationId": "updateTenantBrandingPut", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "404": { "description": "Tenant sans Company par défaut" }, "422": { "description": "Données invalides (couleur hex, URL logo, longueurs)" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] }, "patch": { "tags": [ "Branding" ], "summary": "Mise à jour partielle du branding du master tenant (PATCH)", "description": "Seuls les champs présents dans le payload sont mis à jour. Les champs absents restent inchangés.", "operationId": "updateTenantBrandingPatch", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingInput" } } } }, "responses": { "200": { "description": "Branding mis à jour", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Branding" } }, "type": "object" } } } }, "401": { "description": "Authentification requise" }, "404": { "description": "Tenant sans Company par défaut" }, "422": { "description": "Données invalides" } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/v1/tenant/me": { "get": { "tags": [ "Tenant" ], "summary": "Profil du tenant", "description": "Retourne les informations du tenant authentifie via sa cle API.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/me\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/tenant/me', [\n 'headers' => ['X-API-Key' => 'sk_live_xxxxxx']\n]);\n```", "operationId": "b0a4b0e0b81c333ee860b7b45158bbce", "responses": { "200": { "description": "Profil tenant", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "legal_name": { "type": "string", "nullable": true }, "siret": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true }, "billing_email": { "type": "string", "format": "email" }, "technical_email": { "type": "string", "format": "email", "nullable": true }, "address": { "type": "object", "nullable": true }, "kyb_status": { "type": "string", "enum": [ "pending", "documents_submitted", "under_review", "verified", "rejected" ] }, "kyb_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "balance": { "type": "number", "format": "float" }, "settings": { "type": "object", "nullable": true }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "tenantKeyAuth": [] } ] }, "put": { "tags": [ "Tenant" ], "summary": "Modifier le profil tenant", "description": "Met a jour les informations du tenant.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X PUT \"https://api.scell.io/api/v1/tenant/me\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Nouveau nom\",\n \"billing_email\": \"nouveau@email.com\"\n }'\n```", "operationId": "2fb8140b20434fa8849304d600410a85", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "legal_name": { "type": "string", "maxLength": 255, "nullable": true }, "billing_email": { "type": "string", "format": "email", "maxLength": 255 }, "technical_email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "address": { "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255, "nullable": true }, "postal_code": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "country": { "type": "string", "maxLength": 2, "minLength": 2 } }, "type": "object", "nullable": true }, "settings": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Profil mis a jour", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profil mis a jour avec succes" }, "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/balance": { "get": { "tags": [ "Tenant" ], "summary": "Balance et transactions", "description": "Retourne la balance actuelle et les 50 dernieres transactions.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/balance\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "a9e633c9389bb7a66a7b4651f7cd4fe2", "responses": { "200": { "description": "Balance et historique", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "balance": { "type": "number", "format": "float", "example": 150.5 }, "currency": { "type": "string", "example": "EUR" }, "transactions": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "debit", "credit" ] }, "service": { "type": "string", "enum": [ "invoice", "signature", "credit_note", "manual", "stripe" ] }, "amount": { "type": "number", "format": "float" }, "balance_after": { "type": "number", "format": "float" }, "description": { "type": "string" }, "sub_tenant_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/stats": { "get": { "tags": [ "Tenant" ], "summary": "Statistiques du tenant", "description": "Retourne les statistiques d'utilisation pour une periode donnee.\n\n### Periodes disponibles\n- `today` : Aujourd'hui\n- `week` : Cette semaine\n- `month` : Ce mois (defaut)\n- `year` : Cette annee\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/stats?period=month\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "b05c4cc18db76bf5dd5e8dd6cf8c59a9", "parameters": [ { "name": "period", "in": "query", "description": "Periode (today, week, month, year)", "schema": { "type": "string", "default": "month", "enum": [ "today", "week", "month", "year" ] } } ], "responses": { "200": { "description": "Statistiques", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "period": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "sub_tenants": { "properties": { "total": { "type": "integer" }, "active": { "type": "integer" } }, "type": "object" }, "operations": { "properties": { "invoices": { "type": "integer" }, "signatures": { "type": "integer" } }, "type": "object" }, "financial": { "properties": { "total_debits": { "type": "number", "format": "float" }, "total_credits": { "type": "number", "format": "float" }, "current_balance": { "type": "number", "format": "float" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/regenerate-key": { "post": { "tags": [ "Tenant" ], "summary": "Regenerer la cle API", "description": "Genere une nouvelle cle API. L'ancienne cle sera immediatement invalidee.\n\n**ATTENTION** : La nouvelle cle ne sera affichee qu'une seule fois. Conservez-la precieusement.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/regenerate-key\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "1a2c3beeb67c831658df94a16df275d5", "responses": { "200": { "description": "Nouvelle cle generee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Cle API regeneree avec succes" }, "data": { "properties": { "api_key": { "type": "string", "example": "sk_live_EXAMPLE" }, "prefix": { "type": "string", "example": "sk_live_" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] } }, "type": "object" }, "warning": { "type": "string", "example": "Conservez cette cle, elle ne sera plus affichee." } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/keys/publishable": { "post": { "tags": [ "Tenant" ], "summary": "Generer une cle publishable (API key auth)", "description": "Genere ou renouvelle la cle publishable (pk_*) via cle API secrete. Reservee aux tenants partenaires. Utile pour les scripts d'automatisation.", "operationId": "2bd3219eb56201267ee3646e829ad847", "responses": { "201": { "description": "Cle publishable generee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "publishable_key": { "type": "string" }, "prefix": { "type": "string" }, "environment": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Tenant non partenaire" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/credit-notes": { "get": { "tags": [ "Credit Notes" ], "summary": "Liste des avoirs", "description": "Retourne la liste paginee des avoirs d'un sub-tenant.\n\n### Filtres disponibles\n- `status` : Filtrer par statut (plusieurs valeurs separees par virgule)\n- `type` : Filtrer par type (partial, total)\n- `date_from` / `date_to` : Filtrer par date de creation\n- `buyer_siret` / `seller_siret` : Filtrer par SIRET\n- `min_amount` / `max_amount` : Filtrer par montant total\n- `search` : Recherche full-text (numero, motif, raison sociale, SIRET)\n\n### Tri\n- `sort` : Champ de tri (created_at, issue_date, total, credit_note_number)\n- `order` : Ordre de tri (asc, desc)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/credit-notes?status=sent&search=erreur\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\"\n```", "operationId": "06da8d6bd57e69647e26b939506ee264", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filtrer par statut (plusieurs valeurs separees par virgule)", "schema": { "type": "string", "example": "draft,sent" } }, { "name": "type", "in": "query", "description": "Filtrer par type", "schema": { "type": "string", "enum": [ "partial", "total" ] } }, { "name": "date_from", "in": "query", "description": "Date de debut (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "buyer_siret", "in": "query", "description": "Filtrer par SIRET acheteur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "seller_siret", "in": "query", "description": "Filtrer par SIRET vendeur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "min_amount", "in": "query", "description": "Montant total minimum", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "description": "Montant total maximum", "schema": { "type": "number" } }, { "name": "search", "in": "query", "description": "Recherche full-text (numero, motif, raison sociale, SIRET)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Champ de tri", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "issue_date", "total", "credit_note_number" ] } }, { "name": "order", "in": "query", "description": "Ordre de tri", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page (max: 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Sub-tenant non trouve" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Credit Notes" ], "summary": "Creer un avoir", "description": "Cree un avoir pour un sub-tenant a partir d'une facture existante.\n\n### Tarification\n- **Sandbox** : Gratuit\n- **Production** : 0.04 EUR par avoir (debite de la balance du tenant)\n\n### Types d'avoirs\n- `total` : Avoir pour la totalite de la facture\n- `partial` : Avoir partiel (lignes specifiques)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/credit-notes\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reason\": \"Erreur de facturation\",\n \"type\": \"partial\",\n \"items\": [\n { \"invoice_line_id\": \"uuid\", \"quantity\": 2 }\n ]\n }'\n```", "operationId": "694124229419c1488268fc11fcc9bde5", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_id", "reason", "type" ], "properties": { "invoice_id": { "description": "ID de la facture d'origine", "type": "string", "format": "uuid" }, "reason": { "description": "Motif de l'avoir", "type": "string", "maxLength": 1000 }, "type": { "description": "Type d'avoir", "type": "string", "enum": [ "partial", "total" ] }, "items": { "description": "Lignes a crediter (requis pour avoir partiel)", "type": "array", "items": { "required": [ "invoice_line_id" ], "properties": { "invoice_line_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "minimum": 0.0001 } }, "type": "object" } }, "metadata": { "description": "Metadonnees additionnelles", "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Avoir cree", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Avoir cree avec succes" }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "400": { "description": "Requete invalide" }, "401": { "description": "Non authentifie" }, "402": { "description": "Balance insuffisante" }, "403": { "description": "Acces refuse" }, "404": { "description": "Facture ou sub-tenant non trouve" }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/credit-notes/{creditNoteId}": { "get": { "tags": [ "Credit Notes" ], "summary": "Detail avoir", "description": "Retourne les details complets d'un avoir.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/credit-notes/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\"\n```", "operationId": "0c227254f6f5c5078a6c7d63fc265c45", "parameters": [ { "name": "creditNoteId", "in": "path", "description": "UUID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Non trouve" } }, "security": [ { "apiKeyAuth": [] } ] }, "put": { "tags": [ "Credit Notes" ], "summary": "Modifier un avoir", "description": "Modifie un avoir en brouillon. Seuls les avoirs en draft peuvent etre modifies.\n\n### Champs modifiables\n- `reason` : Motif de l'avoir\n- `items` : Lignes de l'avoir (remplacement complet)\n- `metadata` : Metadonnees additionnelles (fusion avec existantes)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X PUT \"https://api.scell.io/api/v1/tenant/credit-notes/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reason\": \"Nouveau motif\",\n \"items\": [\n { \"invoice_line_id\": \"uuid\", \"quantity\": 3 }\n ]\n }'\n```", "operationId": "27fa39ef96039fe4066ce3cecba336c7", "parameters": [ { "name": "creditNoteId", "in": "path", "description": "UUID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Motif de l'avoir", "type": "string", "maxLength": 1000 }, "items": { "description": "Lignes a crediter (remplace les lignes existantes)", "type": "array", "items": { "required": [ "quantity" ], "properties": { "id": { "description": "UUID de la ligne existante (pour modification)", "type": "string", "format": "uuid" }, "invoice_line_id": { "description": "UUID de la ligne de facture (pour nouvelle ligne)", "type": "string", "format": "uuid" }, "quantity": { "description": "Quantite a crediter", "type": "number", "minimum": 0.0001 } }, "type": "object" } }, "metadata": { "description": "Metadonnees additionnelles (fusionnees avec existantes)", "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Avoir modifie", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Avoir modifie avec succes" }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Avoir non trouve" }, "422": { "description": "L'avoir ne peut pas etre modifie", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "current_status": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "delete": { "tags": [ "Credit Notes" ], "summary": "Supprimer un avoir", "description": "Supprime un avoir en brouillon. Les avoirs envoyes ne peuvent pas etre supprimes.", "operationId": "5107e2dca1e526f1958bd4f66c0c1f8e", "parameters": [ { "name": "creditNoteId", "in": "path", "description": "UUID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Avoir supprime", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Avoir supprime" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Non trouve" }, "422": { "description": "L'avoir ne peut pas etre supprime", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "current_status": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/credit-notes/{creditNoteId}/send": { "post": { "tags": [ "Credit Notes" ], "summary": "Valider et envoyer", "description": "Valide l'avoir, genere le numero definitif et le PDF Factur-X.\nApres validation, l'avoir ne peut plus etre modifie.\n\n### Statuts\n- `draft` : Brouillon (peut etre envoye)\n- `sent` : Valide et envoye (verrouille)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/credit-notes/550e8400-e29b-41d4-a716-446655440000/send\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\"\n```", "operationId": "7f6df43f06439a186659eaed8115ad58", "parameters": [ { "name": "creditNoteId", "in": "path", "description": "UUID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Avoir valide et envoye", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Avoir valide et envoye" }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Non trouve" }, "422": { "description": "L'avoir ne peut pas etre envoye", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "current_status": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/credit-notes/{creditNoteId}/download": { "get": { "tags": [ "Credit Notes" ], "summary": "Telecharger le PDF", "description": "Telecharge le PDF Factur-X de l'avoir. L'avoir doit etre valide et envoye.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/credit-notes/550e8400-e29b-41d4-a716-446655440000/download\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\" \\\n -o avoir.pdf\n```", "operationId": "57676992972dbfbc3323dd020b5b0fcb", "parameters": [ { "name": "creditNoteId", "in": "path", "description": "UUID de l'avoir", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fichier PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Non trouve ou PDF non disponible" }, "422": { "description": "L'avoir n'a pas encore ete envoye", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/{invoiceId}/remaining-creditable": { "get": { "tags": [ "Credit Notes" ], "summary": "Montants restants a crediter", "description": "Calcule les montants restants a crediter sur chaque ligne d'une facture.\nUtile pour creer un avoir partiel.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/invoices/550e8400-e29b-41d4-a716-446655440000/remaining-creditable\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\"\n```", "operationId": "ecb1b7d1ed016b32cf6bef2d3d5e935e", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Montants restants", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "items": { "type": "array", "items": { "properties": { "invoice_line_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "original_quantity": { "type": "number" }, "credited_quantity": { "type": "number" }, "remaining_quantity": { "type": "number" }, "unit_price": { "type": "number" }, "remaining_amount_ht": { "type": "number" } }, "type": "object" } }, "total_remaining": { "type": "number" }, "can_be_credited": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" }, "404": { "description": "Facture non trouvee" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/credit-notes": { "get": { "tags": [ "Credit Notes" ], "summary": "Liste des avoirs directs", "description": "Retourne la liste paginee des avoirs crees directement par le tenant (sans sub-tenant).\n\n### Filtres disponibles\n- `status` : Filtrer par statut (plusieurs valeurs separees par virgule)\n- `type` : Filtrer par type (partial, total)\n- `date_from` / `date_to` : Filtrer par date de creation\n- `buyer_siret` / `seller_siret` : Filtrer par SIRET\n- `min_amount` / `max_amount` : Filtrer par montant total\n- `search` : Recherche full-text (numero, motif, raison sociale, SIRET)\n\n### Tri\n- `sort` : Champ de tri (created_at, issue_date, total, credit_note_number)\n- `order` : Ordre de tri (asc, desc)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/credit-notes?status=sent&search=erreur\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\"\n```", "operationId": "4e52b6c7a6271e9f400ec928fb636f6e", "parameters": [ { "name": "status", "in": "query", "description": "Filtrer par statut (plusieurs valeurs separees par virgule)", "schema": { "type": "string", "example": "draft,sent" } }, { "name": "type", "in": "query", "description": "Filtrer par type", "schema": { "type": "string", "enum": [ "partial", "total" ] } }, { "name": "date_from", "in": "query", "description": "Date de debut (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "buyer_siret", "in": "query", "description": "Filtrer par SIRET acheteur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "seller_siret", "in": "query", "description": "Filtrer par SIRET vendeur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "min_amount", "in": "query", "description": "Montant total minimum", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "description": "Montant total maximum", "schema": { "type": "number" } }, { "name": "search", "in": "query", "description": "Recherche full-text (numero, motif, raison sociale, SIRET)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Champ de tri", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "issue_date", "total", "credit_note_number" ] } }, { "name": "order", "in": "query", "description": "Ordre de tri", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page (max: 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Acces refuse" } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Credit Notes" ], "summary": "Creer un avoir direct", "description": "Cree un avoir direct pour le tenant a partir d'une facture existante emise directement (sans sub-tenant).\n\n### Tarification\n- **Sandbox** : Gratuit\n- **Production** : 0.04 EUR par avoir (debite de la balance du tenant)\n\n### Types d'avoirs\n- `total` : Avoir pour la totalite de la facture\n- `partial` : Avoir partiel (lignes specifiques)\n\n### Important\nLa facture doit appartenir a une company directe du tenant (sans sub_tenant_id).\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/credit-notes\" \\\n -H \"X-Tenant-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"reason\": \"Erreur de facturation\",\n \"type\": \"partial\",\n \"items\": [\n { \"invoice_line_id\": \"uuid\", \"quantity\": 2 }\n ]\n }'\n```", "operationId": "1bb6fcc575169e8da4c337bdb131e7e4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_id", "reason", "type" ], "properties": { "invoice_id": { "description": "ID de la facture d'origine", "type": "string", "format": "uuid" }, "reason": { "description": "Motif de l'avoir", "type": "string", "maxLength": 1000 }, "type": { "description": "Type d'avoir", "type": "string", "enum": [ "partial", "total" ] }, "items": { "description": "Lignes a crediter (requis pour avoir partiel)", "type": "array", "items": { "required": [ "invoice_line_id" ], "properties": { "invoice_line_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "minimum": 0.0001 } }, "type": "object" } }, "metadata": { "description": "Metadonnees additionnelles", "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Avoir cree", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Avoir cree avec succes" }, "data": { "$ref": "#/components/schemas/CreditNote" } }, "type": "object" } } } }, "400": { "description": "Requete invalide" }, "401": { "description": "Non authentifie" }, "402": { "description": "Balance insuffisante" }, "403": { "description": "Acces refuse" }, "404": { "description": "Facture non trouvee" }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices": { "get": { "tags": [ "Tenant Direct Invoices" ], "summary": "Liste des factures directes", "description": "Retourne la liste paginee des factures directes du tenant (sans sub-tenant).\n\n### Filtres disponibles\n- `status` : Filtrer par statut (plusieurs valeurs separees par virgule)\n- `direction` : Filtrer par direction (outgoing, incoming)\n- `date_from` / `date_to` : Filtrer par date d'emission\n- `buyer_siret` / `seller_siret` : Filtrer par SIRET\n- `min_amount` / `max_amount` : Filtrer par montant TTC\n- `search` : Recherche full-text (numero, raison sociale, SIRET)\n\n### Tri\n- `sort` : Champ de tri (created_at, issue_date, due_date, total_ttc, invoice_number)\n- `order` : Ordre de tri (asc, desc)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/invoices?status=validated&search=ACME\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "3f495a4e316980543b9986dc8e69dff1", "parameters": [ { "name": "status", "in": "query", "description": "Filtrer par statut (plusieurs valeurs separees par virgule)", "schema": { "type": "string", "example": "draft,validated" } }, { "name": "direction", "in": "query", "description": "Filtrer par direction", "schema": { "type": "string", "enum": [ "outgoing", "incoming" ] } }, { "name": "date_from", "in": "query", "description": "Date de debut (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "buyer_siret", "in": "query", "description": "Filtrer par SIRET acheteur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "seller_siret", "in": "query", "description": "Filtrer par SIRET vendeur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "min_amount", "in": "query", "description": "Montant TTC minimum", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "description": "Montant TTC maximum", "schema": { "type": "number" } }, { "name": "search", "in": "query", "description": "Recherche full-text (numero, raison sociale, SIRET)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Champ de tri", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "issue_date", "due_date", "total_ttc", "invoice_number" ] } }, { "name": "order", "in": "query", "description": "Ordre de tri", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page (max: 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Tenant Direct Invoices" ], "summary": "Creer une facture directe", "description": "Cree une facture directe pour un client du tenant (sans passer par un sub-tenant).\n\n### Tarification\n- **Sandbox** : Gratuit\n- **Production** : 0.04 EUR par facture (debite de la balance du tenant)\n\n### Formats de sortie\n- `facturx` : PDF/A-3 avec XML embarque (France)\n- `ubl` : Universal Business Language (Europe)\n- `cii` : Cross-Industry Invoice (International)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"direction\": \"outgoing\",\n \"output_format\": \"facturx\",\n \"issue_date\": \"2024-01-15\",\n \"seller\": {\n \"siret\": \"12345678901234\",\n \"name\": \"Mon Entreprise SAS\",\n \"address\": {\"line1\": \"1 rue du Commerce\", \"postal_code\": \"75001\", \"city\": \"Paris\", \"country\": \"FR\"}\n },\n \"buyer\": {\n \"siret\": \"98765432109876\",\n \"name\": \"Client Direct SARL\",\n \"address\": {\"line1\": \"2 avenue des Affaires\", \"postal_code\": \"69001\", \"city\": \"Lyon\", \"country\": \"FR\"}\n },\n \"lines\": [\n {\"description\": \"Prestation de conseil\", \"quantity\": 10, \"unit_price\": 150, \"tax_rate\": 20}\n ],\n \"total_ht\": 1500,\n \"total_tax\": 300,\n \"total_ttc\": 1800\n }'\n```", "operationId": "e06a022f38a3014999ea447e34f3a9ea", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "direction", "output_format", "issue_date", "seller", "buyer", "lines", "total_ht", "total_tax", "total_ttc" ], "properties": { "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "output_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "seller": { "required": [ "siret", "name", "address" ], "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "object" } }, "type": "object" }, "buyer": { "required": [ "siret", "name", "address" ], "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "object" } }, "type": "object" }, "lines": { "type": "array", "items": { "required": [ "description", "quantity", "unit_price", "tax_rate" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0.0001 }, "unit_price": { "type": "number", "minimum": 0 }, "tax_rate": { "type": "number", "maximum": 100, "minimum": 0 } }, "type": "object" }, "minItems": 1 }, "total_ht": { "type": "number", "minimum": 0 }, "total_tax": { "type": "number", "minimum": 0 }, "total_ttc": { "type": "number", "minimum": 0 }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Facture creee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture creee avec succes" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "402": { "description": "Balance insuffisante" }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/bulk": { "post": { "tags": [ "Tenant Direct Invoices" ], "summary": "Creation de factures en masse", "description": "Cree plusieurs factures directes en une seule requete (maximum 50).\n\n### Tarification\n- **Sandbox** : Gratuit\n- **Production** : 0.04 EUR par facture creee avec succes\n\n### Atomicite\n- Les factures sont creees dans une transaction\n- Si une erreur survient, les factures deja creees dans la requete sont conservees\n- Chaque resultat indique si la creation a reussi ou echoue\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/bulk\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoices\": [\n {\n \"direction\": \"outgoing\",\n \"output_format\": \"facturx\",\n \"issue_date\": \"2024-01-15\",\n \"seller\": {\"siret\": \"12345678901234\", \"name\": \"Mon Entreprise\", \"address\": {\"line1\": \"1 rue Test\", \"postal_code\": \"75001\", \"city\": \"Paris\"}},\n \"buyer\": {\"siret\": \"98765432109876\", \"name\": \"Client 1\", \"address\": {\"line1\": \"2 rue Demo\", \"postal_code\": \"69001\", \"city\": \"Lyon\"}},\n \"lines\": [{\"description\": \"Prestation\", \"quantity\": 1, \"unit_price\": 1000, \"tax_rate\": 20}],\n \"total_ht\": 1000,\n \"total_tax\": 200,\n \"total_ttc\": 1200\n }\n ]\n }'\n```", "operationId": "0a12baf27ea5fc6059d5c6b6df2fb152", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoices" ], "properties": { "invoices": { "type": "array", "items": { "required": [ "direction", "output_format", "issue_date", "seller", "buyer", "lines", "total_ht", "total_tax", "total_ttc" ], "properties": { "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "output_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ] }, "issue_date": { "type": "string", "format": "date" }, "seller": { "type": "object" }, "buyer": { "type": "object" }, "lines": { "type": "array", "items": { "type": "object" } }, "total_ht": { "type": "number" }, "total_tax": { "type": "number" }, "total_ttc": { "type": "number" } }, "type": "object" }, "maxItems": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Resultat de la creation en masse", "content": { "application/json": { "schema": { "properties": { "success_count": { "type": "integer", "example": 2 }, "error_count": { "type": "integer", "example": 1 }, "total_charged": { "type": "number", "example": 0.08 }, "results": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "success", "error" ] }, "id": { "type": "string", "format": "uuid", "nullable": true }, "invoice_number": { "type": "string", "nullable": true }, "errors": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "402": { "description": "Balance insuffisante pour traiter toutes les factures" }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/bulk-submit": { "post": { "tags": [ "Tenant Direct Invoices" ], "summary": "Soumission de factures en masse (asynchrone)", "description": "Soumet plusieurs factures a SuperPDP en une seule requete (maximum 50).\n\nLe traitement est **asynchrone** : les factures eligibles sont mises en file d'attente\net traitees en arriere-plan. La reponse 202 est retournee immediatement.\n\n### Regles\n- Seules les factures avec le statut `draft` ou `validated` peuvent etre soumises\n- Les factures deja soumises ou dans un autre statut sont ignorees et listees dans `rejected`\n- Chaque job est retente jusqu'a 3 fois en cas d'erreur reseau (backoff : 30s, 60s, 120s)\n\n### Suivi\nUtilisez `POST /api/v1/tenant/invoices/bulk-status` pour suivre l'avancement du traitement.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/bulk-submit\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_ids\": [\n \"550e8400-e29b-41d4-a716-446655440000\"\n ]\n }'\n```", "operationId": "7c81615aed98c9ea29854715723690c8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_ids" ], "properties": { "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, "type": "object" } } } }, "responses": { "202": { "description": "Soumission acceptee — traitement asynchrone en cours", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Traitement asynchrone lance pour 2 factures." }, "queued_count": { "type": "integer", "example": 2 }, "rejected_count": { "type": "integer", "example": 1 }, "queued_invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "rejected": { "type": "array", "items": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/bulk-status": { "post": { "tags": [ "Tenant Direct Invoices" ], "summary": "Statut de factures en masse", "description": "Recupere le statut de plusieurs factures en une seule requete (maximum 50).\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/bulk-status\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_ids\": [\n \"550e8400-e29b-41d4-a716-446655440000\"\n ]\n }'\n```", "operationId": "4cbe0c346a3228e9f0a053454d2c16be", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_ids" ], "properties": { "invoice_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Statuts des factures", "content": { "application/json": { "schema": { "properties": { "found_count": { "type": "integer", "example": 2 }, "not_found_count": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "found": { "type": "boolean" }, "invoice_number": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "superpdp_id": { "type": "string", "nullable": true }, "superpdp_status": { "type": "string", "nullable": true }, "transmitted_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "422": { "description": "Erreur de validation" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/{invoiceId}/download": { "get": { "tags": [ "Tenant Invoices" ], "summary": "Telecharger une facture (Bearer tenant)", "description": "Telecharge le fichier binaire d'une facture appartenant a un sub-tenant ou cree directement par le tenant. Format defaut : `facturx` (PDF/A-3).\n\n**Format `?format=`** :\n- `facturx` (defaut) : PDF/A-3 avec XML CII embarque\n- `pdf` : Rendu PDF visuel uniquement\n- `xml` : XML pur (UBL ou CII)\n\n**Erreurs** :\n- 404 `INVOICE_FILE_NOT_AVAILABLE` : facture transmise mais fichier absent du storage\n- 404 `INVOICE_FILE_MISSING_ON_STORAGE` : path en DB mais le fichier a ete supprime du disk\n- 422 `INVOICE_DRAFT_NOT_GENERATED` : facture en brouillon, soumettre via /submit d'abord\n- 422 `INVOICE_DOWNLOAD_INVALID_FORMAT` : format demande non supporte", "operationId": "414cc9c551a1165ab7ff75c1255f7dd5", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "Format de sortie", "required": false, "schema": { "type": "string", "default": "facturx", "enum": [ "facturx", "pdf", "xml" ] } } ], "responses": { "200": { "description": "Fichier binaire", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Non authentifie" }, "403": { "description": "Facture appartient a un autre tenant" }, "404": { "description": "Facture introuvable ou fichier non disponible" }, "422": { "description": "Format invalide ou facture en brouillon" } }, "security": [ { "apiKeyAuth": [] }, { "cookieAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/invoices/incoming": { "get": { "tags": [ "Incoming Invoices" ], "summary": "Lister les factures entrantes", "description": "Retourne la liste paginee des factures entrantes (fournisseurs) d'un sub-tenant.\n\n### Filtres disponibles\n- `status` : Filtrer par statut (plusieurs valeurs separees par virgule)\n- `seller_siret` / `buyer_siret` : Filtrer par SIRET\n- `from` / `to` : Filtrer par date d'emission\n- `min_amount` / `max_amount` : Filtrer par montant TTC\n- `search` : Recherche full-text (numero, raison sociale, SIRET)\n\n### Tri\n- `sort` : Champ de tri (created_at, received_at, issue_date, due_date, total_ttc, invoice_number)\n- `order` : Ordre de tri (asc, desc)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/invoices/incoming?status=received&search=ACME\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "2cf9cdfa09b75b6fe070f1b593e56f70", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filtrer par statut (plusieurs valeurs separees par virgule)", "schema": { "type": "string", "example": "received,accepted" } }, { "name": "seller_siret", "in": "query", "description": "Filtrer par SIRET du fournisseur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "buyer_siret", "in": "query", "description": "Filtrer par SIRET de l'acheteur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "from", "in": "query", "description": "Date de debut (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "description": "Montant TTC minimum", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "description": "Montant TTC maximum", "schema": { "type": "number" } }, { "name": "search", "in": "query", "description": "Recherche full-text (numero, raison sociale, SIRET)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Champ de tri", "schema": { "type": "string", "default": "received_at", "enum": [ "created_at", "received_at", "issue_date", "due_date", "total_ttc", "invoice_number" ] } }, { "name": "order", "in": "query", "description": "Ordre de tri", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page (max: 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste des factures entrantes", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncomingInvoice" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "post": { "tags": [ "Incoming Invoices" ], "summary": "Creer une facture entrante (fournisseur)", "description": "Cree manuellement une facture entrante recue d'un fournisseur.\n\n### Caracteristiques\n- **Gratuit** : Pas de tarification pour les factures entrantes\n- **Direction** : Forcee a 'incoming'\n- **Statut initial** : 'received' (en attente de traitement)\n- **Numero de facture** : Celui du fournisseur (pas de generation auto)\n\n### Validation\n- Le SIRET de l'acheteur (buyer) doit correspondre a une company du sub-tenant\n- Les totaux sont verifies pour coherence avec les lignes\n\n### Statuts possibles\n- `received` : Recue, en attente de traitement\n- `accepted` : Acceptee\n- `rejected` : Rejetee\n- `disputed` : Litige en cours\n- `paid` : Payee\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/invoices/incoming\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_number\": \"FAC-FOURNISSEUR-001\",\n \"issue_date\": \"2026-01-15\",\n \"due_date\": \"2026-02-15\",\n \"seller\": {\n \"siret\": \"12345678901234\",\n \"name\": \"Fournisseur SARL\",\n \"address\": {\"line1\": \"1 rue du Commerce\", \"postal_code\": \"75001\", \"city\": \"Paris\", \"country\": \"FR\"}\n },\n \"buyer\": {\n \"siret\": \"98765432109876\",\n \"name\": \"Mon Entreprise\",\n \"address\": {\"line1\": \"2 avenue Client\", \"postal_code\": \"69001\", \"city\": \"Lyon\", \"country\": \"FR\"}\n },\n \"lines\": [\n {\"description\": \"Prestation de service\", \"quantity\": 1, \"unit_price\": 500, \"tax_rate\": 20}\n ],\n \"total_ht\": 500,\n \"total_tax\": 100,\n \"total_ttc\": 600\n }'\n```\n\n**PHP**\n```php\n$response = $client->post('https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/invoices/incoming', [\n 'headers' => ['X-API-Key' => 'sk_live_xxxxxx'],\n 'json' => [\n 'invoice_number' => 'FAC-FOURNISSEUR-001',\n 'issue_date' => '2026-01-15',\n 'seller' => ['siret' => '12345678901234', 'name' => 'Fournisseur SARL', 'address' => [...]],\n 'buyer' => ['siret' => '98765432109876', 'name' => 'Mon Entreprise', 'address' => [...]],\n 'lines' => [['description' => 'Prestation', 'quantity' => 1, 'unit_price' => 500, 'tax_rate' => 20]],\n 'total_ht' => 500, 'total_tax' => 100, 'total_ttc' => 600\n ]\n]);\n```", "operationId": "7b515afe208517081ea8f552f40efe14", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "invoice_number", "issue_date", "seller", "buyer", "lines", "total_ht", "total_tax", "total_ttc" ], "properties": { "invoice_number": { "description": "Numero de facture du fournisseur", "type": "string", "maxLength": 50 }, "external_id": { "description": "Identifiant externe optionnel", "type": "string", "maxLength": 100, "nullable": true }, "issue_date": { "description": "Date d'emission", "type": "string", "format": "date" }, "due_date": { "description": "Date d'echeance", "type": "string", "format": "date", "nullable": true }, "seller": { "description": "Informations du fournisseur (vendeur)", "required": [ "siret", "name", "address" ], "properties": { "siret": { "description": "SIRET du fournisseur", "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "description": "Nom du fournisseur", "type": "string", "maxLength": 255 }, "vat_number": { "description": "Numero de TVA", "type": "string", "maxLength": 20, "nullable": true }, "address": { "required": [ "line1", "postal_code", "city", "country" ], "properties": { "line1": { "type": "string" }, "line2": { "type": "string", "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "maxLength": 2, "minLength": 2 } }, "type": "object" } }, "type": "object" }, "buyer": { "description": "Informations de l'acheteur (votre entreprise)", "required": [ "siret", "name", "address" ], "properties": { "siret": { "description": "SIRET de votre entreprise", "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "description": "Nom de votre entreprise", "type": "string", "maxLength": 255 }, "vat_number": { "type": "string", "maxLength": 20, "nullable": true }, "address": { "type": "object" } }, "type": "object" }, "lines": { "type": "array", "items": { "required": [ "description", "quantity", "unit_price", "tax_rate" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0.0001 }, "unit_price": { "type": "number", "minimum": 0 }, "tax_rate": { "type": "number", "maximum": 100, "minimum": 0 }, "unit": { "type": "string", "maxLength": 10, "nullable": true }, "product_code": { "type": "string", "maxLength": 50, "nullable": true } }, "type": "object" }, "maxItems": 100, "minItems": 1 }, "total_ht": { "description": "Total hors taxes", "type": "number", "minimum": 0 }, "total_tax": { "description": "Total TVA", "type": "number", "minimum": 0 }, "total_ttc": { "description": "Total TTC", "type": "number", "minimum": 0 }, "currency": { "type": "string", "default": "EUR", "maxLength": 3, "minLength": 3 }, "pdf_file": { "description": "PDF encode en base64", "type": "string", "nullable": true }, "pdf_url": { "description": "URL du PDF", "type": "string", "format": "uri", "nullable": true }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "purchase_order": { "type": "string", "maxLength": 50, "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Facture entrante creee avec succes", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture entrante creee avec succes" }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Les donnees fournies sont invalides." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } } } }, "404": { "description": "Sub-tenant non trouve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/incoming/{invoiceId}": { "get": { "tags": [ "Incoming Invoices" ], "summary": "Detail d'une facture entrante", "description": "Retourne les details complets d'une facture entrante.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/invoices/incoming/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "6e257c83915b600598dcba804d4d36eb", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail de la facture entrante", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/incoming/{invoiceId}/accept": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Accepter une facture entrante", "description": "Accepte une facture fournisseur. La facture passe au statut 'accepted'.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/incoming/550e8400-e29b-41d4-a716-446655440000/accept\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "a953d2ffba556e75051347a7aa9ac903", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Facture acceptee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture acceptee avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee" }, "422": { "description": "La facture ne peut pas etre acceptee" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/incoming/{invoiceId}/reject": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Rejeter une facture entrante", "description": "Rejette une facture fournisseur avec un motif obligatoire.\n\n### Codes de rejet\n- `incorrect_amount` : Montant incorrect\n- `duplicate` : Facture en double\n- `unknown_order` : Commande inconnue\n- `incorrect_vat` : TVA incorrecte\n- `other` : Autre motif\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/incoming/550e8400-e29b-41d4-a716-446655440000/reject\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reason\": \"La facture ne correspond pas a notre commande\",\n \"reason_code\": \"unknown_order\"\n }'\n```", "operationId": "b20a42b8de51f9c67c7c1b249b078dd4", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason", "reason_code" ], "properties": { "reason": { "description": "Motif detaille du rejet", "type": "string", "maxLength": 500 }, "reason_code": { "description": "Code de rejet", "type": "string", "enum": [ "incorrect_amount", "duplicate", "unknown_order", "incorrect_vat", "other" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Facture rejetee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture rejetee avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee" }, "422": { "description": "Erreur de validation ou facture non rejectable" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/invoices/incoming/{invoiceId}/mark-paid": { "post": { "tags": [ "Incoming Invoices" ], "summary": "Marquer une facture entrante comme payee", "description": "Marque une facture fournisseur comme payee. Seules les factures acceptees peuvent etre marquees comme payees.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/incoming/550e8400-e29b-41d4-a716-446655440000/mark-paid\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"payment_reference\": \"VIR-2026-001234\",\n \"paid_at\": \"2026-01-24T10:30:00Z\",\n \"note\": \"Paiement par virement bancaire\"\n }'\n```", "operationId": "327d99b3ff74b30f94adcd78f3ae5189", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_means_code" ], "properties": { "payment_means_code": { "description": "Code BT-81 EN16931 UN/ECE 4461 (OBLIGATOIRE pour conformite Factur-X)", "type": "string", "enum": [ "1", "10", "20", "30", "42", "48", "49", "57", "58", "59", "97" ], "example": "58" }, "payment_means_text": { "description": "Libelle BT-82 (optionnel)", "type": "string", "maxLength": 100 }, "payment_reference": { "description": "Reference du paiement", "type": "string", "maxLength": 100 }, "paid_at": { "description": "Date du paiement (defaut: maintenant)", "type": "string", "format": "date-time" }, "note": { "description": "Note interne", "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Facture marquee comme payee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture marquee comme payee avec succes." }, "data": { "$ref": "#/components/schemas/IncomingInvoice" } }, "type": "object" } } } }, "404": { "description": "Facture non trouvee" }, "422": { "description": "La facture ne peut pas etre marquee comme payee" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/invoices": { "get": { "tags": [ "Tenant Invoices" ], "summary": "Liste des factures", "description": "Retourne la liste paginee des factures d'un sub-tenant.\n\n### Filtres disponibles\n- `status` : Filtrer par statut (plusieurs valeurs separees par virgule)\n- `direction` : Filtrer par direction (outgoing, incoming)\n- `date_from` / `date_to` : Filtrer par date d'emission\n- `buyer_siret` / `seller_siret` : Filtrer par SIRET\n- `min_amount` / `max_amount` : Filtrer par montant TTC\n- `search` : Recherche full-text (numero, raison sociale, SIRET)\n\n### Tri\n- `sort` : Champ de tri (created_at, issue_date, due_date, total_ttc, invoice_number)\n- `order` : Ordre de tri (asc, desc)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/invoices?status=validated&search=ACME\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "2136821443d71fae26022b0737e4a948", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filtrer par statut (plusieurs valeurs separees par virgule)", "schema": { "type": "string", "example": "draft,validated" } }, { "name": "direction", "in": "query", "description": "Filtrer par direction", "schema": { "type": "string", "enum": [ "outgoing", "incoming" ] } }, { "name": "date_from", "in": "query", "description": "Date de debut (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Date de fin (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "buyer_siret", "in": "query", "description": "Filtrer par SIRET acheteur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "seller_siret", "in": "query", "description": "Filtrer par SIRET vendeur", "schema": { "type": "string", "maxLength": 14, "minLength": 14 } }, { "name": "min_amount", "in": "query", "description": "Montant TTC minimum", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "description": "Montant TTC maximum", "schema": { "type": "number" } }, { "name": "search", "in": "query", "description": "Recherche full-text (numero, raison sociale, SIRET)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Champ de tri", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "issue_date", "due_date", "total_ttc", "invoice_number" ] } }, { "name": "order", "in": "query", "description": "Ordre de tri", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "description": "Numero de page", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Elements par page (max: 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] }, "post": { "tags": [ "Tenant Invoices" ], "summary": "Creer une facture", "description": "Cree une facture pour un sub-tenant specifique.\n\n### Tarification\n- **Sandbox** : Gratuit\n- **Production** : 0.04 EUR par facture (debite de la balance du tenant)\n\n### Formats de sortie\n- `facturx` : PDF/A-3 avec XML embarque (France)\n- `ubl` : Universal Business Language (Europe)\n- `cii` : Cross-Industry Invoice (International)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/sub-tenants/{subTenantId}/invoices\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"direction\": \"outgoing\",\n \"output_format\": \"facturx\",\n \"issue_date\": \"2024-01-15\",\n \"seller\": {\n \"siret\": \"12345678901234\",\n \"name\": \"ACME Corp\",\n \"address\": {\"line1\": \"1 rue Test\", \"postal_code\": \"75001\", \"city\": \"Paris\", \"country\": \"FR\"}\n },\n \"buyer\": {\n \"siret\": \"98765432109876\",\n \"name\": \"Client SARL\",\n \"address\": {\"line1\": \"2 avenue Demo\", \"postal_code\": \"69001\", \"city\": \"Lyon\", \"country\": \"FR\"}\n },\n \"lines\": [\n {\"description\": \"Prestation de service\", \"quantity\": 1, \"unit_price\": 1000, \"tax_rate\": 20}\n ],\n \"total_ht\": 1000,\n \"total_tax\": 200,\n \"total_ttc\": 1200\n }'\n```", "operationId": "2021b0371f0d6e52d5fa0e1460822a3b", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "direction", "output_format", "issue_date", "seller", "buyer", "lines", "total_ht", "total_tax", "total_ttc" ], "properties": { "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "output_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "seller": { "required": [ "siret", "name", "address" ], "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "object" } }, "type": "object" }, "buyer": { "required": [ "siret", "name", "address" ], "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "object" } }, "type": "object" }, "lines": { "type": "array", "items": { "required": [ "description", "quantity", "unit_price", "tax_rate" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0.0001 }, "unit_price": { "type": "number", "minimum": 0 }, "tax_rate": { "type": "number", "maximum": 100, "minimum": 0 } }, "type": "object" }, "minItems": 1 }, "total_ht": { "type": "number", "minimum": 0 }, "total_tax": { "type": "number", "minimum": 0 }, "total_ttc": { "type": "number", "minimum": 0 }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Facture creee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture creee avec succes" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "402": { "description": "Balance insuffisante" }, "422": { "description": "Erreur de validation" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/invoices/{invoiceId}": { "get": { "tags": [ "Tenant Invoices" ], "summary": "Detail facture", "description": "Retourne les details complets d'une facture.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/invoices/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "69bbc15d4607531777899c4a87cb9f12", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "404": { "description": "Non trouvee" } }, "security": [ { "tenantKeyAuth": [] } ] }, "put": { "tags": [ "Tenant Invoices" ], "summary": "Modifier une facture", "description": "Modifie une facture en brouillon (draft).\n\n### Regles\n- Seules les factures avec le statut `draft` peuvent etre modifiees\n- Si des lignes sont fournies, elles remplacent toutes les lignes existantes\n- Tous les champs sont optionnels (seuls les champs fournis sont mis a jour)\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X PUT \"https://api.scell.io/api/v1/tenant/invoices/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"buyer\": {\n \"siret\": \"11111111111111\",\n \"name\": \"Nouveau Client SARL\",\n \"address\": {\"line1\": \"10 rue Modifiee\", \"postal_code\": \"75002\", \"city\": \"Paris\", \"country\": \"FR\"}\n },\n \"total_ht\": 1500,\n \"total_tax\": 300,\n \"total_ttc\": 1800\n }'\n```", "operationId": "de498a65fe530cfaf3cea738fcc96113", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "direction": { "type": "string", "enum": [ "outgoing", "incoming" ], "nullable": true }, "output_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ], "nullable": true }, "issue_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "seller": { "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "object" } }, "type": "object", "nullable": true }, "buyer": { "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14 }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "object" } }, "type": "object", "nullable": true }, "lines": { "type": "array", "items": { "required": [ "description", "quantity", "unit_price", "tax_rate" ], "properties": { "description": { "type": "string", "maxLength": 500 }, "quantity": { "type": "number", "minimum": 0.0001 }, "unit_price": { "type": "number", "minimum": 0 }, "tax_rate": { "type": "number", "maximum": 100, "minimum": 0 } }, "type": "object" }, "nullable": true }, "total_ht": { "type": "number", "minimum": 0, "nullable": true }, "total_tax": { "type": "number", "minimum": 0, "nullable": true }, "total_ttc": { "type": "number", "minimum": 0, "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Facture modifiee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture modifiee avec succes" }, "data": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" } } } }, "403": { "description": "Modification non autorisee (facture non draft)" }, "404": { "description": "Non trouvee" }, "422": { "description": "Erreur de validation" } }, "security": [ { "tenantKeyAuth": [] } ] }, "delete": { "tags": [ "Tenant Invoices" ], "summary": "Supprimer une facture", "description": "Supprime une facture en brouillon (draft).\n\n### Regles\n- Seules les factures avec le statut `draft` peuvent etre supprimees\n- Les factures soumises, validees ou transmises ne peuvent pas etre supprimees\n- Cette action est irreversible\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X DELETE \"https://api.scell.io/api/v1/tenant/invoices/550e8400-e29b-41d4-a716-446655440000\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "0e3da6a458ef632466e18268bd8770b0", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Facture supprimee", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture supprimee avec succes" } }, "type": "object" } } } }, "403": { "description": "Suppression non autorisee (facture non draft)" }, "404": { "description": "Non trouvee" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/invoices/{invoiceId}/download": { "get": { "tags": [ "Tenant Invoices" ], "summary": "Telecharger une facture (sub-tenant scope)", "description": "Telecharge le fichier binaire d'une facture appartenant au sub-tenant specifie. Equivalent scope sub-tenant de `GET /tenant/invoices/{invoiceId}/download`.\n\n**Format `?format=`** : `facturx` (defaut, PDF/A-3) | `pdf` | `xml`\n\nLa facture doit appartenir au sub-tenant ET au tenant authentifie (verifie via la company). Sinon 404.", "operationId": "bce7c35da6c07bd90ac238bd8386cb97", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "Format de sortie", "required": false, "schema": { "type": "string", "default": "facturx", "enum": [ "facturx", "pdf", "xml" ] } } ], "responses": { "200": { "description": "Fichier binaire", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Non authentifie" }, "404": { "description": "Facture introuvable, fichier non disponible, ou sub-tenant ne possede pas cette facture" }, "422": { "description": "Format invalide ou facture en brouillon" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/invoices/{invoiceId}/submit": { "post": { "tags": [ "Tenant Invoices" ], "summary": "Soumettre a SuperPDP", "description": "Soumet la facture au Portail Public de Facturation (PPF) via SuperPDP.\n\n### Statuts de la facture\n- `draft` : Brouillon (peut etre soumise)\n- `validated` : Validee (peut etre soumise)\n- `transmitted` : En cours de transmission\n- `completed` : Acceptee par le PPF\n- `rejected` : Rejetee par le PPF\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X POST \"https://api.scell.io/api/v1/tenant/invoices/550e8400-e29b-41d4-a716-446655440000/submit\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "10ff7ebfa5516c5539e7de02a9db4cd3", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Soumise", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Facture soumise a SuperPDP" }, "superpdp_id": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Non soumissible", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "current_status": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/invoices/{invoiceId}/status": { "get": { "tags": [ "Tenant Invoices" ], "summary": "Statut SuperPDP", "description": "Recupere le statut actuel de la facture aupres de SuperPDP.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/invoices/550e8400-e29b-41d4-a716-446655440000/status\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "42f52c44aa8fe2e5ff18f5e781787057", "parameters": [ { "name": "invoiceId", "in": "path", "description": "UUID de la facture", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Statut", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "superpdp_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "superpdp_status": { "type": "string", "nullable": true }, "transmitted_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Non trouvee" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/signatures": { "get": { "tags": [ "Tenant Signatures" ], "summary": "Lister toutes les signatures du tenant", "description": "Retourne la liste paginee des signatures du tenant courant, tous sub-tenants confondus.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/signatures?status=pending\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "f0e6bb1f9b3c8bd269f68628cd56c4c2", "parameters": [ { "name": "status", "in": "query", "description": "Filtrer par statut", "schema": { "type": "string", "enum": [ "pending", "completed", "refused", "expired" ] } }, { "name": "environment", "in": "query", "description": "sandbox ou production", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Pagination (max 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/signatures": { "get": { "tags": [ "Tenant Signatures" ], "summary": "Lister les signatures d'un sub-tenant", "description": "Retourne la liste paginee des signatures appartenant a un sub-tenant precis. Le sub-tenant DOIT appartenir au tenant courant (sinon 404 anti-IDOR).\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/SUB_TENANT_UUID/signatures\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "f1ec728f59905a6d3fa5d5bbf3ec909c", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filtrer par statut", "schema": { "type": "string", "enum": [ "pending", "completed", "refused", "expired" ] } }, { "name": "environment", "in": "query", "description": "sandbox ou production", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Pagination (max 100)", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Liste paginee" }, "404": { "description": "Sub-tenant introuvable ou hors scope" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/signatures/{id}": { "get": { "tags": [ "Tenant Signatures" ], "summary": "Detail d'une signature", "description": "Retourne les details complets d'une signature. La signature DOIT appartenir au tenant courant (via company.tenant_id), sinon 404.", "operationId": "558941c1ae69064dde4a636aa9ccdc41", "parameters": [ { "name": "id", "in": "path", "description": "UUID de la signature", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail" }, "404": { "description": "Non trouvee" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/signatures/{id}": { "get": { "tags": [ "Tenant Signatures" ], "summary": "Detail signature (sub-tenant scope)", "description": "Detail d'une signature scope sub-tenant. 404 si la signature n'appartient pas au sub-tenant specifie OU si le sub-tenant n'appartient pas au tenant courant.", "operationId": "50c359bcdf9938097188024ed61b8974", "parameters": [ { "name": "subTenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detail" }, "404": { "description": "Non trouvee ou hors scope" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/stats/overview": { "get": { "tags": [ "Tenant Stats" ], "summary": "Statistiques globales du tenant", "description": "Retourne les statistiques detaillees du tenant incluant :\n- Nombre total de factures par statut\n- Nombre total d'avoirs par statut\n- Montants HT/TTC (mois courant, trimestre, annee)\n- Nombre de sub-tenants actifs\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/stats/overview\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```\n\n**PHP**\n```php\n$response = $client->get('https://api.scell.io/api/v1/tenant/stats/overview', [\n 'headers' => ['X-API-Key' => 'sk_live_xxxxxx']\n]);\n```", "operationId": "753e25ddd93895ec058c910c831975f3", "responses": { "200": { "description": "Statistiques globales", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "invoices": { "properties": { "total": { "type": "integer", "example": 150 }, "by_status": { "type": "object", "example": { "draft": 10, "validated": 50, "transmitted": 90 }, "additionalProperties": { "type": "integer" } } }, "type": "object" }, "credit_notes": { "properties": { "total": { "type": "integer", "example": 20 }, "by_status": { "type": "object", "example": { "draft": 2, "sent": 18 }, "additionalProperties": { "type": "integer" } } }, "type": "object" }, "amounts": { "properties": { "current_month": { "properties": { "subtotal": { "type": "number", "format": "float", "example": 10000 }, "total": { "type": "number", "format": "float", "example": 12000 }, "currency": { "type": "string", "example": "EUR" } }, "type": "object" }, "current_quarter": { "properties": { "subtotal": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "currency": { "type": "string" } }, "type": "object" }, "current_year": { "properties": { "subtotal": { "type": "number", "format": "float", "example": 120000 }, "total": { "type": "number", "format": "float", "example": 144000 }, "currency": { "type": "string", "example": "EUR" } }, "type": "object" } }, "type": "object" }, "sub_tenants": { "properties": { "total": { "type": "integer", "example": 5 }, "active": { "type": "integer", "example": 4 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/stats/monthly": { "get": { "tags": [ "Tenant Stats" ], "summary": "Statistiques mensuelles", "description": "Retourne les statistiques agregees par mois pour une annee donnee.\n\n### Donnees incluses par mois\n- Nombre de factures emises\n- Montant total HT et TTC\n- Nombre d'avoirs emis\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/stats/monthly?year=2026\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "d9bbfc1ac0236b2e42f722aa711be850", "parameters": [ { "name": "year", "in": "query", "description": "Annee pour les statistiques (defaut: annee courante)", "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Statistiques mensuelles", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "year": { "type": "integer", "example": 2026 }, "months": { "type": "array", "items": { "properties": { "month": { "type": "integer", "example": 1 }, "month_name": { "type": "string", "example": "Janvier" }, "invoices_count": { "type": "integer", "example": 25 }, "invoices_subtotal": { "type": "number", "format": "float", "example": 15000 }, "invoices_total": { "type": "number", "format": "float", "example": 18000 }, "credit_notes_count": { "type": "integer", "example": 3 }, "credit_notes_total": { "type": "number", "format": "float", "example": 1500 } }, "type": "object" } }, "totals": { "properties": { "invoices_count": { "type": "integer" }, "invoices_subtotal": { "type": "number", "format": "float" }, "invoices_total": { "type": "number", "format": "float" }, "credit_notes_count": { "type": "integer" }, "credit_notes_total": { "type": "number", "format": "float" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "422": { "description": "Annee invalide" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/tenant/sub-tenants/{subTenantId}/stats/overview": { "get": { "tags": [ "Tenant Stats" ], "summary": "Statistiques d'un sub-tenant", "description": "Retourne les statistiques detaillees pour un sub-tenant specifique.\n\n### Exemples\n\n**cURL**\n```bash\ncurl -X GET \"https://api.scell.io/api/v1/tenant/sub-tenants/123e4567-e89b-12d3-a456-426614174000/stats/overview\" \\\n -H \"X-API-Key: sk_live_xxxxxx\"\n```", "operationId": "833a1e8be9f0d6a8d5327153cf939e78", "parameters": [ { "name": "subTenantId", "in": "path", "description": "UUID du sub-tenant", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Statistiques du sub-tenant", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "sub_tenant_id": { "type": "string", "format": "uuid" }, "sub_tenant_name": { "type": "string" }, "invoices": { "properties": { "total": { "type": "integer" }, "by_status": { "type": "object" } }, "type": "object" }, "credit_notes": { "properties": { "total": { "type": "integer" }, "by_status": { "type": "object" } }, "type": "object" }, "amounts": { "properties": { "current_month": { "type": "object" }, "current_quarter": { "type": "object" }, "current_year": { "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Non authentifie" }, "404": { "description": "Sub-tenant non trouve" } }, "security": [ { "tenantKeyAuth": [] } ] } }, "/v1/verify-certificate": { "post": { "tags": [ "Compliance" ], "summary": "Verifier un certificat de conformite", "description": "Verifie un certificat de conformite ISCA Scell.io fourni en PDF (multipart). Pas d'authentification. Retourne un rapport detaille de verification. Taille max : 50 Mo. Rate-limit : 10 requetes / minute par IP.", "operationId": "b9a9d39946cf8cb16a496cb9a71ccfa4", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "Certificat de conformite au format PDF (max 50 Mo).", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Rapport de verification du certificat", "content": { "application/json": { "schema": { "description": "Rapport detaille produit par le service de verification ISCA (validite, integrite de la chaine de hachage, ancrage, metadonnees).", "type": "object" } } } }, "400": { "description": "Fichier invalide ou upload echoue", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Fichier invalide ou upload echoue." } }, "type": "object" } } } }, "422": { "description": "Erreur de validation (fichier manquant ou type incorrect)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erreur lors du traitement du PDF", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Erreur lors du traitement du PDF : ..." } }, "type": "object" } } } } }, "security": [] } }, "/v1/version": { "get": { "tags": [ "Meta" ], "summary": "Version applicative", "description": "Retourne la version git deployee, le commit court, l'environnement et les versions runtime (PHP, Laravel). Pas d'authentification. Utilise par le monitoring externe et la verification de coherence du certificat de conformite ISCA.", "operationId": "6752bd9b1cc279e1b4306fc3364f003a", "responses": { "200": { "description": "Informations de version", "content": { "application/json": { "schema": { "properties": { "version": { "description": "Version applicative (APP_VERSION / config app.version)", "type": "string", "example": "1.2.1" }, "commit_sha": { "description": "SHA complet du commit deploye", "type": "string", "example": "c7377fc1a2b3c4d5e6f7081923456789abcdef01", "nullable": true }, "commit_short": { "description": "SHA court du commit deploye", "type": "string", "example": "c7377fc", "nullable": true }, "committed_at": { "description": "Date du commit deploye", "type": "string", "format": "date-time", "nullable": true }, "environment": { "description": "Nom de l'environnement applicatif", "type": "string", "example": "production" }, "php_version": { "type": "string", "example": "8.4.3" }, "laravel_version": { "type": "string", "example": "12.0.0" }, "resolved_at": { "description": "Date de resolution du manifest de version", "type": "string", "format": "date-time" } }, "type": "object" } } } } }, "security": [] } }, "/widget/oauth-callback": { "get": { "tags": [ "Onboarding-Widget" ], "summary": "Widget v3 — Page intermediaire OAuth SuperPDP (postMessage)", "description": "Endpoint `redirect_uri` enregistre chez SuperPDP pour le widget v3. SuperPDP redirige le navigateur (popup ouverte par le widget cote partenaire) vers cette URL avec `?code=&state=` apres authentification + KYB.\n\n**Pas d'auth applicative** (route publique car c'est un redirect_uri OAuth). La securite vient de :\n- State CSRF stocke en cache `widget_v3:onboarding_state:{state}` (one-shot via Cache::pull)\n- PKCE S256 valide cote SuperPDP au moment de l'echange du code\n\n**Reponse** : Page Blade qui poste un message `{type: 'scell:onboarding:oauth_callback', success, sub_tenant, recommended_action, code, message}` au `window.opener` puis `window.close()`. Le widget cote partenaire ecoute `message` event pour finaliser le flow.\n\nCet endpoint NE retourne PAS de JSON — c'est une page HTML.", "operationId": "9d4798f3d66dd2d32eb23aac2ca7ffd2", "parameters": [ { "name": "code", "in": "query", "description": "Code OAuth retourne par SuperPDP (absent en cas d'erreur).", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "State CSRF (doit matcher le cache).", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "description": "OAuth error code (RFC 6749 4.1.2.1) — present uniquement en cas de refus.", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "description": "Description humaine de l'erreur OAuth.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page Blade rendue qui poste un postMessage au window.opener.", "content": { "text/html": [] } } }, "security": [] } }, "/widget/onboarding/sirene/lookup": { "post": { "tags": [ "Onboarding-Widget" ], "summary": "Widget v3 — Lookup SIRENE (publishable key)", "description": "Wrapper publishable-key autour de `GET /sirene/{siret}` pour le widget v3 cote partenaire (auth client-side, pas de Bearer requis). Pipeline Etalab -> INSEE -> manual fallback.\n\nLa reponse contient `data.sirene_lookup_failed=true` + `code=SIRENE_MANUAL_ENTRY_REQUIRED` quand les 2 providers sont DOWN — le widget bascule alors en saisie manuelle.", "operationId": "d31784316581b2204887d6da598211e4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siret" ], "properties": { "siret": { "type": "string", "maxLength": 14, "minLength": 14, "example": "12345678901234" }, "force_manual": { "description": "Skip Etalab+INSEE (debug).", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Lookup OK (entreprise trouvee OU manual_entry_required).", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SireneCompanyData" }, "code": { "type": "string", "example": "SIRENE_MANUAL_ENTRY_REQUIRED", "nullable": true } }, "type": "object" } } } }, "400": { "description": "SIRET invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Publishable key invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SIRET introuvable chez Etalab et INSEE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation echouee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/widget/onboarding/sub-tenant": { "post": { "tags": [ "Onboarding-Widget" ], "summary": "Widget v3 — Creation SubTenant immediate", "description": "Cree un SubTenant en mode \"non-transmission\" (papier B2B + B2C illimite) IMMEDIATEMENT, sans attendre SuperPDP. Le widget peut ensuite afficher le banner `recommended_action` pour proposer l'activation SuperPDP (transmission Peppol/PPF).\n\nValidation : Step 0 (email + SIRET + contact) + Step 1 (company_data prefilled depuis Sirene OU saisie manuelle si Sirene KO -> `manual_entry=true`).\n\nRetourne 201 + SubTenantResource avec `onboarding_status=pending_superpdp`.", "operationId": "7ef2a229394b4f18612f76f58583b028", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "session_id", "email", "contact_first_name", "contact_last_name", "company_data" ], "properties": { "session_id": { "description": "UUID genere cote widget (idempotence).", "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email", "example": "gerant@acme.fr" }, "contact_first_name": { "type": "string", "example": "Jean" }, "contact_last_name": { "type": "string", "example": "Dupont" }, "contact_phone": { "description": "Format E.164.", "type": "string", "example": "+33612345678", "nullable": true }, "siret": { "description": "Requis sauf si manual_entry=true.", "type": "string", "example": "12345678901234", "nullable": true }, "manual_entry": { "description": "True si SIRENE+INSEE etaient DOWN au lookup.", "type": "boolean", "example": false }, "external_id": { "description": "ID utilisateur cote SaaS partenaire.", "type": "string", "nullable": true }, "company_data": { "required": [ "name", "address_line1", "postal_code", "city", "country" ], "properties": { "name": { "type": "string", "example": "ACME SAS" }, "legal_name": { "type": "string", "nullable": true }, "siret": { "type": "string", "nullable": true }, "siren": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true }, "legal_form": { "type": "string", "nullable": true }, "address_line1": { "type": "string", "example": "12 rue de la Paix" }, "address_line2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "example": "75002" }, "city": { "type": "string", "example": "Paris" }, "country": { "type": "string", "maxLength": 2, "minLength": 2, "example": "FR" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "SubTenant cree.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SubTenantResource" } }, "type": "object" } } } }, "401": { "description": "Publishable key invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation echouee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/widget/onboarding/superpdp/authorize": { "post": { "tags": [ "Onboarding-Widget" ], "summary": "Widget v3 — Genere URL OAuth SuperPDP prefilled", "description": "Genere l'URL d'autorisation OAuth 2.1 SuperPDP pour le SubTenant existant. PKCE S256 + state CSRF stockes en cache. Prefill `login_hint=email` + `superpdp_company_number=SIREN` pour eviter la double-saisie utilisateur.\n\nLe widget ouvre cette URL dans une popup. Au retour, SuperPDP redirige vers `https://api.scell.io/api/v1/widget/oauth-callback` qui poste un message au window.opener.\n\nUpdate `onboarding_status=superpdp_redirected`.", "operationId": "e7f5392554ea359883c42cc84db9e26f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "sub_tenant_id", "session_id" ], "properties": { "sub_tenant_id": { "type": "string", "format": "uuid" }, "session_id": { "description": "Meme UUID que celui utilise lors de la creation.", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "URL OAuth generee.", "content": { "application/json": { "schema": { "properties": { "authorize_url": { "type": "string", "format": "uri", "example": "https://api.superpdp.tech/oauth2/authorize?client_id=...&state=...&code_challenge=..." }, "state": { "description": "State CSRF one-shot.", "type": "string" } }, "type": "object" } } } }, "401": { "description": "Publishable key invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SubTenant introuvable ou non scope sur ce tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation echouee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/widget/onboarding/superpdp/callback": { "post": { "tags": [ "Onboarding-Widget" ], "summary": "Widget v3 — Exchange code OAuth + 1er polling SuperPDP", "description": "Echange le `code` OAuth contre un access_token + refresh_token (PKCE), persiste les tokens chiffres sur le SubTenant, et declenche immediatement un fetch `/oauth2_sessions/me` pour determiner le statut KYB final.\n\nRetourne le SubTenantResource a jour avec son nouveau `onboarding_status` (active si KYB OK, superpdp_pending_review sinon, superpdp_failed si refus).\n\nNB : Cet endpoint est l'alternative POST quand le widget ne peut pas attendre le postMessage de la popup `/widget/oauth-callback` — il sert aussi de fallback quand le partenaire route lui-meme le code.", "operationId": "b5c0f1e0a7f87e685e80d4c38bbc289a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "sub_tenant_id", "session_id", "code", "state" ], "properties": { "sub_tenant_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" }, "code": { "description": "Code OAuth retourne par SuperPDP.", "type": "string", "maxLength": 2048 }, "state": { "description": "State CSRF retourne par SuperPDP — doit matcher celui retourne par /authorize.", "type": "string", "maxLength": 512 } }, "type": "object" } } } }, "responses": { "200": { "description": "SubTenant mis a jour.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SubTenantResource" } }, "type": "object" } } } }, "401": { "description": "Publishable key invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SubTenant introuvable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Echange OAuth echoue (state expire, code invalide, PKCE KO, ...).", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "SUPERPDP_CALLBACK_FAILED" } }, "type": "object" } } } } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/widget/onboarding/sub-tenant/{id}/resume-url": { "get": { "tags": [ "Onboarding-Widget" ], "summary": "Widget v3 — Signed URL de reprise SuperPDP (7j)", "description": "Genere une signed URL temporaire (7j TTL, HMAC APP_KEY) que le partenaire peut afficher dans son interface ou envoyer par email pour reprendre le tunnel SuperPDP.\n\nNe fonctionne QUE pour les SubTenants en statut **non-final** (pending_superpdp, superpdp_redirected, superpdp_pending_review). Retourne 422 si onboarding_status est `active` ou `superpdp_failed`.", "operationId": "b91907ba8f824a41fb25877eeec27a98", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "URL signee generee.", "content": { "application/json": { "schema": { "properties": { "resume_url": { "type": "string", "format": "uri", "example": "https://api.scell.io/api/v1/widget/onboarding/sub-tenant/{uuid}/resume?expires=...&signature=..." }, "expires_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Publishable key invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SubTenant introuvable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Onboarding deja final (active ou superpdp_failed).", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "ONBOARDING_ALREADY_FINAL" }, "onboarding_status": { "$ref": "#/components/schemas/OnboardingStatus" } }, "type": "object" } } } } }, "security": [ { "publishableKeyAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Lister les webhooks", "description": "Retourne la liste des webhooks configurés.", "operationId": "91193654887d260858477c0e28986aac", "parameters": [ { "name": "company_id", "in": "query", "description": "Filtrer par entreprise", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Liste des webhooks", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Créer un webhook", "description": "Configure un nouveau webhook pour recevoir des notifications en temps réel via POST.", "operationId": "5c31ba93f1b10f759a449de48e3c8ba0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "url", "events", "environment" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://mon-site.com/webhooks/scell" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "invoice.validated", "signature.completed" ] }, "example": [ "invoice.validated", "signature.completed" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "headers": { "type": "object", "example": { "X-Custom-Auth": "secret123" } }, "retry_count": { "type": "integer", "default": 3, "maximum": 5, "minimum": 0 }, "timeout_seconds": { "type": "integer", "default": 30, "maximum": 60, "minimum": 5 } }, "type": "object" } } } }, "responses": { "201": { "description": "Webhook créé", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "secret": { "type": "string" } }, "type": "object" } ] } }, "type": "object" } } } }, "422": { "description": "Erreur de validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}": { "put": { "tags": [ "Webhooks" ], "summary": "Modifier un webhook", "description": "Met à jour la configuration d'un webhook existant.", "operationId": "52f366087c1bccce6838f4d7cb685a4d", "parameters": [ { "name": "id", "in": "path", "description": "ID du webhook", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "headers": { "type": "object" }, "retry_count": { "type": "integer" }, "timeout_seconds": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook mis à jour", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Supprimer un webhook", "description": "Supprime définitivement un webhook.", "operationId": "15ae3ed7a8c0499b618f7e81d5226d84", "parameters": [ { "name": "id", "in": "path", "description": "ID du webhook", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook supprimé", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/regenerate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Régénérer le secret", "description": "Génère un nouveau secret de signature pour le webhook.", "operationId": "5839193e5cba4b11c3c87e503990d937", "parameters": [ { "name": "id", "in": "path", "description": "ID du webhook", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Secret régénéré", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "secret": { "type": "string" } }, "type": "object" } ] } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Tester le webhook", "description": "Envoie un événement de test immédiat vers l'URL configurée.", "operationId": "6e15b2453640c09e1db57c22a7268129", "parameters": [ { "name": "id", "in": "path", "description": "ID du webhook", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test effectué", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "status_code": { "type": "integer" }, "response_time_ms": { "type": "integer" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/logs": { "get": { "tags": [ "Webhooks" ], "summary": "Voir les logs", "description": "Récupère l'historique des envois pour ce webhook.", "operationId": "334142d207cbac3286a6b94952577a53", "parameters": [ { "name": "id", "in": "path", "description": "ID du webhook", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "per_page", "in": "query", "description": "Nombre d'éléments", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Logs du webhook", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "integer" }, "success": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "PaymentMeansCode": { "description": "Code UN/ECE 4461 (BT-81 EN16931 / Factur-X) du moyen d'encaissement. Sous-ensemble retenu = moyens de paiement réellement rencontrés en B2B France. Inscrit dans le XML CII Factur-X au noeud `X`.\n\n**Labels** :\n- `1` : Non spécifié (fallback)\n- `10` : Espèces\n- `20` : Chèque\n- `30` : Virement (international)\n- `42` : Versement bancaire (sans IBAN)\n- `48` : Carte bancaire\n- `49` : Prélèvement\n- `57` : Accord permanent (mandat)\n- `58` : Virement SEPA (B2B France privilégié, default)\n- `59` : Prélèvement SEPA\n- `97` : Compensation inter-comptes", "type": "string", "enum": [ "1", "10", "20", "30", "42", "48", "49", "57", "58", "59", "97" ], "example": "58" }, "User": { "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "full_name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "admin", "user" ] }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Company": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "siret": { "type": "string", "example": "12345678901234" }, "siren": { "type": "string", "example": "123456789" }, "vat_number": { "type": "string", "nullable": true }, "legal_form": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending_kyc", "active", "suspended" ] }, "address_line1": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "example": "FR" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ApiKey": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "masked_key": { "type": "string", "example": "sk_live_...abc123" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Invoice": { "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "invoice_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "direction": { "type": "string", "enum": [ "outgoing", "incoming" ] }, "output_format": { "type": "string", "enum": [ "facturx", "ubl", "cii" ] }, "status": { "type": "string", "enum": [ "draft", "validating", "validated", "converting", "converted", "transmitting", "transmitted", "accepted", "rejected", "disputed", "paid", "received", "completed", "error", "refunded", "partially_refunded" ] }, "seller_name": { "type": "string" }, "seller_siret": { "type": "string" }, "buyer_name": { "type": "string" }, "buyer_siret": { "type": "string" }, "total_ht": { "type": "number", "format": "float" }, "total_tva": { "type": "number", "format": "float" }, "total_ttc": { "type": "number", "format": "float" }, "currency": { "type": "string", "example": "EUR" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "credit_notes_count": { "description": "Nombre d'avoirs (credit notes) emis lies a cette facture (partiel ou total). Disponible depuis l'API 2026-05-04.", "type": "integer", "example": 1 }, "credited_amount": { "description": "Montant total avoire (somme des avoirs valides/envoyes/transmis). Si credited_amount >= total_ttc, la facture est totalement avoiree. Disponible depuis l'API 2026-05-04.", "type": "number", "format": "float", "example": 9 }, "credit_notes": { "description": "Liste des avoirs lies, expose uniquement sur l'endpoint detail (GET /tenant/invoices/{id}). Disponible depuis l'API 2026-05-04.", "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "credit_note_number": { "type": "string" }, "type": { "type": "string", "enum": [ "partial", "total" ] }, "total": { "type": "number", "format": "float" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Signature": { "description": "Demande de signature électronique simple eIDAS EU-SES", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "description": "Référence externe fournie par le client (votre ID métier)", "type": "string", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "waiting_signers", "partially_signed", "completed", "refused", "expired", "error" ] }, "status_message": { "description": "Message d'erreur si status=error", "type": "string", "nullable": true }, "document_name": { "type": "string" }, "document_size": { "description": "Taille du document original en octets", "type": "integer" }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/Signer" } }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "archive_enabled": { "description": "Archivage 10 ans eIDAS activé", "type": "boolean" }, "amount_charged": { "description": "Montant débité en euros (null en sandbox)", "type": "number", "format": "float", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Signer": { "description": "Signataire d'une demande de signature", "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "description": "Format E.164 (+33...)", "type": "string", "nullable": true }, "auth_method": { "description": "Méthode d'envoi du code OTP", "type": "string", "enum": [ "email", "sms", "both" ] }, "status": { "type": "string", "enum": [ "waiting", "signed", "refused" ] }, "signing_url": { "description": "URL HMAC-signée à distribuer au signataire. Pointe vers la page wrapper Scell.io (https://sign.scell.io/sign/...) qui embed la page de signature upstream avec le branding Scell. Format : https://sign.scell.io/sign/{signature_id}/{signer_id}?expires=...&signature=HMAC.", "type": "string", "format": "uri", "nullable": true }, "upstream_signing_url": { "description": "URL upstream brute (uniquement pour debug). Préférer signing_url pour la distribution aux signataires.", "type": "string", "format": "uri", "nullable": true }, "message": { "description": "Message custom envoyé au signataire (placeholder {OTP} supporté)", "type": "string", "nullable": true }, "signed_at": { "type": "string", "format": "date-time", "nullable": true }, "refused_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "Balance": { "properties": { "amount": { "type": "number", "format": "float" }, "auto_reload_enabled": { "type": "boolean" }, "auto_reload_threshold": { "type": "number", "format": "float" }, "auto_reload_amount": { "type": "number", "format": "float" }, "low_balance_alert_threshold": { "type": "number", "format": "float" }, "critical_balance_alert_threshold": { "type": "number", "format": "float" } }, "type": "object" }, "Transaction": { "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "amount": { "type": "number", "format": "float" }, "balance_after": { "type": "number", "format": "float" }, "currency": { "type": "string", "example": "EUR" }, "type": { "type": "string", "enum": [ "credit", "debit" ] }, "service": { "type": "string", "enum": [ "invoice", "signature", "manual", "auto_reload" ] }, "description": { "type": "string" }, "entity_type": { "type": "string", "nullable": true }, "entity_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Webhook": { "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "is_active": { "type": "boolean" }, "failure_count": { "type": "integer" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Error": { "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "nullable": true } }, "type": "object" }, "CreditNote": { "properties": { "id": { "type": "string", "format": "uuid" }, "credit_note_number": { "type": "string", "example": "AV-2024-0001", "nullable": true }, "reference": { "type": "string", "nullable": true }, "invoice_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "partial", "total" ] }, "status": { "type": "string", "enum": [ "draft", "sent" ] }, "reason": { "type": "string" }, "client_name": { "type": "string" }, "client_email": { "type": "string", "format": "email", "nullable": true }, "client_siret": { "type": "string", "nullable": true }, "client_address": { "type": "object", "nullable": true }, "subtotal": { "type": "number", "format": "float" }, "tax_amount": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "currency": { "type": "string", "example": "EUR" }, "issue_date": { "type": "string", "format": "date" }, "is_locked": { "type": "boolean" }, "is_sandbox": { "type": "boolean" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteItem" } } }, "type": "object" }, "CreditNoteItem": { "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_line_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "format": "float" }, "tax_rate": { "type": "number", "format": "float" }, "tax_amount": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" } }, "type": "object" }, "OnboardingSession": { "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "initiated", "siret_verified", "vat_verified", "documents_pending", "documents_submitted", "under_review", "completed", "failed", "expired" ] }, "mode": { "type": "string", "enum": [ "api", "redirect", "embedded" ] }, "siret": { "type": "string", "example": "12345678901234" }, "company_name": { "type": "string" }, "vat_number": { "type": "string", "nullable": true }, "redirect_url": { "type": "string", "format": "uri", "nullable": true }, "embed_token": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "OnboardingComplete": { "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "api_key": { "description": "Clé API du tenant (affichée une seule fois)", "type": "string" }, "kyb_status": { "type": "string", "enum": [ "pending", "documents_submitted", "under_review", "verified", "rejected" ] }, "dashboard_url": { "type": "string", "format": "uri" } }, "type": "object" }, "CompanyVerification": { "properties": { "siret_valid": { "type": "boolean" }, "company": { "properties": { "name": { "type": "string" }, "legal_form": { "type": "string" }, "siret": { "type": "string" }, "siren": { "type": "string" }, "naf_code": { "type": "string" }, "address": { "type": "object" } }, "type": "object" }, "vat": { "properties": { "valid": { "type": "boolean" }, "number": { "type": "string" } }, "type": "object" }, "next_step": { "type": "string" }, "required_documents": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "SubTenant": { "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "external_id": { "description": "ID unique dans votre systeme", "type": "string" }, "name": { "type": "string" }, "siret": { "type": "string", "maxLength": 14, "minLength": 14, "nullable": true }, "vat_number": { "type": "string", "nullable": true }, "address": { "properties": { "line1": { "type": "string" }, "line2": { "type": "string", "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string", "maxLength": 2, "minLength": 2 } }, "type": "object", "nullable": true }, "contact_email": { "type": "string", "format": "email", "nullable": true }, "contact_phone": { "type": "string", "nullable": true }, "onboarding_status": { "description": "Statut d'onboarding (refonte widget v3, 2026-05-08). Remplace kyc_status (drop).", "type": "string", "enum": [ "pending_superpdp", "superpdp_redirected", "superpdp_authorized", "superpdp_pending_review", "active", "superpdp_failed" ] }, "can_issue_invoices": { "type": "boolean" }, "can_transmit_electronic": { "type": "boolean" }, "superpdp_company_verification_status": { "type": "string", "enum": [ "verified", "needs_review", "failed" ], "nullable": true }, "superpdp_user_identity_verification_status": { "type": "string", "enum": [ "verified", "needs_review", "not_verified" ], "nullable": true }, "last_polled_at": { "type": "string", "format": "date-time", "nullable": true }, "is_active": { "type": "boolean" }, "settings": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "IncomingInvoice": { "description": "Facture entrante (fournisseur)", "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_number": { "description": "Numero de facture du fournisseur", "type": "string" }, "external_id": { "description": "Identifiant externe optionnel", "type": "string", "nullable": true }, "direction": { "description": "Direction (toujours incoming)", "type": "string", "enum": [ "incoming" ] }, "status": { "description": "Statut de traitement", "type": "string", "enum": [ "received", "accepted", "rejected", "disputed", "paid" ] }, "issue_date": { "description": "Date d'emission", "type": "string", "format": "date" }, "due_date": { "description": "Date d'echeance", "type": "string", "format": "date", "nullable": true }, "seller_siret": { "description": "SIRET du fournisseur", "type": "string" }, "seller_name": { "description": "Nom du fournisseur", "type": "string" }, "seller_address": { "description": "Adresse du fournisseur", "type": "object" }, "buyer_siret": { "description": "SIRET de l'acheteur", "type": "string" }, "buyer_name": { "description": "Nom de l'acheteur", "type": "string" }, "buyer_address": { "description": "Adresse de l'acheteur", "type": "object" }, "total_ht": { "description": "Total hors taxes", "type": "number", "format": "float" }, "total_tax": { "description": "Total TVA", "type": "number", "format": "float" }, "total_ttc": { "description": "Total TTC", "type": "number", "format": "float" }, "currency": { "type": "string", "example": "EUR" }, "received_at": { "description": "Date de reception", "type": "string", "format": "date-time" }, "accepted_at": { "type": "string", "format": "date-time", "nullable": true }, "rejected_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "rejection_reason": { "description": "Motif de rejet", "type": "string", "nullable": true }, "rejection_code": { "type": "string", "enum": [ "incorrect_amount", "duplicate", "unknown_order", "incorrect_vat", "other" ], "nullable": true }, "payment_reference": { "description": "Reference du paiement", "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "line_number": { "type": "integer" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "format": "float" }, "tax_rate": { "type": "number", "format": "float" }, "total_ht": { "type": "number", "format": "float" }, "total_tax": { "type": "number", "format": "float" }, "total_ttc": { "type": "number", "format": "float" } }, "type": "object" } }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "OnboardingStatus": { "description": "Statut d'onboarding du SubTenant (refonte widget v3, 2026-05-08).", "type": "string", "enum": [ "pending_superpdp", "superpdp_redirected", "superpdp_authorized", "superpdp_pending_review", "active", "superpdp_failed" ] }, "RecommendedAction": { "description": "Action recommandee pour le SaaS partenaire (banner i18n FR/EN). Calculee dynamiquement par SubTenantResource a partir du onboarding_status courant.", "required": [ "code", "severity", "title_fr", "title_en", "message_fr", "message_en", "dismissible" ], "properties": { "code": { "description": "Identifiant stable de l'action (ex: superpdp_kyb_pending).", "type": "string", "example": "superpdp_not_started" }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "success" ] }, "title_fr": { "description": "Titre FR du banner.", "type": "string" }, "title_en": { "description": "Titre EN du banner.", "type": "string" }, "message_fr": { "description": "Message detaille FR.", "type": "string" }, "message_en": { "description": "Message detaille EN.", "type": "string" }, "cta_label_fr": { "description": "Libelle bouton FR (null si pas de CTA).", "type": "string", "nullable": true }, "cta_label_en": { "description": "Libelle bouton EN (null si pas de CTA).", "type": "string", "nullable": true }, "cta_url": { "description": "URL ou clef d'action a executer (ex: superpdp_authorize, superpdp_resume, mailto:support@scell.io).", "type": "string", "nullable": true }, "dismissible": { "description": "L'utilisateur peut-il fermer le banner.", "type": "boolean" } }, "type": "object" }, "SubTenantResource": { "description": "Surface complete d'un SubTenant retournee par les endpoints widget v3 et tenant Bearer (refonte 2026-05-08, drop kyc_*).", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "siret": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true }, "contact_email": { "type": "string", "format": "email", "nullable": true }, "contact_phone": { "type": "string", "nullable": true }, "contact_first_name": { "type": "string", "nullable": true }, "contact_last_name": { "type": "string", "nullable": true }, "sirene_lookup_failed": { "description": "True si le SubTenant a ete cree avec saisie manuelle apres echec Sirene+INSEE.", "type": "boolean" }, "is_active": { "type": "boolean" }, "onboarding_status": { "$ref": "#/components/schemas/OnboardingStatus" }, "can_issue_invoices": { "description": "True si le SubTenant peut emettre des factures (B2C illimite, B2B en mode papier).", "type": "boolean" }, "can_transmit_electronic": { "description": "True si le SubTenant peut transmettre electroniquement (Peppol/PPF) — necessite onboarding_status=active.", "type": "boolean" }, "recommended_action": { "$ref": "#/components/schemas/RecommendedAction" }, "superpdp_company_verification_status": { "type": "string", "enum": [ "verified", "needs_review", "failed" ], "nullable": true }, "superpdp_user_identity_verification_status": { "type": "string", "enum": [ "verified", "needs_review", "not_verified" ], "nullable": true }, "superpdp_company_id": { "type": "integer", "nullable": true }, "superpdp_connected_at": { "type": "string", "format": "date-time", "nullable": true }, "last_polled_at": { "description": "Date du dernier polling GET /oauth2_sessions/me chez SuperPDP.", "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "SireneCompanyData": { "description": "Donnees company normalisees depuis Etalab/INSEE (format unifie consomme par le widget v3).", "properties": { "name": { "type": "string", "example": "QR COMMUNICATION" }, "legal_name": { "type": "string", "example": "QR COMMUNICATION SAS" }, "siret": { "type": "string", "example": "12345678901234" }, "siren": { "type": "string", "example": "123456789" }, "vat_number": { "type": "string", "example": "FR12123456789" }, "legal_form": { "type": "string", "nullable": true }, "naf_code": { "type": "string", "nullable": true }, "address_line1": { "type": "string", "nullable": true }, "address_line2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "country": { "type": "string", "example": "FR" }, "is_active": { "type": "boolean" }, "creation_date": { "type": "string", "format": "date", "nullable": true }, "employee_range": { "type": "string", "nullable": true }, "sirene_lookup_failed": { "description": "True si les providers SIRENE sont DOWN — debloque la saisie manuelle dans le widget.", "type": "boolean", "nullable": true } }, "type": "object" }, "FiscalEntry": { "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "sequence_number": { "description": "Numero de sequence monotone croissant", "type": "integer" }, "entry_type": { "description": "Type d'evenement fiscal", "type": "string", "example": "invoice_validated" }, "entity_type": { "type": "string", "example": "App\\Models\\Invoice", "nullable": true }, "entity_id": { "type": "string", "format": "uuid", "nullable": true }, "fiscal_date": { "type": "string", "format": "date" }, "data_hash": { "description": "SHA-256 du snapshot", "type": "string" }, "chain_hash": { "description": "Hash de chaine", "type": "string" }, "legal_status": { "type": "string", "enum": [ "hors_fiscalite", "donnee_fiscale", "preuve_legale", "declaration_legale" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "FiscalClosing": { "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "sub_tenant_id": { "type": "string", "format": "uuid", "nullable": true }, "closing_date": { "type": "string", "format": "date" }, "closing_type": { "type": "string", "enum": [ "daily", "monthly", "annual" ], "example": "daily" }, "entries_count": { "type": "integer" }, "first_sequence_number": { "type": "integer" }, "last_sequence_number": { "type": "integer" }, "closing_hash": { "description": "SHA-256 du contenu de la cloture (hash de chaine ISCA)", "type": "string" }, "previous_closing_hash": { "type": "string", "nullable": true }, "totals": { "type": "object" }, "cumulative_totals": { "type": "object" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "status": { "type": "string", "enum": [ "closed", "anchored" ] }, "csv_path": { "description": "Chemin S3 du CSV de cloture (NF525-like format)", "type": "string", "nullable": true }, "csv_hash": { "type": "string", "nullable": true }, "ots_proof_base64": { "description": "Receipt OpenTimestamps ancrant le `closing_hash` dans la blockchain Bitcoin, encode en base64 (le binaire BYTEA brut n'est pas expose car non-UTF8). Permet a tout tiers de verifier l'ancrage sans dependre de Scell.io. Null si la cloture n'a pas encore ete soumise aux calendars OTS.", "type": "string", "format": "byte", "example": "AE9wZW5UaW1lc3RhbXBzAABQcm9vZgC/ieLohOiSlA==", "nullable": true }, "ots_status": { "type": "string", "enum": [ "pending", "bitcoin_confirmed", "failed" ], "nullable": true }, "ots_submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "ots_bitcoin_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "ots_calendars": { "type": "array", "items": { "type": "object" }, "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "FiscalRule": { "properties": { "id": { "type": "string", "format": "uuid" }, "rule_key": { "type": "string", "example": "vat_rate_france_standard" }, "version": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "vat", "invoicing", "credit_note", "closing", "export" ] }, "rule_definition": { "type": "object" }, "effective_from": { "type": "string", "format": "date" }, "effective_until": { "type": "string", "format": "date", "nullable": true }, "is_active": { "type": "boolean" }, "legal_reference": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PaymentScheduleLine": { "description": "Ligne d'échéancier de paiement d'un devis", "properties": { "id": { "type": "string", "format": "uuid" }, "quote_id": { "type": "string", "format": "uuid" }, "order": { "description": "Ordre d'affichage de la ligne (1-based)", "type": "integer", "example": 1 }, "amount_type": { "description": "Type de montant : pourcentage du total TTC ou montant fixe en euros", "type": "string", "enum": [ "percent", "fixed" ] }, "amount_value": { "description": "Valeur du montant (pourcentage 0-100 ou montant TTC en euros)", "type": "number", "format": "float", "example": 30 }, "amount_ttc_snapshot": { "description": "Montant TTC calculé au moment du dernier enregistrement (null avant calcul)", "type": "number", "format": "float", "nullable": true }, "due_date": { "description": "Date d'échéance de la ligne (YYYY-MM-DD)", "type": "string", "format": "date", "nullable": true }, "milestone_label": { "description": "Libellé de jalon (ex: \"À la livraison\")", "type": "string", "example": "À la signature", "nullable": true }, "description": { "description": "Description libre de la ligne", "type": "string", "nullable": true }, "auto_generate": { "description": "Si true, une facture d'acompte sera générée automatiquement à l'échéance", "type": "boolean", "example": false }, "status": { "description": "Statut de la ligne", "type": "string", "enum": [ "pending", "invoiced", "cancelled" ] }, "is_locked": { "description": "true si la ligne est verrouillée (déjà facturée ou annulée)", "type": "boolean", "example": false }, "is_overdue": { "description": "true si la date d'échéance est dépassée et la ligne non facturée", "type": "boolean", "example": false }, "invoice_id": { "description": "UUID de la facture d'acompte générée (null si non encore facturée)", "type": "string", "format": "uuid", "nullable": true }, "invoiced_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PaymentScheduleLineInput": { "description": "Données pour créer/modifier une ligne d'échéancier", "required": [ "amount_type", "amount_value" ], "properties": { "amount_type": { "description": "Type de montant", "type": "string", "enum": [ "percent", "fixed" ] }, "amount_value": { "description": "Valeur du montant (> 0)", "type": "number", "format": "float", "example": 30 }, "due_date": { "description": "Date d'échéance (YYYY-MM-DD, >= today). Au moins due_date ou milestone_label requis.", "type": "string", "format": "date", "nullable": true }, "milestone_label": { "description": "Libellé de jalon. Au moins due_date ou milestone_label requis.", "type": "string", "example": "À la livraison", "nullable": true }, "description": { "description": "Description libre (max 1000 car.)", "type": "string", "nullable": true }, "auto_generate": { "description": "Auto-génération de facture d'acompte à l'échéance (requiert due_date)", "type": "boolean", "example": false } }, "type": "object" }, "PaymentSummary": { "description": "Récapitulatif calculé de l'état de paiement d'un devis", "properties": { "quote": { "properties": { "id": { "type": "string", "format": "uuid" }, "quote_number": { "type": "string", "example": "DEV-2026-0001" }, "total_ttc": { "type": "number", "format": "float", "example": 1000 } }, "type": "object" }, "schedule": { "properties": { "planned_total_ttc": { "type": "number", "format": "float" }, "planned_remainder": { "type": "number", "format": "float" }, "lines_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "invoiced_count": { "type": "integer" } }, "type": "object" }, "invoiced": { "properties": { "gross_ttc": { "type": "number", "format": "float" }, "credits_ttc": { "type": "number", "format": "float" }, "net_ttc": { "type": "number", "format": "float" }, "remaining_ttc": { "type": "number", "format": "float" }, "remaining_pct": { "type": "number", "format": "float" } }, "type": "object" }, "next_due": { "properties": { "line_id": { "type": "string", "format": "uuid" }, "due_date": { "type": "string", "format": "date" }, "amount_ttc": { "type": "number", "format": "float" }, "label": { "type": "string", "nullable": true }, "days_until": { "type": "integer" } }, "type": "object", "nullable": true }, "overdue": { "type": "array", "items": { "properties": { "line_id": { "type": "string", "format": "uuid" }, "due_date": { "type": "string", "format": "date" }, "amount_ttc": { "type": "number", "format": "float" }, "label": { "type": "string", "nullable": true }, "days_overdue": { "type": "integer" } }, "type": "object" } }, "superpdp_status": { "type": "array", "items": { "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "status": { "type": "string" }, "accepted_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } }, "type": "object" }, "Branding": { "description": "Branding email d'un tenant ou sub-tenant (logo, couleurs, pied de page)", "properties": { "scope": { "description": "Contexte du branding : master tenant ou sub-tenant", "type": "string", "enum": [ "tenant", "sub_tenant" ] }, "company_id": { "description": "UUID de la Company portant ce branding", "type": "string", "format": "uuid" }, "brand_logo_url": { "description": "URL publique du logo email (PNG/SVG recommandé, max 500 car.)", "type": "string", "format": "uri", "nullable": true }, "brand_primary_color": { "description": "Couleur primaire au format HEX (#RRGGBB)", "type": "string", "example": "#4f46e5", "nullable": true }, "brand_email_footer": { "description": "Pied de page email (mentions légales, coordonnées), max 2000 car.", "type": "string", "nullable": true }, "brand_email_signature": { "description": "Signature email (nom, titre, contact), max 500 car.", "type": "string", "nullable": true }, "is_complete": { "description": "true si tous les champs obligatoires sont renseignés", "type": "boolean" }, "missing_fields": { "description": "Liste des clés manquantes pour compléter le branding", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "BrandingInput": { "description": "Payload de mise à jour du branding", "properties": { "brand_logo_url": { "description": "URL publique du logo email (max 500 car.)", "type": "string", "format": "uri", "nullable": true }, "brand_primary_color": { "description": "Couleur primaire HEX (#RRGGBB)", "type": "string", "example": "#4f46e5", "nullable": true }, "brand_email_footer": { "description": "Pied de page email (max 2000 car.)", "type": "string", "nullable": true }, "brand_email_signature": { "description": "Signature email (max 500 car.)", "type": "string", "nullable": true } }, "type": "object" }, "SendInvoiceByEmailRequest": { "description": "Payload d'envoi de facture par email", "properties": { "recipient_email": { "description": "Email du destinataire (override l'email de l'acheteur, optionnel)", "type": "string", "format": "email", "nullable": true }, "cc": { "description": "Adresses email en copie (max 5)", "type": "array", "items": { "type": "string", "format": "email" }, "nullable": true }, "message": { "description": "Message personnalisé ajouté au corps de l'email (max 2000 car.)", "type": "string", "nullable": true } }, "type": "object" }, "SendInvoiceByEmailResponse": { "description": "Résultat de l'envoi de la facture par email", "properties": { "sent_to": { "description": "Adresse email réelle du destinataire principal", "type": "string", "format": "email" }, "sent_at": { "description": "Horodatage UTC de l'envoi", "type": "string", "format": "date-time" }, "cc": { "description": "Adresses email en copie effectivement utilisées", "type": "array", "items": { "type": "string", "format": "email" } } }, "type": "object" }, "PaymentSchedulePreset": { "description": "Préréglage de plan de paiement (combinaison courante de conditions)", "properties": { "key": { "description": "Identifiant machine du préréglage", "type": "string", "example": "deposit_30_balance_70" }, "label": { "description": "Libellé court", "type": "string", "example": "Acompte 30 % / Solde 70 %" }, "description": { "description": "Explication humaine du préréglage", "type": "string" }, "lines": { "description": "Lignes pré-définies à appliquer à l'échéancier", "type": "array", "items": { "properties": { "percentage": { "description": "Pourcentage du montant total (0-100)", "type": "integer", "example": 30 }, "label": { "description": "Libellé de la tranche", "type": "string", "example": "Acompte (30 %)" }, "due_offset_days": { "description": "Délai en jours depuis la date d'acceptation du devis (null = à l'acceptation)", "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" }, "BuyerAddress": { "description": "Adresse postale structurée (facturation ou livraison).", "required": [ "line1", "postal_code", "city", "country" ], "properties": { "name": { "description": "Nom du destinataire / site (BT-74 livraison). Optionnel.", "type": "string", "maxLength": 255, "nullable": true }, "line1": { "type": "string", "maxLength": 255, "example": "10 rue de la Paix" }, "line2": { "type": "string", "maxLength": 255, "nullable": true }, "postal_code": { "type": "string", "maxLength": 20, "example": "75002" }, "city": { "type": "string", "maxLength": 100, "example": "Paris" }, "region": { "description": "Subdivision pays (BT-79, optionnel).", "type": "string", "maxLength": 100, "nullable": true }, "country": { "description": "Code pays ISO 3166-1 alpha-2.", "type": "string", "maxLength": 2, "minLength": 2, "example": "FR" } }, "type": "object" }, "Buyer": { "description": "Acheteur du registre réutilisable, scopé strictement par (tenant, sub_tenant). Les colonnes dénormalisées sur les factures restent immuables : modifier un acheteur n'impacte jamais les factures déjà émises (compliance ISCA).", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255, "example": "ACME SARL" }, "is_individual": { "description": "Acheteur particulier (B2C) si true ; entreprise (B2B) sinon.", "type": "boolean", "example": false }, "siret": { "description": "SIRET (B2B FR). Optionnel pour un particulier ou un acheteur hors France.", "type": "string", "maxLength": 14, "minLength": 14, "example": "98765432109876", "nullable": true }, "vat_number": { "type": "string", "maxLength": 20, "example": "FR12345678901", "nullable": true }, "legal_id": { "description": "Identifiant légal alternatif (registre étranger).", "type": "string", "maxLength": 50, "nullable": true }, "legal_id_scheme": { "description": "Schéma de l'identifiant légal (ex: code ISO 6523).", "type": "string", "maxLength": 10, "nullable": true }, "email": { "type": "string", "format": "email", "maxLength": 255, "nullable": true }, "phone": { "type": "string", "maxLength": 50, "nullable": true }, "country": { "description": "Pays principal (ISO 3166-1 alpha-2).", "type": "string", "maxLength": 2, "minLength": 2, "example": "FR" }, "billing_address": { "$ref": "#/components/schemas/BuyerAddress" }, "shipping_address": { "oneOf": [ { "$ref": "#/components/schemas/BuyerAddress" } ], "nullable": true, "description": "Adresse de livraison (BG-13). NULL ou identique à billing_address ⇒ ship=bill (BG-13 omis dans le Factur-X)." }, "metadata": { "description": "Données libres (clé/valeur).", "type": "object", "nullable": true }, "notes": { "type": "string", "maxLength": 5000, "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "QuoteLine": { "description": "Ligne d'un devis.", "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string", "maxLength": 500, "example": "Prestation de conseil" }, "detail": { "type": "string", "maxLength": 1000, "nullable": true }, "quantity": { "type": "number", "format": "float", "minimum": 0.001, "example": 2 }, "unit": { "type": "string", "maxLength": 50, "example": "jour", "nullable": true }, "unit_price_ht": { "type": "number", "format": "float", "minimum": 0, "example": 500 }, "tax_rate": { "type": "number", "format": "float", "maximum": 100, "minimum": 0, "example": 20 }, "reference": { "type": "string", "maxLength": 100, "nullable": true }, "position": { "type": "integer", "minimum": 1, "nullable": true }, "total_ht": { "description": "Total HT calculé.", "type": "number", "format": "float" }, "total_tax": { "type": "number", "format": "float" }, "total_ttc": { "type": "number", "format": "float" }, "metadata": { "type": "object", "nullable": true } }, "type": "object" }, "Quote": { "description": "Devis. Audit trail propre (chaîne SHA-256 séparée du ledger ISCA fiscal), isolé par (tenant, sub_tenant).", "properties": { "id": { "type": "string", "format": "uuid" }, "quote_number": { "description": "Numérotation DEV-YYYY-NNNN par (tenant, sub_tenant, année).", "type": "string", "example": "DEV-2026-0042" }, "status": { "type": "string", "enum": [ "draft", "sent", "viewed", "accepted", "refused", "expired", "converted", "cancelled" ], "example": "draft" }, "issue_date": { "type": "string", "format": "date" }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "currency": { "type": "string", "maxLength": 3, "minLength": 3, "example": "EUR" }, "title": { "type": "string", "maxLength": 255, "nullable": true }, "description": { "type": "string", "maxLength": 5000, "nullable": true }, "internal_notes": { "type": "string", "maxLength": 5000, "nullable": true }, "external_id": { "type": "string", "maxLength": 100, "nullable": true }, "invoice_template_id": { "type": "string", "format": "uuid", "nullable": true }, "callback_url": { "description": "URL de redirection après acceptation/refus via le viewer public.", "type": "string", "format": "uri", "maxLength": 500, "nullable": true }, "signature_required": { "type": "boolean" }, "auto_convert_on_accept": { "type": "boolean" }, "buyer_id": { "type": "string", "format": "uuid", "nullable": true }, "buyer_name": { "type": "string", "nullable": true }, "buyer_email": { "type": "string", "format": "email", "nullable": true }, "buyer_siret": { "type": "string", "nullable": true }, "total_ht": { "type": "number", "format": "float" }, "total_tax": { "type": "number", "format": "float" }, "total_ttc": { "type": "number", "format": "float" }, "public_url": { "description": "Lien public signé (HMAC) valable 90 jours par défaut.", "type": "string", "format": "uri", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteLine" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "VatCategory": { "description": "Catégorie TVA (taxonomie interne, mapping vers EN16931).\n\n| Catégorie | Taux FR par défaut | EN16931 | Usage |\n|-----------|-------------------|---------|-------|\n| `STANDARD` | 20 % | S | Taux normal (art. 278 CGI) |\n| `INTERMEDIATE` | 10 % | S | Restauration, transport, hôtellerie |\n| `REDUCED` | 5,5 % | S | Alimentation, livres |\n| `SUPER_REDUCED` | 2,1 % | S | Médicaments remboursés |\n| `ZERO_RATED` | 0 % | Z | Exports hors UE |\n| `EXEMPT` | — | E | Opération exonérée (médical, financier) |\n| `REVERSE_CHARGE` | 0 % | AE | Autoliquidation UE B2B (art. 259-1 CGI) |\n| `OUT_OF_SCOPE` | — | O | Hors champ TVA (export hors UE) |", "type": "string", "enum": [ "STANDARD", "INTERMEDIATE", "REDUCED", "SUPER_REDUCED", "ZERO_RATED", "EXEMPT", "REVERSE_CHARGE", "OUT_OF_SCOPE" ], "example": "STANDARD" }, "VatBuyerContext": { "description": "Acheteur fourni inline (alternative à `buyer_id`). `country` ISO 3166-1 alpha-2.", "properties": { "country": { "description": "Pays acheteur (ISO 3166-1 alpha-2).", "type": "string", "maxLength": 2, "minLength": 2, "example": "DE" }, "is_individual": { "description": "Particulier (B2C) ou entreprise (B2B).", "type": "boolean", "example": false }, "vat_number": { "description": "Numéro de TVA intracommunautaire (B2B UE).", "type": "string", "maxLength": 32, "example": "DE123456789", "nullable": true }, "vat_number_valid": { "description": "TVA validée VIES (typiquement en amont). Bloque/active la règle R2 (reverse charge).", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "LineVatContext": { "description": "Contexte de la ligne pour résolution TVA.", "properties": { "category": { "$ref": "#/components/schemas/VatCategory" }, "place_of_supply": { "description": "Pays lieu de prestation (ISO 3166-1 alpha-2). Override art. 259 A CGI quand différent du pays acheteur (immobilier, restauration, événementiel).", "type": "string", "maxLength": 2, "minLength": 2, "example": "FR", "nullable": true }, "service_nature": { "description": "Nature du service (informatif, libre). Aide à documenter le motif de l'override 259 A.", "type": "string", "maxLength": 100, "example": "real_estate_service", "nullable": true }, "tax_rate": { "description": "Taux saisi par l'utilisateur. Si fourni, des `warnings` de cohérence sont émis en cas de mismatch avec le taux résolu.", "type": "number", "format": "float", "maximum": 100, "minimum": 0, "example": 20, "nullable": true } }, "type": "object" }, "VatSellerContext": { "description": "Override optionnel du vendeur (sub-tenant étranger). Défaut : tenant->defaultCompany ou première Company du sub-tenant.", "properties": { "country": { "type": "string", "maxLength": 2, "minLength": 2, "example": "FR" }, "vat_number": { "type": "string", "maxLength": 32, "example": "FR42494380686", "nullable": true } }, "type": "object" }, "ResolveVatContextRequest": { "description": "Payload `POST /v1/tenant/buyers/vat-context`. Fournir `buyer_id` OU `buyer` inline (au moins l'un des deux).", "properties": { "buyer_id": { "description": "UUID d'un acheteur du registre (scope strict tenant/sub_tenant — anti-IDOR via Policy).", "type": "string", "format": "uuid", "nullable": true }, "buyer": { "oneOf": [ { "$ref": "#/components/schemas/VatBuyerContext" } ], "nullable": true }, "line": { "oneOf": [ { "$ref": "#/components/schemas/LineVatContext" } ], "nullable": true }, "seller": { "oneOf": [ { "$ref": "#/components/schemas/VatSellerContext" } ], "nullable": true }, "sub_tenant_id": { "description": "UUID du sub-tenant émetteur (anti-IDOR via `IssuerResolver`). Doit appartenir au tenant courant — 404 sinon.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" }, "VatResolution": { "description": "Résultat de la résolution TVA pour une ligne.", "required": [ "rate", "category", "en16931_code", "is_auto_resolved", "rule" ], "properties": { "rate": { "description": "Taux applicable (% TVA). 0 pour REVERSE_CHARGE, ZERO_RATED, OUT_OF_SCOPE.", "type": "number", "format": "float", "example": 0 }, "category": { "$ref": "#/components/schemas/VatCategory" }, "en16931_code": { "description": "Code EN16931 (BT-118) : S=standard, AE=reverse_charge, O=out_of_scope, Z=zero_rated, E=exempt.", "type": "string", "enum": [ "S", "AE", "O", "Z", "E" ], "example": "AE" }, "exemption_reason": { "description": "Motif d'exonération (BT-121). Null pour STANDARD/INTERMEDIATE/REDUCED.", "type": "string", "enum": [ "reverse_charge", "export", "intra_eu_supply", "medical", "financial", null ], "example": "reverse_charge", "nullable": true }, "justification": { "description": "Mention légale à afficher sur la facture (BT-120 / texte libre BG-23).", "type": "string", "example": "TVA non applicable, art. 259-1 du CGI (autoliquidation)" }, "is_auto_resolved": { "description": "True si la résolution est sûre. False = ambiguïté, le caller doit confirmer manuellement.", "type": "boolean", "example": true }, "rule": { "description": "Identifiant de la règle déclenchée (R1_fr_domestic, R2_eu_b2b_vat_valid, R3_eu_b2c_no_vat, R4_export, R6_place_of_supply_override, ...).", "type": "string", "example": "R2_eu_b2b_vat_valid" } }, "type": "object" }, "VatWarning": { "description": "Warning de cohérence émis si `line.tax_rate` est fourni et diffère du taux résolu.", "properties": { "code": { "type": "string", "enum": [ "VAT_RATE_MISMATCH", "VAT_CATEGORY_MISMATCH", "VAT_NUMBER_MISSING", "VAT_NUMBER_UNVERIFIED" ], "example": "VAT_RATE_MISMATCH" }, "expected": { "type": "number", "format": "float", "example": 20, "nullable": true }, "actual": { "type": "number", "format": "float", "example": 10, "nullable": true }, "message": { "type": "string", "example": "Le taux saisi diffère du taux résolu (R1_fr_domestic)." } }, "type": "object" }, "ResolveVatContextResponse": { "required": [ "resolution", "warnings" ], "properties": { "resolution": { "$ref": "#/components/schemas/VatResolution" }, "warnings": { "description": "Liste de warnings (vide si tout est cohérent).", "type": "array", "items": { "$ref": "#/components/schemas/VatWarning" } } }, "type": "object" }, "InvoiceTemplate": { "description": "Template de personnalisation pour les factures et avoirs. Miroir de App\\Http\\Resources\\InvoiceTemplateResource.", "properties": { "id": { "description": "CRUD des templates de personnalisation factures / avoirs.\n\nRoutes :\n GET /api/v1/invoice-templates\n POST /api/v1/invoice-templates\n GET /api/v1/invoice-templates/{template}\n PATCH /api/v1/invoice-templates/{template}\n DELETE /api/v1/invoice-templates/{template}\n PUT /api/v1/invoice-templates/{template}/default", "type": "string", "format": "uuid" }, "scope": { "description": "Portee du template. `system` est reserve a Scell (lecture seule cote API publique).", "type": "string", "enum": [ "system", "tenant", "sub_tenant" ] }, "tenant_id": { "description": "Tenant proprietaire (null pour scope system).", "type": "string", "format": "uuid", "nullable": true }, "sub_tenant_id": { "description": "Sub-tenant proprietaire (renseigne uniquement pour scope sub_tenant).", "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "maxLength": 255, "example": "Template Pro" }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "is_default": { "description": "Template par defaut pour son owner.", "type": "boolean" }, "is_available_to_subtenants": { "description": "Disponible aux sub-tenants du tenant.", "type": "boolean" }, "logo_url": { "type": "string", "maxLength": 2048, "nullable": true }, "logo_position": { "type": "string", "enum": [ "top-left", "top-center", "top-right" ], "nullable": true }, "primary_color": { "description": "Hex (#RGB, #RGBA, #RRGGBB, #RRGGBBAA) ou 'transparent'.", "type": "string", "example": "#6366F1", "nullable": true }, "accent_color": { "type": "string", "nullable": true }, "text_color": { "type": "string", "nullable": true }, "background_color": { "type": "string", "nullable": true }, "header_text": { "type": "string", "maxLength": 500, "nullable": true }, "footer_text": { "type": "string", "maxLength": 500, "nullable": true }, "custom_mentions": { "type": "string", "maxLength": 2000, "nullable": true }, "advanced_options": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Token d'authentification utilisateur", "bearerFormat": "JWT", "scheme": "bearer" }, "apiKeyAuth": { "type": "apiKey", "description": "Cle secrete du tenant — format `sk_live_*` (production) ou `sk_test_*` (sandbox). 32 caracteres alphanumeriques apres le prefixe. ⚠ Server-side uniquement. **Le header `X-Tenant-Key` est un ALIAS strictement equivalent** : meme cle, meme regex de validation cote `TenantApiKeyMiddleware`. Aucun format `tk_*` distinct n'existe.", "name": "X-API-Key", "in": "header" }, "tenantKeyAuth": { "type": "apiKey", "description": "ALIAS HISTORIQUE de `X-API-Key`. Accepte exactement la meme cle secrete `sk_live_*` / `sk_test_*` (cf. middleware `TenantApiKeyMiddleware` qui lit `X-Tenant-Key ?? X-API-Key` puis valide la regex `/^sk_(live|test)_[A-Za-z0-9]{32}$/`). Conserve pour la retro-compatibilite — preferer `X-API-Key` dans le code nouveau.", "name": "X-Tenant-Key", "in": "header" }, "cookieAuth": { "type": "apiKey", "description": "Session Sanctum via cookie HttpOnly (authentification SPA dashboard). Necessite un GET /sanctum/csrf-cookie au prealable.", "name": "laravel_session", "in": "cookie" }, "publishableKeyAuth": { "type": "apiKey", "description": "Cle publishable du tenant partenaire (format: pk_live_* ou pk_test_*). Aussi appelee SCELL_PUBLIC_KEY. Usage client-side uniquement (widget onboarding).", "name": "X-Publishable-Key", "in": "header" } } }, "tags": [ { "name": "Auth", "description": "Authentification et gestion de compte" }, { "name": "Companies", "description": "Gestion des entreprises" }, { "name": "API Keys", "description": "Gestion des clés API" }, { "name": "Invoices", "description": "Factures électroniques" }, { "name": "Signatures", "description": "Signatures électroniques" }, { "name": "Webhooks", "description": "Configuration des webhooks" }, { "name": "Onboarding", "description": "API d'onboarding B2B pour les tenants parents" }, { "name": "Tenant", "description": "Gestion du compte tenant" }, { "name": "Credit Notes", "description": "Gestion des avoirs directs du tenant (sans sub-tenant)" }, { "name": "Incoming Invoices", "description": "Gestion des factures fournisseurs (entrantes)" }, { "name": "Tenant Billing", "description": "Facturation et paiements pour les tenants" }, { "name": "Sub-Tenants", "description": "Gestion des sous-comptes" }, { "name": "Payment Schedule", "description": "Gestion de l'échéancier de paiement des devis" }, { "name": "Quotes", "description": "Devis (création, cycle de vie, conversion en facture d'acompte/solde)" }, { "name": "Quotes Public", "description": "Consultation, acceptation et refus d'un devis via lien signé public (sans authentification)" }, { "name": "Buyers", "description": "Registre des acheteurs réutilisables (scope strict tenant/sub_tenant)" }, { "name": "Branding", "description": "Personnalisation du branding email (logo, couleurs, pied de page)" }, { "name": "Misc", "description": "Endpoints utilitaires et données de référence" }, { "name": "Tenant Direct Invoices", "description": "Facturation directe pour les clients du tenant" }, { "name": "Health", "description": "Etat de sante de l'API" }, { "name": "Tenant Auth", "description": "Authentification email/mot de passe pour les tenants" }, { "name": "Pricing", "description": "Tarification Scell.io" }, { "name": "Onboarding-Widget", "description": "Endpoints publics du widget v3 d'onboarding (auth via X-Publishable-Key). Flow Scell-first : SIRENE -> creation SubTenant -> tunnel SuperPDP en option." }, { "name": "Sirene", "description": "Lookup SIRENE (recherche-entreprises.api.gouv.fr + INSEE V3.11) avec fallback saisie manuelle pour debloquer le widget v3 quand les providers sont DOWN." }, { "name": "Fiscal Compliance", "description": "Conformite fiscale LF 2026 : grand-livre, clotures, FEC, attestation, kill-switch, regles" }, { "name": "RGPD", "description": "Conformite RGPD / CNIL (consentement, DPA)" }, { "name": "Public", "description": "Endpoints publics du site (contact, consentement, newsletter)" }, { "name": "Invoice Templates", "description": "Personnalisation des factures et avoirs" }, { "name": "Tenant Invoices", "description": "Facturation pour les sub-tenants" }, { "name": "Tenant Signatures", "description": "Signatures eIDAS EU-SES pour les sub-tenants" }, { "name": "Tenant Stats", "description": "Statistiques du tenant pour le dashboard" }, { "name": "Compliance", "description": "Conformite fiscale ISCA et verification" }, { "name": "Meta", "description": "Metadonnees de la plateforme (version, sante)" }, { "name": "Admin – Quotes", "description": "Admin – Quotes" }, { "name": "Admin", "description": "Admin" }, { "name": "Fiscal", "description": "Fiscal" }, { "name": "Legal", "description": "Legal" }, { "name": "Suppliers", "description": "Suppliers" } ] }