Insourcia Auth API

openapi: 3.2.0
info:
  title: Insourcia Auth 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: Auth
  description: Vérification d'authentification
paths:
  /me:
    get:
      x-credits:
        credits: 0
        unit: par appel
        note: Gratuit.
        subscribers: false
        free: true
      tags:
      - Auth
      summary: Vérifier la clé API
      description: '**Coût :** Gratuit.


        Retourne les informations de l''utilisateur associé à la clé API. Utile pour valider l''authentification.'
      operationId: getMe
      responses:
        '200':
          description: Clé API valide
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    description: Identifiant unique de l'utilisateur
                  plan:
                    type: string
                    enum:
                    - free
                    - pro
                    description: '`pro` avec un abonnement, `free` sans (crédits offerts ou recharge). Préférer `subscriber`.'
                  subscriber:
                    type: boolean
                    description: true si l'organisation qui paie a un abonnement.
                  billing_model:
                    type: string
                    enum:
                    - credits
                    description: 'Modèle de facturation de l''organisation : `credits`.'
                  credits:
                    description: Solde de crédits de l'organisation. null si le solde est momentanément illisible.
                    oneOf:
                    - $ref: '#/components/schemas/CreditsBlock'
                    - type: 'null'
                  keyId:
                    type: string
                    description: Identifiant de la clé API utilisée
                  organization:
                    type:
                    - object
                    - 'null'
                    description: Organisation de l'utilisateur, null s'il n'en a pas
                    properties:
                      name:
                        type: string
                  message:
                    type: string
                    example: Cle API valide.
        '401':
          $ref: '#/components/responses/Unauthorized'
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.
  schemas:
    CreditsBlock:
      type: object
      description: 'Solde de l''organisation qui paie l''appel (`GET /me`). Un énoncé

        d''état : ni prix, ni identifiant de portefeuille.

        '
      properties:
        licence:
          type: string
          enum:
          - free
          - topup
          - subscription
          description: '`free` : crédits offerts seuls ; `topup` : recharge achetée ; `subscription` : abonnement.'
        tier:
          type:
          - integer
          - 'null'
          description: Palier de l'abonnement, null sans abonnement.
        grant_balance:
          type: number
          description: Reste des crédits offerts du mois.
        grant_expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Expiration des crédits offerts du mois, null s'il n'en reste pas.
        purchased_balance:
          type: number
          description: Crédits achetés (recharge ou abonnement) restants.
        total_balance:
          type: number
          description: Solde disponible, crédits offerts compris.
        grid_version:
          type: string
          description: Version de la grille de crédits en vigueur.
        watch:
          type: object
          description: Veille de l'organisation. Abonnement - état de facturation (0,1 crédit par société et par mois). Sans abonnement - companies et over_limit seulement, la veille n'étant pas facturée.
          properties:
            status:
              type: string
              enum:
              - active
              - grace
              - suspended
            companies:
              type: integer
              description: Sociétés distinctes sous veille.
            over_limit:
              type: integer
              description: Sociétés au-delà du garde-fou technique au dernier passage (ni facturées ni surveillées).
            unpaid_companies:
              type: integer
            unpaid_credits:
              type: number
            grace_ends_at:
              type:
              - string
              - 'null'
              format: date-time
            suspended_at:
              type:
              - string
              - 'null'
              format: date-time
    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