Sprawy klientów

Jak przez API i serwer MCP zakładać, czytać i prowadzić sprawy — jeden rekord na problem klienta, niezależnie od tego, ile było rozmów.

Sprawa zbiera w jednym miejscu problem klienta, który ciągnie się przez kilka rozmów, e-maili czy czatów: awarię, zgłoszenie serwisowe, reklamację, pytanie wymagające odpowiedzi. Ma numer, status, priorytet, kategorię, osobę odpowiedzialną, notatki wewnętrzne i powiązania z rozmowami, z których wyrosła.

Dla kogo

Sprawy są dostępne w organizacjach biznesowych, które mają je włączone. Gdzie spraw nie ma, Portal nie pokazuje ich zakresów przy generowaniu klucza ani narzędzi w zakładce MCP, a trasy /cases odpowiadają 404 TENANT_MODULE_UNAVAILABLE (typ działalności bez spraw) albo 403 FEATURE_NOT_AVAILABLE (sprawy jeszcze niewłączone).

Zakresy

Zakres	Co daje
`cases.read`	Lista spraw, szczegóły, notatki i powiązania.
`cases.write`	Zakładanie i edycja spraw, notatki, powiązania. Zawiera `cases.read`.

Oba zakresy są tylko na wprost: * ani *.* ich nie przyznają. Tytuły, opisy, lokalizacje i notatki to dane osobowe klientów — klucz musi je wymienić z nazwy.

Zadania należące do sprawy (tasks w szczegółach sprawy) wracają tylko wtedy, gdy klucz ma też tasks.read. Bez niego pole ma wartość null.

Model

Pole	Opis
`number`	Numer sprawy w Twojej organizacji. W Portalu wyświetlany jako `S-1042`.
`status`	`NEW`, `IN_PROGRESS`, `WAITING_CUSTOMER`, `WAITING_THIRD_PARTY`, `RESOLVED`, `CLOSED`, `CANCELLED`. Zmiana statusu ustawia `statusChangedAt`, a przejście do `RESOLVED` lub `CLOSED` — odpowiednio `resolvedAt` lub `closedAt`.
`priority`	`LOW`, `MEDIUM`, `HIGH`, `URGENT`.
`categoryKey`	Kategoria z zestawu Twojej branży, np. `question`, `complaint`, `service_request`, `bug`, `outage`, `water_leak`, `heating`. Zawsze można użyć `other`. Nieznany klucz przy zapisie to `422`; przy odczycie parsuj kategorie tolerancyjnie — lista może się wydłużyć.
`contact`, `company`, `topic`	Kogo dotyczy sprawa i jakiego obszaru (temat rozmowy). `company` tylko w organizacjach, które prowadzą firmy.
`source`	Skąd sprawa przyszła: `API`, `MCP`, `PORTAL`, `CALL`, `BOT`… Dla `API` i `MCP` `sourceIdentifier` to identyfikator klucza API, który ją założył. `BOT` to sprawa założona przez bota Mediflo w trakcie rozmowy: `sourceIdentifier` ma postać `<identyfikator bota>:<identyfikator rozmowy>`, a w `links` jest rozmowa z botem (dla rozmów telefonicznych).
`externalRef`, `externalUrl`	Numer i link sprawy w Twoim własnym systemie.
`customFields`	Dodatkowe pola formularza sprawy Twojej branży (np. numer lokalu). Odczyt zwraca tylko pola bieżącego formularza. `PATCH` z `customFields` zastępuje cały ich zestaw — pole pominięte zostaje wyczyszczone — a `customFields: null` to `422`.
`links`	Powiązane rozmowy telefoniczne, rozmowy z botem, konwersacje e-mail, czat i SMS/WhatsApp oraz prośby o kontakt.

Najczęstsze operacje

Założenie sprawy z rozmowy, którą właśnie obsłużył Twój system:

curl -X POST https://app.mediflo.ai/api/external/v1/cases \
  -H "Authorization: Bearer mflo_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Brak dostępu do panelu po aktualizacji",
    "categoryKey": "bug",
    "priority": "HIGH",
    "contactId": "6f1c…",
    "externalRef": "JIRA-4821",
    "links": [{ "resourceType": "TELEPHONY_CALL", "resourceId": "9b2e…" }]
  }'

Odpowiedź 201 zawiera całą sprawę, razem z number. Każdy wskazany rekord (kontakt, firma, temat, osoba, tagi, powiązania) musi należeć do Twojej organizacji — inaczej 422 VALIDATION_ERROR z nazwą pola.

Zmiana statusu i przypisania — wysyłasz tylko to, co się zmienia, a null czyści pole:

curl -X PATCH https://app.mediflo.ai/api/external/v1/cases/{caseId} \
  -H "Authorization: Bearer mflo_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "WAITING_CUSTOMER", "assignedToUserId": "c41d…" }'

Pozostałe operacje:

GET /cases?open=true&assignedTo=unassigned — otwarte sprawy bez przypisanej osoby. status i category przyjmują listy po przecinku (nieznany status albo błędnie zapisana kategoria to 422, nigdy szerszy wynik), search szuka w tytule albo po numerze (1042, S-1042), a resourceType z resourceId zwracają sprawy powiązane z jednym rekordem, np. rozmową.
GET /cases/{caseId}/comments i POST /cases/{caseId}/comments — notatki wewnętrzne. Lista zwraca 200 najnowszych, od najstarszej.
POST /cases/{caseId}/links i DELETE /cases/{caseId}/links/{linkId} — powiązania. Ponowne powiązanie tego samego rekordu zwraca 200 z istniejącym powiązaniem, więc ponowienie żądania jest bezpieczne.

Sprawy nie da się usunąć przez API — usuwanie zostaje w Portalu.

Serwer MCP

Asystent AI z kluczem lub logowaniem OAuth dostaje cztery narzędzia: list_cases, get_case, create_case i update_case. Działają na tych samych zasadach co REST — te same zakresy, walidacja i pola odpowiedzi. Przy logowaniu przez OAuth zakresy wynikają z uprawnień w Portalu: cases.view daje cases.read, a cases.manage daje cases.write.

Piąte narzędzie z katalogu, create_caller_case, należy wyłącznie do botów Mediflo: bot z włączonym zakładaniem spraw zakłada nim sprawę dla dzwoniącego i odczytuje mu jej numer. Klucz API organizacji ani logowanie OAuth go nie dostają — i odwrotnie, bot nie dostaje czterech narzędzi powyżej.

Referencja REST

Wszystkie operacje na sprawach z pełnymi schematami żądań i odpowiedzi.

Narzędzia MCP

Schematy wejścia narzędzi spraw i wymagane zakresy.