# eparagony.pl

Integracja eparagony.pl z Ritevo: podłączenie danymi API, przesyłanie paragonów, fiskalizacja i druk, sekret webhooka, ponowne połączenie.

Integracja z eparagony.pl przesyła do eParagony paragony wystawione w Ritevo. Podłączasz ją danymi dostępowymi do API z panelu eParagony i wskazujesz punkt sprzedaży.

> **Wymagana integracja:** Potrzebujesz konta w eParagony z punktem sprzedaży i danych dostępowych do API: Client ID, Client Secret, sekretu webhooka i ID punktu sprzedaży (posId).

Integracji eparagony.pl możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innymi danymi albo innymi ustawieniami wystawiania dokumentów. Każda działa osobno.

Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami.

`externalId` to `posId`. Nowe dane dostępowe podasz przez `PATCH /integrations/accountings/eparagony/{id}/credentials` - w każdym stanie integracji. Sprawdza Client ID i Client Secret w eParagony i ustawia `authError=false` i `active=true`.

## Jakie dokumenty przesyła

- **Paragon** (API: "Paragon" = `RECEIPT`; wartość w `billingType`) - trafia do eParagony jako e-paragon.
- **Faktura VAT** i **Korekta faktury** (API: "Faktura VAT" = `INVOICE`, "Korekta faktury" = `CORRECTION`; wartość w `billingType`) - nie są obsługiwane.

## Skąd wziąć dane dostępowe

Dane dostępowe do API eParagony udostępnia po rejestracji w usłudze, razem z dokumentacją API. Przygotuj je przed dodaniem integracji:

1. Załóż konto w eparagony.pl, jeśli jeszcze go nie masz.
2. Przygotuj **Client ID**, **Client Secret** i sekret webhooka.
3. Przygotuj ID punktu sprzedaży (posId), do którego mają trafiać paragony.
4. Jeśli nie możesz znaleźć tych danych, napisz do pomocy eParagony: pomoc@eparagony.pl.

## Podłączenie konta

Zacznij w Ritevo:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Księgowość** wybierz kafelek **eParagony**.
3. W karcie **Ustawienia podstawowe** wpisz **Nazwa konta** - własną nazwę integracji - i **ID punktu sprzedaży (posId)**.
4. W karcie **Dane dostępowe** wklej **Client ID**, **Client Secret** i **Sekret webhooka**.
5. W karcie **Ustawienia integracji** ustaw **Fiskalizuj dokumenty** i **Drukuj paragon** - opis niżej.
6. Kliknij **Utwórz integrację**. Client ID i Client Secret sprawdzamy od razu w eParagony: jeśli są poprawne, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran Dodaj integrację z zaznaczonym kafelkiem eParagony w sekcji Księgowość](https://ritevo.com/docs/integrations/eparagony/pl-catalogue.webp)

![Ekran dodawania integracji eParagony z kartami Ustawienia podstawowe, Dane dostępowe i Ustawienia integracji](https://ritevo.com/docs/integrations/eparagony/pl-add.webp)

## Ustawienia integracji

Na stronie integracji znajdziesz poniższe pola. Zmiany nazwy i przełączników zapisujesz przyciskiem **Zaktualizuj integrację**:

- **Nazwa konta** - Twoja własna nazwa integracji. Możesz ją zmienić w każdej chwili.
- **ID punktu sprzedaży (posId)** - punkt podany przy dodawaniu. Nie da się go zmienić - inny punkt dodajesz jako nową integrację.
- **Fiskalizuj dokumenty** - po włączeniu eParagony fiskalizuje paragon. Wymaga to działającej u Ciebie usługi drukowania dokumentów eParagony. Domyślnie włączone.
- **Drukuj paragon** - po włączeniu eParagony drukuje paragon. Tylko dla stacjonarnego punktu sprzedaży. Domyślnie wyłączone.
- **Zaktualizuj dane logowania** - podajesz nowe Client ID, Client Secret i sekret webhooka.

Tworzenie: `accountName`, `posId`, `clientId`, `clientSecret`, `webhookSecret`, `fiscalize` (**Fiskalizuj dokumenty**) i `print` (**Drukuj paragon**) - oba `true` albo `false`. Ustawienia zmieniasz przez `PATCH /integrations/accountings/eparagony/{id}` z `accountName`, `fiscalize` i `print`.

> **Warto wiedzieć:** Sekretu webhooka nie da się sprawdzić przy zapisie. Jeśli jest błędny, paragon trafi do eParagony, ale nie dostaniemy potwierdzenia i przesłanie zostanie **W trakcie przesyłania**. Wpisz go dokładnie tak, jak jest w panelu eParagony.

## Przesyłanie dokumentów

> **Warto wiedzieć:** Na jednym zamówieniu może być tylko jedna aktywna faktura i jeden aktywny paragon. Kolejny dokument tego typu wystawisz dopiero po usunięciu poprzedniego. Korekt do faktury możesz wystawić dowolnie wiele.

Dokumenty wystawiasz w zamówieniu. Do eparagony.pl przesyłasz je na dwa sposoby:

- **Ręcznie** - w szczegółach dokumentu, w karcie **Zew. systemy księgowe**, kliknij przycisk z nazwą konta eparagony.pl. Przycisk pojawia się tylko przy dokumentach, które ta integracja obsługuje.
- **Automatycznie** - krokiem **Prześlij fakturę do zew. systemu księgowego** albo **Prześlij paragon do zew. systemu księgowego** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie:

- **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**.
- **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**.
- **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną.

> **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz.

W tej samej karcie każde przesłanie ma swoją ikonę. Po najechaniu na nią widzisz konto, stan i datę:

- **W trakcie przesyłania** (API: "W trakcie przesyłania" = `PENDING`; wartość w `externalTransfers[].status`) - dokument jest wysłany, czekamy na potwierdzenie od eparagony.pl.
- **Przesłano pomyślnie** (API: "Przesłano pomyślnie" = `SUCCESS`; wartość w `externalTransfers[].status`) - dokument jest w eparagony.pl. Kliknij ikonę, żeby go pobrać albo otworzyć.
- **Błąd podczas przesyłania** (API: "Błąd podczas przesyłania" = `FAILED`; wartość w `externalTransfers[].status`) - dokument nie trafił do eparagony.pl. Pod stanem widzisz powód błędu.

> **Warto wiedzieć:** Jeden dokument ma do danej integracji tylko jedno przesłanie: prześlesz go tam raz. Jeśli przesłanie skończy się błędem, możesz je ponowić tym samym przyciskiem. Do innej integracji księgowej ten sam dokument prześlesz osobno.

Akcje dla zamówień: kroki **Prześlij fakturę do zew. systemu księgowego** i **Prześlij paragon do zew. systemu księgowego** to `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` w `actionSteps[].action.type`, z `uuidValue` = id integracji księgowej (`GET /integrations/accountings`). Wyzwalacze **Przesłano fakturę w zew. systemie księgowym** i **Przesłano paragon w zew. systemie księgowym** to `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. Warunki **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego** = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, a dla paragonu `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = id integracji księgowych). Liczy się tylko przesłanie `SUCCESS`. Krok bierze ostatni dokument z `billings[]` zamówienia o danym `billingType` (`INVOICE` albo `RECEIPT`) z `deleted` = `false`. Na zamówieniu jest najwyżej jeden dokument danego `billingType` z `deleted` = `false` - próba wystawienia drugiego zwraca `BILLING_ALREADY_EXISTS`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

### Jak paragon trafia do eParagony

- **Bez fiskalizacji** - eParagony przyjmuje paragon od razu, więc ma on stan **Przesłano pomyślnie** zaraz po wysłaniu.
- **Z fiskalizacją** - paragon ma stan **W trakcie przesyłania**, dopóki eParagony nie potwierdzi fiskalizacji. Potem zmienia się na **Przesłano pomyślnie** albo na **Błąd podczas przesyłania** z powodem od eParagony.
- **Numer** - w eParagony paragon ma numer nadany w Ritevo.
- **Podgląd** - kliknięcie ikony otwiera paragon na stronie eParagony.
- **Stawki VAT** - eParagony przyjmuje od nas 23%, 8%, 5%, 0% i Zw., a także dawne 22%, 7% i 3%. Paragon z inną stawką nie zostanie przesłany - zobaczysz błąd **Stawka podatku nie jest wspierana**.

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy eParagony przestało akceptować Client ID i Client Secret - na przykład po ich zmianie w panelu eParagony. Do tego czasu paragony nie trafią do eParagony.

1. W panelu eParagony skopiuj aktualne dane dostępowe.
2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, wklej Client ID, Client Secret i sekret webhooka i zatwierdź. Sprawdzamy je w eParagony tak samo jak przy dodawaniu - poprawne odświeżą połączenie.

> **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać.

W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony.

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo. Dokumenty przesłane wcześniej zostają w eparagony.pl. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie przesyła faktur ani korekt.
- Nie zmienia ani nie anuluje paragonów, które już trafiły do eParagony.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/accountings/eparagony`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/accountings`. Dokument przesyłasz przez `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.