openapi: 3.0.3
info:
  title: ShadOSINT Public REST API
  description: |
    API d'investigation OSINT haute performance sur plus de 29 millions d'individus français.
    Moteur d'indexation Tantivy en mémoire vive avec temps de réponse moyen inférieur à 40ms.
    
    ### Authentification
    Toutes les requêtes nécessitent un Bearer Token valide passé dans l'en-tête HTTP standard :
    `Authorization: Bearer <votre_token_api>`
    
    ### Rate Limiting
    Les quotas dépendent de votre formule (ex: tier API = 100 requêtes / minute, 10 000 requêtes / jour).
    En cas de dépassement, l'API renvoie un code HTTP `429 Too Many Requests`.
  version: 1.0.0
  contact:
    name: Support ShadOSINT
    url: https://shadosint.fr

servers:
  - url: /
    description: Serveur API courant

paths:
  /api/search:
    get:
      summary: Recherche OSINT multicritère
      description: |
        Effectue une recherche rapide par texte libre ou paramètres combinés.
        Renvoie la liste des individus correspondants hydratés avec détails d'état civil, adresses, banques et coordonnées.
      security:
        - BearerAuth: []
      parameters:
        - name: q
          in: query
          description: Requête globale en texte libre (ex: "Jean Dupont Lyon", numéro de téléphone, email)
          required: false
          schema:
            type: string
            example: "Jean Dupont Lyon"
        - name: nom
          in: query
          description: Filtrer par nom de famille
          required: false
          schema:
            type: string
            example: "DUPONT"
        - name: prenom
          in: query
          description: Filtrer par prénom
          required: false
          schema:
            type: string
            example: "Jean"
        - name: commune
          in: query
          description: Ville ou commune
          required: false
          schema:
            type: string
            example: "Lyon"
        - name: cp
          in: query
          description: Code postal (5 chiffres)
          required: false
          schema:
            type: string
            example: "69001"
        - name: telephone
          in: query
          description: Numéro de téléphone fixe ou mobile
          required: false
          schema:
            type: string
            example: "0612345678"
        - name: courriel
          in: query
          description: Adresse email
          required: false
          schema:
            type: string
            example: "jean.dupont@email.com"
        - name: naissance
          in: query
          description: Date de naissance (formats acceptés: JJ/MM/AAAA ou AAAA-MM-JJ)
          required: false
          schema:
            type: string
            example: "15/04/1985"
        - name: pretty
          in: query
          description: Indenter le résultat JSON
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Recherche exécutée avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Jeton d'authentification invalide ou manquant
        '403':
          description: Quota journalier épuisé pour votre formule
        '429':
          description: Trop de requêtes par minute (Rate limit dépassé)

  /api/system/quota:
    get:
      summary: Consultation des quotas & utilisation
      description: Renvoie le solde de requêtes effectuées aujourd'hui et les limites autorisées par votre tier.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Informations de quota du compte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'

  /api/export/csv:
    get:
      summary: Export au format CSV
      description: Génère un flux CSV téléchargeable des résultats de recherche.
      security:
        - BearerAuth: []
      parameters:
        - name: q
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Fichier CSV
          content:
            text/csv:
              schema:
                type: string

  /api/export/pdf/{id}:
    get:
      summary: Rapport d'investigation PDF
      description: Génère un document PDF complet (état civil, adresses, coordonnées, historique et liens familiaux).
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID interne du dossier à exporter
          schema:
            type: integer
      responses:
        '200':
          description: Rapport PDF généré
          content:
            application/pdf:
              schema:
                type: string
                format: binary

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    SearchResponse:
      type: object
      properties:
        resultats:
          type: array
          items:
            $ref: '#/components/schemas/IndividualRecord'
        plus_de_resultats:
          type: boolean
          example: false
        duree_ms:
          type: integer
          description: Durée d'exécution de la requête en millisecondes
          example: 32
        erreur:
          type: string
          nullable: true

    IndividualRecord:
      type: object
      properties:
        id_interne:
          type: integer
          example: 10459201
        nom:
          type: string
          example: "DUPONT"
        prenom:
          type: string
          example: "Jean"
        naissance:
          type: string
          example: "1985-04-15"
        lieu_naissance:
          type: string
          example: "LYON 4EME"
        genre:
          type: string
          example: "M"
        commune:
          type: string
          example: "LYON"
        code_postal:
          type: string
          example: "69001"
        adresse_voie:
          type: string
          example: "12 RUE DE LA REPUBLIQUE"
        adresse_complement:
          type: string
          example: "BAT B ETG 3"
        code_insee:
          type: string
          example: "69384"
        emails:
          type: array
          items:
            type: string
          example: ["jean.dupont@gmail.com"]
        telephones:
          type: array
          items:
            type: string
          example: ["0612345678"]
        iban:
          type: string
          description: Masqué sur tier FREE/STARTER, visible en PRO et API
          example: "FR7630006000011234567890189"
        bic:
          type: string
          example: "BNPAFRPP"
        nom_banque:
          type: string
          example: "BNP PARIBAS"
        ville_banque:
          type: string
          example: "PARIS"
        pays_banque:
          type: string
          example: "FRANCE"
        matricule:
          type: string
          example: "CAF69102938"
        detail_organisme:
          type: string
          example: "CAF DU RHONE"
        est_responsable:
          type: boolean
          example: true
        sources:
          type: string
          example: "REGISTRE_NATIONAL_CAF"
        derniere_maj:
          type: string
          example: "2024-03"

    QuotaResponse:
      type: object
      properties:
        tier:
          type: string
          example: "API"
        used_today:
          type: integer
          example: 142
        max_per_day:
          type: integer
          example: 10000
        remaining_today:
          type: integer
          example: 9858
        rate_limit_per_min:
          type: integer
          example: 100