Code Monkey home page Code Monkey logo

1984hosting / 1984-dk-woo Goto Github PK

View Code? Open in Web Editor NEW
0.0 1.0 0.0 3.58 MB

Synchronise products, prices and inventory status between your WooCommerce store and your DK account. Have DK generate invoices automatically on checkout without worrying about setitng up an email connection for your WordPress site.

License: GNU General Public License v3.0

PHP 95.21% JavaScript 2.92% CSS 1.87%
accounting dk dkplus iceland inventory invoicing woocommerce wordpress-plugin

1984-dk-woo's Introduction

1984 DK Connection for WooCommerce

Caution

Do not open an issue ticket if you are reporting a security vulnerability. Contact 1984 Hosting directly via [email protected] or the WordPress Security Team instead.

Important

This is a code repository used for the development of 1984 DK Connection for WooCommerce, a WordPress plugin. Using the raw source files without installing dependencies using Composer will not work and the main branch is considered unstable.

Note

To download a working version of the plugin, please visit the Releases Page and download the 1984-dk-woo.zip file for a current version. In the future, you will be able visit https://wordpress.org/plugins/1984-dk-woo/ to get the currently stable release and get automatic updates.

Developer Documentation

Please note that there are two readme files. This one (reamde.md) and the user-facing readme (readme.txt) used for providing metadata to the WordPress.org plugin repository as well as a general introduction to the plugin.

This file is mainly intended for development and contribution purposes.

System Requirements

We use Github actions as a continious integration process to automatically test the plugin using the following PHP and WordPress versions:

  • PHP 8.1 and above
  • WordPress 6.1 and above

We generally assume that the most recent version of WooCommerce is in use and use that for testing across the supported PHP and WordPress versions.

Introduction and main concepts

In the most simple terms this WordPress plugin syncs information between a WooCommerce store and the DK accounting software. It syncs product data, creates invoices for fulfilled orders and sync stock levels for products between the two.

Two sources of truth

  • The WooCommerce store is the source of truth for product prices and availability towards the customer
  • The DK setup is the source of truth for accounting transactions

MVP requirements

User interface

  • Add a settings page and corresponding JSON endpoint to wp-admin
  • Design and add options for sync to the WooCommerce product editor

Kennitala support

  • Add a kennitala field to the shortcode based checkout page
  • Add a kennitala field to the block based checkout page
  • Integrate kennitala to the WooCommerce order editor
  • Add a kennitala text field to the user profile editor

Localisation/translation

  • Add Icelandic locale files

Products

  • Create a corresponding product record in DK when a WooCommerce product is created
  • Sync changes to product records upstream from WooCommerce on update
  • Sync changes to product records downstream from DK on regular intervals or using web hooks

Product Inventory

  • Sync and create product inventory when a product is created in DK
  • Assign a single warehose in DK for items in the WooCommerce store

Customers

  • Let customers add a kennitala to their billing address
  • Create a corresponding customer record in DK when a WooCommerce customer is created
  • Sync changes to customer records upstream from WooCommerce on update
  • Sync changes to customer records downstream from DK on regular intervals or using web hooks

Orders and invoices

  • Create and send invoices to customers via DK after a successful payment
  • Create and send credit invoices on returns
  • Take over the WooCommerce invoice email delivery mechanism and use the same hooks to send invoices via DK

Cost SKUs

  • Assign SKU for delivery costs
  • Assign a SKU for other costs
  • Assign a SKU for coupons

Payment methods

  • Map Payment Gateways in WooCommerce with Payment Methods in DK

Salesperson

  • Assign a salesperson in DK for sales in WooCommerce

Maths

  • Use a BigDecimal-like library to handle tax calculations and such instead of depending on PHP's decimal support

Error handling

  • Improve error handling and validation (Possibly replace false return values in Export classes with WP_Error, and then doing wp_die() on failure instead of failing softly).

Future Features (after the first release)

  • Sync WooCommerce orders with the DK Sales Order module
  • Assign a price group (1, 2, 3) for products

The DK API

The DK API documentation

The DK API documentation is well known for being inaccurate and it seems to be written by two different programmers. They also don't seem to like each other very much.

One version of it can be found at https://apidoc.dkplus.is/ and is generated using Postman.

The other version is generated using Swagger and is available at https://api.dkplus.is/swagger/ui/index.

Either version documents certain endpoints at different states. Some features are missing and some of the specifics described seem to be documented ahead of time and don't actually exsist (as they may only be working internally, with the public version trailing behind). There are also spelling errors and other discrepencies in some JSON properties that are not reflected in the documentation.

Caveats

DK will cut off some string values that exceed its limits without warning. This is not well documented by them.

  • Product Codes (SKU): The DK API is unable to accept longer values than 20.
  • Product variations need to be treated as separate products
  • Product variation SKUs have to be unique and not the same as the parent.
  • Product descriptions: The DK API is unable to accept longer textual values than 40.

This means that syncing product descriptions etc. may not be possible using orthodox methodologies and that string values should always be assumed to be either 20 or 40 characters long. (It may be possible to do so via "attachments" but the documentation for those remains questionable.)

Contributing

The main code repository for the plugin is at https://github.com/1984hosting/. The Subversion account for the WordPress plugin respository is used for "built" releases of the plugin.

We are happy to receive patches and pull requests for new feature ideas, bug fixes and translations. Please contact us directly at [email protected] or the WordPress Security Team in case of security voulnerabilities.

If you are reporting a bug, please describe the steps needed to be taken so that we can replicate it, if possible.

And last but not least, be nice to us and others.

Contact Us

You can contact 1984 Hosting directly by email via [email protected]. The communication lines are short, so you will reach the right person that way, even when it comes to security related issues.

The main author can be contacted via [email protected]. She is available for hire, some of her previous work can be found at and she can be supported via Github Sponsors at https://github.com/sponsors/aldavigdis.

License

This plugin is provided to you as free software under the GPLv3 license. Runtime dependencies are provided under the MIT and Apache licenses, which are compatible with the GPLv3.

1984 DK Connection for WooCommerce

Copyright (C) 2024 1984 Hosting and contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.


1984 Hosting

1984-dk-woo's People

Contributors

aldavigdis avatar ayachmenev avatar it-hive-true avatar helgihg avatar

Watchers

 avatar

1984-dk-woo's Issues

Figure out what different prices mean on DK's side (price 1, price 2 and price 3).

The different prices 1, 2 and 3 simply reflect different prices that the client-side might use in different contexts. For example, if the client-side wanted to have a different discount price when purchasing multiple items at a time, or maybe a special deal with some clients or what not.

We don't need to concern ourselves with that for now, since the plugin doesn't offer any such differences in pricing, at least yet.

If it's possible to program it so that we might easily add it later, that would be nice, though.

Item quantity in DK should be reduced by same amount as ordered.

Take product "Twelve Hundred Forty Four", and let's say that it has unit quantity in DK of 1244 items available.

If you order 4 such items in WooCommerce, the quantity in DK is reduced by 4 in WooCommerce, but only by 1 in DK.

As can be seen in the following screenshots:

WooCommerce (1244-4):
image

DK (1244-1):
image

Add currency conversion support

It turns out that we can't assume that the currency used in DK and the WooCommerce shop is the same as one of our initial users is using EUR as their accounting currency in DK, while their WooCommerce shop uses ISK. This means that we need to add currency conversion support:

  • Fetch currency rates hourly from DK.
  • If the WooCommerce shop uses a different currency from DK, product prices need to be converted on sync if price sync is enabled.
  • Add a checkbox to the wp-admin interface for disabling price sync by default
  • Add an option for conversion markup to reduce risk from rate fluctuations

Currency rates are fetched vita a HTTP GET request to https://api.dkplus.is/api/v1/general/currency.

Settings are boolean but should be array in App\Core\Main.

Stacktrace:

2022-06-14T12:47:38+00:00 CRITICAL Uncaught TypeError: Typed property woo_bookkeeping\App\Core\Main::$settings must be array, bool used in /var/www/html/wp-content/plugins/woocoo/App/Core/Main.class.php:13
Stack trace:
#0 /var/www/html/wp-content/plugins/woocoo/woo_bookkeeping.php(39): woo_bookkeeping\App\Core\Main->__construct()
#1 /var/www/html/wp-includes/class-wp-hook.php(307): woo_bookkeeping_load()
#2 /var/www/html/wp-includes/class-wp-hook.php(331): WP_Hook->apply_filters()
#3 /var/www/html/wp-includes/plugin.php(476): WP_Hook->do_action()
#4 /var/www/html/wp-settings.php(598): do_action()
#5 /var/www/html/wp-config.php(96): require_once('/var/www/html/w...')
#6 /var/www/html/wp-load.php(50): require_once('/var/www/html/w...')
#7 /var/www/html/wp-admin/admin.php(34): require_once('/var/www/html/w...')
#8 /var/www/html/wp-admin/plugins.php(10): require_once('/var/www/html/w...')
#9 {main}
  thrown in /var/www/html/wp-content/plugins/woocoo/App/Core/Main.class.php on line 13

Determine: Product reservation on adding to cart

Developer asks:

Next question is
Should we reserve the product when user adds it into the cart? If yes, then on what time should it be reserved? If at some reason order wasn't completed, after what time a product will be unreserved?

Figure out how to charge for shipping.

This is apparently a bit of a complicated question.

I have consulted Sigmundur on the topic. He intends to send me examples of the complications before the end of 2023-01-11.

Change the plugin name and slug in accordance with WordPress.org plugin review

Just got the following from the WordPress.org plugin review team:

Your plugin display name is: 1984 DK Connection for WooCommerce

Which made the following plugin permalink (aka slug): 1984-dk-woo

Due to the legality of trademarks, and confusion that could happen due to ownership and representation, we cannot permit your chosen display name nor slug and require you to change them.

What to do next

This email contains a great deal of information that will help you with renaming your plugin. Please read the entire email carefully (especially the 'Why This Matters' section) as it will address common mistakes that will delay your review.

We have changed your plugin permalink: 1984-connection-dk-woocommerce

And recommend the following display name: 1984 Connection for DK and WooCommerce

We need you to do the following:

Confirm the permalink is acceptable or suggest one you prefer (note: you must specifically request a different permalink if desired)
Update your code with a new Display Name that does not infringe on trademarks in both the readme and the main plugin file
Go to "Add your plugin" and upload an updated version of this plugin.

Be advised, your display name may not begin with any trademarked terms, nor use them in a manner that might imply a relationship. This often includes portmanteau when meant to reference trademarks for another entity. Some trademarks have stricter enforcement laws than others.

Alternatively if you feel this decision was made in error, you can do one of the following:

Prove that you legally have the right to the original name/slug
Provide the user account for an official owner to whom we should transfer the plugin

This looks a bit silly as we are not connecting DK or WooCommerce with 1984, but the other two, so the options are to:

  • Bite the bullet and let the plugin review team dictate the plugin name and slug
  • Make a reservation about this silliness

WooCommerce: An invalid phone number during checkout reduces product stock, when it shouldn't.

During checkout in WooCommerce, but putting in an invalid phone number like "aerg", then WooCommerce still reduces the stock.

This may be a bug in WooCommerce, but we need to make sure that it's not a bug in Woocoo.

Even weirder is that the stock in DK seems to be reduced by twice as much.

To reproduce:

  1. Place 5 items of a product in the cart (GoodVin3, for example).
  2. During checkout, put in an invalid phone number, like "aerg" and press "PLACE ORDER".
  3. See stock in WooCommerce, which has dropped by 5, even though the purchase did not go through.
  4. See stock in DK, which has dropped by 10, even though the purchase did not go through.

Determine: Timing of the sending of invoice

Developer asks:

Regarding invoices.
Should we generate invoice before payment or after payment? Who will proceed with the payment? We have not found yet, if DK has the payments integration and if it sends the payment statuses.

Import price with VAT.

The imported price is currently without Value-Added Tax (VAT). The imported price should be the one that contains the tax.

See in DK:
image

The number "12.400" in the following image should be "15.376":

image

Figure out how to handle variable products.

Products may come in different varieties, for example a T-shirt that comes in different colors and sizes.

It is currently not obvious how they are managed in DK. We have asked DK and hope to have a response soon. We will also converse with an advisor on how existing software manages this.

Price

In the process, it remains to send the properties to the DK

Option to use VAT-included price (Податок_на_додану_вартість)

Prices in Iceland (and elsewhere in Europe) are shown with VAT included (Податок_на_додану_вартість).

Currently, Woocoo only displays the base price from DK.

In the following image, the base price is to the left, and the VAT-included price is to the right. (VAT in Icelandic is called "Virðisaukaskattur" and is abbreviated as "VSK".)

image

In order to set up VAT tax rates in WooCommerce, the following steps are required:

  1. Enter WordPress administration.
  2. Select WooCommerce on the left.
  3. Select "Settings".
  4. Under the "General" tab, enable the checkbox called "Enable taxes" - and save.
  5. A new tab, called "Tax" should now be visible under WooCommerce -> Settings.

In that tab, WooCommerce allows the user to create different tax rates, that are later applied to products. I have created two tax rates, one is 24% and another is 11%. The WooCommerce user must select which tax to apply for each product, because some products are 24% and others are 11%.

Here is a screenshot of the 24% tax rate, called "Standard rates".

image

Here is a screenshot of the 11% tax rate, called "Reduced rate rates".

image

When users enter the product, they select which tax rate to use here:

image

Also, there is this option in WooCommerce -> Settings -> Tax, which allows the user to decide whether a price that is entered into WooCommerce, already contains the VAT, or if the VAT should be calculated on top of it. The syncing with DK should support this option.

Make plugin translate-able.

We will need the plugin in English and Icelandic, at least.

1984 can make the actual translations, but strings in the plugin need to be translate-able.

Determine: Checking of product quantity and availability

Developer asks:

There are different ways when we can check the product quantity and it's availability.

a) through some period of time. For example evey 1 hour. But in this case it can by out of sync in some short time period. For example it product is last one and we got information that it is in stock, but within this hour it was sold. Then user only in the cart will see that product is already sold and he will not be able to buy it. It is not critical quantity more than 5 in the stock, but if there is only last items left in the stock, this situation may be happened.

b) another way if we will check the product quantity every time when user enters product page. But in this case the time of page loading will be bigger, because we will wait for result from DK about product quantity.

and in any of the ways above we will surely check the product quantity again when user adds product into the cart.

Product name should not be updated, only price/inventory

From README.md:

Field synchronization by field:

  • SKU (product ID): The common identity between both systems, used to identify what products to add and update.
  • Name/Description: Transferred from DK to WooCommerce when product is added, but not updated after that, because users may want different descriptors in WooCommerce than in DK.
  • Inventory/Price: Always updated from DK to WooCommerce.

Import from dkPlus: VAT calculations

When a product is added to dkPlus, the price is given without VAT. The VAT Is then calculated on top of the entered price.

This means that a product with a base price of 12.400 and 24% VAT, will have the total VAT-included price of 15.376, which is 12.400 * 1.24.

image

However, in Woocoo, the price received from dkPlus is assumed to include VAT, so the number gets divided: 12.400 / 1.24.

image

Quantity is not updating on DK's side

The interface on DK's side is incorrect. The user is presented with the option of changing quantity, but it does not update on DK's side.

Apparently more is needed to update quantity. Some kind of transaction. @helgihg will investigate.

Fetching products from DK

The DK test account contains almost 11.000 products, which is infeasible to work with to develop this feature. We will need our own DK test account to adequately develop and test this functionality.

@helgihg will investigate.

Determine: Price synchonization priority

Developer asks:

The Price synchoronization, how and when should it be happened?
For example if price is changed in the DK system, should it be automatically changed on the site itself? Or if the price is changed on the site, but in the DK stock it is different. Which price should be in priority?

Prevent invoices from being POSTed to DK if the relevant order has a product without a SKU

DK can't make an invoice if a DK product ID (SKU in WC) is not assigned to a product or if a product has a SKU but it does not belong to a product in DK.

Currently, the DK API returns an error if an invoice with a product missing its SKU is POSTed. We need to prevent from the POST request from happening and log it into the Order Notes if there is such a product in an order.

This is not an edge case, as new users are likely to have several WooCommerce products without a SKU or a SKU matching a DK product ID.

Determine: Product synchronization priority

Developer asks:

There are a two ways how the store can be synchronized with DK system:
a) if the woocommerce store has its own products on the site and it is synchronized with DK for example by product ID (sku). And all information about product is placed on the site itself, but from DK we get quantity of product and if it is in stock or out of stock
b) the second way if we have relatively empty woocommerce site, and all product with its information and details we get from DK sytem. So it is fully linked with DK, not just quanity, but all the details of the product.
Which way would you prefer? Or should we realise both ways?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.