Documentação em linguagem simples

O que acontece quando você pede um frete

Nive Frete é uma API: você manda um endereço de origem, um de destino e o preço por km, ela devolve a distância e o valor do frete. Ela não guarda pedidos nem clientes — só faz essa conta, usando mapas por trás dos panos para transformar endereço em coordenada.

Como funciona um cálculo de frete

Do momento em que você envia a requisição até a resposta chegar, o sistema segue sempre esses seis passos, nessa ordem.

  1. 1

    Você envia os dois endereços

    Rua, número, bairro, cidade e UF da origem e do destino, mais o preço por km e as regras de cobrança (taxa fixa, frete mínimo, etc).

  2. 2

    O sistema confere os dados

    Campo obrigatório faltando ou número inválido? A requisição para aqui e volta com a lista completa do que precisa corrigir.

  3. 3

    Cada endereço vira um ponto no mapa

    Essa é a parte mais trabalhosa. Se você já mandou latitude/longitude, o sistema usa direto. Senão, primeiro tenta corrigir pequenos erros de digitação no nome da rua, depois olha se já converteu esse endereço antes (para não repetir trabalho), e só então pergunta a um serviço de mapas onde fica aquele endereço — tentando pelo número exato, depois só pela rua, depois só pelo bairro, até achar algo.

  4. 4

    Mede a distância e ajusta pra rota real

    Calcula a distância em linha reta entre os dois pontos e multiplica por um fator de correção, já que na vida real ninguém anda em linha reta.

  5. 5

    Calcula o valor do frete

    Distância × preço por km, mais a taxa fixa — respeitando um piso (frete mínimo), um teto (frete máximo) e um raio máximo de entrega, se você configurou algum.

  6. 6

    Devolve a resposta

    Valor, distância e como cada endereço foi localizado — numero, rua ou bairro — para você decidir se vale confirmar num mapa antes de seguir.

Os três jeitos de falar com a API

Um endpoint faz a conta, um verifica se está tudo de pé, e um ajuda a digitar o endereço certo.

POST /api/v1/frete/calcular

O endpoint principal — é o fluxo de seis passos acima. Recebe os dois endereços e devolve o valor do frete.

GET /api/v1/rua/sugestoes

Autocomplete de rua para formulário: a cada letra digitada, devolve nomes de rua parecidos, consultando só a base local — sem depender do serviço de mapas externo.

GET /api/v1/health

Sem autenticação. Confere se o banco de dados está respondendo — para monitoramento.

Precisa dos campos exatos de cada requisição e resposta? Veja a referência completa, com exemplos →

Quando algo sai diferente do esperado

O endpoint de cálculo pode responder de sete formas. Seis delas não são bugs — são o sistema te dizendo exatamente o que fazer a seguir.

200 Calculado Frete calculado com sucesso (inclusive quando o destino fica fora do raio de entrega — a resposta só vem sem valor).
400 Dados inválidos Faltou campo obrigatório ou algum valor não faz sentido. A resposta lista todos os problemas de uma vez.
401 Sem autorização Chave de API ausente ou incorreta.
422 Rua ambígua O nome digitado é parecido com mais de uma rua conhecida. A resposta traz sugestões — reenvie com a escolhida.
422 Não localizado Esse endereço específico não foi encontrado. Reenvie com latitude/longitude para seguir mesmo assim.
429 Muitas requisições Passou do limite por minuto para sua chave. Aguarde um pouco e tente de novo.
503 Indisponível O serviço de mapas externo está fora do ar no momento — diferente de "endereço não existe". Tente novamente em instantes.

O que roda por trás dos panos

Nada disso muda como você usa a API — mas explica por que ela fica mais rápida com o tempo.

Memória de endereços

Todo endereço já localizado fica guardado. Perguntar de novo pelo mesmo lugar é instantâneo, sem depender de serviço externo.

cache · 180 dias

Mapa externo

Quando não há nada em memória, a API pergunta a um serviço aberto de mapas (OpenStreetMap) onde fica aquele endereço.

Nominatim

Dicionário de ruas por cidade

Cada cidade tem sua própria lista de nomes de rua reais, usada para corrigir erros de digitação antes de perguntar ao mapa.

Overpass API

Atualização automática

Na primeira vez que uma cidade nova aparece, sua lista de ruas é baixada em segundo plano — sem atrasar sua resposta — e revisada todo dia de madrugada.

tarefa diária · 03h
Por que isso importa: na primeira consulta de uma cidade nova, a correção de nome de rua e o autocomplete podem vir vazios — a base ainda está sendo montada. Na próxima consulta, minutos depois, já vem completa.

Autenticação e limites

Toda chamada (menos o /health) exige uma chave enviada no cabeçalho Authorization: Bearer <chave>. Cada chave tem um limite de requisições por minuto — passou disso, a API responde 429 até a janela seguinte abrir.