Contactos

O seu livro de endereços numa só lista: destinatários guardados (ben_…), os seus locais de recolha (plc_…, as suas lojas e armazéns, para escolher a recolha de uma entrega com pickupPlaceId) e clientes (cus_…, todas as pessoas a quem as suas entregas chegaram, guardados a partir das entregas). As listas antigas (/places, /customers, e /beneficiaries e /addresses) devolvem os mesmos registos e mantêm-se como alias obsoletos.

Nesta página

O seu livro de endereços (destinatários, locais de recolha e clientes)
Guardar um destinatário ou adicionar um local de recolha
Os seus próprios endereços primeiro enquanto se escreve uma paragem
Obter um contacto
Editar um destinatário ou um local de recolha
Eliminar um contacto (um cliente é esquecido com os seus endereços)
Os endereços de um contacto

Nota:

Envie a sua chave com key=A_SUA_CHAVE_API no endereço, ou no cabeçalho X-NWays-Api-Key. Chaves de API

Endereço base: https://nways.ng/maps/v1/fleet

O seu livro de endereços (destinatários, locais de recolha e clientes)

GET https://nways.ng/maps/v1/fleet/contacts

Um só tipo (kind=recipient|place|customer, cada um com a sua ordem e as suas páginas), ou todos: os seus locais de recolha (o predefinido primeiro), depois os seus destinatários guardados (por nome, até limit), depois os seus clientes (entrega mais recente primeiro, uma página de cada vez: nextPageToken avança apenas pelos clientes). q encontra um nome, telefone, email, endereço, código de porta ou etiqueta; tag mantém os destinatários de uma etiqueta. recipients indica quantos destinatários correspondem; tags as suas etiquetas, as mais usadas primeiro.

Parâmetros

Nome	Onde	Tipo	Descrição
`kind`	consulta	`string`	Um de: `recipient`, `place`, `customer`.
`q`	consulta	`string`
`tag`	consulta	`string`	Apenas destinatários.
`limit`	consulta	`integer`	Destinatários: 100 (no máximo 1000); clientes: 25 (no máximo 100) por página. ≥ 1.
`pageToken`	consulta	`string`	Clientes: `nextPageToken` (ou `prevPageToken`).

cURL

curl "https://nways.ng/maps/v1/fleet/contacts" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Contactos

Campo	Tipo	Descrição
`contacts`	`Contact[]`	Obrigatório.
`contacts[].id`	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).
`contacts[].kind`	`string`	Obrigatório. Um de: `recipient`, `place`, `customer`.
`contacts[].name`	`string`	Obrigatório.
`contacts[].phone`	`string`	Obrigatório.
`contacts[].altPhone`	`string`
`contacts[].email`	`string`
`contacts[].placeName`	`string`	Destinatários: o nome do local de entrega; clientes: o do seu último local de entrega.
`contacts[].address`	`string`
`contacts[].doorCode`	`string`
`contacts[].lat`	`number \| null`	Obrigatório. null para um cliente sem endereço guardado.
`contacts[].lng`	`number \| null`	Obrigatório.
`contacts[].notes`	`string`
`contacts[].itemDescription`	`string`
`contacts[].packageSize`	`string \| null`
`contacts[].tags`	`string[]`
`contacts[].regulars`	`integer`	Destinatários: entregas recorrentes para eles que ainda não terminaram.
`contacts[].hours`	`string`	Locais
`contacts[].default`	`boolean`	Locais: as novas entregas na consola começam a partir dele.
`contacts[].deliveries`	`integer`	Clientes
`contacts[].addresses`	`integer`	Clientes
`contacts[].lastDeliveryAt`	`string (date-time)`	Clientes
`contacts[].createdAt`	`string (date-time)`
`contacts[].updatedAt`	`string (date-time)`
`recipients`	`integer`
`tags`	`object[]`
`tags[].tag`	`string`
`tags[].count`	`integer`
`nextPageToken`	`string`
`prevPageToken`	`string`

200 OK

{
  "contacts": [
    {
      "id": "ben_4fQ9xLm2Za",
      "kind": "recipient",
      "name": "string",
      "phone": "string",
      "altPhone": "string",
      "email": "string",
      "placeName": "string",
      "address": "string",
      "doorCode": "string",
      "lat": 0,
      "lng": 0,
      "notes": "string",
      "itemDescription": "string",
      "packageSize": "string",
      "tags": [
        "string"
      ],
      "regulars": 0,
      "hours": "string",
      "default": true,
      "deliveries": 0,
      "addresses": 0,
      "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
      "createdAt": "2026-10-15T09:00:00+01:00",
      "updatedAt": "2026-10-15T09:00:00+01:00"
    }
  ],
  "recipients": 0,
  "tags": [
    {
      "tag": "string",
      "count": 0
    }
  ],
  "nextPageToken": "string",
  "prevPageToken": "string"
}

Erros

default Erro

Guardar um destinatário ou adicionar um local de recolha

POST https://nways.ng/maps/v1/fleet/contacts

kind é recipient (um local de entrega guardado: name, phones, email, placeName, address, doorCode, lat, lng, notes, itemDescription, packageSize, tags; até 5000) ou place (um local de recolha: name, doorCode, address, lat, lng, phone, hours, default; até 200; o primeiro é o predefinido). Os clientes vêm das entregas e não podem ser criados aqui. name, lat e lng são obrigatórios.

Corpo do pedido

kind (recipient ou place) e os campos desse tipo; name, lat e lng são obrigatórios para criar um.

Campo	Tipo	Descrição
`kind`	`string`	Um de: `recipient`, `place`.
`name`	`string`	Até 100 caracteres.
`phone`	`string`
`altPhone`	`string`	Destinatários
`email`	`string`	Destinatários
`placeName`	`string`	Destinatários
`address`	`string`	Até 300 caracteres.
`doorCode`	`string`	Até 32 caracteres.
`lat`	`number`
`lng`	`number`
`notes`	`string`	Destinatários
`itemDescription`	`string`	Destinatários
`packageSize`	`string \| null`	Destinatários
`tags`	`string[]`	Destinatários No máximo 8 elementos.
`hours`	`string`	Locais Até 200 caracteres.
`default`	`boolean`	Locais

cURL

curl -X POST "https://nways.ng/maps/v1/fleet/contacts" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"kind":"recipient","name":"Mama Put","phone":"+234 803 555 0101","address":"12 Herbert Macaulay Way","lat":6.5095,"lng":3.3711,"tags":["Shop"]}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "kind": "recipient",
    "name": "Mama Put",
    "phone": "+234 803 555 0101",
    "address": "12 Herbert Macaulay Way",
    "lat": 6.5095,
    "lng": 3.3711,
    "tags": [
      "Shop"
    ]
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/fleet/contacts",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"kind": "recipient", "name": "Mama Put", "phone": "+234 803 555 0101", "address": "12 Herbert Macaulay Way", "lat": 6.5095, "lng": 3.3711, "tags": ["Shop"]},
    timeout=10,
)
data = res.json()

Resposta

Guardado

Campo	Tipo	Descrição
`id`	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).
`kind`	`string`	Obrigatório. Um de: `recipient`, `place`, `customer`.
`name`	`string`	Obrigatório.
`phone`	`string`	Obrigatório.
`altPhone`	`string`
`email`	`string`
`placeName`	`string`	Destinatários: o nome do local de entrega; clientes: o do seu último local de entrega.
`address`	`string`
`doorCode`	`string`
`lat`	`number \| null`	Obrigatório. null para um cliente sem endereço guardado.
`lng`	`number \| null`	Obrigatório.
`notes`	`string`
`itemDescription`	`string`
`packageSize`	`string \| null`
`tags`	`string[]`
`regulars`	`integer`	Destinatários: entregas recorrentes para eles que ainda não terminaram.
`hours`	`string`	Locais
`default`	`boolean`	Locais: as novas entregas na consola começam a partir dele.
`deliveries`	`integer`	Clientes
`addresses`	`integer`	Clientes
`lastDeliveryAt`	`string (date-time)`	Clientes
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

201 OK

{
  "id": "ben_4fQ9xLm2Za",
  "kind": "recipient",
  "name": "string",
  "phone": "string",
  "altPhone": "string",
  "email": "string",
  "placeName": "string",
  "address": "string",
  "doorCode": "string",
  "lat": 0,
  "lng": 0,
  "notes": "string",
  "itemDescription": "string",
  "packageSize": "string",
  "tags": [
    "string"
  ],
  "regulars": 0,
  "hours": "string",
  "default": true,
  "deliveries": 0,
  "addresses": 0,
  "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Erros

default Erro

Os seus próprios endereços primeiro enquanto se escreve uma paragem

GET https://nways.ng/maps/v1/fleet/contacts/addresses

Os seus locais de recolha e os locais de entrega que já usou que correspondem a q (cada palavra, no nome, endereço ou código de porta), os usados mais recentemente primeiro; no máximo limit (5, até 10).

Parâmetros

Nome	Onde	Tipo	Descrição
`q`	consulta	`string`
`limit`	consulta	`integer`	Predefinição: `5`. ≥ 1, ≤ 10.

cURL

curl "https://nways.ng/maps/v1/fleet/contacts/addresses" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/addresses', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts/addresses",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Endereços

Campo	Tipo	Descrição
`addresses`	`object[]`	Obrigatório.

200 OK

{
  "addresses": [
    {}
  ]
}

Erros

default Erro

Obter um contacto

GET https://nways.ng/maps/v1/fleet/contacts/{contactId}

Parâmetros

Nome	Onde	Tipo	Descrição
`contactId`	caminho	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).

cURL

curl "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Contacto

Campo	Tipo	Descrição
`id`	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).
`kind`	`string`	Obrigatório. Um de: `recipient`, `place`, `customer`.
`name`	`string`	Obrigatório.
`phone`	`string`	Obrigatório.
`altPhone`	`string`
`email`	`string`
`placeName`	`string`	Destinatários: o nome do local de entrega; clientes: o do seu último local de entrega.
`address`	`string`
`doorCode`	`string`
`lat`	`number \| null`	Obrigatório. null para um cliente sem endereço guardado.
`lng`	`number \| null`	Obrigatório.
`notes`	`string`
`itemDescription`	`string`
`packageSize`	`string \| null`
`tags`	`string[]`
`regulars`	`integer`	Destinatários: entregas recorrentes para eles que ainda não terminaram.
`hours`	`string`	Locais
`default`	`boolean`	Locais: as novas entregas na consola começam a partir dele.
`deliveries`	`integer`	Clientes
`addresses`	`integer`	Clientes
`lastDeliveryAt`	`string (date-time)`	Clientes
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

200 OK

{
  "id": "ben_4fQ9xLm2Za",
  "kind": "recipient",
  "name": "string",
  "phone": "string",
  "altPhone": "string",
  "email": "string",
  "placeName": "string",
  "address": "string",
  "doorCode": "string",
  "lat": 0,
  "lng": 0,
  "notes": "string",
  "itemDescription": "string",
  "packageSize": "string",
  "tags": [
    "string"
  ],
  "regulars": 0,
  "hours": "string",
  "default": true,
  "deliveries": 0,
  "addresses": 0,
  "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Erros

default Erro

Editar um destinatário ou um local de recolha

PATCH https://nways.ng/maps/v1/fleet/contacts/{contactId}

Os campos do tipo, como na criação (kind pode ser omitido; não pode mudar). Um cliente é o registo das suas entregas e não pode ser editado (400): guarde-o como destinatário.

Parâmetros

Nome	Onde	Tipo	Descrição
`contactId`	caminho	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).

Corpo do pedido

kind (recipient ou place) e os campos desse tipo; name, lat e lng são obrigatórios para criar um.

Campo	Tipo	Descrição
`kind`	`string`	Um de: `recipient`, `place`.
`name`	`string`	Até 100 caracteres.
`phone`	`string`
`altPhone`	`string`	Destinatários
`email`	`string`	Destinatários
`placeName`	`string`	Destinatários
`address`	`string`	Até 300 caracteres.
`doorCode`	`string`	Até 32 caracteres.
`lat`	`number`
`lng`	`number`
`notes`	`string`	Destinatários
`itemDescription`	`string`	Destinatários
`packageSize`	`string \| null`	Destinatários
`tags`	`string[]`	Destinatários No máximo 8 elementos.
`hours`	`string`	Locais Até 200 caracteres.
`default`	`boolean`	Locais

cURL

curl -X PATCH "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"kind":"recipient","name":"string","phone":"string","altPhone":"string","email":"string","placeName":"string","address":"string","doorCode":"string","lat":0,"lng":0,"notes":"string","itemDescription":"string","packageSize":"string","tags":["string"],"hours":"string","default":true}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za', {
  method: 'PATCH',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "kind": "recipient",
    "name": "string",
    "phone": "string",
    "altPhone": "string",
    "email": "string",
    "placeName": "string",
    "address": "string",
    "doorCode": "string",
    "lat": 0,
    "lng": 0,
    "notes": "string",
    "itemDescription": "string",
    "packageSize": "string",
    "tags": [
      "string"
    ],
    "hours": "string",
    "default": true
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.patch(
    "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"kind": "recipient", "name": "string", "phone": "string", "altPhone": "string", "email": "string", "placeName": "string", "address": "string", "doorCode": "string", "lat": 0, "lng": 0, "notes": "string", "itemDescription": "string", "packageSize": "string", "tags": ["string"], "hours": "string", "default": True},
    timeout=10,
)
data = res.json()

Resposta

Contacto

Campo	Tipo	Descrição
`id`	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).
`kind`	`string`	Obrigatório. Um de: `recipient`, `place`, `customer`.
`name`	`string`	Obrigatório.
`phone`	`string`	Obrigatório.
`altPhone`	`string`
`email`	`string`
`placeName`	`string`	Destinatários: o nome do local de entrega; clientes: o do seu último local de entrega.
`address`	`string`
`doorCode`	`string`
`lat`	`number \| null`	Obrigatório. null para um cliente sem endereço guardado.
`lng`	`number \| null`	Obrigatório.
`notes`	`string`
`itemDescription`	`string`
`packageSize`	`string \| null`
`tags`	`string[]`
`regulars`	`integer`	Destinatários: entregas recorrentes para eles que ainda não terminaram.
`hours`	`string`	Locais
`default`	`boolean`	Locais: as novas entregas na consola começam a partir dele.
`deliveries`	`integer`	Clientes
`addresses`	`integer`	Clientes
`lastDeliveryAt`	`string (date-time)`	Clientes
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

200 OK

{
  "id": "ben_4fQ9xLm2Za",
  "kind": "recipient",
  "name": "string",
  "phone": "string",
  "altPhone": "string",
  "email": "string",
  "placeName": "string",
  "address": "string",
  "doorCode": "string",
  "lat": 0,
  "lng": 0,
  "notes": "string",
  "itemDescription": "string",
  "packageSize": "string",
  "tags": [
    "string"
  ],
  "regulars": 0,
  "hours": "string",
  "default": true,
  "deliveries": 0,
  "addresses": 0,
  "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Erros

default Erro

Eliminar um contacto (um cliente é esquecido com os seus endereços)

DELETE https://nways.ng/maps/v1/fleet/contacts/{contactId}

As entregas já feitas mantêm o que lhes foi dado; as entregas de um cliente esquecido seguem o período de retenção da sua frota.

Parâmetros

Nome	Onde	Tipo	Descrição
`contactId`	caminho	`string`	Obrigatório. ben_… (destinatário), plc_… (local) ou cus_… (cliente).

cURL

curl -X DELETE "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za', {
  method: 'DELETE',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.delete(
    "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Eliminado

Sem conteúdo.

Erros

default Erro

Os endereços de um contacto

GET https://nways.ng/maps/v1/fleet/contacts/{contactId}/addresses

Os locais de entrega de um cliente, o último usado primeiro, uma página de cada vez (q, limit, pageToken); o único endereço de um destinatário ou local.

Parâmetros

Nome	Onde	Tipo	Descrição
`contactId`	caminho	`string`	Obrigatório.
`q`	consulta	`string`
`limit`	consulta	`integer`	Predefinição: `25`. ≥ 1, ≤ 100.
`pageToken`	consulta	`string`

cURL

curl "https://nways.ng/maps/v1/fleet/contacts/string/addresses" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/string/addresses', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts/string/addresses",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Endereços

Campo	Tipo	Descrição
`addresses`	`Address[]`	Obrigatório.
`addresses[].id`	`string`	Obrigatório.
`addresses[].name`	`string`	Obrigatório.
`addresses[].address`	`string`	Obrigatório.
`addresses[].doorCode`	`string`	Obrigatório. O código NIPOST ou GhanaPost com que o endereço começa ("" para nenhum).
`addresses[].lat`	`number`	Obrigatório.
`addresses[].lng`	`number`	Obrigatório.
`addresses[].uses`	`integer`	Obrigatório. Entregas que foram para lá.
`addresses[].lastUsedAt`	`string (date-time)`	Obrigatório.
`total`	`integer`	Obrigatório.
`nextPageToken`	`string`
`prevPageToken`	`string`

200 OK

{
  "addresses": [
    {
      "id": "adr_8KwP2nVd5T",
      "name": "string",
      "address": "string",
      "doorCode": "string",
      "lat": 0,
      "lng": 0,
      "uses": 0,
      "lastUsedAt": "2026-10-15T09:00:00+01:00"
    }
  ],
  "total": 0,
  "nextPageToken": "string",
  "prevPageToken": "string"
}

Erros

default Erro