Dokumentacja integracji

Jak uwierzytelniać żądania do API Tracera, odbierać zdarzenia webhookiem i łączyć asystentów AI przez MCP, w imieniu Twojej organizacji.

Uwierzytelnianie kluczem API

Dołącz swój klucz API w nagłówku X-API-Key do każdego żądania. Utwórz klucz w zakładce Klucze API w ustawieniach organizacji.

curl "https://api.tracera.pl/api/v1/external/events?limit=20&eventType=report_completed" \
  -H "X-API-Key: ftk_your_api_key"

Pobieranie zdarzeń (pull)

GET /api/v1/external/events zwraca zdarzenia Twojej organizacji, stronicowane i opcjonalnie filtrowane po eventType. Limit żądań: 30/min na adres IP (burst 10). Parametr limit domyślnie 20, maksymalnie 100.

curl "https://api.tracera.pl/api/v1/external/events?limit=20&eventType=report_completed" \
  -H "X-API-Key: ftk_your_api_key"
{
  "content": [
    {
      "id": "3f2a9c34-1e9a-4c3b-9e2b-9a5d9a6b6b12",
      "organizationUUID": "8f6e2a3d-...-...-...",
      "eventType": "report_completed",
      "payload": { "reportId": "..." },
      "occurredAt": "2026-07-23T09:12:04.512Z"
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 20
}

Typy zdarzeń

Te same wartości eventType pojawiają się zarówno w odpowiedzi API, jak i w treści webhooka.

eventTypeOpis
user_registeredNowy użytkownik zarejestrował się w organizacji.
report_completedRaport inspekcji został ukończony.
alert_violationReguła alertu RCP została naruszona.
fault_reportedZgłoszono nową usterkę.
fault_resolvedUsterka została rozwiązana.
workflow_run_createdUruchomiono proces.
workflow_step_activatedKrok procesu stał się aktywny.
workflow_step_completedKrok procesu został zakończony.
workflow_step_timed_outKrok procesu przekroczył termin i oznaczono go jako przeterminowany.
workflow_run_completedWszystkie kroki procesu są zakończone.

Wpisy RCP (pull)

GET /api/v1/external/rcp/entries zwraca odbicia RCP (check-in/check-out) Twojej organizacji w zadanym zakresie dat, stronicowane. Ze względu na wysoką częstotliwość te dane nie są wysyłane webhookiem – pobieraj je okresowo. Zakres domyślny to ostatnie 30 dni, limit domyślnie 20, maksymalnie 100.

curl "https://api.tracera.pl/api/v1/external/rcp/entries?from=2026-07-01T00:00:00Z&to=2026-07-31T23:59:59Z&limit=50" \
  -H "X-API-Key: ftk_your_api_key"
{
  "content": [
    {
      "id": "6a1e2b3c-4d5e-...-...-...",
      "userId": 42,
      "entryType": "check_in",
      "scannedAt": "2026-07-23T07:58:11Z",
      "status": "valid",
      "nfcTagId": 7,
      "nfcTagUuid": "9c8b7a6d-...-...-..."
    }
  ],
  "total": 964,
  "page": 1,
  "limit": 50
}

Usterki (pull)

GET /api/v1/external/faults zwraca usterki Twojej organizacji, stronicowane i opcjonalnie filtrowane po status oraz severity. Limit domyślnie 20, maksymalnie 100.

curl "https://api.tracera.pl/api/v1/external/faults?status=open&limit=20" \
  -H "X-API-Key: ftk_your_api_key"
{
  "content": [
    {
      "id": "b2f1a3c4-...-...-...",
      "tagId": 7,
      "reporterId": 42,
      "assigneeId": 15,
      "title": "Leaking valve",
      "description": "Valve on line 3 is leaking coolant.",
      "severity": "high",
      "status": "open",
      "createdAt": "2026-07-20T08:15:00Z",
      "updatedAt": "2026-07-20T08:15:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

Inspekcje (pull)

GET /api/v1/external/inspections zwraca inspekcje Twojej organizacji, stronicowane i filtrowane po status, type oraz nfcTagId. Limit domyślnie 20, maksymalnie 100. Każda inspekcja zawiera templateId i templateName szablonu, z którego została wypełniona.

curl "https://api.tracera.pl/api/v1/external/inspections?status=completed&limit=20" \
  -H "X-API-Key: ftk_your_api_key"
{
  "content": [
    {
      "id": "c3d2e1f0-...-...-...",
      "inspectionType": "checklist",
      "status": "completed",
      "scannedAt": "2026-07-22T11:00:00Z",
      "completedAt": "2026-07-22T11:20:00Z",
      "progress": 100,
      "templateId": "5d4c3b2a-...-...-...",
      "templateName": "Vehicle handover",
      "nfcTag": { "id": "9c8b7a6d-...-...-...", "name": "Pump Station A" },
      "user": { "id": "1a2b3c4d-...-...-...", "firstName": "Anna", "lastName": "Kowalska" },
      "createdAt": "2026-07-22T11:00:00Z"
    }
  ],
  "total": 340,
  "page": 1,
  "limit": 20
}

Szczegóły inspekcji (pull)

GET /api/v1/external/inspections/{id} zwraca jedną inspekcję z notatkami, pozycjami checklisty (status, notatka, wartości pól) i usterkami. Każda pozycja checklisty i usterka zawiera zdjęcia jako pliki z podpisanym, czasowo ważnym adresem url – pobierz je od razu albo zapytaj o inspekcję ponownie, aby dostać nowe linki.

curl "https://api.tracera.pl/api/v1/external/inspections/c3d2e1f0-...-...-..." \
  -H "X-API-Key: ftk_your_api_key"
{
  "id": "c3d2e1f0-...-...-...",
  "inspectionType": "checklist",
  "status": "completed",
  "templateName": "Vehicle handover",
  "nfcTag": { "id": "9c8b7a6d-...-...-...", "name": "KR 12345" },
  "completedAt": "2026-07-22T11:20:00Z",
  "notes": "Handed over with full tank.",
  "checklistEntries": [
    {
      "id": "e1d2c3b4-...-...-...",
      "templateItemName": "Front bumper",
      "status": "ok",
      "note": "Small scratch, left corner.",
      "files": [
        { "id": "f1...", "url": "https://signed.example/front.jpg?...", "contentType": "image/jpeg" }
      ]
    }
  ],
  "findings": [
    { "id": "a9b8c7d6-...-...-...", "severity": "low", "description": "Dent on rear door", "files": [] }
  ]
}

Raport PDF inspekcji (pull)

GET /api/v1/external/inspections/{id}/report zwraca podpisany, czasowo ważny downloadUrl najnowszego gotowego raportu PDF. Do czasu zakończenia generowania raportu odpowiada 404; zdarzenie report_completed informuje, że raport jest gotowy.

curl "https://api.tracera.pl/api/v1/external/inspections/c3d2e1f0-...-...-.../report" \
  -H "X-API-Key: ftk_your_api_key"
{
  "id": "7b6a5c4d-...-...-...",
  "downloadUrl": "https://signed.example/report.pdf?...",
  "createdAt": "2026-07-22T11:21:00Z"
}

Tagi NFC / zasoby

GET /api/v1/external/nfc-tags zwraca pełną listę tagów NFC (zasobów) Twojej organizacji. Bez stronicowania – inwentarz tagów w organizacji jest niewielki, więc całość zwracana jest w jednym żądaniu.

curl "https://api.tracera.pl/api/v1/external/nfc-tags" \
  -H "X-API-Key: ftk_your_api_key"
{
  "content": [
    {
      "id": "9c8b7a6d-...-...-...",
      "name": "Pump Station A",
      "location": "Building 2, Level 1",
      "hardwareUid": "04a1b2c3d4e5",
      "role": "inspection"
    }
  ],
  "total": 58
}

Procesy (start i callback)

POST /api/v1/external/workflow-runs uruchamia proces opublikowanego i włączonego workflow dla obiektu z Twojego systemu (subjectType: małe litery, cyfry i podkreślenia; subjectId do 128 znaków; opcjonalny obiekt context do 32 KB). Klucz API musi mieć zakres workflows; klucze bez niego dostają 403.

curl -X POST "https://api.tracera.pl/api/v1/external/workflow-runs" \
  -H "X-API-Key: ftk_your_api_key" \
  -H "Idempotency-Key: order-7781" \
  -H "Content-Type: application/json" \
  -d '{"workflowId":"8f6e2a3d-...-...-...","subjectType":"vehicle","subjectId":"KR 12345","context":{"title":"Brake check"}}'
{
  "id": "5b1c9d7e-...-...-...",
  "status": "active",
  "subjectType": "vehicle",
  "subjectId": "KR 12345",
  "source": "api",
  "needsAttention": false,
  "steps": [
    { "key": "approval", "type": "wait_for_callback", "status": "active" },
    { "key": "repair", "type": "human_task", "status": "pending" }
  ]
}

Wyślij nagłówek Idempotency-Key (do 128 liter, cyfr i . _ : -), aby ponowienie nie uruchomiło drugiego procesu: ten sam klucz z tą samą treścią zwraca pierwotną odpowiedź z nagłówkiem Idempotent-Replayed: true; ten sam klucz z inną treścią to 409. Klucze są pamiętane przez 24 godziny.

Kończenie oczekującego kroku

Krok wait_for_callback pozostaje aktywny, dopóki nie wywołasz POST /api/v1/external/workflow-runs/{runId}/steps/{stepKey}/complete z opcjonalnym obiektem data (do 64 KB), zapisywanym jako wynik kroku. Wszystko poza aktywnym krokiem callback zwraca 409.

curl -X POST "https://api.tracera.pl/api/v1/external/workflow-runs/5b1c9d7e-...-...-.../steps/approval/complete" \
  -H "X-API-Key: ftk_your_api_key" \
  -H "Idempotency-Key: approval-7781" \
  -H "Content-Type: application/json" \
  -d '{"data":{"approved":true,"ticket":"T-9"}}'

Błędy: 400 nieprawidłowa treść, obiekt lub klucz idempotencji; 401 brak lub zły klucz; 403 klucz bez zakresu workflows; 404 nieznany workflow lub proces; 409 konflikt idempotencji albo krok nie czeka.

Zdarzenia procesów

Zdarzenia procesów mają tę samą kopertę co pozostałe zdarzenia, w endpointcie zdarzeń i webhookach. Zdarzenia kroków zawierają stepKey, stepType i result.

{
  "id": "3f2a9c34-1e9a-4c3b-9e2b-9a5d9a6b6b12",
  "organizationUUID": "8f6e2a3d-...-...-...",
  "eventType": "workflow_step_completed",
  "payload": {
    "runId": "5b1c9d7e-...-...-...",
    "subjectType": "vehicle",
    "subjectId": "KR 12345",
    "source": "api",
    "status": "done",
    "stepKey": "approval",
    "stepType": "wait_for_callback",
    "result": { "approved": true }
  },
  "occurredAt": "2026-10-28T09:12:04.512Z"
}

Serwer MCP (asystenci AI)

Bezpieczeństwo

Podłącz Claude Code, Claude Desktop lub dowolnego klienta MCP obsługującego zdalne serwery HTTP do danych Twojej organizacji. Uwierzytelnianie tym samym kluczem X-API-Key co REST API – bez dodatkowej konfiguracji.

claude mcp add --transport http tracera https://api.tracera.pl/api/v1/external/mcp \
  --header "X-API-Key: ftk_your_api_key"

Dostępne narzędzia – każde odpowiada endpointowi REST powyżej i przyjmuje te same filtry jako argumenty tekstowe:

list_inspectionsget_inspectionget_inspection_reportlist_faultslist_nfc_tagslist_eventslist_rcp_entries

Lub wywołaj narzędzie bezpośrednio (JSON-RPC 2.0 przez POST), żeby sprawdzić klucz:

curl -X POST "https://api.tracera.pl/api/v1/external/mcp" \
  -H "X-API-Key: ftk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_faults","arguments":{"status":"open","limit":"5"}}}'

Tylko do odczytu: narzędzia wyłącznie czytają dane i niczego nie zmieniają. Zakres ograniczony do organizacji klucza API – identyfikator organizacji podany w argumentach jest ignorowany. Unieważnienie klucza natychmiast odcina dostęp. Obowiązuje ten sam limit żądań co API (30 żądań/min na IP); wywołanie narzędzia liczy się jako dwa żądania.

Webhooki (push)

Każde zdarzenie jest wysyłane jako POST na Twój targetUrl (musi być https://). Zweryfikuj nagłówek X-FieldTag-Signature sekretem pokazanym przy tworzeniu webhooka, zanim zaufasz treści żądania.

{
  "id": "3f2a9c34-1e9a-4c3b-9e2b-9a5d9a6b6b12",
  "organizationUUID": "8f6e2a3d-...-...-...",
  "eventType": "report_completed",
  "payload": { "reportId": "..." },
  "occurredAt": "2026-07-23T09:12:04.512Z"
}

Dostarczenie ponawiane jest do 3 razy przy błędzie lub statusie spoza zakresu 2xx, z limitem czasu 5 s na próbę.

Weryfikacja podpisu

Bezpieczeństwo
const crypto = require("crypto")

function isValidSignature(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
}
import hashlib
import hmac

def is_valid_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)