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

# iGps API Concepts: Authentication, Tokens, and Positions

> Learn the core iGps concepts — credentials, Bearer tokens, chassis numbers, and the end-to-end flow for querying real-time vehicle positions.

Antes de integrar a iGps, é útil entender os conceitos-chave que fundamentam a API: como a autenticação funciona, como os veículos são identificados e como os dados de posição são estruturados.

## Conceitos Principais

<CardGroup cols={2}>
  <Card title="Credenciais" icon="id-badge" href="/authentication">
    Seu `client_id` e `client_secret` identificam sua aplicação e são necessários para obter um token de acesso.
  </Card>

  <Card title="Tokens de Acesso" icon="key" href="/authentication">
    Tokens Bearer de curta duração autorizam as requisições à API. Os tokens são obtidos através do endpoint de autenticação e devem ser incluídos em toda requisição.
  </Card>

  <Card title="Número do Chassi (VIN)" icon="car" href="/concepts/vehicle-positions">
    O identificador de 17 caracteres usado para consultar veículos. Cada consulta de posição é resolvida com base em um ou mais números de chassi.
  </Card>

  <Card title="Dados de Posição" icon="location-dot" href="/concepts/vehicle-positions">
    Latitude, longitude e timestamp de cada veículo, representando o registro GPS mais recente reportado pelo dispositivo de rastreamento do veículo.
  </Card>
</CardGroup>

## Fluxo da Requisição

<Steps>
  <Step title="Autentique-se">
    Sua aplicação envia seu `client_id` e `client_secret` para `POST /api/v1/auth/token` para comprovar sua identidade.
  </Step>

  <Step title="Receba um Token Bearer">
    A iGps valida suas credenciais e retorna um token Bearer válido por 1 hora. Armazene esse token para uso em requisições subsequentes.
  </Step>

  <Step title="Consulte Posições de Veículos">
    Sua aplicação envia uma lista de números de chassi (VINs) para `POST /api/v1/veiculos/posicoes`, incluindo o token Bearer no cabeçalho `Authorization`.
  </Step>

  <Step title="Receba os Dados de Posição">
    A iGps retorna a posição GPS mais recente conhecida de cada veículo no array `resultados`, junto com um código de status por veículo.
  </Step>
</Steps>

## Versionamento

A API iGps é versionada através do caminho da URL (por exemplo, `/api/v1/`). A versão estável atual é a **v1**. Mudanças incompatíveis, como remoção de campos ou alteração de formatos de requisição, são sempre introduzidas em uma nova versão da URL, de modo que sua integração existente não será afetada por mudanças futuras.

<Info>
  A iGps retorna a posição mais recente conhecida de cada veículo. A atualização da posição depende do intervalo de reporte do dispositivo de rastreamento do veículo.
</Info>