---
title: "Raporty — API v1 i MCP | Dokumentacja Nodea"
description: "Reference modułu Raporty: endpointy REST API v1 (lista raportów, raport, pobranie PDF), zakres account:read, uprawnienie konta products, narzędzie MCP client-reports-list."
url: "https://nodea.pl/pl/dokumentacja-api/client-reports"
lang: "pl"
updated: "2026-11-18"
---

# Raporty — API v1 i MCP | Dokumentacja Nodea

> Reference modułu Raporty — miesięczne raporty serwerów wysyłane przez Nodea: endpointy API v1 tylko do odczytu (lista, szczegóły, pobranie PDF), zakres account:read, narzędzie MCP i przykłady.

Moduł **Raporty** udostępnia miesięczne raporty serwerów, które Nodea wysyła na Twoje konto: wykorzystanie procesora, dysku i sieci, stan kopii zapasowych, dostępność monitorowanych stron, prace administracyjne i wykonane zlecenia — jako plik PDF za każdy miesiąc i grupę raportu. Ten sam widok jest w panelu pod `/app/client-reports`. Dokument opisuje warstwę REST API v1 (`/api/v1/client-reports*`) oraz narzędzie MCP tego modułu. Moduł jest tylko do odczytu.

## Uwierzytelnianie i zakresy (scopes)

API v1 uwierzytelnia się tokenem osobistym Passport przez nagłówek `Authorization: Bearer <token>`.

- `account:read` — wszystkie endpointy i narzędzie modułu.

Limit zapytań: `throttle:api-v1` = 240/min na użytkownika tokenu; pobieranie PDF dodatkowo 60/min. W MCP narzędzie wymaga dodatkowo zakresu transportowego `mcp:use`.

**Dostępność:** moduł jest udostępniany klientom stopniowo. Dopóki nie jest włączony dla klientów, endpointy zwracają `404`, a narzędzie MCP — błąd „Client reports are not available for this account yet.”.

## Konto klienta i widoczność

Raporty należą do **konta klienta** (patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts)). Żądanie działa w bieżącym koncie (przypięcie tokenu → nagłówek `X-Account-Id` → konto domyślne). Obok scope'a tokenu wymagane jest uprawnienie konta `products`. API zwraca wyłącznie raporty **wysłane** (`sent`) oraz **archiwalne** (`archived` — raporty z lat poprzednich zaimportowane z dawnego serwisu raportów). Szkice przygotowywane przez administratorów nie są zwracane. Raport innego konta — także innego konta tego samego użytkownika — odpowiada `404`, tak samo jak nieistniejący identyfikator. Okres to miesiąc kalendarzowy w formacie `YYYY-MM`; czasy zwracane są w UTC (ISO 8601 z `Z`).

## API v1 — endpointy

| Metoda | Ścieżka | Scope | Opis |
| --- | --- | --- | --- |
| GET | /api/v1/client-reports | account:read | Raporty bieżącego konta, od najnowszego miesiąca. Parametry: `period` (YYYY-MM — raport jednego miesiąca), `year` (2000–2100), `per_page` (1–100, domyślnie 20), `page`. |
| GET | /api/v1/client-reports/{id} | account:read | Jeden raport (metadane). `{id}` to identyfikator ULID z listy. |
| GET | /api/v1/client-reports/{id}/pdf | account:read | Plik PDF raportu: `Content-Type: application/pdf`, `Content-Disposition: attachment; filename="raport-YYYY-MM-<grupa>.pdf"`. |

### Odpowiedź — ClientReportResource

- `id` — identyfikator raportu (ULID).
- `period` — miesiąc raportu (YYYY-MM).
- `group_name` — nazwa grupy raportu (jeden raport może obejmować kilka serwerów).
- `brand` (`nodea`|`netgraf`|`mizzox`|`domenomania`|`alterpage`), `brand_label` — marka, pod którą raport wyszedł.
- `status` (`sent`|`archived`), `source` (`generated`|`archive`).
- `sent_at` — kiedy raport wysłano e-mailem (nullable; raporty archiwalne zwykle `null`).
- `pdf_size` — rozmiar pliku w bajtach (nullable), `pdf_url` — adres pobrania PDF (nullable, gdy plik nie jest dostępny).

Lista zwraca obok `data` standardowe `links` i `meta` paginacji; pojedynczy raport — obiekt w `data`.

```json
{
  "data": [{
    "id": "01jbx4w3k2m9q8r7t6v5y4z3a2",
    "period": "2026-09",
    "group_name": "Sklep",
    "brand": "nodea",
    "brand_label": "Nodea",
    "status": "sent",
    "source": "generated",
    "sent_at": "2026-10-06T08:12:00Z",
    "pdf_size": 248311,
    "pdf_url": "https://app.nodea.io/api/v1/client-reports/01jbx4w3k2m9q8r7t6v5y4z3a2/pdf"
  }],
  "links": { "first": "…", "last": "…", "prev": null, "next": null },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 }
}
```

### Kody błędów

- `401` — brak/niepoprawny token.
- `403` — brak scope'a `account:read`, brak kontekstu konta (`no_account_context`) albo brak uprawnienia `products` (`account_permission_denied`).
- `404` — moduł nie jest jeszcze dostępny dla klientów, raport nie istnieje, należy do innego konta, nie został jeszcze wysłany albo plik PDF jest niedostępny.
- `422` — niepoprawny `period`, `year` lub parametry paginacji.
- `429` — przekroczony limit zapytań.

## Przykłady — API

**REST API · curl**

```bash
curl -s "https://app.nodea.io/api/v1/client-reports?year=2026" \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"
```

**REST API · curl**

```bash
curl -s -o raport.pdf "https://app.nodea.io/api/v1/client-reports/01jbx4w3k2m9q8r7t6v5y4z3a2/pdf" \
  -H "Authorization: Bearer $NODEA_TOKEN"
```

## MCP — narzędzia

| Narzędzie | Scope | Argumenty | Opis |
| --- | --- | --- | --- |
| `client-reports-list` | account:read | `period`?, `year`?, `page`, `per_page` (≤100) | Raporty bieżącego konta — pola jak `ClientReportResource` (w tym `pdf_url` do pobrania przez API tym samym tokenem), plus `meta` paginacji. Szkice nie są zwracane. |

Narzędzie jest oznaczone jako read-only i idempotentne. Przykład wywołania JSON-RPC:

**MCP · JSON-RPC**

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"client-reports-list","arguments":{"year":2026}}}
```

Treść raportów (wykresy, podsumowanie) jest dostępna wyłącznie w pliku PDF; API nie udostępnia danych źródłowych raportu.

## Powiązane

- [Konta klientów — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/accounts)
- [Prace administracyjne — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/work-log)
- [Serwery — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/servers)

---

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