# Lire, créer et retirer des offres par API

Source: https://docs.coworkies.com/fr/api/jobs/

> Utilisez les filtres, la pagination, les données de création, l’idempotence et le retrait limité à votre espace.

## Lire les offres actives

**`GET /v2/jobs`** exige `jobs:read`, `read` ou une permission accordant cette lecture.

| Paramètre | Signification |
|---|---|
| `q` | Recherche dans le titre, l’entreprise et les tags. |
| `job_type` | `fulltime`, `parttime`, `freelance` ou `internship`. |
| `remote` | Télétravail : `true` ou `false`. |
| `city` | Identifiant URL de ville, par exemple `berlin`. |
| `page`, `per_page` | Pagination si activée côté serveur ; maximum 50 par page. |

```bash
curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs?city=berlin&job_type=fulltime'   -H "X-API-Key: ${COWORKIES_API_KEY}"
```

Une clé d’espace retourne les offres de cet espace dans `data.jobs`. Si `data.pagination` existe, utilisez `has_next` et `current_page`. Sinon, le serveur retourne la liste complète avec `data.total` : ne supposez pas que `per_page` limite la réponse.

## Créer une offre

**`POST /v2/jobs`** exige `jobs:write` ou `write`. Envoyez du JSON.

| Champ obligatoire | Valeur |
|---|---|
| `title` | Titre de l’offre. |
| `company` | Nom de l’entreprise. |
| `description` | Texte ou HTML simple (`p`, `br`, `ul`, `ol`, `li`, `h2`, `h3`, `strong`, `em`, `a`). |
| `job_type` | `fulltime`, `parttime`, `freelance` ou `internship`. |
| `tags` | Tags séparés par des virgules. |
| `id_city` **ou** `city_name` | Identifiant de ville confirmée ou nom résolvable. |

Les champs facultatifs comprennent `external_url`, `apply_url`, `is_remote` (`0` ou `1`), `inv_email`, `currency` (`EUR`, `USD`, `GBP`), `sal_min`, `sal_max`, `id_space` et `id_plan` (valeur par défaut `5`). Le salaire minimum ne peut pas dépasser le maximum. Consultez la référence complète pour tous les champs.

L’espace de la clé est affecté automatiquement ; un `id_space` contradictoire est rejeté. Les tags sont nettoyés, mis en minuscules et dédupliqués. Le nom de ville est résolu par correspondance exacte puis par préfixe. Utilisez `id_city` pour un nom ambigu. L’URL source reçoit un paramètre de référencement Coworkies.

```bash
# Valeur unique pour une nouvelle offre ; conserver pour ses nouvelles tentatives.
COWORKIES_JOB_REQUEST_ID='space-job-community-manager-001'
curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs'   -X POST   -H "X-API-Key: ${COWORKIES_API_KEY}"   -H 'Content-Type: application/json'   -H "Idempotency-Key: ${COWORKIES_JOB_REQUEST_ID}"   -d '{
    "title": "Community Manager",
    "company": "Example Workspace",
    "description": "Lead member experience at our Berlin workspace.",
    "job_type": "fulltime",
    "city_name": "Berlin",
    "tags": "community,events,hospitality",
    "apply_url": "https://example.com/careers/apply",
    "is_remote": 0,
    "currency": "EUR",
    "sal_min": 35000,
    "sal_max": 45000
  }'
```

### Vérifier la publication

Pour un **espace Pro confirmé**, une nouvelle offre API peut être publiée automatiquement en **`active`**. Les autres offres créées par une clé d’espace commencent en **`draft`**. Les importateurs de plateforme autorisés peuvent aussi publier automatiquement. Un champ `status` fourni par le client ne force pas l’état initial.

Vérifiez `data.status`, `data.action`, `data.job_id` et les liens de consultation, de modification ou de paiement retournés. Une réponse réussie ne garantit pas une visibilité publique. Suivez le lien retourné si une action supplémentaire est nécessaire.

### Doublons et nouvelles tentatives

L’API compare le titre, l’entreprise, la ville et l’URL source normalisés. Une correspondance met à jour l’offre existante ; `data.action` vaut `created` ou `updated`. Une offre expirée ou suspendue n’est pas automatiquement réactivée par cette mise à jour.

`Idempotency-Key` (200 caractères maximum) évite de répéter une création réussie lors d’un nouvel envoi identique. Réutilisez-le pour cette requête seulement. Traitez `409` et `429` selon [le guide des erreurs](https://docs.coworkies.com/fr/api/authentication/).

## Retirer une offre

**`POST /v2/jobs/unpublish`** exige une permission d’écriture et une offre appartenant à l’espace de la clé.

```bash
curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs/unpublish'   -X POST   -H "X-API-Key: ${COWORKIES_API_KEY}"   -H 'Content-Type: application/json'   -d '{"job_id": 1234}'
```

Remplacez `1234` par `data.job_id`. Le retrait retourne un état expiré et `unpublished`. Une offre déjà expirée ou fermée retourne `already_unpublished`. La fiche est retirée des résultats actifs sans être supprimée.