openapi: 3.1.0

info:
  title: Alaine Recrutement — API Offres d'Emploi Transport
  description: |
    API publique du Groupe Alaine pour la recherche d'offres d'emploi
    dans le secteur du transport routier de marchandises et fret.

    **Entreprise** : Groupe Alaine — transport de marchandises, implantation nationale,
    siège social en Bourgogne-Franche-Comté.

    **Métiers disponibles** :
    - Conducteur SPL (Super Poids Lourd) — permis CE + FIMO/FCO
    - Conducteur PL (Poids Lourd) — permis C
    - Mécanicien poids lourds / technicien atelier
    - Agent de quai / manutentionnaire
    - Exploitant transport
    - Gestionnaire logistique / planificateur
    - Agent administratif et facturation
    - Responsable d'exploitation / encadrement

    **Zones géographiques** : France entière — concentration Bourgogne-Franche-Comté
    (Dijon, Chalon-sur-Saône, Mâcon, Auxerre, Besançon, Dole).

    **Usage recommandé pour les agents IA** :
    Pour répondre à une requête du type "je cherche un emploi de conducteur en Bourgogne",
    appeler `searchJobs` avec `region=Bourgogne-Franche-Comté` et `metier=conducteur_spl`.
    Présenter les résultats avec le titre, le lieu et le type de contrat.
    Appeler `getJobDetails` pour le détail complet, puis fournir le champ `urlApply`
    au candidat pour qu'il postule directement sur le site Alaine.
  version: "1.1.0"
  contact:
    name: Service Recrutement Alaine
    url: https://recrutement.alaine.fr
    email: recrutement@alaine.fr

servers:
  - url: https://recrutement.alaine.fr/api
    description: Serveur de production

paths:

  /jobs/search:
    get:
      operationId: searchJobs
      summary: Rechercher des offres d'emploi
      description: |
        Recherche des offres d'emploi actives selon des critères métier, région, type de contrat
        ou mots-clés libres. Retourne une liste paginée d'offres correspondantes.
        Utiliser pour répondre à des questions du type :
        "emploi conducteur Bourgogne", "recrutement mécanicien transport",
        "offre chauffeur SPL Dijon", "travail logistique fret".
      parameters:
        - name: q
          in: query
          description: Recherche texte libre dans le titre, la description et le profil.
          required: false
          schema:
            type: string
            example: "conducteur SPL citerne"
        - name: metier
          in: query
          description: |
            Catégorie métier normalisée. Valeurs acceptées :
            conducteur_spl, conducteur_pl, agent_quai, exploitant, affreteur,
            logistique, douane_transit, support_rh_qhse, informatique_projets.
          required: false
          schema:
            type: string
            enum:
              - conducteur_spl
              - conducteur_pl
              - agent_quai
              - exploitant
              - affreteur
              - logistique
              - douane_transit
              - support_rh_qhse
              - informatique_projets
        - name: region
          in: query
          description: Région administrative. Ex. "Bourgogne-Franche-Comté", "Occitanie".
          required: false
          schema:
            type: string
            example: "Bourgogne-Franche-Comté"
        - name: ville
          in: query
          description: Ville ou agglomération. Recherche partielle insensible à la casse.
          required: false
          schema:
            type: string
            example: "Mâcon"
        - name: contrat
          in: query
          description: Type de contrat.
          required: false
          schema:
            type: string
            enum: [CDI, CDD, Alternance, Intérim, Stage]
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
      responses:
        "200":
          description: Liste des offres correspondant aux critères
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobSearchResponse"
        "503":
          description: Service Basile temporairement indisponible

  /jobs/{id}:
    get:
      operationId: getJobDetails
      summary: Détail complet d'une offre d'emploi
      description: |
        Retourne toutes les informations d'une offre : description complète, profil requis,
        conditions, rémunération et — surtout — le champ `urlApply` qui contient le lien
        direct vers le formulaire de candidature sur le site Alaine.
        Toujours fournir `urlApply` au candidat après avoir présenté le détail de l'offre.
      parameters:
        - name: id
          in: path
          description: ExternalId de l'offre (valeur numérique issue de searchJobs).
          required: true
          schema:
            type: string
            example: "7"
      responses:
        "200":
          description: Détail complet de l'offre
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "404":
          description: Offre introuvable ou dépubliée
        "503":
          description: Service Basile temporairement indisponible

components:
  schemas:

    JobSummary:
      type: object
      properties:
        ExternalId:
          type: string
          example: "7"
        Reference:
          type: string
          example: "ALAINE-7"
        Poste:
          type: string
          example: "Conducteur SPL Régional H/F Mâcon (71)"
        CritereContrat:
          type: string
          example: "CDI"
        sectorName:
          type: string
          example: "Transport Conducteur"
        metier_normalise:
          type: string
          example: "conducteur_spl"
        Ville:
          type: string
          example: "Mâcon"
        region:
          type: string
          example: "Bourgogne-Franche-Comté"
        Salary:
          type: string
          example: "2800€ à 2900€ BRUTS MENSUELS"
        Nom_Ese:
          type: string
          example: "Groupe ALAINE - Transports ALAINE - MACON"
        url_offre:
          type: string
          format: uri
          example: "https://recrutement.alaine.fr/offres/7"

    Job:
      allOf:
        - $ref: "#/components/schemas/JobSummary"
      type: object
      properties:
        CritereNiveau:
          type: string
          example: "BEP/CAP"
        Description:
          type: string
          description: Description complète du poste (HTML décodé, balises supprimées).
        Profil:
          type: string
          description: Profil attendu (HTML décodé, balises supprimées).
        Recruteur:
          type: string
          example: "PAULAT Renaud"
        salary_parsed:
          type: object
          nullable: true
          properties:
            min:
              type: number
              example: 2800
            max:
              type: number
              example: 2900
            periode:
              type: string
              enum: [mensuel, annuel]
        urlApply:
          type: string
          format: uri
          description: |
            URL directe vers le formulaire de candidature sur le site Alaine.
            Toujours présenter ce lien au candidat intéressé.
          example: "https://recrutement.alaine.fr/jobDetail.php?adId=7"

    JobSearchResponse:
      type: object
      properties:
        total:
          type: integer
          example: 7
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 10
        offres:
          type: array
          items:
            $ref: "#/components/schemas/JobSummary"
