> ## Documentation Index
> Fetch the complete documentation index at: https://dev.igps.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Vehicle Position Fields, Status Codes, and Response Shape

> Understand the structure of vehicle position results returned by iGps, including coordinate fields, timestamps, and per-vehicle status codes.

Quando você consulta `/api/v1/veiculos/posicoes`, a iGps retorna um array `resultados`. Cada elemento representa um veículo e contém sua posição GPS mais recente conhecida, junto com um código de status indicando se a posição foi encontrada.

## Identificando Veículos: O Número do Chassi

Cada veículo é identificado pelo seu **VIN (número do chassi) de 17 caracteres**. Este é o mesmo Número de Identificação do Veículo gravado no chassi do veículo e registrado nos documentos de registro.

Ao construir uma requisição, cada número de chassi deve:

* Ter **exatamente 17 caracteres** de comprimento
* Conter apenas **caracteres alfanuméricos** (A-Z, 0-9)

**Exemplo de número de chassi:** `VIN00000000000001`

Você pode enviar entre **1 e 50** números de chassi em uma única requisição. Cada chassi é consultado de forma independente, e a resposta conterá uma entrada de resultado por chassi.

## Campos do Resultado da Posição

Cada objeto no array `resultados` contém os seguintes campos:

<ResponseField name="chassi" type="string" required>
  O número do chassi (VIN) de 17 caracteres que foi consultado. Use este campo para mapear cada resultado ao veículo correspondente da sua requisição.
</ResponseField>

<ResponseField name="status" type="string" required>
  Status do resultado. `ok` se uma posição foi encontrada; `nao_encontrado` se o veículo não foi encontrado.
</ResponseField>

<ResponseField name="timestamp" type="string">
  Data e hora da última posição conhecida, no formato `YYYY-MM-DD HH:MM:SS` (UTC). Presente apenas quando `status` é `ok`.
</ResponseField>

<ResponseField name="latitude" type="number">
  Coordenada de latitude em graus decimais. Presente apenas quando `status` é `ok`.
</ResponseField>

<ResponseField name="longitude" type="number">
  Coordenada de longitude em graus decimais. Presente apenas quando `status` é `ok`.
</ResponseField>

## Códigos de Status

Todo objeto de resultado inclui um campo `status` que descreve o resultado da consulta para aquele veículo específico:

| Status           | Significado                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| `ok`             | Posição encontrada. `timestamp`, `latitude` e `longitude` estão presentes.  |
| `nao_encontrado` | Veículo não encontrado. Nenhum campo de posição é incluído neste resultado. |

Observe que `status` é um campo **por veículo**. Uma única resposta pode conter uma mistura de resultados `ok` e `nao_encontrado`, por exemplo, se apenas alguns dos números de chassi consultados estiverem registrados na iGps.

## Exemplo de Resposta

O exemplo a seguir mostra uma resposta para uma consulta de dois veículos, onde um foi encontrado e o outro não:

```json theme={null}
{
  "resultados": [
    {
      "chassi": "VIN00000000000001",
      "timestamp": "2026-02-11 13:26:03",
      "latitude": -17.797548,
      "longitude": -50.914048,
      "status": "ok"
    },
    {
      "chassi": "VIN00000000000002",
      "status": "nao_encontrado"
    }
  ]
}
```

<Tip>
  Sempre verifique o campo `status` antes de ler `latitude` e `longitude` para evitar erros de referência nula em sua aplicação.
</Tip>