> Źródło: https://redai.pl/dev/katalog-i-platne-moduly/ (dokumentacja modułów portalu redAi). Cała dokumentacja w jednym pliku: https://redai.pl/dev/moduly.md

## Katalog i płatne moduły

**[Katalog modułów](https://redai.pl/dev/katalog/)** to publiczna lista modułów z zaakceptowanym wydaniem: nazwa, autor, kategoria, ikona, opis z `opis_pozycji`, zrzuty ekranu, lista zmian i liczba instancji. Strona modułu ma adres `redai.pl/dev/katalog/<klucz>/` i wygląda jak karta w Administracja › Moduły. Przy każdym module stoi cena: „Bezpłatny” albo stawka netto za miesiąc. Katalog nie pokazuje adresów instancji.

Instalację robi zawsze administrator instancji u siebie, opis w [Trzy zgody](/dev/trzy-zgody-jak-modul-trafia-na-cudza-instancje/).

### Kto komu płaci

```
 Wy (autor)  ── paczka modułu ──▶  redAi  ── moduł w katalogu ──▶  firma
 Wy (autor)  ◀── 100% stawki ────  redAi  ◀── stawka w rozliczeniu ─ firma
             (po Waszej fakturze)
```

- **Firma płaci redAi.** Stawkę modułu redAi dolicza do miesięcznego rozliczenia firmy. Firma nie podpisuje z Wami osobnej umowy.
- **redAi płaci Wam 100% stawki.** Bez prowizji i potrąceń.
- **Wy wystawiacie fakturę na redAi** za zamknięty miesiąc, na kwotę z zakładki Zarobki. Dane do faktury są na koncie i w mailu po zamknięciu miesiąca.

### Stawka: prosto, za miesiąc

Moduł jest bezpłatny, dopóki nie ustawicie stawki. Stawkę ustawiacie na koncie: moduł › **Katalog i stawka**.

- Stawka to kwota **netto w PLN za jedną instancję za miesiąc**, od 0 do 5 000 zł. Bez progów, pakietów i rozliczeń za użycie.
- **Podwyżkę** (także przejście z bezpłatnego na płatny) zatwierdza redAi. Do akceptu obowiązuje stara stawka, a nową widzicie jako „czeka na redAi”. Nowa propozycja zastępuje tę, która jeszcze czeka. O decyzji dostajecie maila.
- **Obniżka** i powrót do bezpłatnego wchodzą od razu, od dnia zmiany.
- Stawka jest jawna: firmy widzą ją w katalogu, na stronie modułu i w portalu przed instalacją. Płatnego modułu portal nie zainstaluje bez potwierdzenia ceny przez administratora.
- Portale, które jeszcze nie pokazują cen, nie widzą płatnych modułów w katalogu (chyba że moduł już na nich stoi).

### Kiedy instancja się liczy

- Liczymy tylko instancje firm, które redAi fakturuje. Instancje testowe, pokazowe i wewnętrzne redAi się nie liczą.
- Instancja płaci za miesiąc, jeśli moduł był na niej **włączony choć jeden dzień** w tym miesiącu (instancja zgłasza to codziennie). Liczy się stawka z ostatniego takiego dnia.
- Jedna instancja w jednym miesiącu to jedna stawka, niezależnie od liczby użytkowników i wywołań.
- Na koncie i w API widzicie same liczby instancji, bez adresów i nazw firm.

### Zamknięcie miesiąca i wypłata

- 1. dnia miesiąca rano zamykamy poprzedni miesiąc. Kwota dostaje status `naliczone` (czeka na Waszą fakturę) i dostajecie maila z kwotą i danymi do faktury.
- **Wystawiacie fakturę na redAi** na kwotę netto z maila (VAT według Waszego statusu), w tytule „Moduły redAi, <miesiąc>”, i wysyłacie ją na adres z maila. Dane redAi do faktury są też na koncie w zakładce **Zarobki**.
- Przelew robimy po fakturze na dane z zakładki **Zarobki** › Dane do rozliczeń: firma albo imię i nazwisko, NIP (jeśli jest), adres, numer konta, e-mail do rozliczeń. Uzupełnijcie je przed pierwszą wypłatą.
- Po przelewie pozycja zmienia status na `wyplacone` z datą.
- Bieżący miesiąc widzicie na koncie i w API jako naliczenie do dziś (`w_toku`). To prognoza, kwota zamyka się dopiero 1. dnia następnego miesiąca.

### API: ile zarobiliście

Ten sam klucz `rmk_...` co przy wysyłce. Kwoty netto w PLN.

```bash
curl -sS https://redai.pl/api/moduly/zarobki -H "Authorization: Bearer $REDAI_KLUCZ"
curl -sS "https://redai.pl/api/moduly/zarobki?miesiecy=24" -H "Authorization: Bearer $REDAI_KLUCZ"
curl -sS "https://redai.pl/api/moduly/zarobki?miesiac=2026-10" -H "Authorization: Bearer $REDAI_KLUCZ"
```

- `?miesiecy=1..120` (domyślnie 12): ile ostatnich zamkniętych miesięcy oddać.
- `?miesiac=RRRR-MM`: jeden miesiąc. Bieżący ma status `w_toku`, miesiąc bez naliczenia ma `brak_naliczenia`.
- `401` bez klucza albo z nieważnym kluczem, `400` przy złym albo przyszłym miesiącu.

```json
{
  "ok": true,
  "waluta": "PLN",
  "netto": true,
  "biezacy": {"miesiac": "2026-10", "kwota": 57.0, "instancjo_mies": 3, "pozycje": [
    {"klucz": "faktury_kosztowe", "nazwa": "Faktury kosztowe", "instancji": 3, "stawki": {"19.00": 3}, "kwota": 57.0}
  ], "do_dnia": "2026-10-15", "status": "w_toku"},
  "miesiace": [
    {"miesiac": "2026-09", "kwota": 38.0, "instancjo_mies": 2, "status": "wyplacone", "wyplacone": "2026-10-03 10:12:00", "pozycje": [...]}
  ],
  "sumy": {"naliczone": 38.0, "wyplacone": 38.0, "do_wyplaty": 0.0},
  "moduly": [
    {"klucz": "faktury_kosztowe", "nazwa": "Faktury kosztowe", "stawka": 19.0, "stawka_czeka": null, "instancji_platnych_teraz": 3}
  ]
}
```

`pozycje[].stawki` to obiekt „stawka: liczba instancji”. Gdy w miesiącu zmieniliście stawkę, zobaczycie tam kilka stawek.

### API: katalog publiczny

Bez klucza, z nagłówkiem `Access-Control-Allow-Origin: *`, więc możecie pokazać swoje moduły na własnej stronie.

```bash
curl -sS https://redai.pl/api/moduly/publiczne                       # wszystkie moduły w katalogu
curl -sS "https://redai.pl/api/moduly/publiczne?klucz=faktury_kosztowe"  # jeden moduł, 404 gdy go nie ma
```

Każda pozycja ma m.in. `klucz`, `nazwa`, `autor`, `wersja`, `kategoria`, `ikona_svg`, opis z `opis_pozycji` (`opis`, `daje`, `przyklady`, `szczegoly`, `kroki`), `zrzuty` (adresy `https://redai.pl/api/moduly/zrzut?z=...` z podpisem i wymiarami), `zmiany`, `instalacji`, `cena_mies` (stawka netto w PLN za instancję za miesiąc, `0` = bezpłatny) i `strona` (adres strony w katalogu).