> ## 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.

# POST /api/v1/veiculos/posicoes — Query Vehicle Positions

> Retrieve the latest GPS position for up to 50 vehicles by chassis number. Returns coordinates, timestamp, and a status for each vehicle.

Use este endpoint para obter a posição GPS mais recente conhecida de um ou mais veículos identificados pelo número do chassi (VIN) de 17 caracteres. Você pode consultar até 50 veículos por requisição.

## Endpoint

```text theme={null}
POST https://api.igps.com.br/api/v1/veiculos/posicoes
```

## Autenticação

<Note>
  Este endpoint requer um token Bearer válido no cabeçalho `Authorization`. Consulte [Autenticação](/authentication) para obter um token.
</Note>

## Cabeçalhos da Requisição

<ParamField header="Content-Type" type="string" required>
  Deve ser `application/json`.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Token Bearer obtido em `POST /api/v1/auth/token`. Formato: `Bearer YOUR_ACCESS_TOKEN`.
</ParamField>

## Corpo da Requisição

<ParamField body="chassis" type="string[]" required>
  Um array de números de chassi (VIN) de 17 caracteres a serem consultados. Mínimo 1, máximo 50 por requisição.
</ParamField>

```json theme={null}
{
  "chassis": [
    "VIN00000000000001",
    "VIN00000000000002"
  ]
}
```

## Exemplo de Requisição

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.igps.com.br/api/v1/veiculos/posicoes \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -d '{
      "chassis": [
        "VIN00000000000001",
        "VIN00000000000002"
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.igps.com.br/api/v1/veiculos/posicoes",
      headers={
          "Content-Type": "application/json",
          "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      },
      json={
          "chassis": ["VIN00000000000001", "VIN00000000000002"]
      }
  )
  data = response.json()
  ```
</CodeGroup>

## Resposta (200 OK)

<ResponseField name="resultados" type="object[]" required>
  Array de resultados de posição, uma entrada por número de chassi consultado.

  <Expandable title="item de resultados">
    <ResponseField name="chassi" type="string" required>
      O número do chassi (VIN) de 17 caracteres que foi consultado.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status do resultado. `ok` se os dados de posição estiverem disponíveis; `nao_encontrado` se o veículo não foi encontrado.
    </ResponseField>

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

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

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

```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"
    }
  ]
}
```

## Respostas de Erro

| Código HTTP               | Causa                                                                                                      | Resolução                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 400 Bad Request           | Corpo da requisição inválido (ausência de `chassis`, tamanho incorreto do array, VIN com tamanho inválido) | Verifique o formato do corpo da requisição                   |
| 401 Unauthorized          | Token de acesso ausente ou expirado                                                                        | Autentique-se novamente usando `POST /api/v1/auth/token`     |
| 429 Too Many Requests     | Limite de requisições excedido                                                                             | Reduza a frequência das requisições; use backoff exponencial |
| 500 Internal Server Error | Erro inesperado do servidor                                                                                | Tente novamente após um curto intervalo                      |

<Tip>
  Verifique o campo `status` de cada resultado. Uma resposta `200 OK` pode incluir veículos com `status: nao_encontrado`. Sempre valide cada item individualmente.
</Tip>