# eparagony.pl

eparagony.pl integration with Ritevo: connecting with API credentials, sending receipts, fiscalisation and printing, webhook secret, reconnecting.

The eparagony.pl integration sends receipts issued in Ritevo to eParagony. You connect it with API credentials from the eParagony panel and point it at a point of sale.

> **Required integration:** You need an eParagony account with a point of sale and API credentials: Client ID, Client Secret, the webhook secret and the point of sale ID (posId).

You can add as many eparagony.pl integrations as you like, including several for the same account - for example with different details or different document settings. Each works on its own.

Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings.

`externalId` is the `posId`. You provide new credentials with `PATCH /integrations/accountings/eparagony/{id}/credentials` - in any state of the integration. It checks the Client ID and Client Secret in eParagony and sets `authError=false` and `active=true`.

## Which documents it sends

- **Receipt** (API: "Receipt" = `RECEIPT`; value in `billingType`) - goes to eParagony as an e-receipt.
- **VAT invoice** and **Invoice correction** (API: "VAT invoice" = `INVOICE`, "Invoice correction" = `CORRECTION`; value in `billingType`) - not supported.

## Where to find the credentials

eParagony provides the API credentials after you register for the service, together with the API documentation. Have them ready before adding the integration:

1. Create an eparagony.pl account if you do not have one yet.
2. Have the **Client ID**, the **Client Secret** and the webhook secret ready.
3. Have the ID of the point of sale (posId) the receipts should go to ready.
4. If you cannot find these details, write to eParagony support: pomoc@eparagony.pl.

## Connecting the account

Start in Ritevo:

1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner.
2. In the **Accounting** section pick the **eParagony** tile.
3. In the **Basic settings** card enter the **Account name** - your own name for the integration - and the **Point of sale ID (posId)**.
4. In the **Credentials** card paste the **Client ID**, the **Client Secret** and the **Webhook secret**.
5. In the **Integration settings** card set **Fiscalise documents** and **Print receipt** - described below.
6. Click **Create integration**. We check the Client ID and Client Secret in eParagony right away: if they are correct, the integration is added and its settings open. If not - you will see an error and nothing is saved.

![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp)

![The Add integration screen with the eParagony tile framed in the Accounting section](https://ritevo.com/docs/integrations/eparagony/en-catalogue.webp)

![The eParagony add-integration screen with the Basic settings, Credentials and Integration settings cards](https://ritevo.com/docs/integrations/eparagony/en-add.webp)

## Integration settings

On the integration page you will find the fields below. You save changes to the name and switches with **Update integration**:

- **Account name** - your own name for the integration. You can change it at any time.
- **Point of sale ID (posId)** - the point entered when adding. It cannot be changed - you add another point as a new integration.
- **Fiscalise documents** - once on, eParagony fiscalises the receipt. This needs the eParagony document printing service running on your side. On by default.
- **Print receipt** - once on, eParagony prints the receipt. For a stationary point of sale only. Off by default.
- **Update credentials** - you enter a new Client ID, Client Secret and webhook secret.

Creating: `accountName`, `posId`, `clientId`, `clientSecret`, `webhookSecret`, `fiscalize` (**Fiscalise documents**) and `print` (**Print receipt**) - both `true` or `false`. You change settings with `PATCH /integrations/accountings/eparagony/{id}` with `accountName`, `fiscalize` and `print`.

> **Good to know:** The webhook secret cannot be checked on saving. If it is wrong, the receipt reaches eParagony, but we get no confirmation and the sending stays **Sending**. Enter it exactly as it is in the eParagony panel.

## Sending documents

> **Good to know:** One order can have only one active invoice and one active receipt. You issue another document of the same type only after deleting the previous one. You can issue any number of corrections to an invoice.

You issue documents in the order. You send them to eparagony.pl in two ways:

- **By hand** - in the document details, in the **External accounting systems** card, click the button with the eparagony.pl account name. The button shows up only on documents this integration supports.
- **Automatically** - with the **Send invoice to external accounting** or **Send receipt to external accounting** step in [order actions](https://ritevo.com/en/docs/automations/order-actions).

Plan sending documents step by step - first issuing, then sending:

- **Invoice** - the first action ends with the **Generate invoice** step. The second starts on the **Invoice (added/removed)** trigger, has the **Has invoice** condition and the **Send invoice to external accounting** step.
- **Receipt** - the same: the first action ends with the **Generate receipt** step, and the second starts on the **Receipt (added/removed)** trigger, has the **Has receipt** condition and the **Send receipt to external accounting** step.
- **Corrections** - you can issue many corrections to one invoice. Send each right after issuing it, before you issue the next one.

> **Good to know:** The send step always sends just one document - the newest non-deleted one of that type. If you first issue all documents and only then turn on sending, only the last one goes out, and you send the others by hand. You cannot send a deleted document.

In the same card every sending has its own icon. Hover over it to see the account, the state and the date:

- **Sending** (API: "Sending" = `PENDING`; value in `externalTransfers[].status`) - the document is sent and we are waiting for eparagony.pl to confirm it.
- **Sent successfully** (API: "Sent successfully" = `SUCCESS`; value in `externalTransfers[].status`) - the document is in eparagony.pl. Click the icon to download or open it.
- **Sending failed** (API: "Sending failed" = `FAILED`; value in `externalTransfers[].status`) - the document did not reach eparagony.pl. The reason is shown under the state.

> **Good to know:** A document has only one sending to a given integration: you send it there once. If the sending fails, you can retry it with the same button. You send the same document to another accounting integration separately.

Order actions: the **Send invoice to external accounting** and **Send receipt to external accounting** steps are `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` in `actionSteps[].action.type`, with `uuidValue` = the accounting integration id (`GET /integrations/accountings`). The **Invoice sent to external accounting** and **Receipt sent to external accounting** triggers are `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. The **Has a successful invoice transfer to external accounting** / **Has no successful invoice transfer to external accounting** conditions are `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, and for receipts `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = accounting integration ids). Only a `SUCCESS` transfer counts. The step takes the latest document in the order's `billings[]` with the given `billingType` (`INVOICE` or `RECEIPT`) and `deleted` = `false`. An order has at most one document of a given `billingType` with `deleted` = `false` - issuing a second one returns `BILLING_ALREADY_EXISTS`. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions).

### How a receipt reaches eParagony

- **Without fiscalisation** - eParagony accepts the receipt straight away, so it is **Sent successfully** right after sending.
- **With fiscalisation** - the receipt stays **Sending** until eParagony confirms the fiscalisation. Then it changes to **Sent successfully** or to **Sending failed** with the reason from eParagony.
- **Number** - in eParagony the receipt carries the number assigned in Ritevo.
- **Preview** - clicking the icon opens the receipt on the eParagony site.
- **VAT rates** - eParagony accepts 23%, 8%, 5%, 0% and Zw. (exempt) from us, as well as the former 22%, 7% and 3%. A receipt with any other rate is not sent - you will see the **Tax rate not supported** error.

## Reconnection required

This state shows up when eParagony stops accepting the Client ID and Client Secret - for example after they were changed in the eParagony panel. Until then receipts will not reach eParagony.

1. Copy the current credentials in the eParagony panel.
2. On the integration page click **Update credentials**, paste the Client ID, Client Secret and webhook secret and confirm. We check them in eParagony the same way as when adding - correct ones refresh the connection.

> **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately.

In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page.

## Deleting the integration

**Delete integration** turns the integration off in Ritevo. Documents sent earlier stay in eparagony.pl. **Restore integration** turns it back on.

## What the integration does not do

- It does not send invoices or corrections.
- It does not change or cancel receipts that are already in eParagony.

## The integration through the API

This integration's endpoints are under `/integrations/accountings/eparagony`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/accountings`. You send a document with `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs.


---

All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.