> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arquos.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Créer une affaire et ses relevés

> Comme l’écran « Nouvelle affaire » : un relevé par équipement, et ses contrats seulement si elle en comporte. C’est la création de relevé de la V1 (create_survey).

### Endpoint & Authentification

| Méthode | URL |
| :- | :- |
| `POST` | `https://api.arquos.eu/api/v2/deals` |

**En-têtes (Headers) :**

* `Authorization: Bearer [VOTRE_JETON_D_API]`
* `X-Arquos-Agency: [IDENTIFIANT_D_AGENCE]` (facultatif, voir [Agence](/v2/agence))
* `Content-Type: application/json`

### Paramètres de la requête

<ParamField header="X-Arquos-Agency" type="string">
  L’identifiant de l’agence où agir. Absent : l’agence par défaut du compte. Une agence hors de sa portée est refusée (403).
</ParamField>

<ParamField body="kind" type="string" required>
  contrat = Contrat d’entretien ; reparation = Réparation ; modernisation = Modernisation ; remplacement = Remplacement complet Valeurs possibles : `contrat`, `reparation`, `modernisation`, `remplacement`.
</ParamField>

<ParamField body="purpose" type="string">
  Pour une modernisation ou un remplacement complet : chiffrer (devis) ou commander les travaux. Valeurs possibles : `chiffrer`, `commander`.
</ParamField>

<ParamField body="withSecondDocument" type="boolean">
  Le second document : un devis en plus d’un contrat d’entretien, ou un contrat en plus d’un devis.
</ParamField>

<ParamField body="equipmentIds" type="string[]" required>
  Les identifiants des équipements, tous dans la même agence.
</ParamField>

<ParamField body="collectionMode" type="string">
  Relevé sur site (par défaut), données existantes, ou entrée directe. Valeurs possibles : `sur_site`, `donnees_existantes`, `entree_directe`.
</ParamField>

<ParamField body="deadline" type="string">
  Date limite du relevé, AAAA-MM-JJ.
</ParamField>

<ParamField body="instructions" type="string">
  Les consignes pour le releveur (accès, clés, contact).
</ParamField>

<ParamField body="name" type="string">
  Le nom de l’affaire ; à défaut, la rue de l’immeuble.
</ParamField>

### Réponse (`201`)

<ResponseField name="id" type="string">
  L’identifiant de l’affaire créée.
</ResponseField>

<ResponseField name="ok" type="boolean">
  Toujours `true` : un refus rend un code d’erreur et sa raison.
</ResponseField>

<ResponseField name="link" type="string">
  Le chemin de la fiche dans Arquos.
</ResponseField>

<ResponseField name="url" type="string">
  L’adresse complète de la fiche, à ouvrir dans un navigateur.
</ResponseField>

### Les erreurs

| Code | Quand |
| :- | :- |
| `400` | Requête mal formée ou champ obligatoire manquant. |
| `401` | Jeton absent, inconnu ou révoqué. |
| `403` | Agence hors de votre portée. |
| `404` | Objet introuvable dans vos agences. |
| `422` | Saisie refusée par Arquos (champ obligatoire, valeur hors bornes, choix inconnu). |
| `429` | Trop d’appels : réessayez après le délai de l’en-tête Retry-After. |

Le corps d'une erreur porte `error`, sa raison en français. Voir [Les erreurs](/v2/erreurs).

<RequestExample>
  ```bash cURL theme={"system"}
  curl --request POST \
  --url https://api.arquos.eu/api/v2/deals \
  --header 'Authorization: Bearer arq_agent_VOTRE_JETON' \
  --header 'Content-Type: application/json' \
  --data '{
  "kind": "contrat",
  "equipmentIds": [
    "texte"
  ]
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"system"}
  {
  "id": "e8afaf6a-edae-4843-b37d-1833931864b8",
  "ok": true,
  "link": "/deals/e8afaf6a-edae-4843-b37d-1833931864b8",
  "url": "https://app.arquos.eu/deals/e8afaf6a-edae-4843-b37d-1833931864b8"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.