PingPoint — MCP-сервер и SDK для отслеживания грузоперевозок

Отслеживание грузоперевозок в реальном времени и видимость загрузки для логистического ПО и ИИ-агентов: MCP-сервер и TypeScript SDK, которые дают любому агенту живую GPS-позицию водителя для грузовой перевозки в США — создайте груз через API, водитель подключается по SMS-ссылке примерно за минуту, и с этого момента позиция, ETA, таймлайн остановок и статистика после поездки — в одном вызове. Никакой интеграции с ELD-провайдером, никакого корпоративного контракта, никаких звонков продавцов.

Полная документация API: https://pingpoint.suverse.io/docs · Спецификация OpenAPI 3.1: /docs/openapi.json

Проблема

Большинство перевозчиков в грузоперевозках США — это компании с одним или двумя грузовиками. У них нет корпоративного телематического стека, контракта на видимость и ИТ-отдела — грузовик и есть компания. Когда брокеру нужно узнать, где находится груз, единственный надёжный инструмент — телефонный звонок водителю.

Именно поэтому «AI track & trace» от большинства вендоров сегодня означает робота, который звонит человеку и спрашивает. Сами данные о позиции никогда не становятся машиночитаемыми — они живут в голове одного водителя, по одному звонку за раз. PingPoint делает саму позицию доступной через API: водитель устанавливает одно приложение по SMS-ссылке, и с этого момента любое ПО — или любой ИИ-агент через MCP — читает живую GPS-позицию, а не просит кого-то набрать номер.

Related MCP server: ThinAir Geo

Как это работает

1. Груз создается через API

POST /v1/agent/loads с телефоном водителя и остановками. Обязательные: driverPhone (E.164 — ссылка для водителя отправляется по SMS на этот номер) и массивы pickups / deliveries; каждая остановка требует address, city, state, zip. Поддерживаются многоостановочные грузы — несколько заборов и несколько доставок, в порядке массивов.

Ответ содержит loadNumber (используется во всех последующих вызовах), публичную trackingLink для клиента и ссылки для водителя (web/app). Две страховки от двойного списания:

• customerRef также служит ключом дедупликации — повторная отправка того же reference возвращает существующий груз (deduplicated: true) вместо создания дубликата;

• заголовок Idempotency-Key делает повторные попытки после сетевого сбоя безопасными — баланс списывается и груз создаётся не более одного раза.

2. Водитель подключается по SMS-ссылке

PingPoint автоматически отправляет водителю ссылку по SMS. Ссылка открывает онбординг: установите приложение, пройдите согласие, готово — примерно минута времени водителя, один раз. Под капотом ссылка содержит одноразовый токен загрузки, который приложение обменивает на постоянный токен устройства, так что следующий груз на тот же номер телефона привязывается без какой-либо новой настройки.

3. Позиция поступает по двум независимым каналам

• Телефон водителя — фоновая геолокация из приложения.

• ELD-донгл на диагностическом порту грузовика — передаёт данные автомобиля по Bluetooth в приложение, которое их ретранслирует. Протестировано с оборудованием IOSiX и Pacific Track PT30. Донгл излучает кадры с частотой 1 Гц; приложение прореживает их перед загрузкой, чтобы сохранённый трек оставался достаточно плотным для геозон, не перегружая конвейер.

Телефон остаётся шлюзом для обоих каналов — донгл общается с приложением, а не с сетью. Смысл двух источников в том, что они отказывают по-разному: донгл продолжает передавать позиции, пока работает двигатель, даже если GPS телефона не может получить сигнал или ОС ограничила фоновую геолокацию. Кадры донгла также несут собственные временные метки, взятые из самого кадра, а не из момента загрузки — поэтому когда буферизованный бэклог сбрасывается после офлайн-периода, записанные времена являются реальными.

4. Статусы обновляются по геозонам — никогда с клавиатуры

Каждая остановка забора и доставки получает геозону. Вход в зону забора переводит груз в AT_PICKUP, выход — в IN_TRANSIT, вход в зону доставки — в AT_DELIVERY, а DELIVERED устанавливается, когда грузовик покидает финальную зону доставки, а не по прибытии. Единственное исключение — явный (бесплатный) вызов delivery-confirm (BOL на руках), который завершает груз, когда грузовик находится на остановке доставки. Временные метки остановок arrivedAt / departedAt берутся из тех же событий геозон.

Внешние записи статуса намеренно закрыты: PATCH …/status всегда отвечает 410 STATUS_DOOR_CLOSED. Это гарантия целостности данных, а не отсутствующая функция — статус, который вы читаете, никогда не был установлен вручную; за ним стоит записанная позиция.

5. Чтение данных

GET /v1/agent/loads/{loadNumber} возвращает живое состояние: статус, GPS-трек (до 500 последних точек), таймлайн остановок с временными метками прибытия/отправления, пройденное расстояние, время простоя, флаг своевременности и блок ETA, вычисленный на основе сохранённой геометрии маршрута и последней позиции. После поездки GET …/trip-stats возвращает агрегированную сводку, вычисленную по каждому записанному пингу. Вебхуки могут отправлять события груза на ваш эндпоинт по мере их возникновения (см. документацию).

 SMS link          +---------------------+
 (sent by  ------> |  Driver phone app   |--- background GPS ---+
  PingPoint)       +---------------------+                      |
                                                                v
                   +---------------------+   1 Hz frames   +--------------------+
                   |  ELD dongle on the  |---------------->| ingest (thinning)  |
                   |  diagnostic port,   |   via the app   +--------------------+
                   |  BLE (IOSiX, PT30)  |                      |
                   +---------------------+                      v
                                                       +-----------------+
                                                       |  position store |
                                                       +-----------------+
                                                            |        |
                                     geofence engine <------+        |
                                            |                        |
        PLANNED -> AT_PICKUP -> IN_TRANSIT -> AT_DELIVERY -> DELIVERED
                                            |                        |
                                            v                        v
                  webhooks -> your endpoint      GET /v1/agent/loads/{n}   (position, ETA)
                                                 GET .../trip-stats        (post-trip summary)

Быстрый старт

Получить ключ

1. Зарегистрируйтесь на pingpoint.suverse.io (e-mail или Google/GitHub).

2. В кабинете откройте Integrations → Agent API и нажмите Issue key.

3. Ключ sup_agent_… приходит по e-mail. PingPoint никогда не хранит секрет — если он потерян, выпустите новый с той же страницы.

Первый вызов

curl -X POST https://api.suverse.io/v1/agent/loads \
  -H "Authorization: Bearer sup_agent_…" \
  -H "Content-Type: application/json" \
  -d '{
    "driverPhone": "+15551234567",
    "pickups":    [{ "address": "6492 Tower Lane", "city": "Claremore", "state": "OK", "zip": "74017" }],
    "deliveries": [{ "address": "6499 Caldwell Park Dr", "city": "Charlotte", "state": "NC", "zip": "28269" }],
    "customerRef": "PO-483920"
  }'

{
  "success": true,
  "loadId": "3b9f6a2e-1c47-4d8a-9e02-7f5b1c8d4a63",
  "loadNumber": "LD-2026-042317",
  "trackingLink": "https://pingpoint.suverse.io/track/trk_…",
  "driverWebLink": "https://pingpoint.suverse.io/driver/drv_…",
  "driverAppLink": "pingpoint://driver/drv_…",
  "driverResolution": "none"
}

Ссылка для водителя уже отправлена на +15551234567 по SMS. Отсюда GET /v1/agent/loads/LD-2026-042317 читает живую позицию.

Подключение MCP-сервера

Claude Code, одна строка:

claude mcp add pingpoint --env PINGPOINT_AGENT_KEY=sup_agent_… -- npx -y @suverselabs/pingpoint-mcp

Claude Desktop (claude_desktop_config.json) или любой агент, поддерживающий MCP:

{
  "mcpServers": {
    "pingpoint": {
      "command": "npx",
      "args": ["-y", "@suverselabs/pingpoint-mcp"],
      "env": {
        "PINGPOINT_AGENT_KEY": "sup_agent_…"
      }
    }
  }
}

Перезапустите агента — инструменты появятся.

MCP-инструменты

Подробный справочник по каждому инструменту с полными примерами запросов/ответов: docs/tools/.

Описания инструментов написаны для вызывающей модели: каждый указывает, сколько он стоит, когда его использовать, а когда нет (например, get_load_position отвечает на вопрос «где грузовик сейчас», get_trip_stats — «как прошла завершённая поездка», и оба предупреждают о цикличном опросе, потому что каждый вызов тарифицируется).

SDK

npm install @suverselabs/pingpoint-sdk

import { PingPointAgent, InsufficientFundsError, DeliveryNotReadyError } from "@suverselabs/pingpoint-sdk";

const pp = new PingPointAgent({ apiKey: process.env.PINGPOINT_AGENT_KEY! });

// $0.65 — driver gets the app link by SMS
const load = await pp.createLoad(
  {
    driverPhone: "+15551234567",
    pickups: [{ address: "6492 Tower Lane", city: "Claremore", state: "OK", zip: "74017" }],
    deliveries: [{ address: "6499 Caldwell Park Dr", city: "Charlotte", state: "NC", zip: "28269" }],
    customerRef: "PO-483920",
  },
  { idempotencyKey: "PO-483920" },
);

const pos = await pp.getPosition(load.loadNumber);   // $0.02
const trip = await pp.getTripStats(load.loadNumber); // $0.02, best after DELIVERED
await pp.confirmDelivery(load.loadNumber, { bolReceivedAt: new Date() }); // free

Методы: createLoad(input, { idempotencyKey? }), getPosition(loadNumber), getTripStats(loadNumber), updateStatus(loadNumber, status) (документирован как выбрасывающий намеренный 410), confirmDelivery(loadNumber, { bolReceivedAt? }), getPricing(), getBalance(). Полный справочник: docs/sdk.md.

Каждый ответ не-2xx выбрасывает типизированный подкласс PingPointAgentError с .status и сырым .body:

try {
  await pp.createLoad(input);
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    console.log(`balance $${err.balanceUsd}, need $${err.priceUsd} — nothing was charged`);
  } else if (err instanceof DeliveryNotReadyError) {
    // driver hasn't arrived yet — do NOT retry; the load completes automatically when the truck departs the delivery zone
  }
}

Node ≥ 18 (использует глобальный fetch), ESM + CJS, ноль зависимостей времени выполнения.

Модель данных

Позиция (get_load_position / getPosition)

Статистика рейса (get_trip_stats / getTripStats)

Коды ошибок

Биллинг

Предоплаченный баланс, оплата за каждый вызов, без подписния. Подробности: abusiness/billing. —

actually need include link: [docs/billing.md](docs/billing.md) — now doing.

Пje pl dis: W? The link should be: docs/billing.md and the translated phrase before says "Подробности в [docs/billing.md]. Let's write.

• Пополнить баланс можно в личном кабинете в разделе BillingБесплатные операции работаю при нулевом балансе.

• 402 означает, что запрос был отклонён до совершения каких-либо изменений: ничего не создано и ничего не списано.

• Повторные вызовы createLoad с тем же Idempotency-Key безопасны — списание происходит не более одного раза; customerRef исключает дубли на уровне бизнес-логики.

• Цены в реальном времени отдаются через GET /v1/agent/pricing — считайте это источником истины и никогда не зашивайте их.

Что это не такое

• Не сертифицированный ELD. PingPoint читает GPS (и данных о дойле данные шины двигателя) для видимости. Это не зарегистрированный в FMCSA ELD и не формирует записи о соответствии HOS/RODS.

• Не проверка перевозчиков. Живая позиция показывает, где находится грузовик, а не является ли перевозчик надёжным, застрахованным или реальным. Сохраняйте все существующие проверки при онбординге.

• Водитель должен установить приложение. Одна ссылка по SMS, одна установка, около минуты — но это настоящий шаг, требующий cooperation. Если линейка not connected phone? Exactly: "Перевозка без связанного phone и detachme" We will not publish.

• Водителю нужно установить приложение. Одна SMS-ссылка, однаью, rue, un действия; a not— dose: no: "No connected phone" -> "без подключённого телефона и без донгла" positions "не даёт позиций".

Как это compares

Корпоративные платформы отслеживания хотят, что у перевозчика уже есть телематика, а у брокера — контракт; vendors based on звонках вставлять телефонный звонок (живу, human or system) into every check. У PingPoint другой подход: one driver install in exchange for an API with payment for every call, public prices and no minimums. Фактическая и построчный сравнение с обеими группами — порядок выдачи ключей, публичные цены, API, MCP/SDK, — maintained at pingpoint.suverse.io/compare.

##Силк

• Документация API: https://pingpoint.suverse.io/docs

• Спецификация OpenAPI 3.1: https://pingpoint.suverse.io/docs/openapi.json

• Сравнение с альтернативами: https://pingpoint.suverse.io/compare

• MCP-сервер на npm: https://www.npmjs.com/package/@suverselabs/pingpoint-mcp

• SDK on npm: https://www.npmjs.com/package/@suverselabs/pingpoint-sdk

• Расширенные документы: architecture · billing · SDK reference · MCP tools

• Контакт: info@suverse.io

Лицензия

MIT © 2026 Sudzik Group Inc.