---
title: "Cesja usług — API v1 i MCP | Dokumentacja Nodea"
description: "Reference modułu Cesja usług: endpointy REST API v1 (lista, szczegóły, anulowanie, kwalifikacja usługi), zakresy account:read i account:write, statusy, kody błędów i narzędzia MCP."
url: "https://nodea.pl/pl/dokumentacja-api/cessions"
lang: "pl"
updated: "2026-11-18"
---

# Cesja usług — API v1 i MCP | Dokumentacja Nodea

> Reference modułu Cesja usług — odczyt cesji bieżącego konta, sprawdzenie, czy usługę można scedować, i anulowanie własnej cesji przez API v1 i MCP. Zgłoszenie, przyjęcie i zatwierdzenie odbywają się w panelu.

Moduł **Cesja usług** pozwala przenieść wybrane usługi (razem z ich zasobami i — z wyboru zgłaszającego — z zaległościami) z jednego konta klienta na inne. Cesję zgłasza właściciel konta oddającego usługi (cedent) w panelu, osoba przyjmująca potwierdza ją z linku w e-mailu i akceptuje regulamin cesji, a na końcu cesję zatwierdza administrator Nodea. API v1 i MCP udostępniają wyłącznie **odczyt**, **sprawdzenie, czy usługę można scedować**, oraz **anulowanie** własnej cesji. Zgłoszenie, przyjęcie i zatwierdzenie są oświadczeniami woli z akceptacją regulaminu, świeżym hasłem i drugim składnikiem logowania — tego token API nie zapewnia, więc odbywają się tylko w panelu (`/app/cessions`).

## Dostępność modułu

Moduł jest włączany stopniowo. Endpointy i narzędzia MCP działają tylko wtedy, gdy moduł jest włączony dla użytkownika tokenu **i** opublikowano regulamin cesji. W przeciwnym razie każdy endpoint odpowiada `404`, a narzędzia MCP nie występują na liście (`tools/list`) i ich wywołanie kończy się błędem „Tool \[...\] not found.”.

## Uwierzytelnianie i zakresy (scopes)

Token osobisty Passport w nagłówku `Authorization: Bearer <token>`. Wymagane zakresy:

- `account:read` — lista i szczegóły cesji, sprawdzenie kwalifikacji usługi.
- `account:write` — anulowanie cesji.

Limit zapytań: `throttle:api-v1`. W MCP każde narzędzie wymaga dodatkowo zakresu transportowego `mcp:use`. Moduł nie wprowadza nowych zakresów.

## Konto klienta i widoczność

Żądanie działa w bieżącym koncie (przypięcie tokenu → nagłówek `X-Account-Id` → konto domyślne; patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts)). Członek konta potrzebuje uprawnienia `manageproducts` (właściciel ma wszystkie). Widoczne są cesje, w których bieżące konto jest stroną:

- `outgoing` — konto oddaje usługi (cedent);
- `incoming` — konto przyjęło usługi jako cesjonariusz (cesja jest widoczna po akceptacji przez osobę przyjmującą).

Cesja, której bieżące konto nie jest stroną, oraz usługa spoza bieżącego konta zwracają `404` — istnienie nie jest potwierdzane.

**Bezpieczeństwo:** odpowiedzi nigdy nie zawierają tokenu z linku zaproszenia ani jego skrótu. Strona przyjmująca nie widzi notatek administratora ani adresu e-mail wpisanego przez cedenta, a cedent widzi nazwę konta cesjonariusza dopiero po akceptacji.

## Przebieg i statusy

Statusy: `awaiting_recipient` | `awaiting_admin` | `approved` | `executing` | `completed` | `failed` | `declined` | `rejected` | `cancelled` | `expired`.

- `awaiting_recipient` — czeka na potwierdzenie osoby przyjmującej (link ważny 7 dni, potem `expired`).
- `awaiting_admin` — przyjęta, czeka na zatwierdzenie administratora (14 dni, potem `expired`).
- `approved`, `executing` — zatwierdzona, w trakcie wykonania; od tej chwili nie można jej anulować.
- `completed` — wykonana: usługi są na koncie cesjonariusza.
- `failed` — wykonanie nie powiodło się, nic nie zostało przeniesione; decyzję podejmuje administrator.
- `declined` (odmowa osoby przyjmującej), `rejected` (odrzucona przez administratora, z powodem), `cancelled` (anulowana), `expired` (wygasła) — stany końcowe.

## API v1 — endpointy

| Metoda | Ścieżka | Scope | Opis |
| --- | --- | --- | --- |
| GET | /api/v1/cessions | account:read | Cesje bieżącego konta (obie strony), najnowsze pierwsze. Parametry: `status` (opcjonalny, jedna z wartości statusu), `direction` (opcjonalny: `outgoing` \| `incoming`), `per_page` (1–100, domyślnie 20), `page`. |
| GET | /api/v1/cessions/{public\_id} | account:read | Szczegóły jednej cesji. `public_id` to 26-znakowy identyfikator z pola `id`. |
| POST | /api/v1/cessions/{public\_id}/cancel | account:write | Anulowanie cesji wychodzącej przez **właściciela** konta cedenta, gdy cesja czeka na osobę przyjmującą albo na administratora. Body (opcjonalne): `{"reason": "…"}` (do 500 znaków, widoczny dla drugiej strony). Odpowiedź: cesja ze statusem `cancelled`. |
| GET | /api/v1/services/{id}/cession-eligibility | account:read | Czy usługę bieżącego konta można teraz scedować, a jeśli nie — dlaczego (klucz powodu). |

### Odpowiedź — cesja

- `id` — identyfikator publiczny (26 znaków); `direction` — `outgoing` | `incoming`; `kind` — `customer` (zgłoszona przez klienta) | `admin_assisted` (przeprowadzona przez administratora za zgodą stron) | `reversal` (cesja zwrotna).
- `status` (jak wyżej), `status_label` (etykieta w języku żądania), `status_tone` — `neutral` | `info` | `success` | `danger`.
- `currency` (np. `PLN`), `transfer_debt` (bool — czy zaległości przechodzą na cesjonariusza), `debt_cents` (kwota zaległości przenoszonych: zaakceptowana przez cesjonariusza, a przed akceptacją — wyliczona przy zgłoszeniu), `debt_cents_executed` (kwota faktycznie przeniesiona, po wykonaniu; inaczej null).
- `from_account` — `{ name }`; `to_account` — `{ name }` albo null (dla cedenta do czasu akceptacji).
- `recipient_email` — adres wpisany przez cedenta (tylko dla `outgoing`, dla `incoming` null); `cedent_note` — notatka cedenta; `rejection_reason` — powód odrzucenia przez administratora.
- Daty (ISO 8601, nullable): `submitted_at`, `token_expires_at` (ważność linku zaproszenia — sam token nigdy nie jest zwracany), `recipient_accepted_at`, `admin_due_at`, `approved_at`, `rejected_at`, `cancelled_at`, `expired_at`, `executed_at`; `failed` (bool).
- `items` — usługi objęte cesją: `[{ service_id, label, is_addon, debt_cents, resources: [{ type, label }] }]` (`service_id` null, gdy usługa już nie istnieje; dodatki przechodzą razem z usługą nadrzędną).
- `debt_lines` — pozycje zaległości: `[{ kind, state, amount_cents }]`; `kind` — `uninvoiced` (przechodzi przy `transfer_debt`) | `invoiced` (zafakturowane — zostaje u cedenta); `state` — `snapshot` | `transferred` | `dropped_paid` | `dropped_void`.

Lista zwraca `{ data: [...], meta: { current_page, per_page, total, last_page } }`, szczegóły i anulowanie `{ data: {...} }`. Ten sam kształt zwracają narzędzia MCP i panel (jeden serializer).

### Odpowiedź — kwalifikacja usługi

- `service_id`, `eligible` (bool).
- `reason` — klucz powodu albo null, `message` — opis powodu w języku żądania albo null. Klucze: `service_not_nodea` | `service_status` | `billing_hold` | `addon` | `domain` | `in_open_cession` | `deletion_request_open` | `upgrade_pending` | `foreign_resource` | `not_on_cedent_account` | `hourly_negative_balance` | `cedent_account_inactive`.
- `requires_debt_transfer` (bool) — usługa zawieszona: można ją scedować tylko razem z zaległościami.

Domeny nie podlegają cesji (`domain`) — zmiana abonenta domeny odbywa się u rejestratora. Dodatek (np. dodatkowy adres IP) przechodzi razem z usługą, do której należy (`addon`).

### Kody błędów

- `401` — brak/niepoprawny token.
- `403` — brak scope'a (np. `account:read` bez `account:write` przy anulowaniu), brak kontekstu konta (`no_account_context`), brak uprawnienia `manageproducts` (`account_permission_denied`) albo anulowanie przez kogoś innego niż właściciel konta cedenta (`account_owner_required` — także strona przyjmująca).
- `404` — moduł niedostępny, nieznana cesja albo cesja / usługa spoza bieżącego konta.
- `409` — `state_changed`: stanu cesji nie można już zmienić (np. anulowanie cesji zatwierdzonej) albo zmienił się w międzyczasie.
- `422` — niepoprawne parametry (`status`, `direction`, `per_page`, `reason` dłuższy niż 500 znaków).
- `423` — `locked`: obiekt jest objęty otwartą cesją; tę odpowiedź zwracają inne operacje na usłudze (np. usunięcie albo zmiana planu) w trakcie cesji.

## Przykłady — API

### Cesje wychodzące czekające na administratora

**REST API · curl**

```bash
curl -s "https://app.nodea.io/api/v1/cessions?direction=outgoing&status=awaiting_admin" \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"
```

### Czy usługę można scedować

**REST API · curl**

```bash
curl -s https://app.nodea.io/api/v1/services/971/cession-eligibility \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"
```

### Anulowanie cesji

**REST API · curl**

```bash
curl -s -X POST https://app.nodea.io/api/v1/cessions/01jcz7k3m9q2w8e4r6t0y5u1i3/cancel \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Zmiana planów"}'
```

## MCP — narzędzia

Narzędzia MCP dzielą model uwierzytelniania, zakresów i konta z API v1 i zwracają te same pola. Cesja albo usługa spoza bieżącego konta zwraca ten sam błąd co nieistniejąca. Odmowy kończą się sufiksem maszynowym, np. `(code: state_changed)` albo `(code: account_owner_required)`.

| Narzędzie | Scope | Tryb | Opis |
| --- | --- | --- | --- |
| cessions-list | account:read | read-only | Lista cesji bieżącego konta; `status`, `direction` (opcjonalne), `page`, `per_page` (max 50). Pola jak w odpowiedzi API, plus `meta` paginacji. |
| cession-get | account:read | read-only | Jedna cesja; `id` (identyfikator publiczny, wymagany). |
| cession-cancel | account:write | destructive | Anulowanie cesji wychodzącej przez właściciela konta; `id`, `confirm: true` (wymagane), `reason` (opcjonalny). |
| service-cession-eligibility | account:read | read-only | Kwalifikacja usługi do cesji; `service_id` (wymagany). Pola jak w odpowiedzi API. |

### Przykład — MCP (JSON-RPC)

**MCP · JSON-RPC**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "service-cession-eligibility",
    "arguments": { "service_id": 971 }
  }
}
```

## Powiązane

- [Konta klientów — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/accounts)
- [Rozliczenia (billing) — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/billing)
- [Dokumenty prawne — API v1 | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/legal)

---

Wersje językowe: [en](https://nodea.io/en/api-docs/cessions.md)  
Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)
