> ## 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 Quickstart: Make Your First API Call in Minutes

> Follow this step-by-step guide to authenticate with the iGps API and retrieve your first real-time GPS vehicle position by chassis number.

Esta página guia você na realização da sua primeira chamada à API iGps, desde a obtenção de um token de acesso até a consulta da posição GPS de um veículo. Ao final, você terá uma requisição funcional que pode adaptar para sua própria integração.

<Steps>
  <Step title="Obtenha um Token de Acesso">
    Antes de chamar qualquer endpoint da iGps, troque seu `client_id` e `client_secret` por um token de acesso Bearer enviando uma requisição `POST` para `/api/v1/auth/token`.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.igps.com.br/api/v1/auth/token \
        -H "Content-Type: application/json" \
        -d '{"client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET"}'
      ```

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

      response = requests.post(
          "https://api.igps.com.br/api/v1/auth/token",
          json={"client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET"}
      )
      token_data = response.json()
      access_token = token_data["access_token"]
      ```
    </CodeGroup>

    Uma resposta bem-sucedida retorna um token e seu tempo de expiração:

    ```json theme={null}
    {
      "access_token": "YOUR_ACCESS_TOKEN",
      "token_type": "Bearer",
      "expires_in": 3600
    }
    ```

    Copie o valor de `access_token`. Você o utilizará na próxima etapa.
  </Step>

  <Step title="Consulte Posições de Veículos">
    Com seu token em mãos, envie uma requisição `POST` para `/api/v1/veiculos/posicoes` com uma lista de números de chassi no corpo da requisição. Você pode incluir até 50 números de chassi por 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}
      response = requests.post(
          "https://api.igps.com.br/api/v1/veiculos/posicoes",
          headers={"Authorization": f"Bearer {access_token}"},
          json={"chassis": ["VIN00000000000001", "VIN00000000000002"]}
      )
      positions = response.json()
      ```
    </CodeGroup>

    A API retorna a posição mais recente registrada para cada veículo:

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

  <Step title="Trate a Resposta">
    Cada entrada em `resultados` inclui um campo `status`:

    * **`ok`**: O veículo foi encontrado e os dados de posição estão disponíveis. Espere os campos `latitude`, `longitude` e `timestamp`.
    * **`nao_encontrado`**: O veículo não foi encontrado para o número de chassi fornecido. Nenhum dado de posição é retornado.

    Use o campo `status` para processar os resultados com segurança em sua aplicação:

    ```python theme={null}
    for vehicle in positions["resultados"]:
        if vehicle["status"] == "ok":
            print(f"{vehicle['chassi']}: ({vehicle['latitude']}, {vehicle['longitude']})")
        else:
            print(f"{vehicle['chassi']}: nao encontrado")
    ```
  </Step>
</Steps>

<Note>
  Substitua `YOUR_CLIENT_ID`, `YOUR_CLIENT_SECRET` e os números de chassi pelos seus valores reais.
</Note>