# Get the authenticated user
Source: https://api.jobaffinity.com/api-reference/account/get-the-authenticated-user

/api-reference/openapi.json get /me
Returns the identity of the authenticated user, their organisation memberships (each as `{id, role, name}`), and the flat `organisation_ids`. Requires a user credential; a system-key caller has no identity here.



# List an organisation's members
Source: https://api.jobaffinity.com/api-reference/account/list-an-organisations-members

/api-reference/openapi.json get /organisation/{organisationid}/users
Returns the members of an organisation, one entry per user even when several memberships exist, an active role winning over a disabled one. The caller must belong to the organisation (or be a superadmin or a system-key caller).



# Get API changelog
Source: https://api.jobaffinity.com/api-reference/api-info/get-api-changelog

/api-reference/openapi.json get /changelog
Returns version history and changes for each API version



# Get API index
Source: https://api.jobaffinity.com/api-reference/api-info/get-api-index

/api-reference/openapi.json get /
Returns API metadata, version information, and main entry points



# Advance an application to its next step
Source: https://api.jobaffinity.com/api-reference/applications/advance-an-application-to-its-next-step

/api-reference/openapi.json post /application/{applicationid}/advance-step
Moves the application, as the recruiter making the call, to `target_step_id` or to the deduced next step when omitted. Requires `expected_current_step_id`: a 409 answers when the application moved in the meantime, so two recruiters cannot silently race. END and operational steps are refused.



# Download latest CV for application
Source: https://api.jobaffinity.com/api-reference/applications/download-latest-cv-for-application

/api-reference/openapi.json get /application/{applicationid}/latest_cv
Returns the latest CV document for an application.
The URL will redirect (307) to a temporary download URL.

**IMPORTANT:** Do not build this URL manually. Use the `latest_cv_url` field from application objects.




# Get application by ID
Source: https://api.jobaffinity.com/api-reference/applications/get-application-by-id

/api-reference/openapi.json get /application/{applicationid}
Returns detailed information about a specific application



# Get candidate profile for an application
Source: https://api.jobaffinity.com/api-reference/applications/get-candidate-profile-for-an-application

/api-reference/openapi.json get /application/{applicationid}/profile
Returns the candidate's structured profile (identity, employments, educations, languages, skills, hobbies) as extracted from their CV. Same data as the profile tab in the UI.



# Get one archived email of an application
Source: https://api.jobaffinity.com/api-reference/applications/get-one-archived-email-of-an-application

/api-reference/openapi.json get /application/{applicationid}/email/{emailid}
Returns the body, recipients and attachments of a single archived email attached to the application.



# Get the process steps of an application
Source: https://api.jobaffinity.com/api-reference/applications/get-the-process-steps-of-an-application

/api-reference/openapi.json get /application/{applicationid}/steps
Returns the visible steps of the application's process, its current step, and the deduced next step of the normal flow (first visible step after the current one by rank, never an END step nor an operational step).



# Get what an application is waiting on
Source: https://api.jobaffinity.com/api-reference/applications/get-what-an-application-is-waiting-on

/api-reference/openapi.json get /application/{applicationid}/pending
Returns what the application is waiting on: the open validation request and its manager, the latest archived email and its direction, and the last action time.



# List applications for a candidate
Source: https://api.jobaffinity.com/api-reference/applications/list-applications-for-a-candidate

/api-reference/openapi.json get /candidate/{candidateid}/application
Returns all applications submitted by a specific candidate



# List applications for a job
Source: https://api.jobaffinity.com/api-reference/applications/list-applications-for-a-job

/api-reference/openapi.json get /job/{jobid}/application
Returns all applications submitted for a specific job



# Preview a recorded template on an application
Source: https://api.jobaffinity.com/api-reference/applications/preview-a-recorded-template-on-an-application

/api-reference/openapi.json get /application/{applicationid}/email-preview
Renders a recorded template on the application — subject and HTML body with the real keywords, exactly as send-email would produce them — without sending anything. Same access rules as send-email.



# Reject an application (one-click)
Source: https://api.jobaffinity.com/api-reference/applications/reject-an-application-one-click

/api-reference/openapi.json post /application/{applicationid}/reject
Moves the application to the configured rejection step and optionally sends a rejection email. Requires a OneClickRejectConfig to be enabled for the application's process.

The rejection step and email template are determined by the organisation's one-click reject configuration.



# Remind a pending validation
Source: https://api.jobaffinity.com/api-reference/applications/remind-a-pending-validation

/api-reference/openapi.json post /validation/{validationid}/remind
Re-sends a pending CV validation request to its recorded manager, reusing the organisation's validation template (subject prefixed with 'Relance : ') and the same magic answer link as the original email. Acts as the recruiter making the call.



# Send a recorded template on an application
Source: https://api.jobaffinity.com/api-reference/applications/send-a-recorded-template-on-an-application

/api-reference/openapi.json post /application/{applicationid}/send-email
Sends a recorded email template on the application, as the recruiter making the call. Optional `subject` and `message` replace the template's subject and body; keywords already rendered stay as sent. A template of another organisation answers 404.



# Get candidate by ID
Source: https://api.jobaffinity.com/api-reference/candidates/get-candidate-by-id

/api-reference/openapi.json get /candidate/{candidateid}
Returns detailed information about a specific candidate



# List all candidates
Source: https://api.jobaffinity.com/api-reference/candidates/list-all-candidates

/api-reference/openapi.json get /candidate
Returns a paginated list of all visible candidates (CVtheque). By default, all candidates visible to the user are listed.



# Look up candidates by email or phone
Source: https://api.jobaffinity.com/api-reference/candidates/look-up-candidates-by-email-or-phone

/api-reference/openapi.json get /candidate/lookup
Finds visible candidates by normalized email or phone. The email is lowercased and trimmed; the phone is parsed to E.164. At least one criterion must survive normalization, otherwise the answer is 400. Criteria that could not be normalized are listed in `rejected_criteria`, and each item reports which criteria it matched in `matched_on`.



# Check apply endpoint availability
Source: https://api.jobaffinity.com/api-reference/job-application-submission/check-apply-endpoint-availability

/api-reference/openapi.json head /apply/{token}
Verifies the availability and status of the apply endpoint without submitting data.



# Submit a job application
Source: https://api.jobaffinity.com/api-reference/job-application-submission/submit-a-job-application

/api-reference/openapi.json post /apply/{token}
Submits a candidate application for a job posting. The full URL (including the authentication token) is provided by the `apply_url` field in the job feed — do not build this URL manually.

A HEAD request can be used to verify the availability and status of the endpoint without submitting any data.

You can use the [validation form](https://jobaffinity.fr/apply/api/#validation-form) to check your data before submitting.



# Get job by ID
Source: https://api.jobaffinity.com/api-reference/jobs/get-job-by-id

/api-reference/openapi.json get /job/{jobid}
Returns detailed information about a specific job



# Get job team
Source: https://api.jobaffinity.com/api-reference/jobs/get-job-team

/api-reference/openapi.json get /job/{jobid}/team
Returns the team members associated with a job



# Get the recruitment funnel of a job
Source: https://api.jobaffinity.com/api-reference/jobs/get-the-recruitment-funnel-of-a-job

/api-reference/openapi.json get /job/{jobid}/stats
Returns the recruitment funnel of one job: total applications, per channel, per week over the last eight weeks, the average of open jobs on the same contract type, and the first active publication date.



# List all jobs
Source: https://api.jobaffinity.com/api-reference/jobs/list-all-jobs

/api-reference/openapi.json get /job
Returns a paginated list of jobs. By default, only jobs owned by the authenticated user (user responsible for the job) are returned. Use `alljobs=1` to return all jobs visible to the user.



# Add a new note
Source: https://api.jobaffinity.com/api-reference/notes/add-a-new-note

/api-reference/openapi.json post /note
Creates a new note for a candidate



# List all notes
Source: https://api.jobaffinity.com/api-reference/notes/list-all-notes

/api-reference/openapi.json get /note
Returns a paginated list of candidate notes, from most recently added to oldest, across all candidates and organisations. Use `candidate_id` or `organisation_id` to filter. You can use the URI provided by the `.notes._self` field from the application detail resource.



# Add a new process step
Source: https://api.jobaffinity.com/api-reference/processes/add-a-new-process-step

/api-reference/openapi.json post /step
Adds a new process step change to an application



# Get process by ID
Source: https://api.jobaffinity.com/api-reference/processes/get-process-by-id

/api-reference/openapi.json get /process/{processid}
Returns details of a specific recruitment process



# List all process step changes
Source: https://api.jobaffinity.com/api-reference/processes/list-all-process-step-changes

/api-reference/openapi.json get /step
Returns a paginated list of all process step changes (most recently added first)



# List all processes
Source: https://api.jobaffinity.com/api-reference/processes/list-all-processes

/api-reference/openapi.json get /process/
Returns a list of all visible recruitment processes



# Get questionnaire answers
Source: https://api.jobaffinity.com/api-reference/questionnaires/get-questionnaire-answers

/api-reference/openapi.json get /application/{applicationid}/questionnaire/{questionnaireid}
Returns answers to a specific questionnaire for an application



# Submit questionnaire answers
Source: https://api.jobaffinity.com/api-reference/questionnaires/submit-questionnaire-answers

/api-reference/openapi.json post /application/{appid}/questionnaire
Submits answers to a questionnaire for an application



# List an organisation's email templates
Source: https://api.jobaffinity.com/api-reference/templates/list-an-organisations-email-templates

/api-reference/openapi.json get /message-template
Returns the recorded email templates of one organisation, optionally narrowed by category. The caller must belong to the organisation.



# List webhook tasks
Source: https://api.jobaffinity.com/api-reference/webhooks/list-webhook-tasks

/api-reference/openapi.json get /webhook/task
Returns a paginated list of webhook tasks



# Authentification
Source: https://api.jobaffinity.com/guides/authentication

Accéder à l'API JobAffinity

## Méthode d'authentification

Chaque requête nécessite une authentification de type **Basic Auth** ([RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617)).

Pour obtenir vos identifiants (login et mot de passe), contactez le support d'Intuition-Software : [support@intuition-software.fr](mailto:support@intuition-software.fr).

## Exemples d'authentification

<CodeGroup>
  ```bash Shell theme={null}
  curl -X GET https://jobaffinity.fr/restapi/v1 \
       --basic --user login:password
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://jobaffinity.fr/restapi/v1',
      auth=('login', 'password')
  )
  ```
</CodeGroup>

## Transmission des paramètres

### Requêtes GET

Les paramètres sont transmis dans l'URL.

```bash theme={null}
curl -X GET "https://jobaffinity.fr/restapi/v1/job?alljobs=true" \
     --basic --user login:password
```

### Requêtes POST

Les données sont transmises dans le corps de la requête au format JSON.

```bash theme={null}
curl -X POST \
  --basic --user login:password \
  --json '{"questionnaire_id":"9220","answers":{"46570":{"answer":"reponse"}}}' \
  https://jobaffinity.fr/restapi/v1/application/75488560/questionnaire
```

<Note>
  Assurez-vous d'utiliser HTTPS pour toutes vos requêtes afin de garantir la sécurité de vos identifiants.
</Note>

## Limitation de taux

<Note>
  L'API est limitée à **45 requêtes par minute par adresse IP**. En cas de dépassement, vous recevrez une réponse HTTP 429.
</Note>


# Auto-découverte
Source: https://api.jobaffinity.com/guides/discovery

Principe d'auto-découverte et de navigation dans l'API

## Principe d'auto-découverte

L'API REST JobAffinity est **auto-découvrable** et **auto-documentée**. Seule l'URL principale de départ est nécessaire : `https://jobaffinity.fr/restapi/v1`

<Warning>
  Il n'est **pas nécessaire** de construire des URLs manuellement. Les URLs de relation sont fournies dans les réponses de l'API. La construction ad-hoc d'URL est déconseillée car les URLs peuvent être modifiées sans changement majeur de version.
</Warning>

## Ressource racine

La ressource racine liste les services de haut niveau exposés et donne l'état de l'API.

```bash theme={null}
GET /restapi/v1
```

### Exemple de réponse

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1",
  "_version": "1.10",
  "_last_version_url": "/restapi/v1",
  "_expiration": null,
  "_changelog": {
    "_self": "/restapi/changelog"
  },
  "candidates": {
    "_self": "/restapi/v1/candidate",
    "description": "List of visible candidates"
  },
  "jobs": {
    "_self": "/restapi/v1/job",
    "description": "List of visible jobs."
  }
}
```

## Champs de surveillance

### Version et migration

* **`_version`** : Version mineure de l'API utilisée
* **`_last_version_url`** : URL racine de la dernière version disponible (vaut `_self` si vous utilisez déjà la dernière version)
* **`_expiration`** : Date d'expiration de la version utilisée (`null` si aucune expiration prévue)

<Warning>
  **Important** : Mettez en place un système d'alerte sur le champ `_expiration`. Lorsqu'il devient différent de `null`, une migration sera nécessaire.
</Warning>

### Changelog

Le champ **`_changelog`** fournit un lien vers la liste des évolutions de l'API.

<Tip>
  Consultez régulièrement le changelog pour découvrir les nouvelles possibilités offertes par l'API.
</Tip>

## Points d'entrée

Les autres champs de la ressource racine (`candidates`, `jobs`, etc.) fournissent les points d'entrée principaux de l'API avec leurs URLs respectives.

## Navigation dans l'API

Utilisez toujours les URLs fournies dans les champs `_self` pour naviguer dans l'API :

```json theme={null}
{
  "job": {
    "_self": "/restapi/v1/job/42",
    "applications": {
      "_self": "/restapi/v1/job/42/application"
    }
  }
}
```

Cette approche garantit que votre code reste fonctionnel même si les URLs changent.


# Pagination
Source: https://api.jobaffinity.com/guides/pagination

Comprendre et gérer la pagination des collections

## Principe de pagination

Les ressources retournant beaucoup de résultats sont automatiquement paginées pour optimiser les performances.

## Utilisation du champ `_next`

Le champ `_next` dans la réponse contient l'URL de la page suivante.

### Exemple de réponse paginée

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1/job",
  "_schema": "/restapi/schemav1/jobs",
  "_next": "/restapi/v1/job?pagecursor=42",
  "items": [
    {
      "id": 1,
      "title": "Développeur Full-Stack",
      "_self": "/restapi/v1/job/1"
    },
    {
      "id": 2,
      "title": "Chef de projet",
      "_self": "/restapi/v1/job/2"
    }
  ]
}
```

## Parcourir toutes les pages

### Algorithme de base

1. Effectuer la première requête
2. Traiter les `items` de la page
3. Vérifier si `_next` est présent et non vide
4. Si oui, requêter `_next` et retourner à l'étape 2
5. Si non, toutes les pages ont été parcourues

### Exemple en Python

```python theme={null}
import requests

def fetch_all_pages(url, auth):
    """Récupère tous les éléments d'une ressource paginée"""
    all_items = []

    while url:
        response = requests.get(url, auth=auth)
        data = response.json()

        if data.get('_status') != 'OK':
            break

        all_items.extend(data.get('items', []))
        url = data.get('_next', '')

    return all_items

# Utilisation
jobs = fetch_all_pages(
    'https://jobaffinity.fr/restapi/v1/job',
    auth=('login', 'password')
)
```

### Exemple en Shell

```bash theme={null}
#!/bin/bash

URL="https://jobaffinity.fr/restapi/v1/job"
AUTH="login:password"

while [ ! -z "$URL" ]; do
  RESPONSE=$(curl -s --basic --user "$AUTH" "$URL")

  # Traiter les items
  echo "$RESPONSE" | jq '.items[]'

  # Obtenir l'URL suivante
  URL=$(echo "$RESPONSE" | jq -r '._next // empty')
done
```

## Ressources paginées

Les ressources suivantes sont paginées :

* Collection de jobs (`/restapi/v1/job`)
* Collection de candidats (`/restapi/v1/candidate`)
* Collection de candidatures par job (`/restapi/v1/job/{id}/application`)
* Collection de candidatures par candidat (`/restapi/v1/candidate/{id}/application`)
* Collection des changements d'étapes (`/restapi/v1/step`)
* Collection des notes (`/restapi/v1/note`)
* Historique des webhooks (`/restapi/v1/webhook/task`)

## Ressources non paginées

Certaines ressources retournent toutes les données en une seule réponse :

* Détails d'un job (`/restapi/v1/job/{id}`)
* Détails d'un candidat (`/restapi/v1/candidate/{id}`)
* Détails d'une candidature (`/restapi/v1/application/{id}`)
* Équipe d'un job (`/restapi/v1/job/{id}/team`)
* Liste des processus (`/restapi/v1/process`)

<Tip>
  N'essayez pas de deviner la taille des pages ou de manipuler le curseur de pagination. Utilisez toujours l'URL fournie par `_next`.
</Tip>


# Structure des réponses
Source: https://api.jobaffinity.com/guides/responses

Comprendre les champs spéciaux et la structure des réponses de l'API

## Format des réponses

Les réponses sont au format **JSON** avec l'en-tête `Content-Type: application/json`.

## Champs spéciaux

Les champs suivants ont une signification particulière dans toutes les réponses de l'API :

### `_status`

Statut de la réponse :

* **`"OK"`** : Les données ont été extraites correctement
* **`"INVALID"`** : Les paramètres de la requête sont invalides (le statut HTTP reste 200)

```json theme={null}
{
  "_status": "OK",
  "data": { ... }
}
```

### `_self`

URI de la ressource actuelle.

* À la racine de la réponse : correspond à l'URL de la requête
* Dans un objet imbriqué : URL permettant d'obtenir l'ensemble des données de cette ressource

```json theme={null}
{
  "_self": "/restapi/v1/job/42",
  "candidate": {
    "_self": "/restapi/v1/candidate/123"
  }
}
```

### `_schema`

URI de la description de la ressource au format **JSON-Schema**.

Cette URL fournit une description exhaustive et à jour du schéma de la ressource.

```json theme={null}
{
  "_schema": "/restapi/schemav1/job"
}
```

<Note>
  Les schémas sont mis à jour automatiquement avec l'API et sont donc plus fidèles que cette documentation.
</Note>

### `_actions`

Liste des actions possibles sur les données courantes.

Ce champ n'est fourni que lorsque des actions sont disponibles. Le contenu dépend des droits de l'utilisateur.

```json theme={null}
{
  "_actions": [
    {
      "_self": "/restapi/v1/note",
      "doc": "Add a new note",
      "method": "POST"
    }
  ]
}
```

### `_next`

URI de la page suivante pour les ressources paginées.

Si ce champ est vide ou absent, vous avez atteint la dernière page.

```json theme={null}
{
  "_next": "/restapi/v1/job?pagecursor=42"
}
```

### `items`

Liste contenant les éléments de la réponse pour les collections.

```json theme={null}
{
  "_self": "/restapi/v1/job",
  "_next": "/restapi/v1/job?pagecursor=10",
  "items": [
    {
      "id": 1,
      "title": "Développeur Full-Stack"
    },
    {
      "id": 2,
      "title": "Chef de projet"
    }
  ]
}
```

## Gestion des erreurs

### Erreurs de validation

Lorsque `_status` vaut `"INVALID"`, un champ `invalid` détaille les erreurs :

```json theme={null}
{
  "_status": "INVALID",
  "invalid": {
    "candidate_id": {
      "code": null,
      "message": "Permission denied"
    },
    "organisation_id": {
      "code": null,
      "message": "Permission denied"
    }
  }
}
```

### Codes HTTP

L'API utilise les codes HTTP standards :

* **200** : Succès (vérifiez aussi `_status`)
* **307** : Redirection temporaire (ex: téléchargement de CV)
* **404** : Ressource non trouvée
* **401** : Authentification requise
* **403** : Accès refusé
* **429** : Trop de requêtes (limite de 45 req/min par IP dépassée)
* **500** : Erreur serveur

## Exemple de réponse complète

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1/job/42",
  "_schema": "/restapi/schemav1/job",
  "id": 42,
  "title": "Développeur Full-Stack",
  "status": "OPEN",
  "applications": {
    "_self": "/restapi/v1/job/42/application"
  },
  "process": {
    "_self": "/restapi/v1/process/72",
    "id": 72
  }
}
```


# Gestion des versions
Source: https://api.jobaffinity.com/guides/versioning

Comprendre le versionnement de l'API et les stratégies de migration

## Principe de versionnement

Le numéro de version de l'API est inclus dans l'URL de base :

```
https://jobaffinity.fr/restapi/v1
```

## Modifications sans changement de version

Les modifications suivantes **ne nécessitent pas** de changement de version majeure :

* Modification des URLs (autre que l'URL de base)
* Ajout de nouveaux champs dans une réponse
* Ajout de nouveaux paramètres de requête
* Ajout/suppression/modification des valeurs d'un ENUM
* Modification de la taille des pages de pagination

<Note>
  Votre code doit être conçu pour ignorer les champs inconnus dans les réponses afin de rester compatible avec ces évolutions.
</Note>

## Modifications avec changement de version

Un changement de version majeure (ex: v1 → v2) sera effectué uniquement pour :

* Suppression de champs existants
* Modification du type de données d'un champ
* Changement de comportement incompatible
* Modifications pouvant entraîner un dysfonctionnement des clients

## Surveillance des versions

### Champs à surveiller

Interrogez régulièrement la ressource racine pour surveiller les changements :

```bash theme={null}
GET https://jobaffinity.fr/restapi/v1
```

**Champs importants** :

* **`_version`** : Version mineure actuelle (ex: "1.10")
* **`_last_version_url`** : URL de la dernière version disponible
* **`_expiration`** : Date d'expiration de la version actuelle
* **`_changelog`** : Lien vers l'historique des modifications

### Exemple de réponse

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1",
  "_version": "1.10",
  "_last_version_url": "/restapi/v1",
  "_expiration": null,
  "_changelog": {
    "_self": "/restapi/changelog"
  }
}
```

### Interprétation

| Situation                      | Signification                              | Action                       |
| ------------------------------ | ------------------------------------------ | ---------------------------- |
| `_last_version_url` == `_self` | Vous utilisez la dernière version          | ✅ Aucune action requise      |
| `_last_version_url` != `_self` | Une nouvelle version est disponible        | ⚠️ Planifier une migration   |
| `_expiration` == `null`        | Pas d'expiration prévue                    | ✅ Version stable             |
| `_expiration` != `null`        | Version sera désactivée à la date indiquée | 🚨 Migration urgente requise |

## Mise en place d'alertes

### Script de surveillance (Python)

```python theme={null}
import requests
from datetime import datetime

def check_api_version():
    """Vérifie l'état de la version de l'API"""
    response = requests.get(
        'https://jobaffinity.fr/restapi/v1',
        auth=('login', 'password')
    )

    data = response.json()

    # Vérifier si une nouvelle version est disponible
    if data['_last_version_url'] != data['_self']:
        print(f"⚠️  ALERTE : Nouvelle version disponible !")
        print(f"   URL actuelle : {data['_self']}")
        print(f"   Nouvelle URL : {data['_last_version_url']}")

    # Vérifier l'expiration
    if data['_expiration']:
        expiration_date = datetime.fromisoformat(data['_expiration'])
        days_remaining = (expiration_date - datetime.now()).days

        print(f"🚨 ALERTE CRITIQUE : Version expire dans {days_remaining} jours")
        print(f"   Date d'expiration : {data['_expiration']}")
        print(f"   Consultez : https://jobaffinity.fr{data['_changelog']['_self']}")

    return data

# Exécuter périodiquement (ex: via cron)
check_api_version()
```

### Script de surveillance (Shell)

```bash theme={null}
#!/bin/bash

RESPONSE=$(curl -s --basic --user "login:password" \
  "https://jobaffinity.fr/restapi/v1")

EXPIRATION=$(echo "$RESPONSE" | jq -r '._expiration // empty')

if [ ! -z "$EXPIRATION" ]; then
  echo "🚨 ALERTE : Version API expire le $EXPIRATION"
  echo "Consultez le changelog pour migrer"
  # Envoyer une alerte (email, Slack, etc.)
  exit 1
fi
```

## Processus de migration

Lorsqu'une nouvelle version majeure est annoncée :

<Steps>
  <Step title="Période de transition">
    Les deux versions (ancienne et nouvelle) restent accessibles simultanément
  </Step>

  <Step title="Tester la nouvelle version">
    Testez votre intégration avec la nouvelle URL fournie par `_last_version_url`
  </Step>

  <Step title="Adapter votre code">
    Effectuez les modifications nécessaires pour la compatibilité
  </Step>

  <Step title="Déployer les changements">
    Mettez à jour votre code en production avant la date d'expiration
  </Step>

  <Step title="Surveillance post-migration">
    Vérifiez que tout fonctionne correctement avec la nouvelle version
  </Step>
</Steps>

## Changelog

Le changelog est accessible via l'URL fournie dans la réponse racine :

```
https://jobaffinity.fr/restapi/changelog
```

Il documente :

* Les nouvelles fonctionnalités
* Les corrections de bugs
* Les changements de comportement
* Les dépréciations
* Les annonces de migration

<Tip>
  Consultez régulièrement le changelog pour découvrir les nouvelles possibilités et optimiser votre intégration.
</Tip>

## Bonnes pratiques

### Conception pour la compatibilité

1. **Ignorer les champs inconnus** : Ne pas échouer sur des champs non reconnus
2. **Utiliser les URLs fournies** : Ne jamais construire d'URLs manuellement
3. **Versionner votre code** : Gardez trace de la version d'API utilisée
4. **Tester régulièrement** : Validez votre intégration à chaque évolution mineure

### Exemple de code robuste (Python)

```python theme={null}
import requests

class JobAffinityAPI:
    def __init__(self, auth):
        self.auth = auth
        self.base_url = 'https://jobaffinity.fr/restapi/v1'

    def get_resource(self, url=None):
        """Récupère une ressource en utilisant les URLs fournies"""
        if url is None:
            url = self.base_url

        response = requests.get(url, auth=self.auth)
        data = response.json()

        # Ignorer les champs inconnus automatiquement
        return data

    def check_version_status(self):
        """Vérifie l'état de la version"""
        root = self.get_resource()

        return {
            'current_version': root.get('_version'),
            'is_latest': root.get('_last_version_url') == root.get('_self'),
            'expiration': root.get('_expiration'),
            'changelog_url': root.get('_changelog', {}).get('_self')
        }

# Utilisation
api = JobAffinityAPI(auth=('login', 'password'))
status = api.check_version_status()

if not status['is_latest']:
    print("⚠️  Nouvelle version disponible")

if status['expiration']:
    print(f"🚨 Migration requise avant {status['expiration']}")
```

## Support

Pour toute question sur la migration :

* Email : [support@intuition-software.fr](mailto:support@intuition-software.fr)
* Le support vous accompagnera durant la période de transition


# Webhooks
Source: https://api.jobaffinity.com/guides/webhooks

Configuration et utilisation des webhooks pour recevoir des notifications en temps réel

## Introduction aux Webhooks

Les webhooks permettent à JobAffinity de notifier votre système en temps réel lors d'événements importants (nouvelle candidature, changement d'étape, etc.).

## Événements disponibles

Les principaux événements webhook sont :

* **`ProcessStepChange`** : Changement d'étape dans le processus d'une candidature
* Autres événements disponibles (contactez le support pour la liste complète)

## Configuration

Pour configurer les webhooks, contactez le support d'Intuition-Software : [support@intuition-software.fr](mailto:support@intuition-software.fr)

Vous devrez fournir :

* L'URL de votre endpoint qui recevra les notifications
* Les événements auxquels vous souhaitez souscrire
* Les méthodes de sécurité souhaitées (authentification, signature, etc.)

## Historique des appels Webhook

Vous pouvez consulter l'historique des appels webhook effectués par JobAffinity.

### Requête

```bash theme={null}
GET /restapi/v1/webhook/task
```

### Réponse

```json theme={null}
{
  "_status": "OK",
  "_schema": "/restapi/schemav1/webhooktasks",
  "_self": "/restapi/v1/webhook/task",
  "_next": "",
  "items": [
    {
      "event": "ProcessStepChange",
      "datetime": "2021-04-01 12:13:14",
      "response_body": "Server Error",
      "response_status": 500,
      "application": {
        "_self": "/restapi/v1/application/42"
      }
    }
  ]
}
```

### Champs de la réponse

* **`event`** : Type d'événement déclenché
* **`datetime`** : Date et heure de l'appel webhook
* **`response_status`** : Code de statut HTTP retourné par votre endpoint
* **`response_body`** : Corps de la réponse de votre endpoint
* **`application`** : Référence à la candidature concernée

<Note>
  Cette ressource est paginée. Utilisez le champ `_next` pour parcourir l'historique complet.
</Note>

## Implémentation d'un endpoint

### Bonnes pratiques

1. **Répondez rapidement** : Votre endpoint doit répondre en moins de 30 secondes
2. **Retournez un code 200** : Même si le traitement est asynchrone
3. **Validez les données** : Vérifiez l'authenticité et la structure des données reçues
4. **Gérez les doublons** : Un même événement peut être envoyé plusieurs fois en cas d'échec
5. **Loggez les appels** : Conservez une trace des webhooks reçus pour le débogage

### Exemple d'endpoint (Python/Flask)

```python theme={null}
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # Récupérer les données du webhook
    data = request.json
    event_type = data.get('event')

    # Traiter selon le type d'événement
    if event_type == 'ProcessStepChange':
        application_url = data.get('application', {}).get('_self')

        # Récupérer les détails complets via l'API
        response = requests.get(
            f'https://jobaffinity.fr{application_url}',
            auth=('login', 'password')
        )

        application_details = response.json()

        # Votre logique métier ici
        process_application_change(application_details)

    # Répondre rapidement
    return jsonify({'status': 'received'}), 200

def process_application_change(application):
    # Traitement asynchrone
    pass
```

### Exemple d'endpoint (Node.js/Express)

```javascript theme={null}
const express = require('express');
const axios = require('axios');

const app = express();
app.use(express.json());

app.post('/webhook', async (req, res) => {
  const { event, application } = req.body;

  // Répondre immédiatement
  res.status(200).json({ status: 'received' });

  // Traitement asynchrone
  if (event === 'ProcessStepChange') {
    try {
      const response = await axios.get(
        `https://jobaffinity.fr${application._self}`,
        {
          auth: {
            username: 'login',
            password: 'password'
          }
        }
      );

      await processApplicationChange(response.data);
    } catch (error) {
      console.error('Error processing webhook:', error);
    }
  }
});

async function processApplicationChange(application) {
  // Votre logique métier
}

app.listen(3000);
```

## Monitoring

Utilisez l'historique des webhooks pour :

* Vérifier que votre endpoint répond correctement
* Déboguer les erreurs
* Détecter les problèmes de performance
* Auditer les événements reçus

<Warning>
  Si votre endpoint retourne régulièrement des erreurs (5xx), les appels webhook peuvent être temporairement suspendus. Surveillez votre historique et corrigez les problèmes rapidement.
</Warning>

## Gestion des versions

Les webhooks suivent le même principe de versioning que l'API REST. En cas de changement majeur dans le format des webhooks, vous serez notifié à l'avance.


# Introduction
Source: https://api.jobaffinity.com/index

Documentation de l'API REST JobAffinity (v1.13)

Bienvenue sur la documentation technique de l'interface de communication **JobAffinity**. Cette API de type REST permet d'interagir avec notre plateforme de recrutement de manière programmatique.

## Vue d'ensemble

L'API REST JobAffinity vous permet de :

* Accéder à vos offres d'emploi et candidatures
* Gérer les processus de recrutement
* Consulter et enrichir votre CVthèque
* Automatiser vos workflows via webhooks

## Caractéristiques principales

<CardGroup>
  <Card title="Auto-découverte" icon="compass">
    Navigation intuitive : seule l'URL racine est nécessaire
  </Card>

  <Card title="Auto-documentée" icon="book">
    Schémas JSON-Schema inclus dans chaque réponse
  </Card>

  <Card title="RESTful" icon="network-wired">
    Architecture REST standard avec HTTPS et JSON
  </Card>

  <Card title="Versionnée" icon="code-branch">
    Gestion de versions pour migrations en douceur
  </Card>
</CardGroup>

## Démarrage rapide

<Steps>
  <Step title="Obtenir vos identifiants">
    Contactez le support : [support@intuition-software.fr](mailto:support@intuition-software.fr)
  </Step>

  <Step title="Tester l'authentification">
    ```bash theme={null}
    curl -X GET https://jobaffinity.fr/restapi/v1 \
         --basic --user login:password
    ```
  </Step>

  <Step title="Explorer l'API">
    Utilisez les URLs fournies dans les réponses pour naviguer dans l'API
  </Step>
</Steps>

## URL de base

```
https://jobaffinity.fr/restapi/v1
```

<Note>
  Cette URL racine est le seul point d'entrée dont vous avez besoin. Toutes les autres URLs vous seront fournies par l'API elle-même.
</Note>

## Format des échanges

* **Protocole** : HTTPS uniquement
* **Méthodes** : GET et POST
* **Format** : JSON (`application/json`)
* **Authentification** : HTTP Basic Auth

## Limitation de taux

<Warning>
  L'API est limitée à **45 requêtes par minute par adresse IP**. Dépasser cette limite entraînera des réponses HTTP 429 (Too Many Requests).
</Warning>

## Prochaines étapes

<CardGroup>
  <Card title="Authentification" icon="key" href="/guides/authentication">
    Apprenez à vous authentifier et à effectuer vos premières requêtes
  </Card>

  <Card title="Architecture" icon="sitemap" href="/guides/discovery">
    Comprenez le principe d'auto-découverte et la navigation
  </Card>

  <Card title="Structure des réponses" icon="file-code" href="/guides/responses">
    Découvrez les champs spéciaux et la structure des réponses
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explorez la documentation complète des endpoints
  </Card>
</CardGroup>

## Support

Pour toute question ou demande d'assistance :

* Email : [support@intuition-software.fr](mailto:support@intuition-software.fr)
* Changelog : [https://jobaffinity.fr/restapi/changelog](https://jobaffinity.fr/restapi/changelog)

<Warning>
  **Important** : Surveillez le champ `_expiration` dans la ressource racine. S'il devient différent de `null`, une migration vers une nouvelle version sera nécessaire.
</Warning>