# Formatos de campos

O modelo que tenta adivinhar o nome do campo recebe ou `400` ou, pior ainda, uma resposta confiante sobre outra carta. Abaixo está o contrato exato.

## Corpo da solicitação de carta

| Campo | Tipo e formato | Obrigatório |
|---|---|---|
| `date` | `YYYY-MM-DD`, e deve ser um dia calendário real | sim |
| `time` | `HH:mm:ss` | sim, ou `timeUnknown: true` |
| `timezoneOffset` | número, horas em relação ao UTC, por exemplo `5.75` | não, padrão `0` (UTC) |
| `timezone` | nome da zona IANA, por exemplo `Europe/Kyiv`, ou `auto` | não, e quando enviado, substitui `timezoneOffset` |
| `latitude` | graus decimais, norte positivo | sim |
| `longitude` | graus decimais, leste positivo | sim |
| `houseSystem` | uma letra, padrão `P` | não |
| `city` | string, apenas assinatura | não |
| `zodiacType` | `tropical` ou `sidereal` | não |

<Aside type="caution">
`city` não faz geocodificação nenhuma. Este campo é para uma assinatura na sua interface, e ele **nunca** substitui as coordenadas.
</Aside>

## Formas abreviadas são rejeitadas

`lat`, `lon`, `lng`, `long`, `tz`, `tzOffset`, `utcOffset`, `gmtOffset`, `timeZone`, `time_zone` retornam `400 INVALID_FIELD` com o nome do campo correto:

```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)." } }
```

Regra e separadores no valor não importam: `TZ_Offset` e `tzoffset` são rejeitados da mesma forma. **Todos** os campos encontrados são relatados de uma vez, não apenas o primeiro, para que você possa corrigi-los de uma só vez.

Motivo da rigidez: antes desta verificação, um campo que a API não lia dava silenciosamente um deslocamento de `0`, e a resposta era uma carta confiante para UTC. Três horas de deslocamento correspondem aproximadamente a 45° de ascendente, ou seja, outro signo a nascer, e nenhum aviso.

## `timezone`: nome da zona em vez do deslocamento

O deslocamento deve ser aquele que os relógios estavam realmente a marcar **nessa data**, e é fácil indicá-lo incorretamente à mão: Kiev em maio de 1990 estava no horário de verão de Moscovo, UTC+4, não +3. Envie `timezone`, e o servidor irá obter o deslocamento da base de dados de fusos horários, incluindo o horário de verão.

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

- `auto` determina a zona com base em `latitude` e `longitude`. Perto da fronteira, o nome é mais preciso.
- Se `timezone` e `timezoneOffset` chegarem juntos, `timezone` tem precedência. `input.timezoneOffset` na resposta mostra o deslocamento que foi utilizado.
- O horário que ocorreu duas vezes (quando os relógios foram atrasados) é considerado na primeira ocorrência. O horário que não ocorreu (quando os relógios foram adiantados) recebe o deslocamento que estava em vigor antes da mudança.
- Sem `time` (apenas data ou `timeUnknown: true`) a zona é lida ao meio-dia local.
- Rejeitado com `400 INVALID_FIELD`: valor vazio, abreviações como `EST` ou `PST`, deslocamento escrito como texto, como `+03:00`, nomes que não estão na base de dados, e `auto` sem coordenadas. `UTC` e `GMT` são aceites.
- Cada objeto é analisado separadamente, portanto `chart1` e `chart2` podem estar em zonas diferentes.

<Aside type="note">
Antes de 1970 a base de dados de fusos horários não é fiável para todos os locais: Amsterdão em junho de 1930 retorna +1, embora os relógios marcassem +0:20. Se o horário local do nascimento for conhecido, envie `timezoneOffset`.
</Aside>

## `houseSystem`: letra, não nome

Exatamente estes 25 códigos da Swiss Ephemeris são aceites:

`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`

A maiúscula/minúscula importa: `I` é Sunshine por McCranky, `i` por Traindl. O nome do sistema (`"Placidus"`, `"Koch"`) retorna `400`. Antes funcionava por acaso, pois o motor lê apenas a primeira letra da string, e por esse mesmo motivo `"Zodiac"` dava silenciosamente Placidus.

## Tempo de nascimento desconhecido

Em vez de fabricar um meio-dia, envie `timeUnknown: true` e não envie `time`. Então `houses`, `houseAspects`, `chartSect` e `siderealTime` chegam como `null`, não fabricados. Detalhes: [Convenções da API](/api-conventions/#невідомий-час-народження).

## Chaves desconhecidas não são rejeitadas

O corpo aceita campos extras silenciosamente: uma chave desconhecida é simplesmente ignorada. Portanto, um erro no nome de um campo que não está na lista de rejeição acima passará despercebido. Verifique-se com a especificação: [`/v1/openapi.json`](https://api.astroway.info/v1/openapi.json).

## Seguinte

- [Erros comuns](/agent-setup/mistakes/)
- [Armadilhas](/agent-setup/gotchas/)