---
title: "eCommerce"
description: "Sklep internetowy. Każda aplikacja jest modułem na jednym modelu danych."
canonical: "https://obop.dev/pl/apps/ecommerce/"
lang: "pl"
---

# eCommerce

## Do czego służy

Store the data of an online shop: listings, shipping methods, discount codes and web orders with a fulfilment flow. Refunds need a manager and an approval. A storefront or other client reads and writes this data through the API.

## Co pakiet robi, a czego nie robi

An online shop: categories, product listings with translations, shipping methods, discount codes, web orders with lines and a fulfilment flow of pending, paid, shipped, delivered, cancelled and refunded. When the instance runs with the public site enabled, visitors browse the published listings and place orders without an account; the server prices every order from the published listing and never trusts the browser. There is no payment provider: an order starts as pending and the shop contacts the buyer. Refunds need a human approval from a manager; agents may only propose them. Customer name, email and addresses are personal data and are never public. Needs the Products package.

## Modele

### `ecommerce_category`

A group of listings shown together in the shop

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.manager`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `name` | text | `none` | nie | `ecommerce.user` | jawnie | Category name shown in the shop |
| `slug` | text | `none` | nie | `ecommerce.user` | jawnie | URL part of the category, lowercase with dashes |
| `description` | text | `none` | nie | `ecommerce.user` | jawnie | Short text about the category |
| `sequence` | number | `none` | nie | `ecommerce.user` | jawnie | Order among categories, lowest first |
| `published` | bool | `none` | nie | `ecommerce.user` | jawnie | Whether the category is visible to shoppers |

### `ecommerce_listing`

A product as it appears in the online shop

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.manager`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `product_id` | ref → product | `none` | nie | `ecommerce.user` | jawnie | The product being sold online |
| `title` | text | `none` | nie | `ecommerce.user` | jawnie | Title shown in the shop |
| `slug` | text | `none` | nie | `ecommerce.user` | jawnie | URL part of the product page, lowercase with dashes |
| `summary` | text | `none` | nie | `ecommerce.user` | jawnie | One or two sentences shown on product cards |
| `description` | longtext | `none` | nie | `ecommerce.user` | jawnie | Description shown on the product page, in Markdown |
| `category_id` | ref → ecommerce_category | `none` | nie | `ecommerce.user` | jawnie | The category the listing is shown under |
| `price` | money | `none` | nie | `ecommerce.user` | jawnie | Shop price including tax (minor currency units, e.g. cents) |
| `compare_at_price` | money | `none` | nie | `ecommerce.user` | jawnie | Previous price shown crossed out (minor currency units) |
| `currency` | text | `none` | nie | `ecommerce.user` | jawnie | ISO 4217 currency code of the prices, for example EUR; empty means the shop currency from the instance settings |
| `sku` | text | `none` | nie | `ecommerce.user` | jawnie | Stock keeping unit shown on the product page |
| `stock_policy` | select (always_available, block_when_out, allow_backorder) | `none` | nie | `ecommerce.user` | jawnie | What happens when stock runs out: always_available, block_when_out, allow_backorder |
| `stock_quantity` | number | `none` | nie | `ecommerce.user` | jawnie | Units on hand, used with the stock policy. Orders do not reduce it: adjust it by hand |
| `published` | bool | `none` | nie | `ecommerce.user` | jawnie | Whether the listing is visible to shoppers |

### `ecommerce_listing_translation`

A listing translated into another language

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.manager`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `listing_id` | ref → ecommerce_listing | `none` | nie | `ecommerce.user` | jawnie | The listing this translates |
| `lang` | select (en, de, fr, pl, fi, sv, es) | `none` | nie | `ecommerce.user` | jawnie | Language of the translation: en, de, fr, pl, fi, sv or es |
| `title` | text | `none` | nie | `ecommerce.user` | jawnie | Translated title |
| `summary` | text | `none` | nie | `ecommerce.user` | jawnie | Translated card text |
| `description` | longtext | `none` | nie | `ecommerce.user` | jawnie | Translated description in Markdown |
| `published` | bool | `none` | nie | `ecommerce.user` | jawnie | Whether the translation is shown; it is only reachable while its listing is published |

### `ecommerce_shipping_method`

A way of delivering orders with its price

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.manager`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `name` | text | `none` | nie | `ecommerce.user` | jawnie | Name shown at checkout, for example Standard delivery |
| `carrier` | text | `none` | nie | `ecommerce.user` | jawnie | Carrier that delivers, for example DHL |
| `price` | money | `none` | nie | `ecommerce.user` | jawnie | Delivery price (minor currency units) |
| `free_over` | money | `none` | nie | `ecommerce.user` | jawnie | Order total above which delivery is free (minor currency units); empty means never |
| `delivery_days` | number | `none` | nie | `ecommerce.user` | jawnie | Usual number of days until delivery |
| `active` | bool | `none` | nie | `ecommerce.user` | jawnie | Whether shoppers can choose it |

### `ecommerce_discount_code`

A code a shopper enters at checkout for a reduction

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.manager`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `code` | text | `none` | nie | `ecommerce.user` | jawnie | The code shoppers type, for example SPRING10 |
| `kind` | select (percent, fixed) | `none` | nie | `ecommerce.user` | jawnie | Type of reduction: percent or fixed |
| `value` | number | `none` | nie | `ecommerce.user` | jawnie | Reduction: basis points for percent (1000 is 10.00 percent), minor currency units for fixed |
| `starts_on` | date | `none` | nie | `ecommerce.user` | jawnie | First day the code works (YYYY-MM-DD) |
| `ends_on` | date | `none` | nie | `ecommerce.user` | jawnie | Last day the code works (YYYY-MM-DD) |
| `max_uses` | number | `none` | nie | `ecommerce.user` | jawnie | How many times the code may be used in total; empty means unlimited |
| `used_count` | number | `none` | nie | `ecommerce.user` | jawnie | How many times it has been used (kept up to date by hand) |
| `minimum_order` | money | `none` | nie | `ecommerce.user` | jawnie | Smallest order total the code applies to (minor currency units) |
| `active` | bool | `none` | nie | `ecommerce.user` | jawnie | Whether the code can be used |

### `ecommerce_order`

An order placed online

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.user`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `number` | text | `none` | nie | `ecommerce.user` | jawnie | Order number shown to the shopper. Free text: packages cannot generate sequences; the public checkout makes a random one |
| `customer_email` | text | `internal` | tak | `ecommerce.user` | zamaskowane | Email address of the shopper |
| `customer_name` | text | `internal` | tak | `ecommerce.user` | zamaskowane | Name of the shopper |
| `customer_id` | ref → party | `none` | nie | `ecommerce.user` | jawnie | The matching contact, once the shopper is known |
| `shipping_address` | longtext | `internal` | tak | `ecommerce.user` | zamaskowane | Delivery address |
| `billing_address` | longtext | `internal` | tak | `ecommerce.user` | zamaskowane | Billing address when different from delivery |
| `shipping_method_id` | ref → ecommerce_shipping_method | `none` | nie | `ecommerce.user` | jawnie | The chosen way of delivery |
| `discount_code_id` | ref → ecommerce_discount_code | `none` | nie | `ecommerce.user` | jawnie | The discount code used, if any |
| `placed_on` | date | `none` | nie | `ecommerce.user` | jawnie | Day the order was placed (YYYY-MM-DD) |
| `currency` | text | `none` | nie | `ecommerce.user` | jawnie | ISO 4217 currency code, for example EUR |
| `subtotal` | money | `none` | nie | `ecommerce.user` | jawnie | Sum of the lines (minor currency units, entered not computed) |
| `discount_total` | money | `none` | nie | `ecommerce.user` | jawnie | Reduction from the discount code (minor currency units) |
| `shipping_total` | money | `none` | nie | `ecommerce.user` | jawnie | Delivery charge (minor currency units) |
| `tax_total` | money | `none` | nie | `ecommerce.user` | jawnie | Tax included in the total (minor currency units) |
| `total` | money | `none` | nie | `ecommerce.user` | jawnie | Amount the shopper pays (minor currency units) |
| `payment_reference` | text | `financial` | tak | `ecommerce.user` | wstrzymane | Reference from the payment provider; never a card number |
| `tracking_reference` | text | `none` | nie | `ecommerce.user` | jawnie | Carrier tracking number |
| `access_token` | text | `secret` | nie | `ecommerce.user` | wstrzymane | Secret link token that lets the shopper who placed a public order see its confirmation page. Nobody can read it back |
| `state` | select (pending, paid, shipped, delivered, cancelled, refunded) | `none` | nie | `ecommerce.user` | jawnie | Fulfilment status: pending, paid, shipped, delivered, cancelled, refunded |

### `ecommerce_order_line`

One product line of a web order

Grupa odczytu: `ecommerce.user`. Grupa zapisu: `ecommerce.user`.

| Pole | Rodzaj | Klasa danych | Dane osobowe | Grupa | Agenci widzą | Opis |
|---|---|---|---|---|---|---|
| `order_id` | ref → ecommerce_order | `none` | nie | `ecommerce.user` | jawnie | The order the line belongs to |
| `product_id` | ref → product | `none` | nie | `ecommerce.user` | jawnie | The product ordered |
| `listing_id` | ref → ecommerce_listing | `none` | nie | `ecommerce.user` | jawnie | The shop listing the line was ordered from |
| `description` | text | `none` | nie | `ecommerce.user` | jawnie | Product text as it was when ordered |
| `quantity` | number | `none` | nie | `ecommerce.user` | jawnie | Units ordered |
| `unit_price` | money | `none` | nie | `ecommerce.user` | jawnie | Price per unit including tax (minor currency units) |
| `subtotal` | money | `none` | nie | `ecommerce.user` | jawnie | Line total (minor currency units, entered not computed) |

## Przepływy pracy

### `ecommerce_order`

| Akcja | Przenosi | Kto może uruchomić | Zatwierdzenie |
|---|---|---|---|
| `ecommerce_order.mark_paid` | state: pending → paid | `ecommerce.user` | nie |
| `ecommerce_order.ship` | state: paid → shipped | `ecommerce.user` | nie |
| `ecommerce_order.deliver` | state: shipped → delivered | `ecommerce.user` | nie |
| `ecommerce_order.cancel` | state: pending → cancelled | `ecommerce.user` | nie |
| `ecommerce_order.refund` | state: paid → refunded | `ecommerce.manager` | tak |
| `ecommerce_order.refund_delivered` | state: delivered → refunded | `ecommerce.manager` | tak |

## Grupy uprawnień

Grupy używane przez tę aplikację:

- `ecommerce.manager`
- `ecommerce.user`

## Kroki zatwierdzania

Kroki, które agent może tylko zaproponować:

- `ecommerce_order.refund`
- `ecommerce_order.refund_delivered`

## Co agenci mogą, a czego nie mogą

Agent może odczytywać, wyszukiwać, tworzyć i aktualizować rekordy tej aplikacji oraz uruchamiać akcje niewymagające zatwierdzenia, w ramach grup uprawnień swojego tokenu.

Te kroki może tylko zaproponować, a człowiek musi je zatwierdzić: `ecommerce_order.refund`, `ecommerce_order.refund_delivered`, `ecommerce_category.delete`, `ecommerce_listing.delete`, `ecommerce_listing_translation.delete`, `ecommerce_shipping_method.delete`, `ecommerce_discount_code.delete`, `ecommerce_order.delete`, `ecommerce_order_line.delete`.

Dane osobowe są maskowane jako tokeny zastępcze: `ecommerce_order.customer_email`, `ecommerce_order.customer_name`, `ecommerce_order.shipping_address`, `ecommerce_order.billing_address`.

Te pola są całkowicie wstrzymane i niedostępne dla agentów: `ecommerce_order.payment_reference`, `ecommerce_order.access_token`.

## Zależności

- `base`
- `product`

## Instalacja

Zainstaluj ją w aplikacji Customize (Marketplace) lub z wiersza poleceń:

```bash
obop modules install-from ecommerce
```

Wymaga bazy danych i uprawnień administratora.

## Zbuduj własną

[Przewodnik po modułach pokazuje, jak pisze się takie aplikacje](/pl/docs/reference/module-manifest/)