How To's
Github testshop
The code for the externalshop can be found here https://github.com/webwinkelfacturen/externalshop.Loom overview of the externalshop code: https://www.loom.com/share/d5a1e61934114f2ca562c8f92006d4e4?sharedAppSource=team_library
To connect to Wisteria OAuth is used. There is example code for this and it is explained here: https://www.loom.com/share/c41e270007c54ea9a67f99d79dd36220?sharedAppSource=team_library
The Wisteria tests: https://www.loom.com/share/d3bdd7e8852b4c20958c45d22832849c?sharedAppSource=team_library
To add a merchant to your partner dashboard: https://www.loom.com/share/1be01ed729984325b9aacba4bb7cbcfc
Signatures
What?
Signing requests
Why?
Done for security.
Example signing post
The input for the signing request is the data to be added, the currect date and the clientsecret.
In PHP the calculation is done as, where the reset function returns the first item in the array:
md5( gmdate("Ydm").gmdate("dmY").$secret.(string)reset($array).gmdate("dmY") )
So for
- $secret = DBsrN.lt6RZ6G4TJGtdGbDo.F and
- $array = ["order" => '{"orderid":100012510}']
- md5(
'20223105'.'31052022'.'DBsrN.lt6RZ6G4TJGtdGbDo.F'.'{"orderid":100012510}'.'31052022'
)
- the signature would be 97586f4d3ef50ea70622d4132955d430
Example signing read
md5( gmdate("Ydm").gmdate("dmY").$secret.gmdate("dmY") )
- $secret = DBsrN.lt6RZ6G4TJGtdGbDo.F and
- the signature would be 123da89bf3fd9d2aebf74cf6017cc6e3
In the example code: externalshop/system/utils/constants.php
Categories
What?
Add categories from the shop to Wisteria.
Why?
Categories are used when pushing closures to Wisteria. In the closures both the turnover and the payments are pushed.
There is a choice between pushing the turnover based on the taxes or on these categories.
Notice: The categories are NOT used for pushing individual sales.
Example post
Request
Response
In the example code: externalshop/tests/categoryapi/addCategories.php
Closures
What?
Add dayclosures from the POS to Wisteria.
Why?
This option can be used if you want to add the dayclosure of a POS. You simple add all turnover per productgroup and
payments per paymentmethod. You do not need to push the underlying receipts. Wisteria creates a daily booking based on
the closure and will push this closure to the accounting system.
Wisteria checks if the categories and paymentmethods are already available. Matching is done on the groupid for categories and
the methodid for the paymentmethods. If a category or paymentmethod is not available it is added automatically to Wisteria.
This means that you will not need separate calls to add categories and paymentmethods.
If you pos works with closures this is an easy way to push the pos finances. It is also easy to verify the booking in the
accounting system with the closure data. If you do not have closures in the pos you should not use this option. In that case
it is better to push the receipts.
Example post
Request
Response
In the example code: externalshop/tests/closureapi/addClosure.php
Customers
What?
Add customer-details from the shop to Wisteria.
Why?
For shop sales customer-details should also be added to the accounting system. The sales for this customer can
then always be booked using this customer in the accounting system. Matching will be done on emailaddress.
There are two ways to add the customer. The customer can be added as part of the sales. Care must be taken that the customer is not already present.
The check is done on customer id and emailaddress. It is also possible to add a customer separately to Wisteria. This option can be choosen if all
sales must be booked on one default debtor.
Example post
Request
Response
In the example code: externalshop/tests/customerapi/addCustomer.php
Ledgercodes
What?
Add ledgercodes to Wisteria.
Why?
The ledgercodes are used in the configuration of the connector. There must be a way to match the ledgercodepercentages from the shop with the
the ledgercodes in the accounting system. Since very often there must a booking in the accounting system
per country we advise you add the ledgercodes per EU iso country code. It is also useful to add separate ledgercodes for the UK, Norway and
Switzerland.
Add one ledgercode for ICP inside the EU and one ledgercode for sales outside the EU.
Example post
Request
In the example code: externalshop/tests/ledgercodeapi/addLedgercodes.php
Sales
What?
Add sales from the shop to Wisteria.
Why?
When adding the shop sales to Wisteria our connectors will pick them up and push them to the accounting system.
A sale consists of sale-lines (required) and possibly shipping, paymentcosts and fees. Discounts can be given either as an overall amount
or per saleline, not both.
When adding an sale to Wisteria many validity checks will be done. It will be checked whether the sale totals match the amounts on the lines.
If both unitprices and lineprices are given in the sale-lines it is checked that these amounts are in sync. Wisteria will accept a delta of max 5 cents.
It is possible to add customer-data with the sale or to add a customerid. If a customerid is used, a customer with that customerid must be
in Wisteria. If the customer-data is added it must be ensured that the customer is not yet in Wisteria. Matching is done on the emailaddress and
the customerid given in the customerdata.
The checks are done to ensure that the data in Wisteria is correct data.
Example post
Request
Response
In the example code: externalshop/tests/saleapi/addSale.php
Paymentmethods
What?
Add the shop paymentmethods to Wisteria.
Why?
The connector uses paymentmethods in two situations:
- Individual sales: Normally the customer-data is pushed to the accounting system. Sometimes this is not required because adding all these customers to the accounting system will result in too many customers in the accounting system. By assigning default debtors per paymentmethod the number of customers in the accounting system will be restricted. Using the fixed debtors may also make an easier matching possible between the payments and sales.
- Closures: For closures the payments are assigned to ledgercodes, depending on the paymentmethods.
Example post
Request
In the example code: externalshop/tests/paymentmethodapi/addPaymentmethods.php
Taxes
What?
Add taxes to Wisteria.
Why?
The taxes are used in the configuration of the connector. There must be a way to match the taxpercentages from the shop with the
taxes, and if applicable, the ledgercodes in the accounting system. Since very often there must a booking in the accounting system
per country we advise you add the taxes per EU iso country code. It is also useful to add separate taxes for the UK, Norway and
Switzerland.
The connector will itself add tax-codes for ICP and sales outside Europe. Taxes for countries outside the EU unequal to UK, Norway and Switzerland will not be processed by the connector. If you try to add them you will receive an error message.
Example post
Request
In the example code: externalshop/tests/taxapi/addTaxes.php
How to connect
Are you looking for instructions how to add, read and remove data to and from Wisteria? Here you can find How to's including code examples.
Which entities
You can choose which entities to use. You can add sales via the order, invoice, receipt, refund and
closure endpoints. You can add additional information via the customer, taxes, payment-methods and category endpoints. You can collect the financial transaction for the accounting system.
Flow via Wisteria to Invoicesystem
Once your data is added to Wisteria the connection with the accounting/invoicesystem can be configured provided the merchant has subscribed to an accounting connection.
The sale will automatically be pushed from Wisteria to the accountingsystem. More details how this can be done and some do's and don'ts….
