# Create a product

Creates a new product (property listing).
**Criteria (`criteria` field):**
- Each criterion is an object with `id` (criteria identifier) and `value`.
- The `id` accepts **either** the XML identifier (e.g. `"TypeBien"`, `"NbPieces"`, `"Surface"`) **or** the numeric ID (e.g. `"27"`). Both are resolved by the API.
- Value format depends on criteria type: string for UNIQUE, number for NUMBER, boolean 0/1 for FLAG, array for MULTIPLE, ISO date for DATE.
- For UNIQUE/MULTIPLE types, the value must exactly match a valid **value code** (`model` field) from the referential. Use `GET /criterias/product/{id}` to discover valid values.
For example:
  - ✅ Correct:
`{"id": "TypeBien", "value": "1"}`
  - ❌ Wrong:
`{"id": "TypeBien", "value": "Appartement"}`
 (this is the value label, not the value code)
The criteria endpoint (`GET /criterias/product/{id}`) returns value objects like:

```json
{ "id": "6", "model": "1", "label": "Appartement" }
```
You must use the `model` field as the `value` in your criteria array.

**Product status (`Statut` criterion):**
- The product is only
**active and visible**
 in the interface when
`Statut = "EnCours"`
.
- If you do NOT send the
`Statut`
 criterion, the system applies the site's default

value (configured per site). This default is usually
`"EnCours"`
 (active), but some

sites may have a different default — in that case the product may not be immediately

visible in the interface.
- **Recommendation:**
 Always explicitly include
`{"id": "Statut", "value": "EnCours"}`

in your criteria array to ensure the product is immediately active.

**DPE (Energy Performance):**
- Send numeric values via
`conso_energ`
 (kWh/m²/year) and
`valeur_GES`
 (kgCO₂/m²/year).
- The system
**automatically calculates**
 the DPE/GES letter (A-G) from numerical values based on property type and country.
- If you already know the letter, send it directly via
`ConsoEner`
 /
`GES`
 criteria instead.

**Geolocation (GPS):**
- If the
`Alentour`
 criterion is provided (format
`"lat,lng"`
, e.g.
`"48.8566,2.3522"`
), it is used directly as the property's GPS coordinates.
- If
`Alentour`
 is NOT provided, the system
**automatically geocodes**
 from
`Adresse`
 +
`CodePostal`
 +
`Ville`
 criteria. Fallback: geocodes from city+postal code only.

**Model (reference):**
- The
`model`
 field is the property's internal reference number (mandate number, agency reference).
- If omitted, the system auto-generates the next available reference for the agency.
- You can use it to store your own identifier for cross-referencing.

**Rooms (`rooms` field):**
- Each room has a
`type`
 (validated against referential list 1), optional
`surface`
,
`niveau`
,
`exposition`
 (list 2),
`vue`
 (list 3),
`sol`
 (list 4),
`commentaire`
.
- Use
`GET /configs/listes/{listeId}/values`
 to discover valid values (1=room types, 2=expositions, 3=views, 4=floor types).

Endpoint: POST /products
Version: 1.6.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer opaque

## Request fields (application/json):

  - `agency_id` (integer, required)
    Agency ID for the product. Must be within the authenticated site's scope
(validated by `manufacturer_in_scope`). Use `GET /agencies` to list available IDs.
    Example: 123

  - `user_id` (integer | null)
    Assigned user (agent) ID. The agent responsible for this property listing.
    Example: 456

  - `model` (string | null)
    Product reference (mandate number, agency reference, your own identifier).
**Auto-generated** if omitted — the system produces the next sequential reference
for the agency. You can use this field to store your own cross-reference ID.
    Example: REF-2025-001

  - `descriptions` (array | null)
    Web descriptions for the product (multilingual). Each entry requires a
`language_code` (ISO 639-2, e.g. `"fr"`).

  - `descriptions.title` (string | null)
    Short title.
    Example: Bel appartement lumineux

  - `descriptions.description` (string | null)
    Full description text.
    Example: Situé au 3ème étage avec ascenseur, cet appartement...

  - `descriptions.language_code` (string, required)
    ISO 639-2 language code.
    Example: fr

  - `criteria` (array, required)
    Product criteria array. **Required.**
Each criterion is an object with:
- `id`
 — Either the XML key (e.g.
`"TypeBien"`
) or numeric ID (e.g.
`"27"`
).

Both are resolved by the API.
- `value`
 — Format depends on criteria type:
  - UNIQUE: exact
**value code**
 string from the referential (the
`model`
 field

from
`GET /criterias/product/{id}`
, e.g.
`"1"`
 (label "Appartement"), NOT the

numeric ID like
`"6"`
)
  - NUMBER: numeric value as string (e.g.
`"85.5"`
)
  - FLAG:
`0`
 or
`1`
  - TEXT: free text string
  - MULTIPLE: array of value code strings
  - DATE: ISO 8601 datetime or
`dd/MM/yyyy`

**Mandatory criteria:**
- `TypeBien`
 (ID 27) — Property type (e.g.
`"1"`
 (Appartement),
`"2"`
 (Maison))
- `TypeTransaction`
 (ID 28) — Transaction type (e.g.
`"Vente"`
,
`"Location"`
)
- `CPVille`
 (ID 65) — Or alternatively
`CodePostal`
 +
`Ville`
 (auto-composed)

**Recommended criteria:**
- `Statut`
 — Product status. Must be
`"EnCours"`
 for the product to be active

and visible. If omitted, the site's default applies (which may create an

inactive product).

**DPE auto-calculation:** If you provide `conso_energ` (numeric) without
`ConsoEner` (letter), the system auto-calculates the DPE letter based on
property type and country. Same for `valeur_GES` → `GES`.
**GPS auto-geocoding:** If you provide `Adresse` + `CodePostal` + `Ville`
without `Alentour`, the system geocodes the address automatically.
Provide `Alentour` directly (format `"lat,lng"`) to bypass geocoding.
Use `GET /criterias/product/all` to discover available criteria and
`GET /criterias/product/{id}` for valid values.
    Example: [{"id":"TypeBien","value":"1"},{"id":"TypeTransaction","value":"Vente"},{"id":"Statut","value":"EnCours"},{"id":"NbPieces","value":"4"},{"id":"Surface","value":"85.5"},{"id":"Prix","value":"350000"},{…

  - `criteria.id` (string, required)
    Criteria identifier (XML key or numeric ID).
    Example: TypeBien

  - `criteria.value` (any, required)
    Criteria value (format depends on type).
    Example: 1

  - `rooms` (array | null)
    Room list. Each room requires a `type` from referential list 1.
Use `GET /configs/listes/1/values` to discover room types.
| Field | Required | Validation | Description |
|  --- | --- | --- | --- |
| `type` | Yes | list 1 | Room type (e.g. "Chambre", "Cuisine") |
| `niveau` | No | numeric | Floor level |
| `surface` | No | numeric | Surface in m² |
| `exposition` | No | list 2 | Exposure (Nord, Sud, Est, Ouest...) |
| `vue` | No | list 3 | View (Jardin, Mer, Rue...) |
| `sol` | No | list 4 | Floor type (Parquet, Carrelage...) |
| `commentaire` | No | string | Free comment |

  - `rooms.type` (string, required)
    Room type from list 1.
    Example: Chambre

  - `rooms.niveau` (number | null)
    Floor level.

  - `rooms.surface` (number | null)
    Surface in m².
    Example: 14.5

  - `rooms.exposition` (string | null)
    Exposure from list 2.

  - `rooms.vue` (string | null)
    View from list 3.

  - `rooms.sol` (string | null)
    Floor type from list 4.

  - `rooms.commentaire` (string | null)
    Free comment.

  - `customer_id` (integer | null)
    Existing customer ID to link as the property owner/seller.
Mutually exclusive with `customer` object.
    Example: 789

  - `customer` (object)
    Create a new customer and link as owner. Used when `customer_id` is not provided.

## Response 201:

  - `201` (unknown)
    Product created

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (integer)

## Response 403:

  - `403` (unknown)
    Access denied. The error `code` is always `FORBIDDEN`; the `message` gives the cause:
- `You do not have permission to perform this action.`
 — the access does not

hold the API pack / right required by the endpoint.
- `Insufficient scope for this request.`
 — the resource targeted by the request

(user, customer, product, agency, transaction, ...) is outside the scope of

the authenticated access.
- `Access denied for this editor.`
 /
`Your IP address has been blocked.`
 —

editor or IP restriction.

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (string, required)

  - `error.message` (string, required)

## Response 422:

  - `422` (unknown)
    Validation failed

## Response 422 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Enum: "VALIDATION_ERROR"

  - `error.message` (string)

  - `error.details` (array)

  - `error.details.field` (string)

  - `error.details.message` (string)

## Response 403 examples:

  - `Missing API pack / right` (unknown)

  - `Resource outside the scope of the access` (unknown)

