Developer documentation

# Base URL unique (production ET sandbox)
https://api.scell.io/api/v1

# Le préfixe de la clé détermine l'environnement automatiquement :
#   sk_live_… / pk_live_…  -> base de données production
#   sk_test_… / pk_test_…  -> base de données sandbox (données de test isolées)
# Il n'existe PAS de host api-sandbox.scell.io — tout passe par api.scell.io.

# 1) Secret key (server-side uniquement) — émission factures, signatures, avoirs
curl https://api.scell.io/api/v1/invoices \
  -H 'X-API-Key: sk_live_xxxxxxxx'

# 2) Publishable key (front/widget) — endpoints widget publics uniquement
curl -X POST https://api.scell.io/api/v1/widget/onboarding/sirene/lookup \
  -H 'X-Publishable-Key: pk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{ "siret": "12345678901234" }'

# 3) Bearer (dashboard SPA, Sanctum) — cookies HttpOnly côté app.scell.io
curl https://api.scell.io/api/v1/auth/me -H 'Authorization: Bearer <token>'

# 4) X-Tenant-Key (legacy multi-tenant) — préférer sk_*/pk_* pour tout nouveau projet

# Créer un compte (tenant) — retourne la 1re clé API
curl -X POST https://api.scell.io/api/v1/register \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ACME SAS",
    "email": "dev@acme.fr",
    "password": "••••••••••••",
    "password_confirmation": "••••••••••••"
  }'

# Émettre une clé secrète server-side supplémentaire (Bearer requis)
curl -X POST https://api.scell.io/api/v1/auth/me/api-key/rotate -H 'Authorization: Bearer <token>'

# B2C (particulier) : buyer_is_individual=true -> SIRET/TVA acheteur optionnels,
# mentions L441-10 (pénalités) et BT-46/47/48 omises (BR-CO-26 EN16931).
curl -X POST https://api.scell.io/api/v1/invoices \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "direction": "outgoing", "output_format": "facturx", "issue_date": "2026-06-05",
    "buyer_is_individual": true,
    "buyer_name": "Jean Dupont",
    "buyer_address": { "line1": "5 rue Bleue", "postal_code": "13001", "city": "Marseille", "country": "FR" },
    "lines": [ { "description": "Abonnement", "quantity": 1, "unit_price": 50, "tax_rate": 20 } ]
  }'

# Le serveur RE-RÉSOUT la TVA de chaque ligne (résolution autoritaire).
# Si le taux est incohérent (ex. 20 % sur une vente intra-UE B2B avec n° TVA valide)
# ET qu'aucune raison d'override n'est fournie -> 409, facture NON persistée :
HTTP/1.1 409 Conflict
{
  "error": "VAT_CORRECTION_REQUIRED",
  "message": "Le taux de TVA d'une ou plusieurs lignes est incohérent avec le contexte…",
  "corrections": [
    {
      "line_index": 0,
      "provided_rate": 20,
      "suggested_rate": 0,
      "suggested_category": "REVERSE_CHARGE",
      "en16931_code": "AE",
      "mention": "Autoliquidation - Article 283-2 du CGI",
      "rule": "R2_eu_b2b_vat_valid"
    }
  ],
  "hint": "Acceptez les taux suggérés, ou renseignez vat_override_reason sur la ligne."
}

# Deux issues : (1) re-soumettre avec suggested_rate/suggested_category,
#               (2) assumer votre taux en ajoutant "vat_override_reason" sur la ligne.

# Demande de signature électronique simple (EU-SES, eIDAS) sur un PDF
curl -X POST https://api.scell.io/api/v1/signatures \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "document_url": "https://votre-app.com/contrat.pdf",
    "document_name": "Contrat de prestation",
    "signers": [
      { "name": "Jean Dupont", "email": "jean@client.fr", "phone": "+33600000000",
        "message": "Merci de signer (code: {OTP})" }
    ],
    "signature_positions": [ { "page": 1, "x": 70, "y": 85, "unit": "percent" } ],
    "signature_options": { "signature_mode": "both", "signer_must_read": true, "timezone": "Europe/Paris" }
  }'

# Relancer / annuler / télécharger le document signé + la preuve
curl -X POST https://api.scell.io/api/v1/signatures/{id}/remind -H 'X-API-Key: sk_live_xxxxxxxx'
curl -X POST https://api.scell.io/api/v1/signatures/{id}/cancel -H 'X-API-Key: sk_live_xxxxxxxx'
curl https://api.scell.io/api/v1/signatures/{id}/download/signed -H 'X-API-Key: sk_live_xxxxxxxx' -o signed.pdf
curl https://api.scell.io/api/v1/signatures/{id}/download/proof  -H 'X-API-Key: sk_live_xxxxxxxx' -o proof.pdf

# Créer un devis, l'envoyer, puis le convertir en acompte / solde
curl -X POST https://api.scell.io/api/v1/quotes \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "buyer_name": "Client SARL", "buyer_siret": "98765432109876",
    "lines": [ { "description": "Projet web", "quantity": 1, "unit_price": 10000, "tax_rate": 20 } ]
  }'
curl -X POST https://api.scell.io/api/v1/quotes/{id}/send -H 'X-API-Key: sk_live_xxxxxxxx'

# Conversion en facture d'acompte (TVA exigible) puis solde (déduit les acomptes)
curl -X POST https://api.scell.io/api/v1/quotes/{id}/convert-to-deposit \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' -d '{ "percent": 30 }'
curl -X POST https://api.scell.io/api/v1/quotes/{id}/convert-to-balance -H 'X-API-Key: sk_live_xxxxxxxx'

# Lien public signable (le client accepte/refuse sans compte) :
# GET /api/v1/public/quotes/{token}   POST …/accept   POST …/refuse   GET …/pdf

# Échéancier de paiement d'un devis : définir des lignes en % OU en montant.
# POST remplace l'INTÉGRALITÉ de l'échéancier (max 50 lignes).
curl -X POST https://api.scell.io/api/v1/quotes/{quoteId}/payment-schedule \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "lines": [
      { "amount_type": "percent", "amount_value": 30, "due_date": "2026-07-01",
        "milestone_label": "Acompte à la commande", "auto_generate": true },
      { "amount_type": "percent", "amount_value": 40, "due_date": "2026-08-15",
        "milestone_label": "Livraison V1" },
      { "amount_type": "amount", "amount_value": 3000.00, "due_date": "2026-09-30",
        "milestone_label": "Solde", "description": "Réception définitive" }
    ]
  }'
# amount_type : "percent" (% du total TTC du devis) | "amount" (montant fixe TTC)
# auto_generate : émet automatiquement la facture (acompte/solde) à l'échéance.

# Consulter, modifier par lot (add/update/remove), tout effacer
curl https://api.scell.io/api/v1/quotes/{quoteId}/payment-schedule          -H 'X-API-Key: sk_live_xxxxxxxx'
curl -X PATCH  https://api.scell.io/api/v1/quotes/{quoteId}/payment-schedule -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' -d '{ "add": [ … ], "update": [ … ], "remove": [ "lineId" ] }'
curl -X DELETE https://api.scell.io/api/v1/quotes/{quoteId}/payment-schedule -H 'X-API-Key: sk_live_xxxxxxxx'

# Convertir une ligne d'échéance en facture (acompte/solde) + résumé agrégé
curl -X POST https://api.scell.io/api/v1/quotes/{quoteId}/payment-schedule/lines/{lineId}/convert -H 'X-API-Key: sk_live_xxxxxxxx'
curl https://api.scell.io/api/v1/quotes/{quoteId}/payment-summary -H 'X-API-Key: sk_live_xxxxxxxx'

# Aperçu PDF d'un devis EN COURS de saisie (rien n'est persisté, aucun numéro émis).
# Même corps qu'une création de devis ; renvoie le PDF directement.
curl -X POST https://api.scell.io/api/v1/quotes/preview \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "buyer_name": "Client SARL", "buyer_siret": "98765432109876",
    "currency": "EUR",
    "lines": [ { "description": "Projet web", "quantity": 1, "unit_price": 10000, "tax_rate": 20 } ],
    "notes": "Devis valable 30 jours."
  }' -o devis-preview.pdf
# Astuce : POST /api/v1/documents/preview (type:"quote") rend l'aperçu HTML A4 live
# (avec branding + modèle), utilisé par l'écran de création du dashboard.

# 1) Découvrir les lignes encore créditables d'une facture
curl https://api.scell.io/api/v1/invoices/{invoiceId}/remaining-creditable -H 'X-API-Key: sk_live_xxxxxxxx'
# -> { "data": { "items": [ { "invoice_line_id": "…", "remaining_quantity": 2, "tax_rate": 20 } ],
#                 "can_be_credited": true } }

# 2) Avoir PARTIEL : sélectionner des lignes de la facture (prix + taux hérités par ligne)
curl -X POST https://api.scell.io/api/v1/credit-notes \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{ "invoice_id": "019df46f-…", "reason": "Retour partiel", "type": "partial",
        "items": [ { "invoice_line_id": "…", "quantity": 1 } ] }'
# Avoir TOTAL : { "invoice_id": "…", "reason": "Annulation", "type": "total" }

# 3) Émettre (immuable après — chaîne ISCA)
curl -X POST https://api.scell.io/api/v1/credit-notes/{id}/send -H 'X-API-Key: sk_live_xxxxxxxx'

# Acheteur réutilisable (idempotent sur SIRET en B2B / email en B2C)
curl -X POST https://api.scell.io/api/v1/buyers \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "name": "Client SARL", "is_individual": false, "country": "FR",
    "siret": "98765432109876", "vat_number": "FR12987654321", "email": "compta@client.fr",
    "billing_address": { "line1": "2 av. Lyon", "postal_code": "69001", "city": "Lyon", "country": "FR" }
  }'
# Puis réutiliser sur une facture : { "buyer_id": "<uuid>", "lines": [ … ] }
# Fournisseurs : dérivés automatiquement des factures reçues (POST /api/v1/incoming-invoices).
# GET /api/v1/suppliers  →  lister  |  GET /api/v1/suppliers/:id  →  détail
# PATCH /api/v1/suppliers/:id  →  enrichir uniquement email / phone / notes / metadata
# ⚠ Pas de création manuelle (POST) ni suppression (DELETE) — identité figée depuis la facture source.

# Catégorie d'organisation (custom, distincte de la catégorie fiscale)
curl -X POST https://api.scell.io/api/v1/product-categories \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{ "name": "Prestations web", "color": "#0066FF", "position": 1 }'

# Produit / service réutilisable
curl -X POST https://api.scell.io/api/v1/products \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "name": "Forfait audit SEO",
    "description": "Audit technique + plan d'\''action sur 3 mois",
    "sku": "SEO-AUDIT-3M",
    "revenue_category": "service",          // goods | service | accommodation (fiscal)
    "product_category_id": "<uuid catégorie>",
    "unit": "C62",                          // code UN/ECE (C62 = unité)
    "unit_price_ht": 1500.00,
    "default_tax_rate": 20,
    "default_discount_rate": 0,
    "currency": "EUR",
    "is_active": true
  }'

# Lister (recherche q + filtres), détail, mise à jour, suppression
curl 'https://api.scell.io/api/v1/products?q=audit&revenue_category=service&is_active=true' -H 'X-API-Key: sk_live_xxxxxxxx'
curl https://api.scell.io/api/v1/products/{id} -H 'X-API-Key: sk_live_xxxxxxxx'
curl -X PATCH https://api.scell.io/api/v1/products/{id} -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' -d '{ "unit_price_ht": 1600 }'

# Réutiliser un produit sur une ligne de facture/devis/avoir : "product_id" pré-remplit
# description/prix/TVA/unité. "save_to_catalog": true enregistre une ligne saisie (upsert).
curl -X POST https://api.scell.io/api/v1/invoices \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "direction": "outgoing", "output_format": "facturx", "issue_date": "2026-06-05",
    "buyer_name": "Client SARL", "buyer_siret": "98765432109876",
    "lines": [
      { "product_id": "<uuid produit>", "quantity": 1 },
      { "description": "Maintenance mensuelle", "quantity": 1, "unit_price": 200, "tax_rate": 20,
        "save_to_catalog": true, "product_category_id": "<uuid catégorie>" }
    ]
  }'

# Branding e-mail : lire / modifier (brand_email_enabled, couleurs, pied de page…)
curl https://api.scell.io/api/v1/branding/tenant -H 'X-API-Key: sk_live_xxxxxxxx'
curl -X PATCH https://api.scell.io/api/v1/branding/tenant \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{ "brand_primary_color": "#0066FF", "brand_email_enabled": true }'

# Logo e-mail : upload direct multipart (jpeg/png/webp/svg, max 2 Mo)
curl -X POST https://api.scell.io/api/v1/branding/tenant/logo \
  -H 'X-API-Key: sk_live_xxxxxxxx' -F 'logo=@logo.svg'

# Aperçu HTML de l'e-mail brandé, avec overrides non persistés (essai avant enregistrement)
curl 'https://api.scell.io/api/v1/branding/tenant/preview?brand_primary_color=%230066FF' \
  -H 'X-API-Key: sk_live_xxxxxxxx'

# Appliquer au modèle de facture les couleurs extraites du logo e-mail
curl -X POST https://api.scell.io/api/v1/invoice-templates/derive-colors-from-email-logo \
  -H 'X-API-Key: sk_live_xxxxxxxx'

# Aperçu HTML live d'un document en cours de saisie (rien n'est persisté)
curl -X POST https://api.scell.io/api/v1/documents/preview \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' \
  -d '{
    "type": "invoice",
    "buyer": { "name": "Client SARL", "siret": "98765432109876" },
    "lines": [{ "description": "Prestation conseil", "quantity": 2, "unit_price": 450.00, "tax_rate": 20 }]
  }'

# Consommation et solde du compte Scell.io (modèle prépayé)
curl https://api.scell.io/api/v1/tenant/billing/usage -H 'X-API-Key: sk_live_xxxxxxxx'
curl https://api.scell.io/api/v1/tenant/balance      -H 'X-API-Key: sk_live_xxxxxxxx'

# Recharger des crédits (Stripe PaymentIntent) ou acheter un pack
curl -X POST https://api.scell.io/api/v1/tenant/billing/top-up \
  -H 'X-API-Key: sk_live_xxxxxxxx' -H 'Content-Type: application/json' -d '{ "amount": 5000 }'
curl -X POST https://api.scell.io/api/v1/tenant/billing/packs/{packSlug}/checkout -H 'X-API-Key: sk_live_xxxxxxxx'

// Corps d'erreur normalisé. La validation (422) détaille par champ ;
// les erreurs métier portent un code dans "error".
{ "message": "…", "errors": { "lines.0.tax_rate": ["…"] } }                  // 422 validation
{ "error": "VAT_CORRECTION_REQUIRED", "message": "…", "corrections": [ … ] } // 409 métier

// Codes métier utiles à intercepter :
//   401 TENANT_NOT_RESOLVED            clé sans tenant rattaché
//   404 SUB_TENANT_NOT_FOUND           sub_tenant_id hors scope (anti-IDOR)
//   422 NO_ISSUER_COMPANY              aucune company émettrice résolue
//   403 KYB_REQUIRED / KYC_REQUIRED    production : vérification incomplète
//   403 SUB_TENANT_NOT_READY           onboarding sous-tenant non vérifié (prod)
//   409 VAT_CORRECTION_REQUIRED        taux TVA incohérent (voir section TVA)
//   409 QUOTE_NOT_EDITABLE             devis verrouillé (accepté/signé)
//   422 SUB_TENANT_HAS_FISCAL_ENTRIES  suppression refusée (ledger ISCA)
//   429 rate limit dépassé (header Retry-After)

1<!-- 2) COTE CLIENT — embarquer le widget en mode "superpdp".
2     N'expose QUE l'etape SUPER PDP : ouvre directement la popup OAuth,
3     sans repasser par identite / Sirene / creation du sub-tenant.
4     Requiert le widget v3.2.0+. -->
5<script src="https://cdn.scell.io/widget/v1/onboarding.js"></script>
6
7<scell-onboarding
8  mode="superpdp"
9  resume-token="https://api.scell.io/api/v1/widget/onboarding/sub-tenant/{id}/superpdp-resume?expires=...&signature=..."
10></scell-onboarding>
11
12<script>
13  document.querySelector('scell-onboarding')
14    .addEventListener('onboarding:completed', (e) => {
15      // Memes events que le flux complet : { subTenant, credentials }
16      console.log('SUPER PDP reconnecte :', e.detail.subTenant.id);
17    });
18
19  document.querySelector('scell-onboarding')
20    .addEventListener('onboarding:error', (e) => {
21      console.error(e.detail.code, e.detail.message);
22    });
23</script>

1{
2  "title": "Abonnement SaaS — Plan Pro",   // requis
3
4  // Émetteur : sans sub_tenant_id => tenant master ; sinon le sous-tenant
5  "sub_tenant_id": "uuid",                  // optionnel
6
7  // Acheteur : buyer_id (registre) OU les champs buyer_* à plat
8  "buyer_id": "uuid",                       // optionnel (sinon buyer_*)
9  "buyer_name": "GN IMMO",
10  "buyer_country": "FR",
11  "buyer_is_individual": false,             // true => B2C (siret/tva optionnels)
12  "buyer_siret": "49438068600076",
13  "buyer_vat_number": "FR42494380686",
14  "buyer_email": "compta@gnimmo.com",
15  "buyer_address": { "line1": "…", "postal_code": "…", "city": "…", "country": "FR" },
16  "buyer_shipping_address": { "name": "…", "line1": "…", "postal_code": "…", "city": "…", "country": "FR" },
17
18  "currency": "EUR",                        // optionnel, défaut "EUR"
19  "output_format": "facturx",               // facturx | ubl | cii
20  "payment_terms": "Paiement à 30 jours.",  // optionnel
21
22  // Lignes (requis) — même forme qu'une ligne de facture
23  "lines": [
24    {
25      "description": "Abonnement mensuel Plan Pro",
26      "quantity": 1,
27      "unit_price": 49.00,
28      "vat_rate": 20,
29      "unit": "mois",                       // optionnel
30      "discount": 0,                        // % remise sur la ligne, optionnel
31      "category": "subscription"            // regroupement libre, optionnel
32    }
33  ],
34
35  // Cadence (requis)
36  "recurrence": {
37    "interval_unit": "month",               // day | week | month | year
38    "interval_count": 1,                    // tous les N (défaut 1)
39    "day_of_month": 1,                      // 1..31, clampé à la longueur du mois (31 => 28/29/30)
40    "day_of_week": 1                        // 1..7 ISO (lun..dim) — uniquement si interval_unit "week"
41  },
42
43  "start_date": "2026-07-01",               // requis (date ISO) — 1re émission
44
45  // Condition d'arrêt
46  "end_mode": "after_occurrences",          // never | on_date | after_occurrences
47  "end_date": "2027-06-30",                 // requis si end_mode = "on_date"
48  "max_occurrences": 12,                    // requis si end_mode = "after_occurrences"
49
50  "emission_mode": "auto_send",             // draft | auto_send (défaut auto_send)
51  "notify_before_days": 3,                  // 0..30 — rappel J-N avant chaque émission
52
53  "metadata": { "plan": "pro" }             // optionnel
54}