# Formats de champs

Un modèle qui devine le nom d'un champ reçoit soit un `400`, soit, pire encore, une réponse confiante pour une carte différente. Voici le contrat exact.

## Corps de la requête de carte

| Champ | Type et format | Obligatoire |
|---|---|---|
| `date` | `YYYY-MM-DD`, et ce doit être un jour de calendrier réel | oui |
| `time` | `HH:mm:ss` | oui, ou `timeUnknown: true` |
| `timezoneOffset` | nombre, heures depuis UTC, ex. `5.75` | non, par défaut `0` (UTC) |
| `timezone` | nom de zone IANA, ex. `Europe/Kyiv`, ou `auto` | non, et si envoyé, remplace `timezoneOffset` |
| `latitude` | degrés décimaux, nord positif | oui |
| `longitude` | degrés décimaux, est positif | oui |
| `houseSystem` | une seule lettre, par défaut `P` | non |
| `city` | chaîne de caractères, signature uniquement | non |
| `zodiacType` | `tropical` ou `sidereal` | non |

<Aside type="caution">
`city` ne géocode rien. C'est un champ pour la signature dans ton interface, et il ne remplace **jamais** les coordonnées.
</Aside>

## Les abréviations sont rejetées

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` renvoient un `400 INVALID_FIELD` avec le nom du champ correct :

```json
{ "error": { "code": "INVALID_FIELD",
  "message": "Unsupported field \"tz\". Rename it to \"timezoneOffset\" (numeric hours from UTC, e.g. 5.75; a zone name goes in timezone)." } }
```

La casse et les séparateurs n'ont pas d'importance : `TZ_Offset` et `tzoffset` sont rejetés de la même manière. Tous les champs trouvés sont signalés **immédiatement**, et non le premier, afin que tu puisses corriger en une seule fois.

La raison est stricte : avant cette validation, un champ non lu par l'API donnait silencieusement un décalage de `0`, et la réponse était une carte confiante pour l'UTC. Trois heures de décalage représentent environ 45° d'ascendant, c'est-à-dire un signe ascendant différent, et aucun avertissement.

## `timezone` : nom de la zone au lieu du décalage

Le décalage doit être celui qu'indiquaient les horloges **à cette date précise**, et il est facile de le spécifier manuellement de manière incorrecte : Kiev en mai 1990 vivait à l'heure d'été de Moscou, UTC+4, et non +3. Envoie `timezone`, et le serveur prendra le décalage de la base de données des fuseaux horaires, y compris l'heure d'été.

```json
{ "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
  "latitude": 50.45, "longitude": 30.52 }
```

- `auto` détermine la zone en fonction de `latitude` et `longitude`. Près d'une frontière, le nom est plus précis.
- Si `timezone` et `timezoneOffset` sont envoyés ensemble, `timezone` est prioritaire. `input.timezoneOffset` dans la réponse indique le décalage qui a été utilisé.
- L'heure qui a eu lieu deux fois (lorsque les horloges ont été reculées) est prise la première fois. L'heure qui n'a pas eu lieu (lorsque les horloges ont été avancées) reçoit le décalage qui était en vigueur avant le changement.
- Sans `time` (seulement la date ou `timeUnknown: true`), la zone est lue pour le midi local.
- Sont rejetés avec un `400 INVALID_FIELD` : valeur vide, abréviations comme `EST` ou `PST`, décalage écrit en texte comme `+03:00`, noms qui ne sont pas dans la base de données, et `auto` sans coordonnées. `UTC` et `GMT` sont acceptés.
- Chaque objet est analysé séparément, donc `chart1` et `chart2` peuvent être dans des zones différentes.

<Aside type="note">
Avant 1970, la base de données des fuseaux horaires n'est pas fiable pour chaque lieu : Amsterdam en juin 1930 est renvoyé comme +1, bien que les horloges indiquaient +0:20. Si l'heure locale de cette naissance est connue, envoie `timezoneOffset`.
</Aside>

## `houseSystem` : lettre, pas un nom

Seuls ces 25 codes Swiss Ephemeris sont acceptés :

`P` `K` `R` `C` `E` `W` `B` `M` `O` `A` `T` `V` `D` `F` `G` `H` `I` `i` `L` `N` `Q` `S` `U` `X` `Y`

La casse est significative : `I` est Sunshine selon Makransky, `i` selon Trindl. Le nom du système (`"Placidus"`, `"Koch"`) renvoie un `400`. Auparavant, cela fonctionnait par hasard, car le moteur ne lit que la première lettre de la chaîne, et pour la même raison, `"Zodiac"` donnait silencieusement Placidus.

## Heure de naissance inconnue

Au lieu d'un midi inventé, transmets `timeUnknown: true` et ne transmets pas `time`. Alors `houses`, `houseAspects`, `chartSect` et `siderealTime` seront `null`, et non inventés. Détails : [Conventions de l'API](/api-conventions/#невідомий-час-народження).

## Les clés inconnues ne sont pas rejetées

Le corps accepte les champs superflus silencieusement : une clé inconnue est simplement ignorée. Par conséquent, une erreur dans le nom d'un champ qui n'est pas dans la liste des rejets ci-dessus ne se manifestera pas. Référe-toi à la spécification : [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Suite

- [Erreurs courantes](/agent-setup/mistakes/)
- [Pièges](/agent-setup/gotchas/)