Wofür sie gedacht ist

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.

Was das Paket leistet und was nicht

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. Orders take stock off the listing at checkout, apply discount codes and tax rates on the server, and are paid by bank transfer, by card through Stripe Checkout or in a local demo mode; the payment record, the provider reference and refunds are kept with the order. 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.

Moduldetails

Version: 0.5.0
Autor: SpaceCorps
Lizenz: AGPL-3.0-or-later
Benötigt Kern: ^0.2 (aktuell ist Kern 0.2.0)
Reifegrad: Beta
Kategorien: Vertrieb

Modelle

`ecommerce_category`

A group of listings shown together in the shop

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`name`	text	`none`	nein	`ecommerce.user`	im Klartext	Category name shown in the shop
`slug`	text	`none`	nein	`ecommerce.user`	im Klartext	URL part of the category, lowercase with dashes
`description`	text	`none`	nein	`ecommerce.user`	im Klartext	Short text about the category
`sequence`	number	`none`	nein	`ecommerce.user`	im Klartext	Order among categories, lowest first
`published`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether the category is visible to shoppers

`ecommerce_listing`

A product as it appears in the online shop

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`product_id`	ref → product	`none`	nein	`ecommerce.user`	im Klartext	The product being sold online
`title`	text	`none`	nein	`ecommerce.user`	im Klartext	Title shown in the shop
`slug`	text	`none`	nein	`ecommerce.user`	im Klartext	URL part of the product page, lowercase with dashes
`summary`	text	`none`	nein	`ecommerce.user`	im Klartext	One or two sentences shown on product cards
`description`	longtext	`none`	nein	`ecommerce.user`	im Klartext	Description shown on the product page, in Markdown
`image`	image	`none`	nein	`ecommerce.user`	im Klartext	Main picture of the product (PNG, JPEG, WebP or GIF, up to 5 MiB; it is re-encoded and its metadata removed on upload)
`image_alt`	text	`none`	nein	`ecommerce.user`	im Klartext	Text that describes the main picture for people who cannot see it
`category_id`	ref → ecommerce_category	`none`	nein	`ecommerce.user`	im Klartext	The category the listing is shown under
`price`	money	`none`	nein	`ecommerce.user`	im Klartext	Shop price including tax (minor currency units, e.g. cents)
`compare_at_price`	money	`none`	nein	`ecommerce.user`	im Klartext	Previous price shown crossed out (minor currency units)
`currency`	text	`none`	nein	`ecommerce.user`	im Klartext	ISO 4217 currency code of the prices, for example EUR; empty means the shop currency from the instance settings
`sku`	text	`none`	nein	`ecommerce.user`	im Klartext	Stock keeping unit shown on the product page
`stock_policy`	select (always_available, block_when_out, allow_backorder)	`none`	nein	`ecommerce.user`	im Klartext	What happens when stock runs out: always_available, block_when_out, allow_backorder
`stock_quantity`	number	`none`	nein	`ecommerce.user`	im Klartext	Units on hand, used with the stock policy. Every order takes its units off at checkout, and a cancelled, expired or refunded order puts them back; correct it by hand after a stock count
`published`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether the listing is visible to shoppers

`ecommerce_listing_image`

An extra picture of a listing for its gallery

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`listing_id`	ref → ecommerce_listing	`none`	nein	`ecommerce.user`	im Klartext	The listing the picture belongs to; it is shown only while the listing is published
`image`	image	`none`	nein	`ecommerce.user`	im Klartext	The picture (PNG, JPEG, WebP or GIF, up to 5 MiB)
`alt`	text	`none`	nein	`ecommerce.user`	im Klartext	Text that describes the picture for people who cannot see it
`sequence`	number	`none`	nein	`ecommerce.user`	im Klartext	Order in the gallery, lowest first
`published`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether the picture is shown in the shop

`ecommerce_listing_translation`

A listing translated into another language

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`listing_id`	ref → ecommerce_listing	`none`	nein	`ecommerce.user`	im Klartext	The listing this translates
`lang`	select (en, de, fr, pl, fi, sv, es)	`none`	nein	`ecommerce.user`	im Klartext	Language of the translation: en, de, fr, pl, fi, sv or es
`title`	text	`none`	nein	`ecommerce.user`	im Klartext	Translated title
`summary`	text	`none`	nein	`ecommerce.user`	im Klartext	Translated card text
`description`	longtext	`none`	nein	`ecommerce.user`	im Klartext	Translated description in Markdown
`published`	bool	`none`	nein	`ecommerce.user`	im Klartext	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

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`name`	text	`none`	nein	`ecommerce.user`	im Klartext	Name shown at checkout, for example Standard delivery
`carrier`	text	`none`	nein	`ecommerce.user`	im Klartext	Carrier that delivers, for example DHL
`price`	money	`none`	nein	`ecommerce.user`	im Klartext	Delivery price (minor currency units)
`free_over`	money	`none`	nein	`ecommerce.user`	im Klartext	Order total above which delivery is free (minor currency units); empty means never
`delivery_days`	number	`none`	nein	`ecommerce.user`	im Klartext	Usual number of days until delivery
`active`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether shoppers can choose it

`ecommerce_discount_code`

A code a shopper enters at checkout for a reduction

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`code`	text	`none`	nein	`ecommerce.user`	im Klartext	The code shoppers type, for example SPRING10
`kind`	select (percent, fixed)	`none`	nein	`ecommerce.user`	im Klartext	Type of reduction: percent or fixed
`value`	number	`none`	nein	`ecommerce.user`	im Klartext	Reduction: basis points for percent (1000 is 10.00 percent), minor currency units for fixed
`starts_on`	date	`none`	nein	`ecommerce.user`	im Klartext	First day the code works (YYYY-MM-DD)
`ends_on`	date	`none`	nein	`ecommerce.user`	im Klartext	Last day the code works (YYYY-MM-DD)
`max_uses`	number	`none`	nein	`ecommerce.user`	im Klartext	How many times the code may be used in total; empty means unlimited
`used_count`	number	`none`	nein	`ecommerce.user`	im Klartext	How many times it has been used. The shop counts a use when the order is placed and gives it back when the order is cancelled or never paid
`minimum_order`	money	`none`	nein	`ecommerce.user`	im Klartext	Smallest order total the code applies to (minor currency units)
`per_customer_limit`	number	`none`	nein	`ecommerce.user`	im Klartext	How many times one customer (by email address) may use the code; empty means no limit
`category_id`	ref → ecommerce_category	`none`	nein	`ecommerce.user`	im Klartext	Only listings of this category get the reduction; empty means the whole order
`active`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether the code can be used

`ecommerce_discount_use`

How many times one customer has used one discount code (the customer is kept as a hash, never as an email address)

Lesegruppe: ecommerce.manager. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`code_id`	ref → ecommerce_discount_code	`none`	nein	`ecommerce.manager`	im Klartext	The discount code
`customer_hash`	text	`internal`	ja	`ecommerce.manager`	maskiert	Hash of the customer's email address, so the per-customer limit can be checked without keeping the address here
`count`	number	`none`	nein	`ecommerce.manager`	im Klartext	Uses so far

`ecommerce_tax_rate`

A tax rate the shop applies to listings, computed on the server

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`name`	text	`none`	nein	`ecommerce.user`	im Klartext	Name shown on the order, for example VAT
`rate_bp`	number	`none`	nein	`ecommerce.user`	im Klartext	Rate in basis points: 1900 is 19.00 percent
`country`	text	`none`	nein	`ecommerce.user`	im Klartext	Two-letter country code (for example DE) of the delivery address this rate is for; empty means every country that has no rate of its own
`category_id`	ref → ecommerce_category	`none`	nein	`ecommerce.user`	im Klartext	Only listings of this category; empty means every listing (and delivery)
`included`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether listing prices already include this tax (the usual way in the EU). If not, the tax is added on top at checkout
`active`	bool	`none`	nein	`ecommerce.user`	im Klartext	Whether the rate is applied

`ecommerce_order`

An order placed online

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.user.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`number`	text	`none`	nein	`ecommerce.user`	im Klartext	Order number shown to the shopper. Free text: packages cannot generate sequences; the public checkout makes a random one
`customer_email`	text	`internal`	ja	`ecommerce.user`	maskiert	Email address of the shopper
`customer_name`	text	`internal`	ja	`ecommerce.user`	maskiert	Name of the shopper
`customer_id`	ref → party	`none`	nein	`ecommerce.user`	im Klartext	The matching contact, once the shopper is known
`shipping_address`	longtext	`internal`	ja	`ecommerce.user`	maskiert	Delivery address
`billing_address`	longtext	`internal`	ja	`ecommerce.user`	maskiert	Billing address when different from delivery
`shipping_method_id`	ref → ecommerce_shipping_method	`none`	nein	`ecommerce.user`	im Klartext	The chosen way of delivery
`discount_code_id`	ref → ecommerce_discount_code	`none`	nein	`ecommerce.user`	im Klartext	The discount code used, if any
`discount_code`	text	`none`	nein	`ecommerce.user`	im Klartext	The code the shopper entered, as it is shown on the order
`discount_use_id`	text	`internal`	ja	`ecommerce.user`	maskiert	Which per-customer use counter this order counted against, so it can be given back
`country`	text	`internal`	ja	`ecommerce.user`	maskiert	Two-letter country code of the delivery address, which decides the tax rate
`tax_summary`	longtext	`none`	nein	`ecommerce.user`	im Klartext	The tax lines of the order as JSON: name, rate in basis points, whether included in the prices, amount
`stock_returned`	bool	`none`	nein	`ecommerce.user`	im Klartext	Set when the units of a cancelled, expired or refunded order were put back on the listings, so it happens once
`reserved_until`	number	`none`	nein	`ecommerce.user`	im Klartext	Unix time until which an unpaid order holds its stock; after that it is cancelled and the stock goes back
`payment_method`	select (manual, stripe, fake)	`none`	nein	`ecommerce.user`	im Klartext	How the shopper chose to pay: manual (bank transfer or invoice), stripe (card) or fake (demo)
`placed_on`	date	`none`	nein	`ecommerce.user`	im Klartext	Day the order was placed (YYYY-MM-DD)
`currency`	text	`none`	nein	`ecommerce.user`	im Klartext	ISO 4217 currency code, for example EUR
`subtotal`	money	`none`	nein	`ecommerce.user`	im Klartext	Sum of the lines at listing prices (minor currency units, computed by the shop at checkout)
`discount_total`	money	`none`	nein	`ecommerce.user`	im Klartext	Reduction from the discount code (minor currency units)
`shipping_total`	money	`none`	nein	`ecommerce.user`	im Klartext	Delivery charge (minor currency units)
`tax_total`	money	`none`	nein	`ecommerce.user`	im Klartext	All tax on the order, both the part included in the prices and the part added on top (minor currency units)
`total`	money	`none`	nein	`ecommerce.user`	im Klartext	Amount the shopper pays: lines, minus the discount, plus delivery, plus tax that was added on top (minor currency units)
`payment_reference`	text	`financial`	ja	`ecommerce.user`	zurückgehalten	Reference from the payment provider; never a card number
`tracking_reference`	text	`none`	nein	`ecommerce.user`	im Klartext	Carrier tracking number
`access_token`	text	`secret`	nein	`ecommerce.user`	zurückgehalten	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`	nein	`ecommerce.user`	im Klartext	Fulfilment status: pending, paid, shipped, delivered, cancelled, refunded

`ecommerce_order_line`

One product line of a web order

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.user.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`order_id`	ref → ecommerce_order	`none`	nein	`ecommerce.user`	im Klartext	The order the line belongs to
`product_id`	ref → product	`none`	nein	`ecommerce.user`	im Klartext	The product ordered
`listing_id`	ref → ecommerce_listing	`none`	nein	`ecommerce.user`	im Klartext	The shop listing the line was ordered from
`description`	text	`none`	nein	`ecommerce.user`	im Klartext	Product text as it was when ordered
`quantity`	number	`none`	nein	`ecommerce.user`	im Klartext	Units ordered
`unit_price`	money	`none`	nein	`ecommerce.user`	im Klartext	Price per unit including tax (minor currency units)
`subtotal`	money	`none`	nein	`ecommerce.user`	im Klartext	Line total (minor currency units, entered not computed)
`discount_amount`	money	`none`	nein	`ecommerce.user`	im Klartext	Part of the order discount that falls on this line (minor currency units)
`tax_name`	text	`none`	nein	`ecommerce.user`	im Klartext	Name of the tax applied to this line
`tax_rate_bp`	number	`none`	nein	`ecommerce.user`	im Klartext	Tax rate of this line in basis points
`tax_amount`	money	`none`	nein	`ecommerce.user`	im Klartext	Tax on this line, included in the prices or added on top (minor currency units)

`ecommerce_payment`

A payment for a web order: which provider, its reference, the amount and what became of it. The shop never sees card data

Lesegruppe: ecommerce.user. Schreibgruppe: ecommerce.manager.

Feld	Art	Datenklasse	Personenbezogene Daten	Gruppe	Agenten sehen	Beschreibung
`order_id`	ref → ecommerce_order	`none`	nein	`ecommerce.user`	im Klartext	The order being paid
`provider`	select (manual, stripe, fake)	`none`	nein	`ecommerce.user`	im Klartext	Who takes the payment: manual (bank transfer or invoice), stripe (Stripe Checkout) or fake (local demo)
`external_id`	text	`financial`	nein	`ecommerce.user`	zurückgehalten	The provider's reference for this payment, for example a Stripe Checkout Session id. Never a card number
`checkout_url`	text	`financial`	nein	`ecommerce.user`	zurückgehalten	Where the shopper pays, kept so the payment page can send them back to it while the payment is open
`state`	select (open, succeeded, failed, expired, cancelled, refunded)	`none`	nein	`ecommerce.user`	im Klartext	Payment status: open (waiting for the shopper), succeeded, failed, expired, cancelled, refunded
`amount`	money	`none`	nein	`ecommerce.user`	im Klartext	Amount to pay, set by the server from the order (minor currency units)
`currency`	text	`none`	nein	`ecommerce.user`	im Klartext	ISO 4217 currency code of the amount
`refund_id`	text	`financial`	nein	`ecommerce.user`	zurückgehalten	The provider's reference for the refund, once the payment was refunded
`refunded_amount`	money	`none`	nein	`ecommerce.user`	im Klartext	Amount returned to the shopper (minor currency units)
`event_ids`	longtext	`none`	nein	`ecommerce.user`	im Klartext	Ids of the provider events already applied, as JSON, so a repeated notification changes nothing

Workflows

`ecommerce_order`

Aktion	Bewegt	Wer sie ausführen darf	Freigabe
`ecommerce_order.mark_paid`	state: pending → paid	`ecommerce.user`	nein
`ecommerce_order.ship`	state: paid → shipped	`ecommerce.user`	nein
`ecommerce_order.deliver`	state: shipped → delivered	`ecommerce.user`	nein
`ecommerce_order.cancel`	state: pending → cancelled	`ecommerce.user`	nein
`ecommerce_order.refund`	state: paid → refunded	`ecommerce.manager`	ja
`ecommerce_order.refund_delivered`	state: delivered → refunded	`ecommerce.manager`	ja

`ecommerce_payment`

Aktion	Bewegt	Wer sie ausführen darf	Freigabe
`ecommerce_payment.mark_failed`	state: open → failed	`ecommerce.manager`	nein
`ecommerce_payment.cancel`	state: open → cancelled	`ecommerce.manager`	nein

Berechtigungsgruppen

Von dieser App verwendete Gruppen:

ecommerce.manager
ecommerce.user

Freigabeschritte

Schritte, die ein Agent nur vorschlagen kann:

ecommerce_order.refund
ecommerce_order.refund_delivered

Was Agenten tun können und was nicht

Ein Agent kann Datensätze dieser App lesen, durchsuchen, anlegen und aktualisieren sowie Aktionen ausführen, die keine Freigabe brauchen, und zwar innerhalb der Berechtigungsgruppen seines Tokens.

Diese Schritte kann er nur vorschlagen, und eine Person muss sie freigeben: ecommerce_order.refund, ecommerce_order.refund_delivered, ecommerce_category.delete, ecommerce_listing.delete, ecommerce_listing_image.delete, ecommerce_listing_translation.delete, ecommerce_shipping_method.delete, ecommerce_discount_code.delete, ecommerce_discount_use.delete, ecommerce_tax_rate.delete, ecommerce_order.delete, ecommerce_order_line.delete, ecommerce_payment.delete.

Personenbezogene Daten werden als Platzhalter maskiert: ecommerce_discount_use.customer_hash, ecommerce_order.customer_email, ecommerce_order.customer_name, ecommerce_order.shipping_address, ecommerce_order.billing_address, ecommerce_order.discount_use_id, ecommerce_order.country.

Diese Felder werden Agenten vollständig vorenthalten: ecommerce_order.payment_reference, ecommerce_order.access_token, ecommerce_payment.external_id, ecommerce_payment.checkout_url, ecommerce_payment.refund_id.

Abhängigkeiten

Jede Abhängigkeit nennt die Versionen, die sie akzeptiert. Integrierte Apps werden mit dem Kern versioniert; eine Anforderung an sie wird daher gegen die Kernversion geprüft.

Contacts: ^0.2 (integriert)
Products: ^0.2 (integriert)

Beim Installieren dieser App aus dem Marktplatz werden fehlende Abhängigkeiten mitinstalliert, in einem Plan, der einmal bestätigt wird.

Installation

Installieren Sie sie in der App Customize (Marktplatz) oder über die Kommandozeile:

bash

obop modules install-from ecommerce

Erfordert eine Datenbank und Administratorrechte.

Selbst bauen

Der Modulleitfaden zeigt, wie Apps wie diese geschrieben werden

Wofür sie gedacht ist ​

Was das Paket leistet und was nicht ​

Moduldetails ​

Modelle ​

ecommerce_category ​

ecommerce_listing ​

ecommerce_listing_image ​

ecommerce_listing_translation ​

ecommerce_shipping_method ​

ecommerce_discount_code ​

ecommerce_discount_use ​

ecommerce_tax_rate ​

ecommerce_order ​

ecommerce_order_line ​

ecommerce_payment ​

Workflows ​

ecommerce_order ​

ecommerce_payment ​

Berechtigungsgruppen ​

Freigabeschritte ​

Was Agenten tun können und was nicht ​

Abhängigkeiten ​

Installation ​

Selbst bauen ​

Verwandte Apps

Wofür sie gedacht ist

Was das Paket leistet und was nicht

Moduldetails

Modelle

`ecommerce_category`

`ecommerce_listing`

`ecommerce_listing_image`

`ecommerce_listing_translation`

`ecommerce_shipping_method`

`ecommerce_discount_code`

`ecommerce_discount_use`

`ecommerce_tax_rate`

`ecommerce_order`

`ecommerce_order_line`

`ecommerce_payment`

Workflows

`ecommerce_order`

`ecommerce_payment`

Berechtigungsgruppen

Freigabeschritte

Was Agenten tun können und was nicht

Abhängigkeiten

Installation

Selbst bauen