Jak działa PrinterTracker i jak z nim rozmawiać

Jak działa PrinterTracker

PrinterTracker zbiera liczniki i stan kopiarek u klientów serwisu i pokazuje je w jednym panelu. Składa się z trzech części: agenta w sieci każdej lokalizacji klienta, chmury, która przyjmuje i interpretuje dane, oraz panelu serwisu. Odczyty nie kończą drogi w panelu — pobiera je system rozliczeniowy przez publiczne API.

1. 1. Agent skanuje sieć klienta

   Mały program (Windows lub Linux) w sieci klienta pyta drukarki przez SNMP o liczniki, materiały eksploatacyjne i stan. Domyślnie co 15 minut, zakres sieci ustawiasz w panelu.

2. 2. Dane idą do chmury tylko w jedną stronę

   Agent sam łączy się z api.printertracker.com przez HTTPS (port 443). Nic nie nasłuchuje w sieci klienta, nie trzeba otwierać portów ani VPN.

3. 3. Chmura interpretuje surowe dane

   Serwer rozpoznaje model po numerze seryjnym i identyfikatorze SNMP, liczy liczniki mono / kolor / skan z profili producentów, wykrywa awarie i niskie stany tonerów. Nowy model to aktualizacja serwera, nie agentów.

4. 4. Serwis widzi wszystko w panelu

   Grupy (klienci) → podgrupy (lokalizacje) → urządzenia. Alerty, historia liczników, prognoza końca tonera, powiadomienia e-mail.

5. 5. Odczyty trafiają do rozliczeń

   PrinterTracker nie wystawia faktur. Odczyty pobiera system rozliczeniowy (PrinterController w MERP lub dowolny inny) przez publiczne API opisane niżej.

Model danych

• Grupa — klient serwisu (firma, szpital, urząd). Ma NIP i identyfikator klienta w MERP, po którym dopasujesz go w swoim systemie.
• Podgrupa — lokalizacja klienta: jedna sieć, jeden agent. Klient z trzema budynkami ma trzy podgrupy.
• Urządzenie — drukarka lub kopiarka rozpoznana po numerze seryjnym. Nowo wykryte urządzenie czeka na zatwierdzenie w panelu (state = new), potem jest monitorowane (active) albo ignorowane.
• Odczyt liczników — migawka liczników urządzenia. Chmura trzyma najwyżej jeden odczyt na urządzenie na godzinę. W obrębie godziny nowszy odczyt zastępuje starszy, dopóki nie został przekazany do rozliczeń — potem jest niezmienny.
• Alert — problem wyliczony ze stanu (agent nie odpowiada, brak odczytów, awaria, nieznany materiał) albo wystąpienie alertu skonfigurowanego przez serwis (np. toner poniżej 10%). Alert znika, gdy problem mija.

Agent SNMP w sieci klienta

Agent to jedna statyczna binarka bez zależności: usługa Windows albo systemd na Linuksie. Instaluje go dział IT klienta jednym poleceniem z linku instalacyjnego wysłanego z panelu; link jest ważny 14 dni i gaśnie po pierwszej instalacji.

Czego potrzebuje

• Ruch wychodzący HTTPS na api.printertracker.com (port 443). Nic więcej: bez portów przychodzących, bez VPN, bez przekierowań.
• Dostęp do drukarek po SNMP (UDP 161) w sieci, w której stoi komputer z agentem. Agent próbuje SNMPv2c, a gdy drukarka odpowiada tylko na SNMPv1 (np. część Canonów), przełącza się automatycznie. Community public; zakresy sieci do skanowania ustawia serwis w panelu.
• Windows (amd64, arm64) albo Linux z systemd (amd64, arm64). Jedna binarka, bez dodatkowych zależności.

Czego nie robi

• Nie czyta treści wydruków, książek adresowych ani historii zadań — pobiera liczniki, materiały, stan i konfigurację techniczną.
• Nie nasłuchuje na żadnym porcie i nie przyjmuje połączeń — także od PrinterTracker. Konfigurację odbiera przy każdym własnym kontakcie z chmurą.
• Nie aktualizuje się sam. Nową wersję instaluje się tym samym poleceniem; stara instalacja jest odcinana po pierwszym kontakcie nowej.

Każdy agent ma własny klucz powiązany z jedną podgrupą. Klucz da się unieważnić w panelu w każdej chwili — od tej pory agent dostaje 401 i nic już nie wysyła.

Publiczne REST API

Publiczne API pod adresem https://api.printertracker.com/public_api/v1/ udostępnia integracjom te same dane, które serwis widzi w panelu: klientów, lokalizacje, urządzenia, liczniki, materiały, awarie i alerty. Jest tylko do odczytu, zwraca JSON i jest wersjonowane w adresie (v1).

Pierwsze zapytanie w trzy kroki

1. Właściciel konta serwisu wchodzi w panelu w Moje konto → Integracje (API) i generuje token, podając, do czego służy (np. „MERP — synchronizacja liczników”).
2. Token zaczyna się od pt_ i jest pokazany tylko raz. Chmura przechowuje jedynie jego skrót, więc zgubiony token trzeba odwołać i wygenerować nowy.
3. Token trafia do nagłówka Authorization każdego żądania:

curl -H "Authorization: Bearer pt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.printertracker.com/public_api/v1/devices/?state=active&limit=100"

Pełny, zawsze aktualny opis kontraktu to schemat OpenAPI generowany z kodu serwera: https://api.printertracker.com/public_api/v1/schema/?format=json. Da się z niego wygenerować klienta w dowolnym języku.

Uwierzytelnianie i limity

• Token = jeden serwis. Wszystko, co zwraca API, należy do serwisu, który wydał token. Nie ma parametru wybierającego klienta czy serwis — obiekt, do którego token nie ma dostępu, zwraca 404, tak samo jak obiekt nieistniejący.
• Zakresy (scope). Token integracyjny ma zakres read. Agenci SNMP używają osobnych tokenów z zakresem agent, którymi nie da się czytać danych, i odwrotnie — próba daje 403.
• Limit 60 żądań na minutę na token. Każda odpowiedź niesie nagłówki X-RateLimit-Limit i X-RateLimit-Remaining; po przekroczeniu 429 z Retry-After. Synchronizacja co kilka minut ze stronami po 500 obiektów mieści się w tym z dużym zapasem; większy limit ustalamy indywidualnie.
• Odwołanie. Token odwołany w panelu przestaje działać natychmiast (401). Do 20 aktywnych tokenów na serwis — po jednym na integrację, żeby dało się odciąć jedną bez wpływu na resztę.
• Sesja panelu nie działa w API, a token API nie loguje do panelu. To dwa osobne wejścia do tych samych danych.

Stronicowanie i filtry

Listy są stronicowane kursorem. Odpowiedź ma kształt { "results": [...], "next": "<kursor>" | null }. Kolejną stronę pobierasz tym samym żądaniem z parametrem cursor=<kursor>, aż next będzie null. Parametr limit ustawia rozmiar strony (domyślnie 100, najwyżej 500). Kursor jest nieprzezroczysty i ważny dla tego samego zestawu filtrów.

Daty są w ISO 8601 w UTC (2026-09-17T09:55:41Z). Filtry czasowe (since, until, updated_since) przyjmują też przesunięcie strefy. Nieznana wartość filtra to 400, nieistniejący identyfikator w filtrze to 404.

Synchronizacja przyrostowa liczników

Zapamiętaj najwyższe widziane received_at i pytaj counters/?since=… o nowsze odczyty. Ten sam odczyt (id) może wrócić, gdy w bieżącej godzinie został zastąpiony nowszym — wtedy zmienia się received_at, a odczyt przekazany już do rozliczeń nigdy się nie zmienia. Do rozliczeń bezpieczniej brać counter_total, gdy split_confirmed jest false: podział mono / kolor pochodzi wtedy z profilu-kandydata, jeszcze niepotwierdzonego na fakturze.

Referencja endpointów

Wszystkie ścieżki względem https://api.printertracker.com/public_api/v1/. Identyfikatory id są stałe; do dopasowania po swojej stronie służą też serial_number urządzenia i merp_client_id grupy.

Pola, które warto znać

state

Urządzenie: new (wykryte, czeka na zatwierdzenie), active (monitorowane), ignored.

status

Stan z ostatniego odczytu: ok, warning, error, albo offline, gdy monitorowane urządzenie nie dostarczyło odczytu od ponad 2 godzin.

counters

Bieżące liczniki mono, color, scan, total; null, gdy drukarka nie podaje wartości.

toner

Procenty k, c, m, y; brak klucza = nieznany. Pełna lista materiałów z prognozą dni do końca w devices/{id}/supplies/.

source

Odczyt: backend — liczniki policzone w chmurze z surowych danych SNMP (agent 0.2.0+), agent — liczniki z agenta 0.1.x.

agent.status

Podgrupa: online, offline (brak kontaktu), pending (agent utworzony, nie zainstalowany); null, gdy podgrupa nie ma agenta.

severity

Alert lub awaria: critical, warning, info. Alerty są posortowane od najpoważniejszych.

rule_id

Alert skonfigurowany w panelu ma identyfikator reguły; alerty systemowe mają null.

Przykładowe odpowiedzi

Urządzenia

{
  "results": [
    {
      "id": 214,
      "serial_number": "ZLD1234567",
      "manufacturer": "Canon",
      "model": "iR-ADV C5840",
      "ip_address": "192.168.100.21",
      "location": "Sekretariat, 2 piętro",
      "is_color": true,
      "state": "active",
      "status": "warning",
      "status_message": "Niski poziom tonera",
      "group_id": 12,
      "subgroup_id": 31,
      "counters": { "mono": 184320, "color": 52110, "scan": 90412, "total": 236430 },
      "split_confirmed": true,
      "toner": { "k": 62, "c": 8, "m": 41, "y": 39 },
      "firmware": "68.05",
      "discovered_at": "2026-09-10T08:20:11Z",
      "last_reading_at": "2026-09-17T09:55:41Z"
    }
  ],
  "next": null
}

Liczniki od północy, po dwa na stronę

GET https://api.printertracker.com/public_api/v1/counters/?since=2026-09-17T00:00:00Z&limit=2

{
  "results": [
    {
      "id": 88213,
      "device_id": 214,
      "read_at": "2026-09-17T09:55:41Z",
      "counter_mono": 184320,
      "counter_color": 52110,
      "counter_scan": 90412,
      "counter_total": 236430,
      "split_confirmed": true,
      "source": "backend",
      "received_at": "2026-09-17T09:55:44Z"
    },
    {
      "id": 88102,
      "device_id": 214,
      "read_at": "2026-09-17T08:55:12Z",
      "counter_mono": 184290,
      "counter_color": 52098,
      "counter_scan": 90401,
      "counter_total": 236388,
      "split_confirmed": true,
      "source": "backend",
      "received_at": "2026-09-17T08:55:15Z"
    }
  ],
  "next": "cD04ODEwMg%3D%3D"
}

Aktywne alerty

[
  {
    "id": "fault-5120",
    "severity": "critical",
    "title": "Zacięcie papieru",
    "detail": "Canon iR-ADV C5840 · Sekretariat, 2 piętro",
    "at": "2026-09-17T09:31:07Z",
    "group_id": 12,
    "subgroup_id": 31,
    "device_id": 214,
    "agent_id": null,
    "rule_id": null
  },
  {
    "id": "agent-offline-9",
    "severity": "critical",
    "title": "Agent nie odpowiada",
    "detail": "szpital-oddzial-a — odczyty z 9 urządzeń wstrzymane",
    "at": "2026-09-17T07:12:00Z",
    "group_id": 12,
    "subgroup_id": 31,
    "device_id": null,
    "agent_id": 9,
    "rule_id": null
  }
]

Błędy

Każdy błąd ma jedną kopertę. Pole code jest stabilne i do obsługi w kodzie, message jest dla człowieka.

{
  "error": {
    "code": "validation_error",
    "message": "Nieprawidłowe dane.",
    "details": { "status": ["\"broken\" is not a valid choice."] }
  }
}

Wersje i zmiany

W obrębie v1 zmiany są wyłącznie addytywne: nowe pola i nowe endpointy, nigdy usunięcie ani zmiana znaczenia istniejącego pola. Integracja, która ignoruje nieznane pola, działa bez zmian. Zmiana łamiąca oznacza v2 pod nowym adresem; stara wersja dostaje nagłówki Deprecation i Sunset i działa jeszcze co najmniej 6 miesięcy.

• 17 września 2026 — zasoby dla integracji: grupy, podgrupy, urządzenia, liczniki, materiały, awarie, alerty; tokeny z panelu; limit 60/min.
• 16 września 2026 — agent 0.2.0: surowe obserwacje SNMP, discovery z panelu.
• 14 września 2026 — pierwsza wersja API dla agenta SNMP.

Brakuje pola, filtra albo zasobu? Zmiana addytywna jest tania — napisz przez formularz kontaktowy, opisz, co integrujesz i jakich danych potrzebujesz.