Error Codes

System-wide error codes returned by the Open API inside the code parameter.

Troubleshooting (Solução de Problemas)

Abaixo estão descritos os problemas mais comuns enfrentados durante a integração com a API BrasilSat e como corrigi-los:

1. Erro de Assinatura Inválida ou Login Incorreto (20001 ou 10007)

Este erro geralmente ocorre por diferenças no cálculo da assinatura criptográfica (signature):

• Letras Minúsculas (Lower-case): Ambos os hashes MD5 intermediário e final devem ser gerados em letras minúsculas. Algumas ferramentas ou linguagens geram caracteres em maiúsculas por padrão. Garanta a conversão para minúsculas usando funções como .toLowerCase() no JavaScript ou .lower() no Python.
• Quebras de Linha (Newlines): Ao gerar hashes usando utilitários em linha de comando (como echo), certifique-se de usar a flag -n (ex: echo -n "$PASSWORD") para evitar que uma quebra de linha \n seja adicionada no final da string antes de calcular o MD5.

2. Erro de Horário da Requisição (10014 - Request time error)

O servidor da API rejeita requisições onde o parâmetro time está dessincronizado com o relógio do servidor:

• Formato UNIX: Garanta que o timestamp enviado esteja no formato UNIX em segundos (10 dígitos), e não em milissegundos (13 dígitos).
• Fuso Horário: O timestamp UNIX é baseado em UTC/GMT. Certifique-se de que o relógio do servidor de sua aplicação esteja sincronizado via NTP.

3. Invalidação Prematura do Token (10010, 10011, 10012)

O access_token é válido por 2 horas, mas qualquer nova requisição de obtenção de token invalida o anterior imediatamente.

• Prática Incorreta: Solicitar um novo token a cada requisição de endpoint. Se houver concorrência (múltiplas requisições paralelas), elas irão falhar pois o token antigo será invalidado enquanto outra chamada está em curso.
• Prática Recomendada: Guarde o token em cache (em memória ou no banco de dados) e reutilize-o. Faça uma nova chamada para /api/authorization apenas a cada 90 minutos para atualizá-lo.

4. Erros de Parâmetro e Codificação (10004 ou 10005)

Ao enviar parâmetros complexos:

• Múltiplos IMEIs: Ao passar múltiplos IMEIs na URL, separe-os estritamente por vírgula , sem adicionar espaços em branco (ex: imeis=3588...,3551... e não imeis=3588..., 3551...).
• URL Encoding: Parâmetros passados via Query String que contêm caracteres especiais (como senhas com símbolos ou parâmetros de comandos em JSON como {"mileage":"30"}) devem ser devidamente encodados para URL (URL encoded).