N-WaysReferência da API
Cada endpoint da N-Ways Maps Platform, os seus parâmetros, a sua resposta e os seus erros, gerados a partir dos nossos ficheiros OpenAPI.
Nesta página
N-Ways Maps Platform — Maps, Places and Routes API
A superfície estável para parceiros da N-Ways Maps Platform (/maps/v1). É a fonte de verdade da documentação para programadores e das bibliotecas cliente; os testes de contrato com ficheiros de referência do servidor (backend/internal/partnerapi/testdata/golden) fixam cada resposta aqui descrita.
Autenticação. Cada chamada precisa de uma chave de API de parceiro: X-NWays-Api-Key: nw_… (servidores, aplicações) ou ?key=nw_… (navegadores, estilos de mapa). As restrições de API de uma chave indicam produtos; a sua restrição de aplicação (sites, bundle ids iOS, pacote Android + SHA-1, endereços IP de servidores) diz onde pode ser usada. As aplicações enviam X-Ios-Bundle-Identifier, ou X-Android-Package e X-Android-Cert. As chaves só funcionam enquanto a N-Ways tiver a plataforma ativada: enquanto está desativada, cada chamada responde 503 PLATFORM_DISABLED (com Retry-After; a sua chave está em ordem), e quando a N-Ways a reserva às organizações convidadas, a chave de qualquer outra organização responde 403 PLATFORM_PREVIEW_ONLY.
Produtos e faturação (SKU). tiles (mosaicos de mapa; SKU tiles por mosaico e map_loads por leitura de estilo), static_maps, geocode (geocodificação, inversa, códigos postais, GhanaPost, Plus Codes; um lote conta cada código), autocomplete (faturado por sessão), address_validation, search (locais; SKU search básico, places_contact, places_atmosphere consoante os campos pedidos), routing (SKU routing, e routing_advanced para percursos com trânsito, okada/keke/danfo/motorbike/van/boat/train, mais de 10 pontos intermédios ou tarifas), route_matrix (faturado por elemento), route_optimization, fares, traffic. Os tipos de letra são gratuitos com qualquer chave Maps.
Convenções. As coordenadas entram como {"lat": 6.45, "lng": 3.39} (ou lat,lng numa query) e saem como GeoJSON [lng, lat]. Distâncias em metros, durações em segundos, valores na unidade principal da moeda. lang=en|fr|pt (pt é português europeu). fields= (uma lista separada por vírgulas; a.b entra em objetos) mantém apenas esses campos de cada resultado e, para locais, define o SKU. Na v1 só se acrescentam campos; as alterações incompatíveis chegam como /maps/v2, com 12 meses de sobreposição.
Erros. Um único envelope para erros de chave, de quota e de produto: {"error": {"code": 400, "status": "INVALID_ARGUMENT", "reason": "LAT_LNG_REQUIRED", "message": "…", "details": […]}}. reason é estável (baseie-se nele); message diz exatamente o que aconteceu e como corrigir; details contém o ErrorInfo da Google (o motivo, domain: nways.ng e metadata com os factos: docs e, consoante o motivo, o que foi visto e o que é permitido, que limite e quando é reposto) e uma ligação Help para a entrada do motivo em https://nways.ng/developers/errors. As recusas trazem cabeçalhos CORS para a página que chama, para que o código no navegador as possa ler. Motivos de chave, de plataforma e de quota, pela ordem em que são verificados: PLATFORM_DISABLED (503), API_KEY_MISSING, API_KEY_INVALID (uma chave que a N-Ways nunca emitiu), API_KEY_REVOKED (eliminada, ou o valor antigo de uma chave regenerada) (401); PLATFORM_PREVIEW_ONLY, ORGANISATION_CLOSED, ORGANISATION_SUSPENDED, API_ACCESS_OFF (a organização gere as suas entregas no N-Ways sem a API), API_TURNED_OFF (a N-Ways desligou a API da organização; a mensagem indica o motivo), PROJECT_SUSPENDED, API_KEY_PAUSED, API_KEY_SERVICE_BLOCKED, API_KEY_HTTP_REFERRER_BLOCKED, API_KEY_IP_ADDRESS_BLOCKED, API_KEY_IOS_APP_BLOCKED, API_KEY_ANDROID_APP_BLOCKED (403); RATE_LIMIT_EXCEEDED, QUOTA_EXCEEDED, TEMPORARILY_BLOCKED (429); BILLING_DISABLED (402: a quota mensal gratuita esgotou-se e não resta crédito: adicione crédito na consola, Faturação); BACKEND_ERROR (503). Os motivos de produto estão listados em cada operação. Qualquer operação pode também responder NOT_FOUND (um caminho desconhecido), INVALID_JSON e BODY_TOO_LARGE (um corpo de pedido), INTERNAL (500: envie o X-Request-Id) e, onde se calculam percursos, ROUTING_UNAVAILABLE (503, com Retry-After). As viagens de okada, motorbike, keke e danfo que a lei proíbe respondem 422 com OKADA_BANNED_ORIGIN, OKADA_BANNED_DESTINATION, OKADA_BANNED_STOP, OKADA_BANNED_ROUTE; MOTORBIKE_BANNED_ORIGIN, MOTORBIKE_BANNED_DESTINATION, MOTORBIKE_BANNED_STOP, MOTORBIKE_BANNED_ROUTE; KEKE_BANNED_ORIGIN, KEKE_BANNED_DESTINATION, KEKE_BANNED_STOP, KEKE_BANNED_ROUTE; DANFO_BANNED_ORIGIN, DANFO_BANNED_DESTINATION, DANFO_BANNED_STOP, DANFO_BANNED_ROUTE (a proibição vem na mensagem).
Cabeçalhos. Cada resposta traz X-Request-Id (envie-o ao suporte). As chamadas permitidas trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos); um 429 e PLATFORM_DISABLED trazem Retry-After.
Anfitriões. api.nways.ng/maps/v1 para tudo. Os estilos alojados leem os arquivos PMTiles e os tipos de letra a partir da CDN tiles.nways.ng/maps/v1 (/tiles/{tileset}.pmtiles, /tiles/countries.json, /fonts/…, mesmos caminhos): uma cópia pública, sem chave nem contagem; a sua chave é verificada e o carregamento de mapa contado quando o estilo é lido. Os URL .mvt de um só mosaico ficam na API, com chave. Quando o motor de percursos está em baixo, os percursos, as matrizes e as otimizações respondem 503 ROUTING_UNAVAILABLE com Retry-After: envie o mesmo pedido de novo.
Limites de pedidos (valores por omissão por chave e por minuto): tiles 6000, static_maps 600, geocode 600, autocomplete 1200, address_validation 300, search 600, routing 300, route_matrix 3000 elementos, route_optimization 60, fares 120, traffic 60.
Atribuição. As respostas baseadas no OpenStreetMap trazem attribution; mostre "© OpenStreetMap contributors" onde quer que mostre os dados (a ODbL assim o exige). Ver https://nways.ng/developers/terms.
| Endereço base | https://nways.ng/maps/v1 |
| Version | 1.0.0 |
| Ficheiro OpenAPI | partner-v1.openapi.yaml · JSON |
| Endpoints | Descrição |
|---|---|
GET /styles/{style}.json | Um estilo de mapa alojado (um carregamento de mapa) |
GET /tiles/countries.json | Os arquivos de mosaicos de todos os países |
GET /tiles/{tileset}.pmtiles | Ler o arquivo PMTiles de um país (pedidos de intervalo) |
GET /tiles/{tileset}/{z}/{x}/{y}.mvt | Um mosaico vetorial |
GET /fonts/{stack}/{range}.pbf | Glifos de tipos de letra para as legendas do mapa (gratuito) |
GET /staticmap | Uma imagem de mapa |
GET /geocode | Pesquisar locais, endereços e códigos |
GET /reverse | O que está num ponto |
GET /postcodes/{code} | Um código postal NIPOST |
POST /postcodes/batch | Até 100 códigos postais NIPOST de uma vez |
GET /ghanapost/{code} | Um endereço GhanaPost GPS |
GET /pluscodes/{code} | A área de um Plus Code e o que lá está |
GET /autocomplete | Sugestões à medida que se escreve (faturado por sessão) |
POST /addresses/validate | Este endereço existe, onde fica, qual é a forma correta? |
GET /places/nearby | Negócios e locais perto de um ponto |
GET /places/search | Negócios e locais por texto |
GET /places/{id} | Detalhes de um local |
POST /routes/compute | Um percurso, com até 25 pontos intermédios |
POST /routes/matrix | Tempos de viagem de muitas origens para muitos destinos (por elemento) |
POST /routes/optimize | Que veículo visita que paragens, e por que ordem |
GET /fares/estimate | Quanto custa uma viagem |
GET /traffic | Trânsito em direto numa zona |
N-Ways Maps Platform — Fleet and logistics API
O conjunto logístico da N-Ways Maps Platform (produtos de parceiro fleet e traffic_feed). Cada chamada precisa de uma chave de API de parceiro que inclua o produto; as chaves só funcionam enquanto a N-Ways tiver o acesso de parceiro ativado para si.
Autenticação. Envie a chave como X-NWays-Api-Key: nw_… (servidores, aplicações de estafetas) ou ?key=nw_…. As chamadas de frota escrevem os seus próprios dados (veículos, tarefas, webhooks), por isso use uma chave restrita aos endereços IP dos seus servidores ou à sua aplicação de estafetas (pacote Android + SHA-1, bundle id iOS). Navegadores: apenas a página pública de seguimento.
Erros. Os erros de chave e de quota e os erros de produto partilham um único envelope: {"error": {"code": 404, "status": "NOT_FOUND", "reason": "TASK_NOT_FOUND", "message": "…", "details": […]}} (details: o ErrorInfo da Google com os factos em metadata e uma ligação Help para o motivo em https://nways.ng/developers/errors). Motivos de plataforma e de chave: PLATFORM_DISABLED (503, Retry-After: a plataforma está desativada, a sua chave está em ordem), PLATFORM_PREVIEW_ONLY, API_KEY_MISSING, API_KEY_INVALID, API_KEY_REVOKED, ORGANISATION_CLOSED, ORGANISATION_SUSPENDED, API_ACCESS_OFF, API_TURNED_OFF, PROJECT_SUSPENDED, API_KEY_PAUSED, API_KEY_SERVICE_BLOCKED, API_KEY_*_BLOCKED, BILLING_DISABLED, RATE_LIMIT_EXCEEDED, QUOTA_EXCEEDED, TEMPORARILY_BLOCKED, BACKEND_ERROR. BILLING_DISABLED é um 402: a quota mensal gratuita esgotou-se e não resta crédito (adicione crédito na consola, Faturação).
Funcionalidades que a N-Ways desativou. A N-Ways pode desativar uma funcionalidade para uma organização (403, a mensagem diz porquê e a quem contactar; nada mais muda): DELIVERIES_OFF (novas tarefas), CONTRACTORS_OFF (enviar tarefas a motoristas N-Ways, convidá-los ou contratá-los), SMART_PRICE_OFF (sugestões de pagamento e Smart Price: envie você mesmo payMax), WEBHOOKS_OFF (sem envios de webhooks; adicionar ou testar um endpoint é recusado), ERP_OFF (a exportação de eventos), TRACKERS_OFF (adicionar rastreadores, e as suas posições e alarmes; os rastreadores continuam registados). As novas tarefas de uma organização suspensa são recusadas com ORGANISATION_SUSPENDED, tal como as suas chaves; as tarefas em curso continuam.
Limites de pedidos. Valores por omissão por chave e por minuto: fleet 6000, traffic_feed 60. As respostas trazem X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Ids. Os veículos, motoristas e tarefas são identificados pelos seus próprios ids (1–64 caracteres de A–Z a–z 0–9 _ . : -), únicos por projeto. O que a N-Ways cria (webhooks, regras de alerta e alertas, ligações e convites de estafeta, provas, entregas de webhook) tem um id opaco em texto: um prefixo, _ e 10 letras ou algarismos (wh_Ub3yH9sLk2, rule_…, alr_…, lnk_…, rin_…, prf_…, dlv_…). Trate os ids como texto e nunca os analise. As formas numeradas antigas (wh_12, rule_7, inv_3…) continuam a ser aceites nos caminhos até 1 de abril de 2027. As horas estão em RFC 3339, em UTC.
Condições dos dados. As posições que envia são guardadas como histórico de viagens durante retentionDays (30 por omissão, 1–90) e depois apagadas. Os valores de ETA e de trânsito servem apenas a viagem: são apagados quando uma tarefa termina. As suas posições só alimentam o trânsito em direto público da N-Ways se der o seu consentimento (shareTraffic, desativado por omissão); nesse caso são usadas de forma anónima, como as de qualquer telemóvel (uma sessão por veículo e por dia, nunca os seus ids). O fluxo de trânsito é agregado a partir de muitos dispositivos e nunca contém um trajeto individual.
| Endereço base | https://nways.ng/maps/v1/fleet |
| Version | 1.0.0 |
| Ficheiro OpenAPI | partner-fleet.openapi.yaml · JSON |
| Endpoints | Descrição |
|---|---|
GET /settings | Obter as definições de frota do projeto |
PUT /settings | Alterar as definições de frota (os campos omitidos mantêm o seu valor) |
GET /drivers | Listar motoristas |
POST /drivers | Adicionar um motorista |
GET /drivers/{id} | Obter um motorista |
PATCH /drivers/{id} | Alterar um motorista |
DELETE /drivers/{id} | Eliminar um motorista (os veículos continuam a circular sem ele) |
GET /vehicles | Listar veículos com as suas últimas posições conhecidas |
POST /vehicles | Adicionar um veículo |
GET /vehicles/{id} | Obter um veículo e a sua última posição conhecida |
PATCH /vehicles/{id} | Alterar um veículo (driverId "" retira o motorista) |
DELETE /vehicles/{id} | Eliminar um veículo e o seu histórico de viagens |
GET /vehicles/{id}/history | Histórico de viagens de um veículo (do mais antigo para o mais recente) |
GET /vehicles/{id}/events | A cronologia de um veículo a partir do seu rastreador (ignição ligada e desligada, corte de alimentação e reposição), da mais recente para a mais antiga |
POST /locations | Enviar posições (em lote) |
GET /tasks/{id}/proofs | A prova de entrega da tarefa (fotografias, assinaturas) e a nota do estafeta |
GET /proofs/{proofId} | A imagem de uma prova (JPEG, PNG ou WebP), guardada enquanto a sua tarefa for guardada |
GET /tasks | Listar tarefas, das mais recentes para as mais antigas |
POST /tasks | Criar uma entrega |
GET /tasks/{id} | Obter uma tarefa com a sua ETA em direto |
PATCH /tasks/{id} | Editar uma entrega |
POST /tasks/{id}/assign | Atribuir (ou reatribuir) um veículo — created|assigned → assigned; evento task.assigned |
POST /tasks/{id}/pickup | Marcar como recolhida — assigned → picked_up |
POST /tasks/{id}/complete | Marcar como entregue — assigned|picked_up|arriving → completed; evento task.completed |
POST /tasks/{id}/fail | Marcar como falhada — qualquer estado em aberto → failed; evento task.failed |
POST /tasks/{id}/cancel | Cancelar — qualquer estado em aberto → cancelled |
POST /tasks/{id}/pin-email | Enviar o PIN de entrega do cliente para o seu e-mail |
GET /whatsapp/number | Se um PIN de entrega pode ir para um número no WhatsApp |
POST /tasks/{id}/area | Definir ou limpar a área própria de uma entrega |
GET /places | Listar os seus locais de recolha (o predefinido primeiro) |
POST /places | Adicionar um local de recolha (até 200) |
GET /places/{placeId} | Obter um local de recolha |
PATCH /places/{placeId} | Editar um local de recolha |
DELETE /places/{placeId} | Eliminar um local de recolha |
GET /customers | Listar os seus clientes, da entrega mais recente para a mais antiga |
GET /customers/{customerId} | Obter um cliente |
DELETE /customers/{customerId} | Esquecer um cliente e os seus endereços |
GET /customers/{customerId}/addresses | Listar os endereços de um cliente, do último usado para o mais antigo |
POST /tasks/{id}/share | A ligação de seguimento do destinatário (uma nova se tiver expirado; nenhuma depois de a tarefa terminar) |
GET /webhooks | Listar endpoints de webhook |
POST /webhooks | Adicionar um endpoint (até 10); a resposta traz o seu segredo de assinatura, mostrado uma única vez |
PATCH /webhooks/{id} | Alterar o url, os eventos ou o active de um endpoint |
DELETE /webhooks/{id} | Eliminar um endpoint e o seu registo de entregas |
POST /webhooks/{id}/rotate-secret | Um novo segredo de assinatura (mostrado uma única vez); o antigo deixa de funcionar de imediato |
POST /webhooks/{id}/test | Pôr em fila um evento ping para o endpoint |
GET /webhooks/{id}/deliveries | O registo de entregas do endpoint, das mais recentes para as mais antigas (guardado 30 dias) |
POST /webhooks/{id}/deliveries/{deliveryId}/retry | Enviar de novo uma entrega agora (falhada, ou entregue e pretendida outra vez); as suas tentativas são mantidas |
GET /alert-rules | Listar regras de alerta |
POST /alert-rules | Adicionar uma regra de alerta (até 100) |
GET /alert-rules/{ruleId} | Obter uma regra |
PATCH /alert-rules/{ruleId} | Alterar uma regra (o tipo mantém-se); active false suspende-a e resolve os seus alertas abertos |
DELETE /alert-rules/{ruleId} | Eliminar uma regra (os seus alertas abertos são resolvidos) |
GET /alert-events | Alertas gerados, dos mais recentes para os mais antigos |
GET /alert-events/{alertId} | Obter um alerta |
POST /alert-events/{alertId}/acknowledge | Confirmar um alerta aberto (sem mais lembretes; mantém-se até se resolver por si ou ser resolvido) |
POST /alert-events/{alertId}/resolve | Resolver um alerta (envia asset.alert_resolved) |
GET /events/export | Descarregar todos os eventos (CSV para Excel ou Google Sheets, ou JSON) |
GET /traffic-feed | Velocidades das estradas numa caixa (produto traffic_feed; empresarial) |
GET /offline/regions | Regiões para as quais existem pacotes offline |
GET /offline/packs/{region} | O manifesto do pacote de uma região (202 enquanto está a ser criado; volte a pedir depois de Retry-After) |
GET /offline/packs/{region}/{file} | Descarregar um ficheiro do pacote (pedidos Range suportados; ETag = o seu hash) |
GET /trackers | Listar os seus rastreadores, com contagens por estado |
POST /trackers | Adicionar um rastreador pelo seu IMEI (o primeiro a reclamar fica com ele) |
GET /trackers/catalog | O catálogo de dispositivos, as redes SIM do seu país e os respetivos APN, e para onde os dispositivos comunicam |
POST /trackers/import | Adicionar muitos rastreadores a partir de um CSV (verifique-o primeiro com dryRun) |
GET /trackers/setup.csv | A folha dos instaladores, os SMS de configuração de cada rastreador por ordem (CSV) |
GET /trackers/forwarding | O reencaminhamento a partir da sua plataforma de seguimento, os seus endereços e as unidades que envia |
POST /trackers/forwarding | Ativar o reencaminhamento, ou dar-lhe um novo token (o antigo deixa de funcionar de imediato) |
DELETE /trackers/forwarding | Desativar o reencaminhamento (as unidades continuam listadas) |
POST /trackers/forwarding/units/{unitId}/add | Adicionar uma unidade reencaminhada como um dos seus rastreadores (um veículo novo com o nome dela, a menos que indique um) |
DELETE /trackers/forwarding/units/{unitId} | Esquecer uma unidade reencaminhada (volta se a sua plataforma a enviar de novo) |
GET /tracker-transfers | Os seus pedidos para transferir rastreadores para aqui, e os rastreadores que foram transferidos para outro lado |
POST /tracker-transfers | Pedir um rastreador que outra organização detém (proprietários e administradores) |
POST /tracker-transfers/{transferId}/start | Está agora a fazer o dispositivo iniciar sessão de novo (o seu SMS de reinício); um novo login nos 3 minutos seguintes transfere-o |
DELETE /tracker-transfers/{transferId} | Retirar um pedido |
GET /trackers/{trackerId} | Obter um rastreador, os seus passos de configuração e o que está mal |
PATCH /trackers/{trackerId} | Editar um rastreador (o seu veículo, modelo, SIM) |
DELETE /trackers/{trackerId} | Remover um rastreador (pode depois ser adicionado por qualquer pessoa) |
GET /trackers/{trackerId}/log | O registo do dispositivo (ligações, tramas em bruto, campos descodificados, respostas enviadas, erros), do mais antigo para o mais recente |
GET /trackers/{trackerId}/stream | O registo e o estado do dispositivo à medida que mudam (server-sent events) |
POST /trackers/{trackerId}/virtual | Conduzir um rastreador virtual em vez deste (com o seu próprio protocolo, através do gateway da N-Ways) |
DELETE /trackers/{trackerId}/virtual | Parar o seu rastreador virtual |
GET /trackers/{trackerId}/commands | Comandos enviados a um rastreador (os últimos 30), e quais aceita |
POST /trackers/{trackerId}/commands | Enviar um comando (proprietários e administradores); a resposta chega no registo do dispositivo |
GET /live | Todos os veículos agora, com o seu estafeta, estado, entrega atual e zonas |
GET /alerts | O que precisa de atenção agora, do mais urgente para o menos urgente |
GET /routes | Para onde vai cada veículo em entrega |
GET /zones | As zonas do projeto (círculos), cada uma com quantos veículos estão nela agora |
POST /zones | Adicionar uma zona (no máximo 200 por projeto) |
GET /zones/{id} | Obter uma zona |
PATCH /zones/{id} | Mudar o nome, mover ou redimensionar uma zona (lat e lng em conjunto) |
DELETE /zones/{id} | Eliminar uma zona |
GET /vehicles/{id}/links | As ligações de estafeta do veículo (nunca os seus endereços), das mais recentes para as mais antigas |
POST /vehicles/{id}/links | Uma ligação que um estafeta abre no telemóvel para partilhar a posição deste veículo (sem precisar de aplicação) |
DELETE /links/{linkId} | Parar de imediato uma ligação de estafeta (a sua página passa a indicar que terminou) |
GET /drivers/{id}/invites | Os convites do estafeta para a N-Ways Business (nunca os seus códigos), dos mais recentes para os mais antigos |
POST /drivers/{id}/invites | Convidar o estafeta para a N-Ways Business |
DELETE /invites/{inviteId} | Retirar um convite (o seu código deixa de funcionar) |
DELETE /drivers/{id}/app | Desligar a conta N-Ways do estafeta deste motorista |
Ficheiros
A mesma referência em ficheiros legíveis por máquina, para gerar o seu próprio cliente ou importar numa ferramenta de API. A coleção Postman tem cada pedido com as variáveis {{apiKey}} e {{baseUrl}}.