Github testshop
The code for the externalshop can be found here
https://github.com/webwinkelfacturen/externalshop.
The code for the external accountingsystem can be found here
https://github.com/webwinkelfacturen/externalbs.
Loom overview of the externalshop code:
https://www.loom.com/share/d5a1e61934114f2ca562c8f92006d4e4?sharedAppSource=team_library
Loom overview of the externalbs code:
https://www.loom.com/share/68bb7ab98fd047d0ab7c6d91551c68d8
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
Example signing read
md5( gmdate("Ydm").gmdate("dmY").$secret.gmdate("dmY") )
- date = 2022-05-31
- $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 in the daily bookings to the accounting systems. In the daily bookings both the turnover and the payments are pushed.
There is a choice between pushing the turnover based on the taxes or on the product categories.
Notice: The categories are NOT used for pushing individual sales. So the categories are not used when pushing
orders, invoices, individual receipts and refunds.
Example post
Request
{"categories":"[{\"categoryid\":111,\"code\":\"CAT_001\",\"name\":\"Tea\"},{\"categoryid\":112,\"code\":\"CAT_002\",\"name\":\"Bread\"},{\"categoryid\":211,\"code\":\"CAT_003\",\"name\":\"Cookies\"},{\"categoryid\":212,\"code\":\"CAT_004\",\"name\":\"Vegetables\"}]","signature":"d7283f9128fe22ae8d2db1e887f9467d"}
Response
{"data":[{"categoryid":"111","code":"CAT_001","name":"Tea"},{"categoryid":"112","code":"CAT_002","name":"Bread"},{"categoryid":"211","code":"CAT_003","name":"Cookies"},{"categoryid":"212","code":"CAT_004","name":"Vegetables"}],"message":"Your data is inserted successfully"}
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
{"closure":"{\"closureid\":111,\"closurenumber\":\"CLS_001\",\"closurename\":\"Dagafsluiting 2021-03-21\",\"closuredate\":\"2021-03-21\",\"registerid\":\"2\",\"registername\":\"Toonbank\",\"currency\":\"EUR\",\"productcategories\":[{\"groupid\":1,\"lineExcl\":50,\"taxValue\":4.5,\"taxRate\":9},{\"groupid\":2,\"lineExcl\":50,\"taxValue\":4.5,\"taxRate\":9},{\"groupid\":3,\"lineExcl\":100,\"taxValue\":4.5,\"taxRate\":21}],\"payments\":[{\"methodid\":1,\"total\":54.5},{\"methodid\":2,\"total\":121}]}","signature":"491fcaba18d1e1dafe8df20872fee0fc"}
Response
{"data":{"closureid":"111","closurenumber":"CLS_001","closurename":"Dagafsluiting 2021-03-21","closuredate":"2021-03-21 00:00:00","currency":"EUR","registerid":"2","registername":"Toonbank","payments":[{"closureid":"111","methodid":"1","methodname":null,"total":"54.5"},{"closureid":"111","methodid":"2","methodname":null,"total":"121"}],"productcategories":[{"groupid":"1","currency":null,"lineExcl":"50.0000","taxValue":"4.5000","taxRate":"9.0000"},{"groupid":"2","currency":null,"lineExcl":"50.0000","taxValue":"4.5000","taxRate":"9.0000"},{"groupid":"3","currency":null,"lineExcl":"100.0000","taxValue":"4.5000","taxRate":"21.0000"}]}
In the example code: externalshop/tests/closureapi/addClosure.php
Customers
What?
Add customer-details from the shop to Wisteria.
Why?
For shop orders, refunds and invoices very often the 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 order or invoice. 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
orders / refunds / invoices must be booked on one default debtor.
Also for receipts a customer can be added. The only difference is that it is not required.
Example post
Request
{"customer":"{\"customerid\":1,\"customernumber\":\"CUST001\",\"firstname\":\"Jean\",\"lastname\":\"Doe\",\"company\":\"Grocery online\",\"address1\":\"Stationstraat 12\",\"zipcode\":\"1000 AA\",\"city\":\"Amsterdam\",\"isocountry\":\"NL\",\"mobile\":\"0612345678\",\"email\":\"jean@mycompany.nl\"}","signature":"f4fd6431c2bfcef9d6288caa2aa24d9b"}
Response
{"data":{"customerid":"1","orderid":"","customernumber":"CUST001","firstname":"Jean","lastname":"Doe","company":"Grocery online","address1":"Stationstraat 12","address2":null,"housenr":null,"zipcode":"1000 AA","city":"Amsterdam","state":null,"country":null,"isocountry":"NL","kvk":null,"btwnr":null,"telnr":null,"mobile":"0612345678","email":"jean@mycompany.nl","iscompany":null,"isicp":null,"isinternational":null,"incltax":null},"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/customerapi/addCustomer.php
Financial transaction
What?
Read financial transactions from Wisteria.
Why?
The financialtransactions are used as input for the financial booking in the external accountingsystem.
A financial transaction consists of two parts. A part friendly with parsed data. The fields are fixed and
information on VAT and ledgercode from the external accounting system is already added.
The second part is the raw order from the shop system. This part can be used if data must be enriched.
Retrieve a financial transaction from Wisteria.
Example get
Request
url with signature
Response
{"data":{"friendly":{"orderid":8832,"customerid":"CUST123","affiliatenr":"AFF001","items":[{"productid":1902,"variantid":"","categoryids":"","quantity":1,"articlecode":"","ean":"","mpn":"","sku":1902,"description":"Witte fiets","taxpercentage":21,"invoicesystemtaxid":"VATCODE1","unitDiscountIncl":0,"unitDiscountExcl":0,"lineDiscountIncl":0,"lineDiscountExcl":0,"linePriceExclNoDiscount":66.11,"linePriceInclNoDiscount":79.99,"linePriceExclWithDiscount":66.11,"linePriceInclWithDiscount":79.99,"unitPriceExclNoDiscount":66.11,"unitPriceInclNoDiscount":79.99,"unitPriceExclWithDiscount":66.11,"unitPriceInclWithDiscount":79.99,"itemVatNoDiscount":13.88,"itemVatWithDiscount":13.88,"lineVatNoDiscount":13.88,"lineVatWithDiscount":13.88,"itemdiscountVat":0,"linediscountVat":0,"productname":"","variantname":"","meta":[{"id":100268,"key":"_reduced_stock","value":"1","display_key":"_reduced_stock","display_value":"1"}],"ledgercode":"80001","taxledgercode":""}],"shipping":{"quantity":1,"description":"Post NL","sku":"","articlecode":"","ean":"","mpn":"","productid":"","variantid":"","taxpercentage":"21","invoicesystemtaxid":"VATCODE1","unitDiscountIncl":"","unitDiscountExcl":"","lineDiscountIncl":"","lineDiscountExcl":"","linePriceExclNoDiscount":5.99,"linePriceInclNoDiscount":7.25,"linePriceExclWithDiscount":5.99,"linePriceInclWithDiscount":7.25,"unitPriceExclNoDiscount":5.99,"unitPriceInclNoDiscount":7.25,"unitPriceExclWithDiscount":5.99,"unitPriceInclWithDiscount":7.25,"itemVatNoDiscount":1.2579,"itemVatWithDiscount":1.2579,"lineVatNoDiscount":1.2579,"lineVatWithDiscount":1.2579,"itemdiscountVat":null,"linediscountVat":null,"ledgercode":"60003","taxledgercode":""},"payment":{"paymentid":"mollie_wc_gateway_ideal","quantity":1,"description":"iDEAL","articlecode":"","ean":"","mpn":"","sku":"","productid":"","variantid":"","taxpercentage":0,"invoicesystemtaxid":"","unitDiscountIncl":0,"unitDiscountExcl":0,"lineDiscountIncl":0,"lineDiscountExcl":0,"linePriceExclNoDiscount":0,"linePriceInclNoDiscount":0,"linePriceExclWithDiscount":0,"linePriceInclWithDiscount":0,"unitPriceExclNoDiscount":0,"unitPriceInclNoDiscount":0,"unitPriceExclWithDiscount":0,"unitPriceInclWithDiscount":0,"itemVatNoDiscount":0,"itemVatWithDiscount":0,"lineVatNoDiscount":0,"lineVatWithDiscount":0,"itemdiscountVat":0,"linediscountVat":0,"ledgercode":"8000","taxledgercode":0},"payments":[{"paymentid":"mollie_wc_gateway_ideal#ord_xxxxx","orderid":8832,"ordernumber":null,"invoiceid":null,"transactionid":"tr_t4vmE2SldP","amount":"87.24","paymentdate":"2022-04-06","paymentmethodid":null,"paymentmethod":"iDEAL","type":null,"currency":"EUR","status":"paid"}],"orderstatus":"completed","paymentstatus":"paid","invoiceid":"1112","invoicenumber":"2685","ordernumber":"3169","orderdate":"2022-04-06T16:59:40","isicp":false,"isinternational":false,"currency":"","ordertotalExclNoDiscount":72.1,"ordertotalInclNoDiscount":87.24,"ordertotalExclWithDiscount":72.1,"ordertotalInclWithDiscount":"87.24","ordertotalVatExclDiscount":15.14,"ordertotalVatInclDiscount":"15.14","carttotalExclNoDiscount":0,"carttotalInclNoDiscount":0,"carttotalExclWithDiscount":0,"carttotalInclWithDiscount":0,"carttotalVatExclDiscount":0,"carttotalVatInclDiscount":0,"orderdiscountIncl":0,"orderdiscountvat":0,"orderdiscountExcl":0,"notes":"","paymentid":"mollie_wc_gateway_ideal","paymentmethod":"iDEAL","customer":{"customerid":-1,"orderid":-1,"referenceid":"","firstname":"Sophie","lastname":"Fischer","password":null,"company":"","address1":"Stationstraat 12","address2":"","housenr":"","zipcode":"1000 AA","city":"Amsterdam","state":"","country":"NL","isocountry":"NL","deliveryfirstname":"Sophie","deliverylastname":"Fischer","deliverycompany":"","deliveryaddress1":"Stationstraat 12","deliveryaddress2":"","deliveryhousenr":null,"deliveryzipcode":"1000 AA","deliverycity":"Amsterdam","deliverystate":"","deliverycountry":"NL","deliveryisocountry":"NL","kvk":"","btwnr":"","telnr":"0623138822","mobile":"","email":"info@sponiza.nl"},"transactionid":"123456"},"raw":{"id":8832,"parent_id":0,"status":"completed","currency":"EUR","version":"5.6.2","prices_include_tax":true,"date_created":"2022-04-06T16:59:40","date_modified":"2022-04-07T10:34:10","discount_total":"0.00","discount_tax":"0.00","shipping_total":"5.99","shipping_tax":"1.26","cart_tax":"13.88","total":"87.24","total_tax":"15.14","customer_id":0,"order_key":"wc_order_lHBTCHiyxZYX3","billing":{"first_name":"Sophie","last_name":"Fischer","company":"","address_1":"Stationstraat 12","address_2":"","city":"Amsterdam","state":"","postcode":"1000 AA","country":"NL","email":"info@sponiza.nl","phone":"0623138822"},"shipping":{"first_name":"Sophie","last_name":"Fischer","company":"","address_1":"Stationstraat 12","address_2":"","city":"Amsterdam","state":"","postcode":"1000 AA","country":"NL","phone":""},"payment_method":"mollie_wc_gateway_ideal","payment_method_title":"iDEAL","transaction_id":"ord_3lnmu4","customer_ip_address":"82.169.196.205","customer_user_agent":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/100.0.4896.60 Safari\/537.36","created_via":"checkout","customer_note":"","date_completed":"2022-04-07T10:34:10","date_paid":"2022-04-06T17:00:08","cart_hash":"7xcdfg69786753b73e3scc47099f23fsd","number":"3169","meta_data":[{"id":254618,"key":"_order_number","value":"3169"},{"id":254652,"key":"_billing_street_name","value":"Stationstraat"},{"id":254653,"key":"_billing_house_number","value":"12"},{"id":254654,"key":"_billing_house_number_suffix","value":""},{"id":254655,"key":"_shipping_street_name","value":"Stationstraat"},{"id":254656,"key":"_shipping_house_number","value":"12"},{"id":254657,"key":"_shipping_house_number_suffix","value":""},{"id":254658,"key":"is_vat_exempt","value":"no"},{"id":254659,"key":"_postnl_order_version","value":"4.2.0"},{"id":254660,"key":"_postnl_order_weight","value":"0"},{"id":254661,"key":"_postnl_shipment_options_extra","value":"a:2:{s:12:\"collo_amount\";i:1;s:6:\"weight\";d:0;}"},{"id":254662,"key":"_postnl_highest_shipping_class","value":"flat_rate:1"},{"id":254663,"key":"_postnl_delivery_options","value":"O:36:\"WCPN_DeliveryOptionsFromOrderAdapter\":6:{s:7:\"\u0000*\u0000date\";N;s:15:\"\u0000*\u0000deliveryType\";s:8:\"standard\";s:14:\"\u0000*\u0000packageType\";s:7:\"package\";s:18:\"\u0000*\u0000shipmentOptions\";O:36:\"WCPN_ShipmentOptionsFromOrderAdapter\":7:{s:12:\"\u0000*\u0000signature\";N;s:17:\"\u0000*\u0000only_recipient\";N;s:12:\"\u0000*\u0000age_check\";N;s:15:\"\u0000*\u0000large_format\";N;s:9:\"\u0000*\u0000return\";N;s:12:\"\u0000*\u0000insurance\";N;s:20:\"\u0000*\u0000label_description\";N;}s:10:\"\u0000*\u0000carrier\";N;s:17:\"\u0000*\u0000pickupLocation\";N;}"},{"id":254664,"key":"_mollie_order_id","value":"ord_3lnmu4"},{"id":254665,"key":"_mollie_payment_id","value":"tr_u5vmE2NsdP"},{"id":254666,"key":"_mollie_payment_mode","value":"live"},{"id":254674,"key":"_new_order_email_sent","value":"true"},{"id":254675,"key":"_mollie_paid_and_processed","value":"1"},{"id":254725,"key":"_wcpdf_packing_slip_date","value":"1649324049"},{"id":254726,"key":"_wcpdf_packing_slip_date_formatted","value":"2022-04-07 10:34:09"},{"id":254727,"key":"_postnl_shipments","value":"a:1:{i:148294623;a:4:{s:11:\"shipment_id\";i:148294623;s:6:\"status\";s:20:\"pending - registered\";s:11:\"track_trace\";s:15:\"3DVDFH206812878\";s:8:\"shipment\";a:39:{s:2:\"id\";i:148294623;s:9:\"parent_id\";N;s:10:\"account_id\";i:139450;s:7:\"shop_id\";i:54852;s:13:\"shipment_type\";i:1;s:9:\"recipient\";a:10:{s:2:\"cc\";s:2:\"NL\";s:6:\"person\";s:28:\"Sophie Fischer\";s:11:\"postal_code\";s:7:\"1000 AA\";s:4:\"city\";s:11:\"Amsterdam\";s:5:\"email\";s:29:\"info@sponiza.nl\";s:5:\"phone\";s:0:\"\";s:6:\"street\";s:14:\"Stationstraat\";s:22:\"street_additional_info\";s:0:\"\";s:6:\"number\";s:2:\"12\";s:13:\"number_suffix\";s:0:\"\";}s:6:\"sender\";a:10:{s:7:\"company\";s:23:\"Sponiza IT op Bos\";s:11:\"postal_code\";s:6:\"1791AD\";s:6:\"number\";s:2:\"12\";s:6:\"street\";s:11:\"Halsstraat\";s:4:\"city\";s:8:\"Amstelveen\";s:6:\"person\";s:14:\"Harry Boonstra\";s:5:\"email\";s:26:\"info@sponiza.nl\";s:2:\"cc\";s:2:\"NL\";s:22:\"street_additional_info\";s:0:\"\";s:5:\"phone\";s:0:\"\";}s:6:\"status\";i:2;s:7:\"options\";a:9:{s:12:\"package_type\";i:1;s:17:\"label_description\";s:0:\"\";s:14:\"only_recipient\";i:0;s:9:\"signature\";i:0;s:6:\"return\";i:0;s:12:\"large_format\";i:0;s:13:\"delivery_date\";s:19:\"2022-04-08 09:34:08\";s:13:\"delivery_type\";i:2;s:9:\"insurance\";a:2:{s:6:\"amount\";i:0;s:8:\"currency\";s:3:\"EUR\";}}s:16:\"general_settings\";a:3:{s:22:\"save_recipient_address\";i:0;s:26:\"disable_auto_detect_pickup\";i:0;s:10:\"tracktrace\";a:5:{s:23:\"send_track_trace_emails\";i:0;s:26:\"email_on_handed_to_courier\";i:0;s:3:\"bcc\";i:0;s:21:\"delivery_notification\";i:0;s:32:\"carrier_email_basic_notification\";i:0;}}s:6:\"pickup\";N;s:19:\"customs_declaration\";N;s:19:\"physical_properties\";a:1:{s:6:\"weight\";i:0;}s:7:\"created\";s:19:\"2022-04-07 11:34:09\";s:8:\"modified\";s:19:\"2022-04-07 11:34:09\";s:20:\"reference_identifier\";s:4:\"8832\";s:10:\"created_by\";i:48076;s:11:\"modified_by\";i:48076;s:18:\"transaction_status\";s:6:\"unpaid\";s:14:\"drop_off_point\";N;s:6:\"hidden\";i:0;s:5:\"price\";a:2:{s:6:\"amount\";i:0;s:8:\"currency\";s:3:\"EUR\";}s:7:\"barcode\";s:15:\"3DVDFH206812878\";s:6:\"region\";s:2:\"NL\";s:17:\"external_provider\";N;s:20:\"external_provider_id\";N;s:14:\"payment_status\";s:6:\"unpaid\";s:10:\"carrier_id\";i:1;s:11:\"platform_id\";i:5;s:6:\"origin\";N;s:10:\"user_agent\";N;s:19:\"secondary_shipments\";a:0:{}s:18:\"collection_contact\";N;s:28:\"multi_collo_main_shipment_id\";N;s:19:\"external_identifier\";s:15:\"3DVDFH206812878\";s:7:\"delayed\";b:0;s:9:\"delivered\";b:0;s:20:\"link_consumer_portal\";N;s:19:\"partner_tracktraces\";a:0:{}}}}"},{"id":254728,"key":"_postnl_last_shipment_ids","value":"a:1:{i:0;i:148294623;}"},{"id":254731,"key":"_wcpdf_invoice_settings","value":{"enabled":"1","attach_to_email_ids":{"customer_completed_order":"1","customer_invoice":"1"},"display_date":"invoice_date","display_number":"","number_format":{"prefix":"","suffix":"","padding":""},"my_account_buttons":"available","invoice_number_column":"1","paper_size":"a4","font_subsetting":false,"header_logo":"4922","header_logo_height":"","shop_name":{"default":"Sponiza IT"},"shop_address":{"default":"Halsstraat 12\r\n1100 AA Amstelveen\r\nE. info@sponiza.nl"},"footer":{"default":""},"extra_1":{"default":""},"extra_2":{"default":""},"extra_3":{"default":""}}},{"id":254732,"key":"_wcpdf_invoice_date","value":"1649324050"},{"id":254733,"key":"_wcpdf_invoice_date_formatted","value":"2022-04-07 10:34:10"},{"id":254734,"key":"_wcpdf_invoice_number","value":"2685"},{"id":254735,"key":"_wcpdf_invoice_number_data","value":{"number":2685,"formatted_number":"2685","prefix":"","suffix":"","document_type":"invoice","order_id":8832,"padding":""}}],"line_items":[{"id":13743,"name":"Witte fiets","product_id":1902,"variation_id":0,"quantity":1,"tax_class":"","subtotal":"66.11","subtotal_tax":"13.88","total":"66.11","total_tax":"13.88","taxes":[{"id":1,"total":"13.882562","subtotal":"13.882562"}],"meta_data":[{"id":100268,"key":"_reduced_stock","value":"1","display_key":"_reduced_stock","display_value":"1"}],"sku":"","price":66.107438,"parent_name":null}],"tax_lines":[{"id":13745,"rate_code":"NL-21% BTW-1","rate_id":1,"label":"21% BTW","compound":false,"tax_total":"13.88","shipping_tax_total":"1.26","rate_percent":21,"meta_data":[]}],"shipping_lines":[{"id":13744,"method_title":"Post NL","method_id":"flat_rate","instance_id":"1","total":"5.99","total_tax":"1.26","taxes":[{"id":1,"total":"1.2579","subtotal":""}],"meta_data":[{"id":100261,"key":"Items","value":"Witte fiets × 1","display_key":"Items","display_value":"Witte fiets × 1"}]}],"fee_lines":[],"coupon_lines":[],"refunds":[],"date_created_gmt":"2022-04-06T15:59:40","date_modified_gmt":"2022-04-07T09:34:10","date_completed_gmt":"2022-04-07T09:34:10","date_paid_gmt":"2022-04-06T16:00:08","currency_symbol":"\u20ac","_links":{"self":[{"href":"https:\/\/www.sponiza.nl\/wp-json\/wc\/v2\/orders\/8832"}],"collection":[{"href":"https:\/\/www.sponiza.nl\/wp-json\/wc\/v2\/orders"}]}}},"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/financialtransactionapi/readFinancialtransaction.php
Invoices
What?
Add invoices from the shop to Wisteria.
Why?
When adding the shop invoices to Wisteria our connectors will pick them up and push them to the accounting system.
For a connection either the orders or the invoices are pushed. Not both, since that would result in double turnover bookings.
An invoices consists of invoice-lines (required) and possibly shipping-lines, paymentcosts and fees. Discounts can be given
either as an overall amount or per invoiceline, not both.
When adding an invoice to Wisteria many validity checks will be done. It will be checked whether the invoice totals match the amounts on the lines.
If both unitprices and lineprices are given in the invoice-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 invoice 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
{"invoice":"{\"invoiceid\":4,\"orderid\":4,\"invoicenumber\":\"INV004\",\"affiliatenr\":\"testaff2\",\"paymentdate\":\"2021-03-02\",\"invoicedate\":\"2021-03-01\",\"totalExclWithDiscount\":200,\"totalInclWithDiscount\":230,\"totalVatWithDiscount\":30,\"lines\":[{\"referenceid\":3,\"lineid\":1,\"name\":\"productnaam2\",\"productcode\":\"sku2\",\"quantity\":2,\"lineInclWithDiscount\":121,\"lineExclWithDiscount\":100,\"lineVatWithDiscount\":21,\"unitInclWithDiscount\":60.5,\"unitExclWithDiscount\":50,\"unitVatWithDiscount\":10.5,\"taxpercentage\":21}],\"shipping\":[{\"referenceid\":3,\"lineid\":2,\"name\":\"productnaam3\",\"productcode\":\"sku3\",\"quantity\":2,\"lineInclWithDiscount\":109,\"lineExclWithDiscount\":100,\"lineVatWithDiscount\":9,\"unitInclWithDiscount\":54.5,\"unitExclWithDiscount\":50,\"unitVatWithDiscount\":4.5,\"taxpercentage\":9}],\"customer\":{\"customerid\":2,\"customernumber\":\"CUST_002\",\"firstname\":\"Jimmy\",\"lastname\":\"Doe\",\"company\":\"Sportschool\",\"address1\":\"Stationstraat\",\"housenr\":\"12a\",\"zipcode\":\"1000 AA\",\"city\":\"Amsterdam\",\"countryname\":\"Nederland\",\"isocountry\":\"NL\",\"mobile\":\"312309324342\",\"email\":\"jimmy@mycompany.nl\"}}","signature":"3dc2424d2ba8fa54665d3618de02513b"}
Response
{"data":{"invoiceid":"4","invoicenumber":"INV004","isicp":null,"currency":null,"isinternational":null,"invoicestatus":null,"paymentstatus":null,"invoicedate":"2021-03-01 00:00:00","affiliatenr":"testaff2","cartnr":null,"customerid":"2","orderid":"4","iscredit":null,"duedays":null,"duedate":null,"pdf":null,"totalpaid":null,"totalunpaid":null,"totalInclWithDiscount":"230.0000","totalExclWithDiscount":"200.0000","totalVatWithDiscount":"30.0000","totalDiscountIncl":null,"totalDiscountExcl":null,"totalDiscountVat":null,"lines":[],"customer":{"customerid":"2","orderid":"2","customernumber":"CUST_002","firstname":"Jimmy","lastname":"Doe","company":"Sportschool","address1":"Stationstraat","address2":null,"housenr":"12a","zipcode":"1000 AA","city":"Amsterdam","state":null,"country":null,"isocountry":"NL","kvk":null,"btwnr":null,"telnr":null,"mobile":"312309324342","email":"jimmy@mycompany.nl","iscompany":null,"isicp":null,"isinternational":null,"incltax":null},"fees":[],"payment":[],"shipping":[]},"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/invoiceapi/addInvoice.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
{"ledgercodes":"[{\"ledgercodeid\":61,\"code\":"8000",\"name\":\"Omzet 21%\",\"description\":\"Verkopen Hoog NL\",\"taxpercentage\":\"21\",\"type\":\"turnover\",\"country\":\"NL\"},{\"ledgercodeid\":62,\"code\":\"8010\",\"name\":\"Omzet 9%\",\"description\":\"Verkopen Laag NL\",\"taxpercentage\":\"0.09\",\"type\":\"turnover\",\"country\":\"NL\"},{\"ledgercodeid\":63,\"code\":\"8110\",\"name\":\"Omzet 6% BE\",\"description\":\"Verkopen Laag BE\",\"percentage\":6,\"type\":\"turnover\",\"country\":\"BE\"},{\"ledgercodeid\":64,\"code\":\"8100\",\"name\":\"testledgercode\",\"description\":\"Verkopen Hoog BE\",\"percentage\":0.21,\"type\":\"turnover\",\"country\":\"BE\"}]","signature":"8ff6657af67372582b57d28b7451d33b"}
Response
{"data":[{"ledgercodeid":"61","code":"8000","percentage":"21","name":"Omzet 21%","description":"Verkopen Hoog NL","type":"turnover","country":"NL"},{"ledgercodeid":"62","code":"8010","percentage0":"21","name":"Omzet 9%","description":"Verkopen Laag NL","type":"turnover","country":"NL"},{"ledgercodeid":"63","code":"8110","percentage":"6","name":"Omzet 6% BE","description":"Verkopen Laag BE","type":"turnover","country":"BE"},{"ledgercodeid":"64","code":"8100","percentage":"21","name":"Omzet 21% BE","description":"Verkopen Hoog BE","type":"turnover","country":"BE"}],"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/ledgercodeapi/addLedgercodes.php
Orders
What?
Add orders from the shop to Wisteria.
Why?
When adding the shop orders to Wisteria our connectors will pick them up and push them to the accounting system.
For a connection either the orders or the invoices are pushed. Not both, since that would result in double turnover bookings.
An order consists of order-lines (required) and possibly shipping, paymentcosts and fees. Discounts can be given either as an overall amount
or per orderline, not both.
When adding an order to Wisteria many validity checks will be done. It will be checked whether the order totals match the amounts on the lines.
If both unitprices and lineprices are given in the order-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 order 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
{"order":"{\"orderid\":112,\"ordernumber\":\"ORD003\",\"affiliatenr\":\"testaff2\",\"paymentstatus\":\"paid\",\"orderstatus\":\"completed\",\"orderdate\":\"2021-03-21\",\"totalExclWithDiscount\":100,\"totalInclWithDiscount\":109,\"totalVatWithDiscount\":9,\"items\":[{\"referenceid\":112,\"lineid\":1,\"name\":\"Bag of Apples\",\"productcode\":\"SKU_BOA\",\"quantity\":1,\"lineInclWithDiscount\":54.5,\"lineExclWithDiscount\":50,\"lineVatWithDiscount\":4.5,\"taxpercentage\":9}],\"shipping\":[{\"referenceid\":112,\"shippingid\":1,\"name\":\"Verzendkosten\",\"quantity\":1,\"lineInclWithDiscount\":54.5,\"lineExclWithDiscount\":50,\"lineVatWithDiscount\":4.5,\"taxpercentage\":9}],\"customer\":{\"customerid\":1,\"customernumber\":\"CUST001\",\"firstname\":\"Jean\",\"lastname\":\"Doe\",\"company\":\"Grocery online\",\"address1\":\"Stationstraat 12\",\"zipcode\":\"1000 AA\",\"city\":\"Amsterdam\",\"isocountry\":\"NL\",\"mobile\":\"0612345678\",\"email\":\"jean@mycompany.nl\"}}","signature":"82dfaa9c9c6747c2d09cc21cedb52d73"}
Response
{"data":[{"orderid":"112","affiliatenr":"testaff2","cartnr":null,"currency":null,"customerid":"1","deliveryaddressid":null,"paymentstatus":"paid","orderstatus":"completed","ordernumber":"ORD003","orderdate":"2021-03-21 00:00:00","deliverydate":null,"totalDiscountVat":null,"totalDiscountIncl":null,"totalDiscountExcl":null,"totalInclWithDiscount":"109.0000","totalExclWithDiscount":"100.0000","totalVatWithDiscount":"9.0000","items":[],"customer":{"customerid":"1","orderid":"112","customernumber":"CUST001","firstname":"Jean","lastname":"Doe","company":"Grocery online","address1":"Stationstraat 12","address2":null,"housenr":null,"zipcode":"1000 AA","city":"Amsterdam","state":null,"country":null,"isocountry":"NL","kvk":null,"btwnr":null,"telnr":null,"mobile":"0612345678","email":"jean@mycompany.nl","iscompany":null,"isicp":null,"isinternational":null,"incltax":null},"shipping":[{"name":"Verzendkosten","referenceid":"112","shippingid":"1","code":null,"taxpercentage":"9.0000","unitInclWithDiscount":null,"unitExclWithDiscount":null,"unitVatWithDiscount":null,"unitDiscountIncl":null,"unitDiscountExcl":null,"unitDiscountVat":null,"createddate":"2021-04-15 00:00:00"}],"payment":[],"fees":[]}],"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/orderapi/addOrder.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.
- Daily bookings: For daily bookings the payments are assigned to ledgercodes, depending on the paymentmethods.
Example post
Request
{"paymentmethods":"[{\"paymentmethodid\":112,\"name\":\"ideal\",\"type\":\"standard\"},{\"paymentmethodid\":113,\"name\":\"cash\",\"type\":\"standard\"}]","signature":"2035ddf2b385d8778cef2df9dc2b34b8"}
Response
{"data":[{"paymentmethodid":"112","name":"ideal","type":"standard"},{"paymentmethodid":"113","name":"cash","type":"standard"}],"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/paymentmethodapi/addPaymentmethods.php
Receipts
What?
Add receipts from the shop to Wisteria.
Why?
When adding the shop receipts to Wisteria our connectors will pick them up and push them to the accounting system.
Receipts are mostly used in poses. The difference between a receipt and order / invoice is that a receipt does not require a customer.
Shipping can be added to a receipt, but most often it is not. Receipts can be pushed individually to the accounting system, but they can
also be pushed as a daily booking to the accounting system.
An receipt consists of receipt-lines (required) and possibly shipping, paymentcosts and fees. Discounts can be given either as an overall amount
or per receiptline, not both.
When adding an receipt to Wisteria many validity checks will be done. It will be checked whether the receipt totals match the amounts on the lines.
If both unitprices and lineprices are given in the receipt-lines it is checked that these amounts are in sync. Wisteria will accept a delta of max 5 cents.
It is possible - but not required - to add customer-data with the receipt 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
{"receipt":"{\"receiptid\":112,\"receiptnumber\":\"REC005\",\"affiliatenr\":\"testaff2\",\"paymentstatus\":\"paid\",\"receiptstatus\":\"completed\",\"receiptdate\":\"2021-03-21\",\"totalExclWithDiscount\":100,\"totalInclWithDiscount\":109,\"totalVatWithDiscount\":9,\"customerid\":2,\"lines\":[{\"referenceid\":112,\"lineid\":1,\"name\":\"Bag of Apples\",\"productcode\":\"SKU_BOA\",\"quantity\":1,\"lineInclWithDiscount\":54.5,\"lineExclWithDiscount\":50,\"lineVatWithDiscount\":4.5,\"taxpercentage\":9,\"totalDiscountIncl\":0,\"totalDiscountExcl\":0}],\"shipping\":[{\"referenceid\":112,\"lineid\":1,\"name\":\"Bag of Bananas\",\"productcode\":\"SKU_BOB\",\"quantity\":1,\"lineInclWithDiscount\":54.5,\"lineExclWithDiscount\":50,\"lineVatWithDiscount\":4.5,\"taxpercentage\":9}]}","signature":"59509031e9700911d676d2d47f7ef867"}
Response
{"data":{"receiptid":"112","receiptnumber":"REC005","receiptdate":"2021-03-21 00:00:00","customerid":"2","deliveryaddressid":null,"affiliatenr":"testaff2","receiptstatus":"completed","paymentstatus":"paid","totalInclWithDiscount":"109.0000","totalExclWithDiscount":"100.0000","totalVatWithDiscount":"9.0000","totalDiscountIncl":null,"totalDiscountExcl":null,"totalDiscountVat":null,"isicp":null,"currency":null,"isinternational":null,"pdf":null,"duedate":null,"duedays":null,"totalpaid":null,"totalunpaid":null,"lines":[],"customer":false,"fees":[],"payment":[]},"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/orderapi/addOrder.php
Refunds
What?
Add refunds from the shop to Wisteria.
Why?
When adding the shop refunds to Wisteria our connectors will pick them up and push them to the accounting system.
Refunds should be associated with an order. A refund should contain negative amounts. For invoices there are no refunds, since there are credit-invoices.
A credit-invoice is an invoice, so there is no special entity for credit-invoices.
About the negative amounts. The totals are negative, as are the lineprices. If you add unitprices to the lines you should add a negative quantity
and a positive amount or a positive quantity and a negative amount. Most accounting systems that use unitprices will require a negative quantity
and a positive amount. This will also be better in case the merchant expects the accounting system to update the stock.
A refund consists of refund-lines (required) and possibly shipping, paymentcosts and fees. Discounts can be given either as an overall amount
or per refundline, not both.
When adding a refund to Wisteria many validity checks will be done. It will be checked whether the refund totals match the amounts on the lines.
If both unitprices and lineprices are given in the refund-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 refund 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
{"refund":"{\"refundid\":122,\"refundnumber\":\"RET001\",\"orderid\":112,\"ordernumber\":\"ORD003\",\"affiliatenr\":\"testaff2\",\"paymentstatus\":\"paid\",\"refundstatus\":\"completed\",\"refunddate\":\"2021-03-21\",\"totalExclWithDiscount\":-150,\"totalInclWithDiscount\":-163.5,\"totalVatWithDiscount\":-13.5,\"lines\":[{\"referenceid\":112,\"lineid\":1,\"name\":\"Bag of Apples\",\"productcode\":\"SKU_BOA\",\"quantity\":-2,\"lineInclWithDiscount\":-109,\"lineExclWithDiscount\":-100,\"lineVatWithDiscount\":-9,\"unitInclWithDiscount\":54.5,\"unitExclWithDiscount\":50,\"unitVatWithDiscount\":4.5,\"taxpercentage\":9}],\"shipping\":[{\"referenceid\":112,\"shippingid\":1,\"name\":\"Verzendkosten\",\"quantity\":-1,\"lineInclWithDiscount\":-54.5,\"lineExclWithDiscount\":-50,\"lineVatWithDiscount\":-4.5,\"unitInclWithDiscount\":54.5,\"unitExclWithDiscount\":50,\"unitVatWithDiscount\":4.5,\"taxpercentage\":9}],\"customer\":{\"customerid\":1,\"customernumber\":\"CUST001\",\"firstname\":\"Jean\",\"lastname\":\"Doe\",\"company\":\"Grocery online\",\"address1\":\"Stationstraat 12\",\"zipcode\":\"1000 AA\",\"city\":\"Amsterdam\",\"isocountry\":\"NL\",\"mobile\":\"0612345678\",\"email\":\"jean@mycompany.nl\"}}","signature":"be97f1e957a7cf1f4eac559e477067f7"}
Response
{"data":{"refundid":"122","refundnumber":"RET001","orderid":"112","customerid":"","ordernumber":"ORD003","affiliatenr":"testaff2","refundstatus":"completed","refunddate":"2021-03-21 00:00:00","paymentstatus":"paid","totalInclWithDiscount":"-163.5000","totalExclWithDiscount":"-150.0000","totalVatWithDiscount":"-13.5000","totalDiscountIncl":null,"totalDiscountExcl":null,"totalDiscountVat":null,"isicp":null,"isinternational":null,"currency":null,"pdf":null,"duedate":null,"duedays":null,"totalpaid":null,"totalunpaid":null,"items":[],"customer":false,"fees":[],"shipping":[],"payment":[]},"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/refundapi/addRefund.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
{"taxes":"[{\"taxid\":111,\"taxcode\":\"VL\",\"percentage\":9,\"title\":\"testtax\",\"country\":\"NL\"},{\"taxid\":112,\"taxcode\":\"VH\",\"percentage\":0.21,\"title\":\"testtax\",\"country\":\"NL\"},{\"taxid\":211,\"taxcode\":\"VLBE\",\"percentage\":6,\"title\":\"testtax\",\"country\":\"BE\"},{\"taxid\":212,\"taxcode\":\"VHBE\",\"percentage\":0.21,\"title\":\"testtax\",\"country\":\"BE\"}]","signature":"8ff6657af67372582b57d28b7451d33b"}
Response
{"data":[{"taxid":"111","taxcode":"VL","percentage_1":"0.0900","percentage_100":"9.0000","title":"testtax","description":null,"country":"NL"},{"taxid":"112","taxcode":"VH","percentage_1":"0.2100","percentage_100":"21.0000","title":"testtax","description":null,"country":"NL"},{"taxid":"211","taxcode":"VLBE","percentage_1":"0.0600","percentage_100":"6.0000","title":"testtax","description":null,"country":"BE"},{"taxid":"212","taxcode":"VHBE","percentage_1":"0.2100","percentage_100":"21.0000","title":"testtax","description":null,"country":"BE"}],"message":"Your data is inserted successfully"}
In the example code: externalshop/tests/taxapi/addTaxes.php
