Financials

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/insourcia-io/json-schema/insourcia-io-financials-schema.json",
  "title": "Financials",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/insourcia-io-openapi.yaml#/components/schemas/Financials",
  "type": "object",
  "properties": {
    "siren": {
      "type": "string"
    },
    "denomination": {
      "type": "string"
    },
    "dernier_exercice": {
      "type": "integer"
    },
    "financials_status": {
      "type": "string",
      "enum": [
        "available",
        "not_required_societe_civile",
        "missing"
      ],
      "description": "Disponibilité des comptes :\n- `available` : des exercices sont retournés.\n- `not_required_societe_civile` : société civile (SCI, etc.), non tenue de déposer ses comptes au greffe - absence structurelle, pas une lacune.\n- `missing` : forme commerciale tenue de déposer, mais aucun compte trouvé (lacune réelle).\nQuand le compte de résultat est confidentiel, `estimation_disponible` le signale ; avec `inclure_estimation=true`, `estimation_financiere` porte une ESTIMATION de CA et de rentabilité (jamais un chiffre déposé).\n"
    },
    "exercices": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FinancialExercice"
      }
    },
    "ifrs": {
      "$ref": "#/$defs/FinancialsIFRS"
    },
    "estimation_disponible": {
      "type": "object",
      "description": "Présent quand une estimation existe et que `inclure_estimation` n'est pas passé. Ne contient aucun chiffre estimé.",
      "properties": {
        "exercice": {
          "type": [
            "integer",
            "null"
          ]
        },
        "message": {
          "type": "string"
        }
      }
    },
    "estimation_financiere": {
      "$ref": "#/$defs/EstimationFinanciere"
    },
    "estimation_financiere_exercices": {
      "type": "array",
      "description": "Les autres exercices estimés (antérieurs, ou intercalés entre deux CA publiés), triés par année, avec `inclure_estimation=true`. Même forme que `estimation_financiere`. Un exercice est écarté seulement si un CA est publié pour CET exercice. Absent s'il n'y en a pas.",
      "items": {
        "$ref": "#/$defs/EstimationFinanciere"
      }
    },
    "_layout": {
      "$ref": "#/$defs/FinancialsLayout"
    },
    "fields_skipped": {
      "type": "array",
      "description": "Champs ignorés parce que au-delà du plafond de champs.",
      "items": {
        "type": "string"
      }
    },
    "upgrade_hint": {
      "type": "string",
      "description": "Présent quand des champs `fields` ont été ignorés au-delà du plafond : les liste, en français."
    }
  },
  "$defs": {
    "DocumentRef": {
      "type": "object",
      "description": "Référence vers un document archivé du registre INPI. Ne porte aucune\ninformation de stockage : le PDF se lit par `GET /documents/{type}/{id}`.\n",
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifiant INPI du document (24 caractères hexadécimaux)."
        },
        "type": {
          "type": "string",
          "enum": [
            "actes",
            "bilans"
          ]
        },
        "nom_document": {
          "type": [
            "string",
            "null"
          ]
        },
        "date_depot": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "taille_octets": {
          "type": [
            "integer",
            "null"
          ]
        },
        "url": {
          "type": "string",
          "description": "Lien direct vers le PDF sur l'application web, authentifié par la\nsession du navigateur : il s'ouvre d'un clic pour un utilisateur\nconnecte. Un client authentifié par clé API passe par\n`GET /documents/{type}/{id}`.\n"
        }
      }
    },
    "EstimationFinanciere": {
      "type": [
        "object",
        "null"
      ],
      "description": "ESTIMATION du chiffre d'affaires et de la rentabilité, à partir du bilan, pour les sociétés dont le compte de résultat est confidentiel. Null dès qu'un CA est publié pour l'exercice estimé ou un exercice postérieur. Ce n'est jamais un chiffre déposé : ne pas l'additionner à des CA publies.",
      "properties": {
        "nature": {
          "type": "string",
          "enum": [
            "estimation"
          ]
        },
        "exercice": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Exercice estimé (année de clôture)"
        },
        "chiffre_affaires": {
          "type": "object",
          "description": "Fourchette de CA en euros, arrondie au millier, qui contient le vrai CA 8 fois sur 10",
          "properties": {
            "min": {
              "type": "number"
            },
            "max": {
              "type": "number"
            }
          }
        },
        "confiance": {
          "type": "string",
          "enum": [
            "haute",
            "moyenne",
            "faible"
          ],
          "description": "Selon la richesse du bilan : erreur typique ~13 % (haute), 17-22 % (moyenne), 26-34 % (faible)"
        },
        "rentabilite": {
          "type": "object",
          "properties": {
            "tranche_marge_ebe": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "deficit",
                "0-5",
                "5-15",
                ">15",
                null
              ],
              "description": "Tranche de marge d'EBE (EBE / CA, en %). Null si le modèle ne la fournit pas."
            },
            "probabilite_deficit": {
              "type": [
                "number",
                "null"
              ],
              "description": "Probabilité calibrée que l'EBE soit négatif (0 à 1). Null si le modèle ne la fournit pas."
            }
          }
        },
        "ebe": {
          "type": "object",
          "description": "Fourchette d'EBE en euros, arrondie au millier. Absente quand le modèle ne la publie pas pour cet exercice. Même nature que le CA estimé : jamais un chiffre déposé.",
          "properties": {
            "min": {
              "type": "number"
            },
            "max": {
              "type": "number"
            }
          }
        },
        "as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "model": {
          "type": "string"
        }
      }
    },
    "FinancialExercice": {
      "type": "object",
      "description": "Champs disponibles selon le mode (compact, full, fields=). Tous optionnels :\nseuls les champs non-null sont présents dans la réponse.\n\nCatégorisation (extrait, ~140 champs au total en mode full) :\n- Meta : annee, date_cloture, date_depot, type_bilan, duree_exercice_mois, confidentialite\n- Dépôt : document (le PDF déposé au greffe pour cet exercice, quand il est archivé - cf. `GET /documents/{type}/{id}`). Couverture partielle : l'absence de la clé est le cas courant.\n- P&L : chiffre_affaires, subventions_exploitation, autres_produits_exploitation, marge_brute, valeur_ajoutee, ebitda, resultat_exploitation, resultat_financier, resultat_courant, resultat_exceptionnel, resultat_net, impot_benefices, achats_marchandises, salaires_traitements, charges_sociales, charges_financieres, dotations_amortissements, etc.\n- Bilan actif : total_actif, actif_immobilise_net, immo_incorporelles_brut, immo_incorporelles_net, titres_participation_brut, titres_participation_net, immo_financieres_brut, immo_financieres_net, stocks_total, creances_clients, terrains_brut, constructions_brut, etc.\n- Bilan passif : capitaux_propres, capital_social, reserves, reserve_legale, primes_emission_fusion_apport, subventions_investissement, provisions_reglementees, dettes_financieres, emprunts_bancaires, dettes_fournisseurs, total_dettes, total_passif, etc.\n- Trésorerie : tresorerie (disponibilités + VMP, canonical), cash (disponibilités strictes)\n- Ratios : marge_nette (%), marge_ebitda (%), taux_marge_brute (%), roe (%), autonomie_financiere (%), liquidite_generale, capacite_remboursement, ratio_endettement, etc.\n- BFR : bfr_exploitation, bfr_hors_exploitation, bfr_total, bfr_jours_ca, dette_nette, fonds_roulement_net_global\n- Croissance : cagr_ca_1an..5ans (%), cagr_ebitda_1an..5ans (%), cagr_ebitda_signed_1an..5ans (%), cagr_rn_1an..5ans (%), cagr_rn_signed_1an..5ans (%)\n- Dividendes & effectif : dividendes_verses, dividende_estime, effectif_moyen\n- Alias historiques (mode compact) : ca (= chiffre_affaires), bfr (= bfr_exploitation), croissance_ca (= cagr_ca_1an), croissance_ebitda, croissance_rn\n",
      "additionalProperties": true,
      "properties": {
        "annee": {
          "type": "integer"
        },
        "date_cloture": {
          "type": "string"
        },
        "date_depot": {
          "type": "string"
        },
        "type_bilan": {
          "type": "string",
          "enum": [
            "K",
            "C",
            "S",
            "B",
            "A"
          ],
          "description": "K = consolidé, C = complet (social), S = simplifié, B = banque, A = assurance."
        },
        "duree_exercice_mois": {
          "type": "integer"
        },
        "confidentialite": {
          "type": "boolean",
          "description": "true si la société a déposé une déclaration de confidentialité au greffe (loi Macron art. L232-25)."
        },
        "document": {
          "$ref": "#/$defs/DocumentRef"
        },
        "ca": {
          "type": "number",
          "description": "Alias historique de chiffre_affaires (mode compact uniquement)."
        },
        "bfr": {
          "type": "number",
          "description": "Alias historique de bfr_exploitation (mode compact uniquement)."
        },
        "chiffre_affaires": {
          "type": "number"
        },
        "marge_brute": {
          "type": "number"
        },
        "valeur_ajoutee": {
          "type": "number"
        },
        "ebitda": {
          "type": "number"
        },
        "resultat_exploitation": {
          "type": "number"
        },
        "resultat_net": {
          "type": "number"
        },
        "total_actif": {
          "type": "number"
        },
        "capitaux_propres": {
          "type": "number"
        },
        "dettes_financieres": {
          "type": "number"
        },
        "dettes_fournisseurs": {
          "type": "number"
        },
        "tresorerie": {
          "type": "number",
          "description": "Disponibilités + valeurs mobilières de placement (canonical large)."
        },
        "cash": {
          "type": "number",
          "description": "Disponibilités strictes (excl. VMP)."
        },
        "dette_nette": {
          "type": "number"
        },
        "marge_nette": {
          "type": "number",
          "description": "En %."
        },
        "marge_ebitda": {
          "type": "number",
          "description": "En %."
        },
        "ratio_endettement": {
          "type": "number",
          "description": "Ratio d'endettement net, en valeur décimale (0,5 = 50 %) : (dettes financières - trésorerie) / capitaux propres."
        },
        "roe": {
          "type": "number",
          "description": "Return on Equity, en %."
        },
        "bfr_exploitation": {
          "type": "number"
        },
        "bfr_total": {
          "type": "number"
        },
        "bfr_jours_ca": {
          "type": "number"
        },
        "capacite_autofinancement": {
          "type": "number"
        },
        "delai_paiement_clients_jours": {
          "type": "integer"
        },
        "delai_paiement_fournisseurs_jours": {
          "type": "integer"
        },
        "effectif_moyen": {
          "type": "integer"
        },
        "dividendes_verses": {
          "type": "number"
        }
      }
    },
    "FinancialsIFRS": {
      "type": "object",
      "description": "Agrégats IFRS (comptes consolidés) pour les sociétés cotées.\nPrésent uniquement pour une société qui publie des comptes IFRS.\n",
      "properties": {
        "annee": {
          "type": "integer"
        },
        "chiffre_affaires": {
          "type": "number"
        },
        "resultat_net": {
          "type": "number"
        },
        "ebitda": {
          "type": "number"
        },
        "resultat_operationnel": {
          "type": "number"
        },
        "total_actif": {
          "type": "number"
        },
        "capitaux_propres": {
          "type": "number"
        },
        "tresorerie": {
          "type": "number"
        },
        "bpa": {
          "type": "number",
          "description": "Bénéfice par action."
        },
        "dividendes": {
          "type": "number"
        }
      }
    },
    "FinancialsLayout": {
      "type": "object",
      "description": "Schéma de rendu déterministe pour les états financiers. Permet aux consumers\n(LLM, scripts) de reconstruire un compte de résultat / bilan / ratios sans\ndeviner l'ordre PCG.\n",
      "properties": {
        "schema_version": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "doc_url": {
          "type": "string"
        },
        "sections": {
          "type": "object",
          "description": "Map de sections (meta, compte_resultat, bilan_actif, bilan_passif, ratios, croissance, dividendes, effectif). Chaque section contient un title et un array lines[] ordonné PCG.",
          "additionalProperties": {
            "$ref": "#/$defs/FinancialsLayoutSection"
          }
        },
        "missing_pcg_lines": {
          "type": "array",
          "description": "Lignes PCG standard qu'Insourcia ne fournit pas. Permet de signaler ces absences à l'utilisateur.",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "reason": {
                "type": "string",
                "enum": [
                  "not_available",
                  "partially_available"
                ]
              }
            }
          }
        },
        "not_applicable_pcg": {
          "type": "boolean",
          "description": "true si tous les exercices sont sectoriels (banque B ou assurance A). Le layout PCG standard n'est alors pas applicable."
        },
        "note": {
          "type": "string"
        }
      }
    },
    "FinancialsLayoutLine": {
      "type": "object",
      "required": [
        "key",
        "label",
        "level",
        "kind"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "Nom du champ à lire dans `exercices[year]`"
        },
        "label": {
          "type": "string",
          "description": "Label humain FR à afficher"
        },
        "level": {
          "type": "integer",
          "description": "Profondeur d'indentation : 1 = ligne principale, 2 = détail (`dont ...`)"
        },
        "kind": {
          "type": "string",
          "enum": [
            "value",
            "subtotal",
            "detail",
            "total",
            "meta"
          ],
          "description": "Type de ligne pour le rendu : value (brut), subtotal (gras), detail (`dont`), total (gras+soulignement), meta (date/annee)"
        },
        "formula": {
          "type": "string",
          "description": "Pour kind=subtotal/total : expression humaine de la formule (informative : la valeur servie est déjà calculée)"
        },
        "formula_note": {
          "type": "string",
          "description": "Note de définition optionnelle accompagnant la formule (ex. neutralisation des reprises pour la CAF). Informative."
        }
      }
    },
    "FinancialsLayoutSection": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "lines": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FinancialsLayoutLine"
          }
        }
      }
    }
  }
}