Ligar o seu ERP

Como circulam os dados

1. Os seus despachantes trabalham na consola (ou na aplicação N-Ways Business): entregas, estafetas, motoristas N-Ways, alertas.
2. Cada alteração é um evento. O N-Ways envia-o para o seu endereço HTTPS em poucos segundos, assinado com o segredo do seu webhook.
3. O seu ERP atualiza o registo, encontrado pela referência que deu à entrega ou pelo identificador N-Ways.
4. Nada se perde. As chamadas falhadas são repetidas durante cerca de 22 horas; pode reenviar qualquer uma a partir do registo de envios, e obter de novo todos os eventos por data com a API de exportação.

1. Adicione o seu endereço

Na consola: Definições → Webhooks → Adicionar webhook. Indique um endereço HTTPS acessível a partir da internet e escolha todos os eventos ou apenas os de que o seu ERP precisa. O segredo de assinatura (whsec_…) só é mostrado uma vez: guarde-o com os seus outros segredos. Até 10 endereços por organização, cada um com os seus próprios cabeçalhos (uma chave de API para o seu gateway, por exemplo).

Ou com uma chave de servidor:

curl -X POST "https://nways.ng/maps/v1/fleet/webhooks" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_DE_SERVIDOR" -H "Content-Type: application/json" \
  -d '{"url": "https://erp.example.com/nways/events"}'

2. Envie um evento de teste

Enviar teste no webhook publica um evento ping. Registos → Envios dos webhooks na consola mostra cada tentativa, a resposta do seu servidor e quando é a próxima. Responda com qualquer código 2xx em menos de 10 segundos; faça o trabalho demorado (a escrita no ERP) depois de responder.

3. Verifique a assinatura

Cada chamada leva X-NWays-Signature: t=<segundos unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de "<t>.<corpo em bruto>" com o segredo do seu webhook. Verifique-a sobre o corpo em bruto, antes de o analisar, e recuse uma marca temporal com mais de 5 minutos de diferença.

using System.Security.Cryptography;
using System.Text;

static bool Verified(string raw, string header, string secret)
{
    var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p.Length > 1 ? p[1] : "");
    if (!long.TryParse(parts.GetValueOrDefault("t"), out var t)) return false;
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
    using var mac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var want = Convert.ToHexString(mac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{raw}"))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(want), Encoding.UTF8.GetBytes(parts.GetValueOrDefault("v1", "")));
}

import com.sap.gateway.ip.core.customdev.util.Message
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

def Message processData(Message message) {
    def raw = message.getBody(String)
    def parts = message.getHeaders()['X-NWays-Signature'].split(',').collectEntries { it.split('=', 2) as List }
    long t = parts.t as long
    if (Math.abs(System.currentTimeMillis() / 1000 - t) > 300) throw new Exception('old signature')
    def mac = Mac.getInstance('HmacSHA256')
    mac.init(new SecretKeySpec(message.getProperty('NWAYS_SECRET').bytes, 'HmacSHA256'))
    def want = mac.doFinal("${t}.${raw}".bytes).encodeHex().toString()
    if (!java.security.MessageDigest.isEqual(want.bytes, (parts.v1 ?: '').bytes)) throw new Exception('bad signature')
    return message
}

import hashlib, hmac, time

def verified(raw: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    if abs(time.time() - int(parts.get("t", 0))) > 300:
        return False
    want = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, parts.get("v1", ""))

4. Faça corresponder os campos

Para onde vai habitualmente cada campo de um evento de entrega (data.task). Guarde o id N-Ways como referência externa no seu registo, para que cada evento seguinte o encontre; coloque o seu próprio número de documento na reference da entrega ao criá-la: volta em cada evento.

Estados: created → assigned → picked_up → arriving → completed, ou failed (com failureReason) ou cancelled. Um evento pode chegar duas vezes ou fora de ordem: guarde os id dos eventos já tratados e confie no status da tarefa em vez da ordem de chegada. Não há campos de dinheiro, propositadamente.

5. Reconcilie

Se o seu ERP esteve em baixo, nada se perde. Reenvie qualquer envio a partir de Registos → Envios dos webhooks, ou obtenha de novo os eventos por data (JSON ou CSV, os mesmos conteúdos que os webhooks enviam):

curl "https://nways.ng/maps/v1/fleet/events/export?format=json&from=2026-10-01&to=2026-10-16" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_DE_SERVIDOR"

Entregas, veículos e motoristas também podem ser lidos a qualquer momento com a API Frota (GET /maps/v1/fleet/tasks, /vehicles, /drivers), para verificar todas as noites que os dois lados coincidem. Use uma chave restrita aos endereços IP dos seus servidores e à API Frota.

Que eventos

Todos os eventos da lista de webhooks: entregas (task.*, delivery.rated), motoristas e veículos (connection.*, driver.availability_changed, vehicle.offline), pedidos a motoristas N-Ways (dispatch.*), zonas e alertas (zone.*, asset.*). Os conteúdos levam a version 2026-10-16; dentro de uma versão, só são acrescentados campos.