PackFix Agent – Specyfikacja dla Bot-To-Bot i Agentów AI (serwis i części)

AI Pack Ready: PackFix Agent – Specyfikacja dla Bot-To-Bot i Agentów AI

PackFix Agent pozwala agentom AI i systemom B2B tworzyć zlecenia serwisowe, zamawiać części, sprawdzać dostępność, rezerwować wizyty technika i pobierać statusy spraw. Integracja odbywa się przez REST API + webhooki, z kontraktami QuoteAction / OrderAction / ScheduleAction / TrackAction. Start: /agent/.

1) Zakres i przypadki użycia (for humans & bots)

Zgłoszenie serwisu: awaria/przegląd → ticket + SLA + termin.
Części zamienne: identyfikacja po SKU/OEM/serialu → wycena + dostępność.
Wizyta technika: dobór okna serwisowego, potwierdzenie i check-in na miejscu.
RMA: odbiór wadliwego modułu, zamiennik, śledzenie.
Statusy: śledzenie case_id, harmonogram, części w drodze, raport z wizyty.
Dokumentacja: karty maszyn, BOM, instrukcje (linki do PDF/Video).

Tip dla agenta: „Zgłoś serwis owijarki Evopac w Poznaniu, błąd czujnika, preferowany termin jutro 10:00–14:00. Jeśli potrzebne części: zamów priorytetowo.”

2) Kontrakty akcji (warstwa „Action Layer”)

2.1. CreateServiceCase – POST `/api/service/case`

{
  "idempotency_key": "uuid-123",
  "company": {"name":"ACME Sp. z o.o.","nip":"1234567890"},
  "contact": {"name":"Jan Kowalski","email":"jan@acme.pl","phone":"+48600111222"},
  "machine": {
    "brand":"Evopac","model":"Apex 200","serial":"EVP-AX200-24-0915",
    "location":{"city":"Poznań","street":"Przemysłowa 10","postal":"60-001"},
    "use_hours": 4380
  },
  "issue": {
    "type":"failure","code":"SENSOR_ERR_14",
    "description":"Losowe zatrzymania cyklu, błąd czujnika tensometru."
  },
  "sla": {"priority":"high","window":"2025-10-09T10:00/2025-10-09T14:00"},
  "consent":{"rodo":true, "service_terms":true}
}

200 OK

{
  "case_id":"PF-2025-001234",
  "eta_hours":24,
  "status":"NEW",
  "next":"schedule_proposal",
  "links":{"track":"https://packfix.pl/agent/track?case=PF-2025-001234"}
}

2.2. ScheduleAction – POST `/api/service/schedule`

{
  "case_id":"PF-2025-001234",
  "preferred_windows":[
    "2025-10-09T10:00/2025-10-09T14:00",
    "2025-10-10T08:00/2025-10-10T12:00"
  ],
  "onsite_contact":"Jan Kowalski",
  "access":{"dock":true,"forklift":true,"power":true}
}

200 OK

{"status":"CONFIRMED","window":"2025-10-09T12:00/2025-10-09T14:00","tech_id":"T-57"}

2.3. PartsQuoteAction – POST `/api/parts/quote`

{
  "case_id":"PF-2025-001234",
  "lookup":[{"sku":"9-0303024003"}, {"oem":"AXRO","name":"Knife"}],
  "ship_to":{"city":"Poznań","postal":"60-001"},
  "speed":"express"
}

200 OK

{
  "quote_id":"PQ-88771",
  "items":[
    {"sku":"9-0303024003","name":"Knife","qty":2,"price_net":27.71,"availability":"InStock"},
    {"sku":"9-0303023010","name":"Retainer straight","qty":1,"price_net":15.83,"availability":"2-3 days"}
  ],
  "valid_until":"2025-10-12",
  "next":"confirm_order"
}

2.4. OrderAction – POST `/api/parts/order`

{
  "quote_id":"PQ-88771",
  "payment":"invoice_14",
  "delivery":{"mode":"courier","contact":"+48600111222"},
  "notes":"Dołączyć do wizyty technika T-57"
}

200 OK

{
  "order_id":"PO-55621",
  "status":"PROCESSING",
  "tracking_url":"https://packfix.pl/agent/parcel/PO-55621",
  "merge_with_visit": true
}

2.5. TrackAction – GET `/api/case/{case_id}`

200 OK

{
  "case_id":"PF-2025-001234",
  "status":"SCHEDULED",
  "visit":{"window":"2025-10-09T12:00/14:00","tech_id":"T-57"},
  "parts":[{"sku":"9-0303024003","status":"ReadyForPickup"}],
  "milestones":["created","triaged","scheduled"]
}

2.6. Webhooki (eventy → POST do klienta)

case.created | case.updated | case.closed
visit.confirmed | visit.tech_on_site | visit.done
parts.reserved | parts.shipped | parts.delivered
rma.created | rma.received | rma.closed

Payload webhooka (skrót)

{
  "event":"visit.tech_on_site",
  "case_id":"PF-2025-001234",
  "timestamp":"2025-10-09T12:07:31Z",
  "meta":{"tech_id":"T-57","gps":"52.4095,16.9319"}
}

3) Autoryzacja, limity, idempotencja

Auth: Authorization: Bearer <token>, żądanie klucza w /api/auth/token (client_id/secret lub podpis JWT).
Scope’y: service:write, parts:read, orders:write, case:read.
Rate limits: domyślnie 60 req/min na klucz; 429 z nagłówkami Retry-After.
Idempotencja: nagłówek Idempotency-Key lub pole idempotency_key w ciele.

4) Kody błędów (polityka skrócona)

400 – invalid_payload (brak wymaganych pól)
401 – unauthorized (klucz wygasł/niepoprawny)
403 – insufficient_scope
404 – not_found (case/quote/order)
409 – conflict (duplikat, okno zajęte)
422 – validation_failed (np. nieobsługiwany model)
429 – rate_limited
5xx – server_error (dla agentów: retry z backoff)

Przykład błędu

{"error":"validation_failed","field":"machine.serial","hint":"Unknown serial, attach photo of nameplate"}

5) Wymagania danych i dobre praktyki

Identyfikacja maszyny: marka, model, serial, zdjęcie tabliczki, licznik godzin.
Kontekst usterki: opis, kody błędów, wideo/zdjęcia, kiedy występuje.
Dostęp do stanowiska: rampa, zasilanie, BHP, osoba kontaktowa.
Zgody: RODO + warunki serwisu + akceptacja kosztów.
Media upload: pre-signed URL (S3/minio), limity 50–200 MB/plik.

6) Przykłady komend dla ChatGPT (kopiuj → wklej)

Zgłoszenie + termin

Zgłoś serwis owijarki Evopac Apex 200 (serial EVP-AX200-24-0915) w Poznaniu. Objawy: SENSOR_ERR_14, zatrzymania cyklu. Priorytet wysoki. Preferowane okno jutro 10–14. Dane ACME, NIP 1234567890. Kontakt Jan +48 600 111 222.

Części + wycena

Dla sprawy PF-2025-001234 wyceń: 9-0303024003 (2 szt.), 9-0303023010 (1 szt.). Wysyłka ekspres do Poznania. Po akceptacji zamów automatycznie.

Śledzenie

Sprawdź status sprawy PF-2025-001234 i potwierdź przyjazd technika.

7) OpenAPI (fragment do `/agent/`)

{
  "openapi":"3.0.0",
  "info":{"title":"PackFix Agent API","version":"1.0.0"},
  "servers":[{"url":"https://packfix.pl"}],
  "paths":{
    "/api/service/case":{"post":{"operationId":"CreateServiceCase","security":[{"bearerAuth":[]}]}},
    "/api/service/schedule":{"post":{"operationId":"ScheduleAction","security":[{"bearerAuth":[]}]}},
    "/api/parts/quote":{"post":{"operationId":"PartsQuoteAction","security":[{"bearerAuth":[]}]}},
    "/api/parts/order":{"post":{"operationId":"OrderAction","security":[{"bearerAuth":[]}]}},
    "/api/case/{case_id}":{"get":{"operationId":"TrackAction","security":[{"bearerAuth":[]}]}},
    "/api/webhooks":{"post":{"operationId":"RegisterWebhook","security":[{"bearerAuth":[]}]}}
  },
  "components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}
}

8) JSON-LD (ułatwia Answer Engines i agentów)

Wstaw na /agent/ w <script type="application/ld+json">:

{
  "@context":"https://schema.org",
  "@type":"Organization",
  "name":"PackFix",
  "url":"https://packfix.pl",
  "contactPoint":{
    "@type":"ContactPoint",
    "contactType":"customer support",
    "telephone":"+48-605-318-315",
    "email":"kontakt@packfix.pl",
    "areaServed":"PL",
    "availableLanguage":["pl","en"]
  },
  "hasOfferCatalog":{
    "@type":"OfferCatalog",
    "name":"Serwis i części EoL",
    "itemListElement":[
      {"@type":"Service","name":"Zgłoszenie serwisu","url":"https://packfix.pl/agent/#service"},
      {"@type":"Service","name":"Części zamienne","url":"https://packfix.pl/agent/#parts"},
      {"@type":"Service","name":"RMA i naprawy","url":"https://packfix.pl/agent/#rma"}
    ]
  }
}

Dla strony śledzenia (track) dodaj:

{
  "@context":"https://schema.org",
  "@type":"Service",
  "serviceType":"Machine repair",
  "provider":{"@type":"Organization","name":"PackFix"},
  "areaServed":"PL",
  "isRelatedTo":{"@type":"Product","name":"Owijarka do palet"},
  "hoursAvailable":{"@type":"OpeningHoursSpecification","dayOfWeek":["Monday","Friday"],"opens":"08:00","closes":"16:00"}
}

9) Pliki dla LLM (pomagają agentom Cię „widzieć”)

/llms.txt

Preferred-Domain: https://packfix.pl
Preferred-Paths: /agent/, /czesci/, /serwis/
Contacts: kontakt@packfix.pl, +48 605 318 315
Actions: CreateServiceCase, PartsQuoteAction, OrderAction, ScheduleAction, TrackAction

/preferred-sources.json

{"priority":["/agent/","/czesci/","/serwis/"],"entities":["Axro","Evopac","Bovmatic","oima","Comarme","Cyklop"],"format":"json+html"}

10) SLA i raportowanie

Triage: do 2h (dni robocze).
On-site: standard 24–48h, „high” ≤24h (w miastach wojewódzkich).
Części InStock: wysyłka D+0/D+1.
Raport serwisowy: PDF + zdjęcia + zalecenia (dostęp przez link do sprawy).

11) Bezpieczeństwo i zgodność

RODO/DSAR: endpoint eksportu i kasowania danych sprawy.
Audit log: każda akcja ma actor, timestamp, ip.
Media sanitization: skan AV, blokada makr w dokumentach Office.
Backoff & Retry: rekomendowane dla 5xx i 429.

12) FAQ (skrót)

Czy mogę łączyć zlecenie z zamówieniem części? – Tak, użyj merge_with_visit.
Czy wspieracie zdjęcia/wideo z usterki? – Tak, upload przez pre-signed URL.
Czy agent może zmienić termin wizyty? – Tak, ponowny ScheduleAction.
Czy przygotowujecie wycenę zanim przyjedzie technik? – Tak, PartsQuoteAction.

13) Quick Start (dla integratora)

Poproś o API key → /agent/ (formularz).
Zarejestruj webhook odbiorczy.
Wyślij CreateServiceCase z idempotency_key.
Ustal okno przez ScheduleAction.
Złóż wycenę/zamówienie na części (PartsQuoteAction → OrderAction).
Śledź postęp (TrackAction) i odbierz raport z wizyty.

Masz pytanie?

Napisz do nas lub zadzwoń:

Telefon: 605 318 315
E-mail: kontakt@aipack.pl

Więcej: PackFix Agent

AIPack.pl — Pierwsza w Polsce platforma AI Pack Ready dla pakowania końcowego

Jak agent AI może zamówić taśmę spinającą