Integrarea API REST CloudTAK: conectarea sistemelor externe la rețeaua tactică

De echipa de inginerie Corvus Intelligence · Despre echipă →

29 mai 2026 12 min de citire

API-ul REST al CloudTAK transformă un server TAK dintr-un releu pasiv într-un hub de integrare activ. În loc să ceară fiecărei surse de date să vorbească CoT nativ prin TCP/TLS — singura cale spre TAK Server moștenit — CloudTAK expune o suprafață HTTP și WebSocket completă pe care orice sistem modern o poate apela: tablouri de senzori, platforme logistice, pipeline-uri de inferență AI, fluxuri SIGINT și tablouri de bord personalizate. Acest ghid acoperă în detaliu toate suprafețele majore ale API-ului: autentificare, injectare CoT, streaming track-uri în timp real, gestionarea misiunilor, upload pachete de date, administrarea grupurilor, webhook-uri și copilotul AI TAKpilot ca exemplu de integrare. Dacă trebuie mai întâi să configurați un server CloudTAK, consultați ghidul nostru pentru implementarea serverului CloudTAK.

Autentificare: token-uri JWT, chei API și domenii de acces

API-ul REST CloudTAK aplică autentificarea pe fiecare endpoint, cu excepția verificării stării (GET /api/health). Sunt suportate două tipuri de credențiale, ambele transmise ca antet HTTP Authorization: Bearer <token>.

Token-uri JWT

Token-urile JWT sunt de scurtă durată și emise per sesiune de utilizator. Obțineți unul trimițând credențiale la endpoint-ul de autentificare:

curl -s -X POST https://tak.yourdomain.com:8443/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "operator01", "password": "s3cur3p@ss"}' \
  | jq -r '.token'

TTL implicit este 86400 secunde (24 ore); configurabil prin CLOUDTAK_JWT_TTL. JWT-urile poartă rolul utilizatorului și apartenența la grupuri ca claims, deci verificările de permisiuni sunt fără stare.

Chei API

Cheile API sunt token-uri cu viață lungă potrivite pentru integrări automate serviciu-la-serviciu. Generați-le prin API-ul admin:

curl -s -X POST https://tak.yourdomain.com:8443/api/token \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sensor-array-east",
    "scopes": ["cot:write"],
    "rateLimit": 500
  }' | jq -r '.token'

Domenii de acces suportate și ce deblochează:

Domeniu	Acordă acces la
`cot:write`	Injectarea evenimentelor CoT prin POST /api/cot
`cot:read`	Interogarea track-urilor istorice prin GET /api/cot
`events:subscribe`	Conectare la stream-ul WebSocket la /api/ws
`mission:write`	Crearea, actualizarea și ștergerea misiunilor
`package:write`	Încărcarea pachetelor de date și atașamentelor
`group:write`	Crearea grupurilor și gestionarea apartenența
`admin`	Toate domeniile plus gestionarea utilizatorilor și configurația serverului

Revocați o cheie oricând: DELETE /api/token/{id}. Listați cheile active cu GET /api/token.

URL de bază și limite de rată

Toate endpoint-urile REST sunt servite sub https://<host>:8443/api/. Limita globală implicită este de 100 cereri pe secundă per cheie API. Răspunsurile HTTP 429 includ un antet Retry-After. Specificația OpenAPI este disponibilă la GET /api/docs.

Injectare CoT: POST /api/cot

Endpoint-ul de injectare CoT este calea principală pentru transmiterea rapoartelor de poziție, markerilor de contact, alertelor și oricăror alte evenimente CoT în imaginea tactică din sisteme externe. Acceptă atât CoT XML brut, cât și un format JSON convenabil.

Payload XML

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<event version="2.0"
       uid="sensor-east-001"
       type="a-f-G-U-C"
       how="m-g"
       time="2026-05-29T14:32:00Z"
       start="2026-05-29T14:32:00Z"
       stale="2026-05-29T14:37:00Z">
  <point lat="50.4501" lon="30.5234" hae="145.0" ce="10.0" le="5.0"/>
  <detail>
    <contact callsign="SENSOR-EAST-01"/>
    <remarks>Contact radar terestru, viteză 12 kph, rulment 045</remarks>
    <group name="Surveillance" role="Team Member"/>
  </detail>
</event>'

Payload JSON

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "logistics-truck-07",
    "type": "a-f-G-U-C",
    "callsign": "LOG-07",
    "lat": 50.4610,
    "lon": 30.5190,
    "hae": 138.0,
    "ce": 5.0,
    "le": 3.0,
    "staleSeconds": 300,
    "remarks": "Convoi de aprovizionare, ETA punct de control 14:45Z",
    "group": "Logistics",
    "role": "Team Member"
  }'

CloudTAK serializează acest JSON la o înveliș CoT XML complet intern. O injectare reușită returnează HTTP 201. Evenimentul se propagă imediat la toți clienții abonați și la stream-ul WebSocket.

Streaming track-uri: WebSocket /api/ws

Pentru consumul în timp real al imaginii tactice, endpoint-ul WebSocket oferă un stream continuu, cu latență scăzută, de evenimente CoT.

Conectare și abonare

// Exemplu Node.js folosind biblioteca 'ws'
const WebSocket = require('ws');

const ws = new WebSocket('wss://tak.yourdomain.com:8443/api/ws', {
  headers: { 'Authorization': `Bearer ${process.env.CLOUDTAK_API_KEY}` }
});

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    filter: {
      groups: ['Surveillance', 'Logistics'],
      bbox: [29.5, 50.0, 31.5, 51.0],
      types: ['a-f-G', 'a-h-G', 'a-u-G']
    }
  }));
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.type === 'cot') {
    console.log(`Track: ${event.payload.uid} la ${event.payload.lat},${event.payload.lon}`);
  } else if (event.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

Serverul trimite un mesaj ping la fiecare 30 secunde. Clienții trebuie să răspundă cu pong în 10 secunde sau conexiunea este închisă.

API misiuni: creare, actualizare, ștergere și atribuire

Misiunile în CloudTAK sunt contexte operaționale numite care grupează track-uri, pachete de date și utilizatori. API-ul misiunilor permite sistemelor externe să creeze misiuni programatic.

Crearea unei misiuni

curl -s -X POST https://tak.yourdomain.com:8443/api/mission \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPERAȚIUNEA CLEARWATER",
    "description": "Capturarea punctului de control, Faza 1",
    "classification": "UNCLASSIFIED",
    "bbox": [30.10, 50.35, 30.25, 50.45],
    "groups": ["Alpha-Company", "ISR-Detachment"]
  }' | jq '{uid: .uid, name: .name}'

Răspunsul include uid-ul misiunii (UUID). Actualizați metadatele cu PATCH /api/mission/{uid}. Ștergeți cu DELETE /api/mission/{uid}.

API pachete de date: MBTiles, KMZ, GeoJSON și versionare

# Încărcarea unui strat MBTiles pentru acoperire hartă offline
curl -s -X POST \
  https://tak.yourdomain.com:8443/api/mission/${MISSION_UID}/attachment \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/data/aoi-sector-north.mbtiles" \
  -F "name=Hartă de bază sector nord" \
  -F "contentType=application/vnd.mbtiles" \
  | jq '{attachmentId: .id, version: .version}'

Straturile de hartă de sine stătătoare sunt încărcate prin POST /api/layer. Pentru implementări offline: MBTiles și PMTiles pentru hărți offline.

Grupuri și canale: filtrarea vizibilității și controlul accesului la track-uri

Grupurile CloudTAK implementează segregarea vizibilității track-urilor. Un track purtând un tag de grup este vizibil doar pentru clienții conectați care sunt membri ai acelui grup. Aceasta permite separarea pe baza necesității de cunoaștere în cadrul unui server TAK partajat.

Crearea unui grup și atribuirea utilizatorilor

# Crearea unui grup
curl -s -X POST https://tak.yourdomain.com:8443/api/group \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ISR-Detachment", "description": "Celulă Informații, Supraveghere, Recunoaștere"}' \
  | jq '.id'

# Adăugarea unui utilizator la grup
curl -s -X POST https://tak.yourdomain.com:8443/api/group/ISR-Detachment/user \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "isr-analyst-01"}'

Un client poate aparține simultan mai multor grupuri. Track-urile fără tag de grup sunt vizibile pentru toți utilizatorii serverului.

TAKpilot ca exemplu de integrare

TAKpilot este copilotul AI al Corvus Intelligence pentru operațiuni bazate pe TAK. TAKpilot se abonează la stream-ul WebSocket de track-uri, procesează comenzi în limbaj natural de la operatori și le execută ca apeluri API CloudTAK.

O comandă în limbaj natural precum "marchează grila 38T YQ 45123 67890 ca contact ostil, atribuie la misiunea Alpha-Company" declanșează următoarea secvență API în TAKpilot:

Conversia MGRS 38T YQ 45123 67890 în grade zecimale (conversie internă, fără apel API).
POST /api/cot cu tipul a-h-G (ostil terestru) și coordonatele convertite.
GET /api/mission?name=Alpha-Company pentru a rezolva UID-ul misiunii.
POST /api/mission/{uid}/cot pentru a asocia evenimentul CoT injectat cu misiunea.
Răspuns la operator prin interfața de chat TAKpilot confirmând acțiunea.

Webhook-uri: abonarea la evenimente și transmiterea la sisteme externe

Webhook-urile permit CloudTAK să trimită evenimente la sisteme externe în loc să ceară acestor sisteme să interogeze API-ul REST sau să mențină o conexiune WebSocket persistentă.

Înregistrarea unui webhook

curl -s -X POST https://tak.yourdomain.com:8443/api/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "kafka-bridge",
    "url": "https://integration.yourdomain.com/cloudtak-events",
    "events": ["new_track", "mission_update", "user_join"],
    "secret": "hmac_signing_secret_32chars_min",
    "active": true
  }' | jq '{id: .id, status: .status}'

CloudTAK semnează fiecare livrare webhook cu o semnătură HMAC-SHA256 în antetul X-CloudTAK-Signature. Verificați semnătura la recepție:

// Receptor webhook Express.js cu verificare semnătură
const crypto = require('crypto');

app.post('/cloudtak-events', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-cloudtak-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Semnătură nepotrivită');
  }

  const event = JSON.parse(req.body);
  // Transmiteți la Kafka, Slack, SIEM etc.
  kafkaProducer.send({ topic: 'tak-events', messages: [{ value: req.body }] });
  res.status(200).send('OK');
});

Eșecurile de livrare declanșează reîncercări cu backoff exponențial: 1, 2, 4, 8, 16 secunde. Vizualizați istoricul livrărilor: GET /api/webhook/{id}/deliveries.

Tipuri de evenimente webhook suportate

new_track — un nou UID apare pentru prima dată pe imagine.
track_stale — timestamp-ul stale al unui track a trecut fără actualizare.
mission_update — o misiune a fost creată, modificată, arhivată sau ștearsă.
user_join — un nou client s-a conectat și autentificat.
user_leave — un client s-a deconectat sau sesiunea a expirat.
cot_alert — un eveniment CoT cu prefixul de tip b-a (alertă) a fost primit.

Conectați-vă sistemele la ecosistemul TAK

Construim integrări API CloudTAK pentru rețele de senzori, platforme logistice, pipeline-uri de inferență AI și tablouri de bord C2 personalizate — și le alimentăm cu TAKpilot, copilotul nostru AI pentru operațiuni tactice.

Copilot AI TAKpilot → Rezervați un briefing

Această analiză a fost pregătită de inginerii Corvus Intelligence care construiesc software critic pentru organizații de apărare și guvernamentale. Aflați mai multe despre echipa noastră →

Întrebări frecvente

Ce metode de autentificare suportă API-ul REST CloudTAK?

API-ul REST CloudTAK suportă două metode de autentificare: token-uri JWT bearer și chei API statice. Token-urile JWT sunt emise prin POST /api/login și expiră după un TTL configurabil (implicit 24 ore). Cheile API sunt token-uri cu viață lungă generate prin API-ul admin, potrivite pentru integrări serviciu-la-serviciu.

Care este Content-Type corect pentru injectarea CoT prin API-ul REST?

Endpoint-ul de injectare CoT CloudTAK (POST /api/cot) acceptă două tipuri de conținut: application/xml pentru payload-uri CoT XML brute și application/json pentru un wrapper JSON pe care CloudTAK îl convertește intern în CoT XML. Includeți întotdeauna antetul Content-Type explicit.

Cum filtrez stream-ul WebSocket de track-uri la un grup specific sau zonă geografică?

Endpoint-ul WebSocket CloudTAK (/api/ws) acceptă un obiect filtru de abonare la momentul conexiunii. Filtrul suportă trei câmpuri: groups (tablou de nume de grupuri), bbox (casetă de delimitare GeoJSON [minLon, minLat, maxLon, maxLat]) și types (tablou de șiruri de tipuri CoT). Puteți actualiza filtrele pe o conexiune activă.

Care este limita de rată pe endpoint-ul de injectare CoT?

Limita implicită CloudTAK este de 100 evenimente CoT pe secundă per cheie API. Configurabilă prin variabila de mediu CLOUDTAK_COT_RATE_LIMIT sau per cheie prin API-ul admin. Dacă integrarea depășește limita, API-ul returnează HTTP 429 Too Many Requests cu un antet Retry-After.

Cum creez o misiune și atașez pachete de date prin API?

Crearea misiunii este un proces în doi pași: mai întâi POST la /api/mission cu un nume, descriere și atribuire opțională de grup pentru a obține un UID de misiune. Apoi POST la /api/mission/{uid}/attachment cu un corp multipart/form-data conținând fișierul pachetului de date (MBTiles, KMZ sau GeoJSON).

Pot încărca straturi de hartă MBTiles prin API-ul CloudTAK?

Da. POST la /api/layer cu un corp multipart/form-data conținând fișierul MBTiles și metadate (name, minZoom, maxZoom, bounds). CloudTAK validează formatul MBTiles și face stratul disponibil pentru toți clienții conectați. PMTiles este de asemenea suportat prin același endpoint.

Cum funcționează webhook-urile în CloudTAK?

Webhook-urile CloudTAK sunt înregistrate prin POST /api/webhook cu un URL țintă, tipuri de evenimente și un secret HMAC opțional pentru semnarea payload-ului. În caz de eșec, CloudTAK reîncercă cu backoff exponențial până de 5 ori.

Cum folosește TAKpilot API-ul CloudTAK pentru a executa comenzi în limbaj natural?

TAKpilot primește comenzi în limbaj natural de la operatori și le descompune în apeluri API CloudTAK. O comandă de marcare a unei locații devine POST /api/cot cu tipul CoT adecvat. TAKpilot menține un context de sesiune și consumă, de asemenea, stream-ul WebSocket reactiv.

La ce tipuri de evenimente mă pot abona prin WebSocket-ul CloudTAK?

Stream-ul WebSocket CloudTAK emite cinci tipuri de evenimente: cot (un eveniment CoT XML), track_update (o actualizare delta a unui track existent), mission_update (o misiune a fost creată, modificată sau ștearsă), user_event (un client s-a conectat, deconectat sau și-a schimbat indicativul) și system_event (evenimente de pe server). Abonați-vă selectiv folosind câmpul filtru types.

Cum versionez pachetele de date atașate la misiuni?

CloudTAK menține un istoric de versiuni pentru fiecare atașament de pachet de date. Fiecare încărcare la /api/mission/{uid}/attachment creează o nouă versiune. Versiunea curentă (cea mai recentă) este servită implicit. Pentru a recupera o versiune specifică, adăugați parametrul de interogare version: GET /api/mission/{uid}/attachment/{attachmentId}?version=2.