Eigen homemade-webshop facturen importeren

[vanmeerdervoort]

Hoi,

Ik heb een homemade online reserverings systeem dat facturen genereert en mailt. Hoe kan ik dit het beste met accumulus koppelen?
Kan ik de door mijn software gegenereerde factuurnummers en info aan accumulus doorgeven via de API en daarmee in accumulus een nieuwe (gekoppelde) factuur maken met referentie aan mijn software-factuur? Of moet ik mijn hele software ombouwen en alles via accumulus gaan doen?

Hoe werkt dit bij van te voren gegenereerde facturen van bijvoorbeeld WooCommerce?

Graag wat tips

Groet
Vincent

[Guido]

Ik heb een homemade online reserverings systeem dat facturen genereert en mailt. Hoe kan ik dit het beste met acumulus koppelen?

Simpel gezegd heb je 2 opties. Je kunt periodiek importeren via een CSV-bestand of automatisch via de API. Met de API heb je meer controle over hoe en volgens welke spelregels je dingen inschiet.

Kan ik de door mijn software gegenereerde factuurnummers en info aan acumulus doorgeven via de API en daarmee in acumulus een nieuwe (gekoppelde) factuur maken met referentie aan mijn software-factuur?

Ja. Hiervoor gebruik je de invoice_add API. Laat: "xml -> customer -> invoice -> number" leeg en vermeld de referentie naar jouw software-factuur in: "xml -> customer -> invoice -> description". Hiermee waarborg je dat er voor de administratie een aaneengesloten nummering is en behoud je de referentie naar de originele factuur. Het maakt het ook makkelijker om extra verkoopkanalen of losse verkoopfacturen in de administratie bij te zetten.

Of moet ik mijn hele software ombouwen en alles via acumulus gaan doen?

Dat is een keuze. Je kunt er voor kiezen om de gegenereerde facturen in de eigen software niet meer uit te sturen maar door Acumulus te laten verzenden. Zie hiervoor het "emailaspdf" onderdeel van de invoice_add API en uiteraard het factuursjabloon in Acumulus.

Hoe werkt dit bij van te voren gegenereerde facturen van bijvoorbeeld WooCommerce?

Goede vraag. De ontwikkelaar van de plugin weet dit vast een stuk beter te vertellen maar volgens mij is het in grote lijnen zo dat je op een bepaald (gekozen) moment de webwinkel software een trigger geeft aan de plugin. De plugin vist info uit de webwinkel-database en zet die door naar de Acumulus API. Voor facturen die al gegenereerd zijn voordat de plugin geinstalleerd was wordt dan gekozen om de factuurstatus tijdelijk te wisselen (naar een status die de klant niet op de hoogte brengt) waarmee de trigger alsnog plaats vind.

Graag wat tips

- Maak gebruik van een proefaccount. Vervuil er gerust een stuk of wat om te voorkomen dat je volautomatisch een complete administratie overhoop haalt. Proefaccounts zijn geheel vrijblijvend en worden na verloop van tijd automatisch verwijderd.
- Gebruik emailonerror en emailonwarning bij elke call die je met de API maakt.
- Schakel in Acumulus de API-codes en boekstuknummers in. Zie Beheer -> Geavanceerd. Hiermee krijg je bruikbare codes voor de koppeling makkelijk inzichtelijk.
- De meeste API-calls geven een aantal standaard waarden terug. Parse in ieder geval de warnings en de errors zodat je weet als er dingen semi-goed of verkeerd gaan.
- Sla het entryid lokaal op in het geval dat je een entryid terug krijgt van de API (bij het correct inschieten van een factuur bijvoorbeeld) en koppel dit lokaal aan de factuur in de webshop. Hiermee kun je voorkomen dat je facturen dubbel overzet. Je zou in theorie ook nog in de webshop checks kunnen inbouwen om totalen te vergelijken met de entry_info API van https://www.siel.nl/acumulus/API/Entry/Get_Entry_Details/ en ergens lokaal een vlag kunnen opsteken als iets afwijkt.
- Kies expliciet voor de identifiers van de kostenplaatsen, rekeningen en factuursjablonen en val niet terug op de standaard waarden.
- Overweeg de connector feedback goed in te richten: https://www.siel.nl/acumulus/API/Basic_Submit/ . Mochten er berichten in de bitbucket van de API terecht komen dan kunnen we gerichter contact opnemen. Een deel hiervan komt ook terug op het notitie-tabblad van de boeking.

- Guido

[Guido]

Aanvullend kun je nog per betaalmethode een aparte rekening, kostenplaats en factuursjabloon kiezen. Zeker als betalingen via een betaalprovider lopen is automatisch boeken op de juiste tussenrekening in Acumulus erg praktisch.

[vanmeerdervoort]

Hoi Guido, dank voor je snelle en uitgebreide antwoord!

Ik denk dat ik inderdaad het zo ga doen dat ik na het aanmaken van de factuur in de webshop meteen een API call naar Accumulus doe om de factuur (met referentie) als nieuwe accumulus factuur te boeken. Goed voor consistentie in accumulus maar tegelijk kan ik dan mijn huidige betaalflow bewaren.


Een vraag nog, als een klant een wijziging op de factuur wil (item erbij of eraf) kan ik dat in mijn software eenvoudig doen, kan ik die wijziging ook via API call naar accumulus sturen om de 'schaduw/referentie' factuur daar aan te passen? Ik kon zo snel in de API handleiding niet vinden of er een call voor was.

Dank!

Vincent

[Guido]

In aCumulus (met 1 c ) kun je een factuur maar beperkt wijzigen. Je zult de originele factuur als creditfactuur moeten inschieten. De meest eenvoudige methode is om dezelfde factuur nogmaals aan te bieden maar alle factuurregels met -1 te vermenigvuldigen. Vervolgens zet je de nieuwe factuur met de wijzigingen over.

[vanmeerdervoort]

 Ah, sorry hehe. Acumulus dus. 
Helemaal duidelijk, hartelijk dank!


Vincent

[Guido]

Nog een tip: Escape alle 5 verschillende XML-controle-karakters:

  &
  "
  '
  <
  >

naar html-entities.

Verder: Als je de xml_string methode gebruikt, vergeet dan niet de string te url-encoden voordat je deze aan de API doorgeeft.

[erwin-burorader]

De webshops HikaShop, Magento, OpenCart2, PrestaShop, VirtueMart en WooCommerce maken gebruik van een gemeenschappelijke library die het meeste werk (onder andere het hele xml en communicatiegebeuren, instellingen en batchformulier, entry-id beheer) voor zijn rekening neemt. Deze library is zo gebouwd dat het toevoegen van nog een webshop eenvoudig zou moeten zijn.

De library:
- is beschikbaar onder de GNU GPL v3 licentie
- is (nog) niet beschikbaar als een aparte download, maar door de koppeling voor een van bovengenoemde shops te downloaden heb je ook de source van de library.
- is goed gedocumenteerd, hooguit dat een stappenplan op hoog niveau ontbreekt om de library voor een nieuwe webshop op te zetten
- de library bevat veel code specifiek voor de verschillende webshops en die kan dus als voorbeeld dienen om zelf iets op te zetten
- bevat veel logging en logopties, dus relatief eenvoudig te debuggen en volgen.