Mihin se on tarkoitettu

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.

Mitä paketti tekee ja mitä ei

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.

Moduulin tiedot

Versio: 0.5.0
Tekijä: SpaceCorps
Lisenssi: AGPL-3.0-or-later
Vaatii ytimen: ^0.2 (nykyinen ydin on 0.2.0)
Kypsyys: Beta
Luokat: Myynti

Mallit

`ecommerce_category`

A group of listings shown together in the shop

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`name`	text	`none`	ei	`ecommerce.user`	selkoisena	Category name shown in the shop
`slug`	text	`none`	ei	`ecommerce.user`	selkoisena	URL part of the category, lowercase with dashes
`description`	text	`none`	ei	`ecommerce.user`	selkoisena	Short text about the category
`sequence`	number	`none`	ei	`ecommerce.user`	selkoisena	Order among categories, lowest first
`published`	bool	`none`	ei	`ecommerce.user`	selkoisena	Whether the category is visible to shoppers

`ecommerce_listing`

A product as it appears in the online shop

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`product_id`	ref → product	`none`	ei	`ecommerce.user`	selkoisena	The product being sold online
`title`	text	`none`	ei	`ecommerce.user`	selkoisena	Title shown in the shop
`slug`	text	`none`	ei	`ecommerce.user`	selkoisena	URL part of the product page, lowercase with dashes
`summary`	text	`none`	ei	`ecommerce.user`	selkoisena	One or two sentences shown on product cards
`description`	longtext	`none`	ei	`ecommerce.user`	selkoisena	Description shown on the product page, in Markdown
`image`	image	`none`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	Text that describes the main picture for people who cannot see it
`category_id`	ref → ecommerce_category	`none`	ei	`ecommerce.user`	selkoisena	The category the listing is shown under
`price`	money	`none`	ei	`ecommerce.user`	selkoisena	Shop price including tax (minor currency units, e.g. cents)
`compare_at_price`	money	`none`	ei	`ecommerce.user`	selkoisena	Previous price shown crossed out (minor currency units)
`currency`	text	`none`	ei	`ecommerce.user`	selkoisena	ISO 4217 currency code of the prices, for example EUR; empty means the shop currency from the instance settings
`sku`	text	`none`	ei	`ecommerce.user`	selkoisena	Stock keeping unit shown on the product page
`stock_policy`	select (always_available, block_when_out, allow_backorder)	`none`	ei	`ecommerce.user`	selkoisena	What happens when stock runs out: always_available, block_when_out, allow_backorder
`stock_quantity`	number	`none`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	Whether the listing is visible to shoppers

`ecommerce_listing_image`

An extra picture of a listing for its gallery

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`listing_id`	ref → ecommerce_listing	`none`	ei	`ecommerce.user`	selkoisena	The listing the picture belongs to; it is shown only while the listing is published
`image`	image	`none`	ei	`ecommerce.user`	selkoisena	The picture (PNG, JPEG, WebP or GIF, up to 5 MiB)
`alt`	text	`none`	ei	`ecommerce.user`	selkoisena	Text that describes the picture for people who cannot see it
`sequence`	number	`none`	ei	`ecommerce.user`	selkoisena	Order in the gallery, lowest first
`published`	bool	`none`	ei	`ecommerce.user`	selkoisena	Whether the picture is shown in the shop

`ecommerce_listing_translation`

A listing translated into another language

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`listing_id`	ref → ecommerce_listing	`none`	ei	`ecommerce.user`	selkoisena	The listing this translates
`lang`	select (en, de, fr, pl, fi, sv, es)	`none`	ei	`ecommerce.user`	selkoisena	Language of the translation: en, de, fr, pl, fi, sv or es
`title`	text	`none`	ei	`ecommerce.user`	selkoisena	Translated title
`summary`	text	`none`	ei	`ecommerce.user`	selkoisena	Translated card text
`description`	longtext	`none`	ei	`ecommerce.user`	selkoisena	Translated description in Markdown
`published`	bool	`none`	ei	`ecommerce.user`	selkoisena	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

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`name`	text	`none`	ei	`ecommerce.user`	selkoisena	Name shown at checkout, for example Standard delivery
`carrier`	text	`none`	ei	`ecommerce.user`	selkoisena	Carrier that delivers, for example DHL
`price`	money	`none`	ei	`ecommerce.user`	selkoisena	Delivery price (minor currency units)
`free_over`	money	`none`	ei	`ecommerce.user`	selkoisena	Order total above which delivery is free (minor currency units); empty means never
`delivery_days`	number	`none`	ei	`ecommerce.user`	selkoisena	Usual number of days until delivery
`active`	bool	`none`	ei	`ecommerce.user`	selkoisena	Whether shoppers can choose it

`ecommerce_discount_code`

A code a shopper enters at checkout for a reduction

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`code`	text	`none`	ei	`ecommerce.user`	selkoisena	The code shoppers type, for example SPRING10
`kind`	select (percent, fixed)	`none`	ei	`ecommerce.user`	selkoisena	Type of reduction: percent or fixed
`value`	number	`none`	ei	`ecommerce.user`	selkoisena	Reduction: basis points for percent (1000 is 10.00 percent), minor currency units for fixed
`starts_on`	date	`none`	ei	`ecommerce.user`	selkoisena	First day the code works (YYYY-MM-DD)
`ends_on`	date	`none`	ei	`ecommerce.user`	selkoisena	Last day the code works (YYYY-MM-DD)
`max_uses`	number	`none`	ei	`ecommerce.user`	selkoisena	How many times the code may be used in total; empty means unlimited
`used_count`	number	`none`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	Smallest order total the code applies to (minor currency units)
`per_customer_limit`	number	`none`	ei	`ecommerce.user`	selkoisena	How many times one customer (by email address) may use the code; empty means no limit
`category_id`	ref → ecommerce_category	`none`	ei	`ecommerce.user`	selkoisena	Only listings of this category get the reduction; empty means the whole order
`active`	bool	`none`	ei	`ecommerce.user`	selkoisena	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)

Lukuryhmä: ecommerce.manager. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`code_id`	ref → ecommerce_discount_code	`none`	ei	`ecommerce.manager`	selkoisena	The discount code
`customer_hash`	text	`internal`	kyllä	`ecommerce.manager`	maskattu	Hash of the customer's email address, so the per-customer limit can be checked without keeping the address here
`count`	number	`none`	ei	`ecommerce.manager`	selkoisena	Uses so far

`ecommerce_tax_rate`

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

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`name`	text	`none`	ei	`ecommerce.user`	selkoisena	Name shown on the order, for example VAT
`rate_bp`	number	`none`	ei	`ecommerce.user`	selkoisena	Rate in basis points: 1900 is 19.00 percent
`country`	text	`none`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	Only listings of this category; empty means every listing (and delivery)
`included`	bool	`none`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	Whether the rate is applied

`ecommerce_order`

An order placed online

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.user.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`number`	text	`none`	ei	`ecommerce.user`	selkoisena	Order number shown to the shopper. Free text: packages cannot generate sequences; the public checkout makes a random one
`customer_email`	text	`internal`	kyllä	`ecommerce.user`	maskattu	Email address of the shopper
`customer_name`	text	`internal`	kyllä	`ecommerce.user`	maskattu	Name of the shopper
`customer_id`	ref → party	`none`	ei	`ecommerce.user`	selkoisena	The matching contact, once the shopper is known
`shipping_address`	longtext	`internal`	kyllä	`ecommerce.user`	maskattu	Delivery address
`billing_address`	longtext	`internal`	kyllä	`ecommerce.user`	maskattu	Billing address when different from delivery
`shipping_method_id`	ref → ecommerce_shipping_method	`none`	ei	`ecommerce.user`	selkoisena	The chosen way of delivery
`discount_code_id`	ref → ecommerce_discount_code	`none`	ei	`ecommerce.user`	selkoisena	The discount code used, if any
`discount_code`	text	`none`	ei	`ecommerce.user`	selkoisena	The code the shopper entered, as it is shown on the order
`discount_use_id`	text	`internal`	kyllä	`ecommerce.user`	maskattu	Which per-customer use counter this order counted against, so it can be given back
`country`	text	`internal`	kyllä	`ecommerce.user`	maskattu	Two-letter country code of the delivery address, which decides the tax rate
`tax_summary`	longtext	`none`	ei	`ecommerce.user`	selkoisena	The tax lines of the order as JSON: name, rate in basis points, whether included in the prices, amount
`stock_returned`	bool	`none`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	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`	ei	`ecommerce.user`	selkoisena	How the shopper chose to pay: manual (bank transfer or invoice), stripe (card) or fake (demo)
`placed_on`	date	`none`	ei	`ecommerce.user`	selkoisena	Day the order was placed (YYYY-MM-DD)
`currency`	text	`none`	ei	`ecommerce.user`	selkoisena	ISO 4217 currency code, for example EUR
`subtotal`	money	`none`	ei	`ecommerce.user`	selkoisena	Sum of the lines at listing prices (minor currency units, computed by the shop at checkout)
`discount_total`	money	`none`	ei	`ecommerce.user`	selkoisena	Reduction from the discount code (minor currency units)
`shipping_total`	money	`none`	ei	`ecommerce.user`	selkoisena	Delivery charge (minor currency units)
`tax_total`	money	`none`	ei	`ecommerce.user`	selkoisena	All tax on the order, both the part included in the prices and the part added on top (minor currency units)
`total`	money	`none`	ei	`ecommerce.user`	selkoisena	Amount the shopper pays: lines, minus the discount, plus delivery, plus tax that was added on top (minor currency units)
`payment_reference`	text	`financial`	kyllä	`ecommerce.user`	pidätetty	Reference from the payment provider; never a card number
`tracking_reference`	text	`none`	ei	`ecommerce.user`	selkoisena	Carrier tracking number
`access_token`	text	`secret`	ei	`ecommerce.user`	pidätetty	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`	ei	`ecommerce.user`	selkoisena	Fulfilment status: pending, paid, shipped, delivered, cancelled, refunded

`ecommerce_order_line`

One product line of a web order

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.user.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`order_id`	ref → ecommerce_order	`none`	ei	`ecommerce.user`	selkoisena	The order the line belongs to
`product_id`	ref → product	`none`	ei	`ecommerce.user`	selkoisena	The product ordered
`listing_id`	ref → ecommerce_listing	`none`	ei	`ecommerce.user`	selkoisena	The shop listing the line was ordered from
`description`	text	`none`	ei	`ecommerce.user`	selkoisena	Product text as it was when ordered
`quantity`	number	`none`	ei	`ecommerce.user`	selkoisena	Units ordered
`unit_price`	money	`none`	ei	`ecommerce.user`	selkoisena	Price per unit including tax (minor currency units)
`subtotal`	money	`none`	ei	`ecommerce.user`	selkoisena	Line total (minor currency units, entered not computed)
`discount_amount`	money	`none`	ei	`ecommerce.user`	selkoisena	Part of the order discount that falls on this line (minor currency units)
`tax_name`	text	`none`	ei	`ecommerce.user`	selkoisena	Name of the tax applied to this line
`tax_rate_bp`	number	`none`	ei	`ecommerce.user`	selkoisena	Tax rate of this line in basis points
`tax_amount`	money	`none`	ei	`ecommerce.user`	selkoisena	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

Lukuryhmä: ecommerce.user. Kirjoitusryhmä: ecommerce.manager.

Kenttä	Tyyppi	Tietoluokka	Henkilötieto	Ryhmä	Agentit näkevät	Kuvaus
`order_id`	ref → ecommerce_order	`none`	ei	`ecommerce.user`	selkoisena	The order being paid
`provider`	select (manual, stripe, fake)	`none`	ei	`ecommerce.user`	selkoisena	Who takes the payment: manual (bank transfer or invoice), stripe (Stripe Checkout) or fake (local demo)
`external_id`	text	`financial`	ei	`ecommerce.user`	pidätetty	The provider's reference for this payment, for example a Stripe Checkout Session id. Never a card number
`checkout_url`	text	`financial`	ei	`ecommerce.user`	pidätetty	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`	ei	`ecommerce.user`	selkoisena	Payment status: open (waiting for the shopper), succeeded, failed, expired, cancelled, refunded
`amount`	money	`none`	ei	`ecommerce.user`	selkoisena	Amount to pay, set by the server from the order (minor currency units)
`currency`	text	`none`	ei	`ecommerce.user`	selkoisena	ISO 4217 currency code of the amount
`refund_id`	text	`financial`	ei	`ecommerce.user`	pidätetty	The provider's reference for the refund, once the payment was refunded
`refunded_amount`	money	`none`	ei	`ecommerce.user`	selkoisena	Amount returned to the shopper (minor currency units)
`event_ids`	longtext	`none`	ei	`ecommerce.user`	selkoisena	Ids of the provider events already applied, as JSON, so a repeated notification changes nothing

Työnkulut

`ecommerce_order`

Toiminto	Siirtää	Kuka voi suorittaa	Hyväksyntä
`ecommerce_order.mark_paid`	state: pending → paid	`ecommerce.user`	ei
`ecommerce_order.ship`	state: paid → shipped	`ecommerce.user`	ei
`ecommerce_order.deliver`	state: shipped → delivered	`ecommerce.user`	ei
`ecommerce_order.cancel`	state: pending → cancelled	`ecommerce.user`	ei
`ecommerce_order.refund`	state: paid → refunded	`ecommerce.manager`	kyllä
`ecommerce_order.refund_delivered`	state: delivered → refunded	`ecommerce.manager`	kyllä

`ecommerce_payment`

Toiminto	Siirtää	Kuka voi suorittaa	Hyväksyntä
`ecommerce_payment.mark_failed`	state: open → failed	`ecommerce.manager`	ei
`ecommerce_payment.cancel`	state: open → cancelled	`ecommerce.manager`	ei

Käyttöoikeusryhmät

Tämän sovelluksen käyttämät ryhmät:

ecommerce.manager
ecommerce.user

Hyväksyntävaiheet

Vaiheet, joita agentti voi vain ehdottaa:

ecommerce_order.refund
ecommerce_order.refund_delivered

Mitä agentit voivat ja eivät voi tehdä

Agentti voi lukea, hakea, luoda ja päivittää tämän sovelluksen tietueita sekä suorittaa toiminnot, jotka eivät vaadi hyväksyntää, tunnisteensa käyttöoikeusryhmien rajoissa.

Se voi vain ehdottaa näitä vaiheita, ja ihmisen on hyväksyttävä ne: 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.

Henkilötiedot maskataan paikkamerkeiksi: 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.

Nämä kentät pidätetään agenteilta kokonaan: ecommerce_order.payment_reference, ecommerce_order.access_token, ecommerce_payment.external_id, ecommerce_payment.checkout_url, ecommerce_payment.refund_id.

Riippuvuudet

Jokainen riippuvuus kertoo hyväksymänsä versiot. Sisäänrakennetut sovellukset versioituvat ytimen mukana, joten niitä koskeva vaatimus tarkistetaan ytimen versiota vasten.

Contacts: ^0.2 (sisäänrakennettu)
Products: ^0.2 (sisäänrakennettu)

Kun tämä sovellus asennetaan moduulikaupasta, myös puuttuvat riippuvuudet asennetaan yhdessä suunnitelmassa, jonka vahvistat kerran.

Asennus

Asenna se Customize-sovelluksesta (Marketplace) tai komentoriviltä:

bash

obop modules install-from ecommerce

Vaatii tietokannan ja ylläpitäjän oikeudet.

Tee oma

Moduulioppaassa näytetään, miten tällaiset sovellukset kirjoitetaan

Mihin se on tarkoitettu ​

Mitä paketti tekee ja mitä ei ​

Moduulin tiedot ​

Mallit ​

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 ​

Työnkulut ​

ecommerce_order ​

ecommerce_payment ​

Käyttöoikeusryhmät ​

Hyväksyntävaiheet ​

Mitä agentit voivat ja eivät voi tehdä ​

Riippuvuudet ​

Asennus ​

Tee oma ​

Liittyvät sovellukset

Mihin se on tarkoitettu

Mitä paketti tekee ja mitä ei

Moduulin tiedot

Mallit

`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`

Työnkulut

`ecommerce_order`

`ecommerce_payment`

Käyttöoikeusryhmät

Hyväksyntävaiheet

Mitä agentit voivat ja eivät voi tehdä

Riippuvuudet

Asennus

Tee oma