Autenticação da API iGps

A API iGps utiliza autenticação por token Bearer. Antes de consumir os endpoints disponíveis, sua aplicação deve utilizar o client_id e o client_secret fornecidos pela iGps para obter um token de acesso. Esse token deve ser enviado no cabeçalho Authorization das requisições realizadas aos recursos disponíveis para sua integração. O mesmo processo de autenticação é utilizado para acessar os diferentes recursos da API, incluindo clientes, veículos, dispositivos, vínculos de rastreadores, posições, comandos, cadastros, integrações administrativas, financeiras e demais funcionalidades autorizadas.

Obtenha Suas Credenciais

As credenciais são fornecidas pela iGps individualmente para cada integração.

client_id: identifica sua aplicação ou integração.
client_secret: credencial utilizada para autenticar sua aplicação.

Entre em contato com a iGps para solicitar seu client_id e client_secret.

O client_secret é uma credencial confidencial. Não o exponha em aplicações frontend, aplicativos distribuídos aos usuários, repositórios públicos ou código-fonte compartilhado.

Solicite um Token de Acesso

Envie uma requisição POST para /api/v1/auth/token informando suas credenciais no corpo da requisição em formato JSON.

curl -X POST https://api.dnsx.com.br/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

import requests

response = requests.post(
    "https://api.dnsx.com.br/api/v1/auth/token",
    json={
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
    }
)

response.raise_for_status()

token_data = response.json()
access_token = token_data["access_token"]

Uma autenticação bem-sucedida retorna o token de acesso e seu tempo de validade:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

Campo	Descrição
`access_token`	Token utilizado para autenticar as requisições à API
`token_type`	Tipo do token retornado. Utilize `Bearer` no cabeçalho `Authorization`
`expires_in`	Tempo de validade do token, em segundos

Utilize o Token nas Requisições

Após obter o token, inclua-o no cabeçalho Authorization das requisições:

Authorization: Bearer YOUR_ACCESS_TOKEN

Todas as chamadas para endpoints protegidos devem seguir esse padrão. Como exemplo, abaixo está uma consulta autenticada ao endpoint de posições:

curl -X POST https://api.dnsx.com.br/api/v1/veiculos/posicoes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "chassis": [
      "VIN00000000000001"
    ]
  }'

O endpoint de posições acima é apenas um exemplo de requisição autenticada. O mesmo padrão de autenticação deve ser utilizado nos demais endpoints disponíveis para sua integração.

Autenticação dos Demais Recursos

Depois de autenticada, sua aplicação pode utilizar o token para acessar os recursos liberados para sua integração. Dependendo das permissões disponibilizadas pela iGps, a API pode ser utilizada para operações como:

cadastro e consulta de clientes;
cadastro e consulta de veículos;
cadastro e consulta de dispositivos;
vínculo de rastreadores com veículos;
associação de dispositivos a placas;
consulta de marcas de veículos;
consulta de modelos de veículos;
consulta de posições e coordenadas;
consulta de informações de rastreamento;
envio de comandos aos dispositivos;
consulta de informações relacionadas aos comandos enviados;
recebimento de retornos por callbacks e webhooks;
integração com sistemas administrativos;
integração com sistemas financeiros;
integração com sistemas de cobrança;
integração com ERPs;
integração com plataformas proprietárias;
integração com gerenciadoras de risco;
integração com sistemas de parceiros.

A autenticação permanece a mesma independentemente do recurso utilizado.

Validade do Token

O token possui validade de 3600 segundos (1 hora) a partir do momento de sua emissão. Enquanto o token permanecer válido, ele pode ser reutilizado nas chamadas realizadas pela sua aplicação. Não é necessário solicitar um novo token antes de cada requisição. Quando o token expirar, sua aplicação deverá solicitar um novo token utilizando novamente o client_id e o client_secret.

Renovação Automática

Recomendamos que sua integração controle o tempo de validade do token e solicite um novo token automaticamente antes de sua expiração. Essa abordagem evita interrupções nas chamadas realizadas pela aplicação. O exemplo abaixo demonstra uma implementação em Python que reutiliza o token atual e solicita um novo token quando ele estiver próximo de expirar:

import time
import requests


class IgpsClient:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._token_expiry = 0

    def get_token(self):
        if self._token and time.time() < self._token_expiry - 60:
            return self._token

        response = requests.post(
            "https://api.dnsx.com.br/api/v1/auth/token",
            json={
                "client_id": self.client_id,
                "client_secret": self.client_secret
            }
        )

        response.raise_for_status()

        data = response.json()

        self._token = data["access_token"]
        self._token_expiry = time.time() + data["expires_in"]

        return self._token

Nesse exemplo, o token atual é reutilizado enquanto permanecer válido. Quando restarem menos de 60 segundos para sua expiração, um novo token será solicitado automaticamente.

Exemplo de Requisição Autenticada em Python

Depois de obter o token, ele pode ser reutilizado nas chamadas subsequentes:

import requests


client = IgpsClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

token = client.get_token()

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.dnsx.com.br/api/v1/veiculos/posicoes",
    headers=headers,
    json={
        "chassis": [
            "VIN00000000000001"
        ]
    }
)

response.raise_for_status()

data = response.json()

print(data)

Tratamento de Token Expirado

Caso uma requisição seja realizada utilizando um token expirado ou inválido, a API poderá retornar:

401 Unauthorized

Ao receber uma resposta indicando falha de autenticação, sua aplicação deve solicitar um novo token utilizando o client_id e o client_secret. Depois de obter o novo token, a aplicação poderá repetir a requisição. Evite criar ciclos de repetição ilimitados. Caso a obtenção de um novo token também falhe, trate o erro adequadamente e registre a ocorrência para análise.

Erros de Autenticação

Status HTTP	Significado	Ação recomendada
`400 Bad Request`	A requisição possui campos ausentes ou inválidos	Verifique o JSON enviado e confirme se `client_id` e `client_secret` foram informados corretamente
`401 Unauthorized`	As credenciais ou o token informado não são válidos	Verifique as credenciais ou solicite um novo token
`429 Too Many Requests`	O limite de requisições foi excedido	Aguarde antes de realizar novas tentativas e respeite os limites definidos para a API
`500 Internal Server Error`	Ocorreu um erro inesperado no servidor	Tente novamente após um intervalo. Se o problema persistir, entre em contato com a iGps

Boas Práticas de Segurança

Armazene o client_id e o client_secret de forma segura.
Utilize variáveis de ambiente ou um gerenciador de segredos para armazenar credenciais.
Nunca exponha o client_secret em aplicações executadas diretamente no navegador.
Não inclua credenciais em aplicativos distribuídos aos usuários.
Não envie credenciais para repositórios públicos.
Não registre credenciais ou tokens completos em logs.
Reutilize o token enquanto ele permanecer válido.
Renove o token automaticamente quando necessário.
Utilize sempre HTTPS para comunicação com a API.
Mantenha credenciais de produção separadas das utilizadas em desenvolvimento e homologação.
Substitua as credenciais caso exista suspeita de comprometimento.

Integração sem SDK

A API iGps utiliza padrões amplamente adotados para integração:

requisições HTTP;
arquitetura REST;
payloads em JSON;
autenticação Bearer;
códigos de status HTTP.

Por isso, nenhum SDK proprietário da iGps é necessário. Sua integração pode ser desenvolvida utilizando qualquer linguagem de programação ou tecnologia capaz de realizar requisições HTTP, como Python, PHP, JavaScript, Node.js, Java, C#, Go, Ruby, entre outras.

Depois de implementar a autenticação, o mesmo token Bearer pode ser utilizado para consumir os endpoints autorizados para sua integração enquanto permanecer válido.

Introdução

Conceitos Principais

Guias

Autenticação da API iGps

Obtenha Suas Credenciais

Solicite um Token de Acesso

Utilize o Token nas Requisições

Autenticação dos Demais Recursos

Validade do Token

Renovação Automática

Exemplo de Requisição Autenticada em Python

Tratamento de Token Expirado

Erros de Autenticação

Boas Práticas de Segurança

Integração sem SDK

​Obtenha Suas Credenciais

​Solicite um Token de Acesso

​Utilize o Token nas Requisições

​Autenticação dos Demais Recursos

​Validade do Token

​Renovação Automática

​Exemplo de Requisição Autenticada em Python

​Tratamento de Token Expirado

​Erros de Autenticação

​Boas Práticas de Segurança

​Integração sem SDK

Obtenha Suas Credenciais

Solicite um Token de Acesso

Utilize o Token nas Requisições

Autenticação dos Demais Recursos

Validade do Token

Renovação Automática

Exemplo de Requisição Autenticada em Python

Tratamento de Token Expirado

Erros de Autenticação

Boas Práticas de Segurança

Integração sem SDK