Insourcia Documents API

openapi: 3.2.0
info:
  title: Insourcia Documents API
  description: 'API publique Insourcia pour la recherche et l''analyse de sociétés françaises. ## Authentification


    Chaque requête porte un en-tête `Authorization: Bearer `. Deux types de jetons sont acceptés :

    - **Clé API** (format `isk_xxx`) : à créer dans l''application, rubrique Paramètres > API / MCP (`https://app.insourcia.io/settings/api`) ;

    - **JWT OAuth 2.1** : obtenu par le parcours OAuth du serveur MCP. ## Facturation en crédits


    L''API se paie sur le solde de crédits de votre organisation. **1 crédit = 1 fiche société.** Chaque opération indique son coût en tête de description (« Coût : ») et dans l''extension `x-credits`, lisible par un programme : `base` (crédits par appel), `perResult` (par résultat de recherche servi), `sections` (crédits par société servie, pour chaque section non vide), `subscriptionOnly` (opération réservée aux abonnements), `freeRelookup` (relecture gratuite, pendant `freeRelookupDays` jours, soit 30). **Règles de facturation.**

    - Seul ce qui est servi est facturé : une section vide ne coûte rien, une société introuvable ne coûte rien. - Une erreur est gratuite : seule une réponse 2xx est débitée. Un 4xx ou un 5xx (paramètre invalide, refus, `server_busy`) ne débite rien. - Relire la même section d''une même société dans les 30 jours qui suivent son premier débit est gratuit, entre la fiche, ses sections et leurs lots (par exemple `GET /companies/{siren}/financials` puis `GET /companies/batch/financials`). Une recherche est facturée à chaque appel. - Avant l''appel, le coût maximal est réservé sur le solde ; après, seul le coût réel est débité et le reste est rendu. Un appel dont le coût maximal dépasse le solde est refusé (402) sans rien débiter. - Les sections réservées aux abonnements (score crédit, estimation financière, email de dirigeant, données Insourcia d''une recherche) sont omises d''une réponse sans abonnement et listées dans `_billing.sections_skipped`, sans coût. Une opération entièrement réservée répond 403 `subscription_required`. **Coût et solde dans chaque réponse facturable.**

    - `X-Credits-Charged` : crédits débités par cet appel (0 pour une relecture ou un rejeu). - `X-Credits-Remaining` : solde de l''organisation après l''appel. - `X-Credits-Grant-Remaining` et `X-Credits-Grant-Expires-At` : reste et date d''expiration des crédits offerts du mois. - `X-Billing-Grid-Version` : version de la grille qui a calculé le coût. - Le bloc `_billing` du corps (`charged`, `breakdown`, `free_relookups`, `sections_skipped`, `grid_version`) détaille le calcul. Il est ajouté sur demande, avec `?billing=1` ou l''en-tête `X-Billing-Detail: 1`. - `GET /me` donne le solde à tout moment (bloc `credits`), gratuitement. **Rejeu sans double débit.** Un en-tête `Idempotency-Key` (200 caractères au plus) lie l''appel à ses arguments pendant 24 h : le même appel renvoyé sous la même clé est servi à nouveau sans être débité. La même clé sur un autre appel répond 409 `idempotency_key_reused`, et sur un appel encore en cours 409 `idempotency_key_in_progress`. **Erreurs de facturation.**

    - 402 `insufficient_credits` : solde insuffisant pour le coût maximal de l''appel (`credits_remaining`, `credits_required`). - 402 `spend_cap_reached` : plafond de dépense quotidien ou mensuel de l''organisation atteint (`cap` : `daily` ou `monthly`). - 403 `subscription_required` : opération réservée aux abonnements. - 409 `idempotency_key_reused` / `idempotency_key_in_progress` : voir ci-dessus. - 503 `service_unavailable` : facturation momentanément indisponible, rien n''est débité. **Offre.** 100 crédits offerts chaque mois à toute organisation, dès l''inscription. Recharge à 0,01 € le crédit, sans expiration. Abonnements :


    | Abonnement | Crédits inclus |

    |---|---|

    | 49 € par mois | 10 000 crédits par mois |

    | 99 € par mois | 20 000 crédits par mois |

    | 199 € par mois | 40 000 crédits par mois |

    | 499 € par mois | 100 000 crédits par mois |

    | 999 € par mois | 200 000 crédits par mois |


    Grille `2026-11-12.v9` (en-tête `X-Billing-Grid-Version`).'
  version: 1.0.0
  x-billing-grid-version: 2026-11-12.v9
  contact:
    name: Insourcia Support
    email: support@insourcia.io
servers:
- url: https://api.insourcia.io/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Documents
  description: Lecture des documents archivés du registre INPI (bilans, actes)
paths:
  /documents/{type}/{id}:
    get:
      x-credits:
        credits: 1
        unit: par document
        note: 1 crédit par appel. Relire un même document dans les 30 jours est gratuit.
        subscribers: false
        base: 1
        subscriptionOnly: false
        freeRelookup: true
        freeRelookupDays: 30
      tags:
      - Documents
      summary: Lire un document archivé (bilan, acte)
      description: '**Coût :** 1 crédit par appel. Relire un même document dans les 30 jours est gratuit.


        Retourne le PDF d''un document archivé depuis le registre INPI.


        L''identifiant provient de `exercices[].document.id` de

        `GET /companies/{siren}/financials` : cet endpoint ne se parcourt pas,

        il se résout.


        Requêtes conditionnelles (`If-None-Match` sur l''`ETag`) et requêtes

        partielles (`Range`) supportées.


        Chaque lecture est facturée au tarif d''un document (voir « Coût »).'
      operationId: getDocument
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
          enum:
          - actes
          - bilans
      - name: id
        in: path
        required: true
        description: Identifiant INPI du document (24 caractères hexadécimaux).
        schema:
          type: string
      responses:
        '402':
          $ref: '#/components/responses/CreditsRequired'
        '200':
          description: Le document
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '206':
          description: Contenu partiel (un en-tête Range a été transmis)
        '304':
          description: Non modifié (l'ETag correspond à `If-None-Match`)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Document inconnu, ou aucun fichier archivé pour ce document
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Source documentaire indisponible
        '503':
          description: Stockage documentaire non configure
components:
  responses:
    Unauthorized:
      description: Clé API invalide ou manquante
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: Invalid or missing API key.
            message_fr: Clé API invalide ou manquante.
    RateLimited:
      description: Limite de débit atteinte (fenêtre glissante d'une minute). Rien n'est débité.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Secondes avant de pouvoir réessayer
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/Error'
            - type: object
              properties:
                window:
                  type: string
                  enum:
                  - minute
                retry_after_seconds:
                  type: integer
                limit_source:
                  type: string
                  enum:
                  - user
                  - organization
                  description: '`organization` quand la limite est celle de l''organisation (clé d''organisation), `user` sinon.'
          example:
            error: rate_limited
            window: minute
            retry_after_seconds: 12
            limit_source: organization
            message: Trop de requetes (plafond 25/minute). Reessayez dans 12 s.
    CreditsRequired:
      description: 'Facturation en crédits uniquement. Solde de crédits insuffisant pour le coût maximal de l''appel

        (`insufficient_credits`), ou plafond de dépense de l''organisation atteint (`spend_cap_reached`).

        Rien n''est débité.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                - insufficient_credits
                - spend_cap_reached
              message:
                type: string
              credits_remaining:
                type: number
                description: Solde de l'organisation (`insufficient_credits`).
              credits_required:
                type: number
                description: Coût maximal réservé pour cet appel (`insufficient_credits`).
              cap:
                type: string
                enum:
                - daily
                - monthly
                description: Plafond atteint (`spend_cap_reached`).
          example:
            error: insufficient_credits
            message: Solde de crédits insuffisant pour cet appel.
            credits_remaining: 0.4
            credits_required: 1
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Code d'erreur stable. C'est lui qu'un client doit lire pour réagir, jamais le texte de `message`.
        message:
          type: string
          description: Explication pour un développeur ou un agent, en anglais.
        message_fr:
          type: string
          description: Version française de `message`, pour l'afficher telle quelle à un utilisateur francophone. Absente quand `message` n'a pas de version française.
        parameter:
          type: string
          description: 'Sur un `invalid_parameter` qui refuse des valeurs inconnues : le paramètre en cause (ex. `fields`).'
        unknown:
          type: array
          items:
            type: string
          description: Les valeurs refusées par ce paramètre, telles qu'envoyées. Présent avec `parameter`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Clé API (isk_xxx) ou JWT OAuth 2.1