Insourcia Webhooks API

openapi: 3.2.0
info:
  title: Insourcia Webhooks 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: Webhooks
  description: Webhooks sortants signés (HMAC-SHA256) pour les événements de veille
paths: {}
webhooks:
  company.alert:
    post:
      tags:
      - Webhooks
      summary: Alerte société (webhook sortant)
      description: 'Insourcia envoie ce POST à l''URL de votre endpoint dès qu''un événement est

        détecté sur une société d''une veille surveillée (procédure collective,

        changement de dirigeant, cession, dépôt de comptes, radiation...).


        La requête est signée en HMAC-SHA256. En cas d''échec elle est retentée, et

        chaque livraison est journalisée. Configuration : Paramètres de notifications

        > Webhooks. Les webhooks sont ouverts à tous les comptes, 5 adresses par organisation.


        En-têtes :

        - `X-Insourcia-Signature` = `sha256=`, calculé sur les octets

        `{X-Insourcia-Timestamp}.{corps brut}` avec le secret de l''endpoint ;

        - `X-Insourcia-Timestamp` : horodatage unix ;

        - `X-Insourcia-Delivery` : identifiant de livraison (`delivery_id`), pour

        l''idempotence.


        Répondez avec un code 2xx pour accuser réception. Sinon la livraison est

        retentée (1, 5, 30, 120 puis 360 min), puis l''endpoint est désactivé après

        des échecs consécutifs. Aucune garantie d''ordre : dédupliquez sur `delivery_id`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCompanyAlert'
      responses:
        2XX:
          description: Accusé de réception. Tout code 2xx marque la livraison réussie.
  webhook.ping:
    post:
      tags:
      - Webhooks
      summary: Événement test (webhook sortant)
      description: Envoyé par le bouton "Tester" pour valider votre endpoint et la vérification de signature. Mêmes en-têtes signés que company.alert.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPing'
      responses:
        2XX:
          description: Accusé de réception.
components:
  schemas:
    WebhookPing:
      type: object
      description: Corps JSON POST du bouton Tester.
      required:
      - event
      - schema_version
      - delivery_id
      - occurred_at
      properties:
        event:
          type: string
          const: webhook.ping
        schema_version:
          type: string
          example: '1'
        delivery_id:
          type: string
          example: whp_1f2e3d4c
        occurred_at:
          type: string
          format: date-time
        message:
          type: string
          example: Insourcia webhook test event
    WebhookCompanyAlert:
      type: object
      description: Corps JSON POST envoyé à votre endpoint pour chaque événement de veille.
      required:
      - event
      - schema_version
      - delivery_id
      - occurred_at
      - alert
      properties:
        event:
          type: string
          const: company.alert
        schema_version:
          type: string
          example: '1'
        delivery_id:
          type: string
          description: Identifiant stable de la livraison (idempotence, aussi en en-tête X-Insourcia-Delivery). Constant entre les reprises.
          example: clz1a2b3c4d5e6f7
        occurred_at:
          type: string
          format: date-time
        source:
          type: object
          description: La veille (recherche sauvegardée ou liste) à l'origine de l'alerte.
          properties:
            type:
              type: string
              enum:
              - saved_search
              - list
            id:
              type: string
            name:
              type:
              - string
              - 'null'
        alert:
          type: object
          required:
          - siren
          - company_name
          properties:
            siren:
              type: string
              example: '552081317'
            company_name:
              type: string
              example: GO SPORT FRANCE
            category:
              type: string
              description: Type d'événement brut (procedure_collective, dirigeant_entered, cession, nouveaux_comptes, radiation...) ou, à défaut, le type d'alerte (new_additions, new_removals).
              example: procedure_collective
            label:
              type:
              - string
              - 'null'
              description: Libellé lisible du signal.
              example: Procedure collective
            summary:
              type: string
              example: Ouverture de liquidation judiciaire
            occurred_on:
              type: string
              description: Date de détection (YYYY-MM-DD).
              example: '2026-07-12'
            date_note:
              type:
              - string
              - 'null'
              example: effet 03/11/2025 (enregistre 12/07/2026)
            company_url:
              type:
              - string
              - 'null'
              example: https://app.insourcia.io/company/552081317
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Clé API (isk_xxx) ou JWT OAuth 2.1