Sellsy Connector PrestaShop: volledige gids

Overzicht

De Sellsy-connector van DataFirefly koppelt uw PrestaShop-winkel aan Sellsy, de Franse SaaS-oplossing voor CRM, facturatie en beheer. Hij synchroniseert automatisch uw klanten, producten, bestellingen, facturen, betalingen en creditnota’s van PrestaShop naar Sellsy via de Sellsy API v2. De synchronisatie is eenrichtingsverkeer: PrestaShop → Sellsy.

Installatie

1. Ga in de PrestaShop-backoffice naar Modules > Modulebeheer.
2. Klik op Een module installeren en upload het bestand dfsellsy.zip.
3. Klik na de installatie op Configureren.

De module maakt twee tabellen aan (dfsellsy_link voor de koppeling PrestaShop ↔ Sellsy, dfsellsy_log voor het logboek) en een tabblad “Sellsy Connector” in het menu Modules.

De API-toegang aanmaken in Sellsy

De connector gebruikt OAuth2-authenticatie (client credentials) van API v2.

1. Open in Sellsy Menu > Instellingen > Ontwikkelaarsportaal.
2. Klik in het tabblad API V2 op Een API-toegang aanmaken.
3. Kies de medewerker die aan de toegang wordt gekoppeld (bij voorkeur een beheerder, voor alle rechten) en vink de benodigde scopes aan (klanten, documenten, catalogus, betalingen).
4. Sla op en kopieer daarna de Client ID en het Client Secret.

Configuratie van de module

Vul op de configuratiepagina van de module in:

• Client ID en Client Secret: de OAuth2-gegevens die u in Sellsy hebt aangemaakt. Laat het secret-veld leeg om de al opgeslagen waarde te behouden.
• Klanten synchroniseren: maakt of werkt een Sellsy-relatie bij aan bij registratie en wijziging van een klant.
• Bestellingen synchroniseren: zet de bestellingen om in Sellsy-documenten.
• Sellsy-documenttype voor bestellingen: factuur of verkooporder.
• Trigger voor de bestellingssynchronisatie: bij de betaalbevestiging of bij de bevestiging van de bestelling.
• Sellsy-documenten valideren: valideert facturen en creditnota’s automatisch na aanmaak (anders blijven ze als concept in Sellsy staan).
• Betalingen registreren: registreert de PrestaShop-betalingen op de Sellsy-factuur (alleen bij het type factuur).
• Terugbetalingen synchroniseren als creditnota’s: maakt bij elke PrestaShop-creditnota een Sellsy-creditnota aan en koppelt die aan de oorspronkelijke factuur.
• Producten synchroniseren: stuurt de catalogus naar de Sellsy-items.

Gebruik de knop API-verbinding testen om uw gegevens te controleren voordat u de synchronisaties inschakelt.

Klantsynchronisatie

Bij registratie of wijziging van een klant maakt of werkt de module een Sellsy-relatie bij. Klanten met een ingevuld veld “bedrijf” worden Sellsy-bedrijven (met het SIRET-nummer indien beschikbaar), de anderen particulieren. Een zoekopdracht op e-mail voorkomt duplicaten, en het hoofdfactuuradres wordt bij de aanmaak meegestuurd.

Bestellingssynchronisatie

Afhankelijk van de gekozen trigger wordt een bevestigde of betaalde bestelling een Sellsy-document met de productregels, de verzendkosten en de winkelwagenkortingen (als negatieve regel). De PrestaShop-btw-tarieven worden automatisch gekoppeld aan de Sellsy-belastingen. Elke bestelling wordt maar één keer gesynchroniseerd (idempotentie).

Facturen, validatie en betalingen

Wanneer het documenttype “factuur” is:

• is de optie Documenten valideren actief, dan wordt de factuur na aanmaak automatisch gevalideerd;
• is de optie Betalingen registreren actief, dan wordt elke PrestaShop-betaling op de factuur geregistreerd, zonder duplicaat, inclusief gedeeltelijke of meerdere betalingen;
• is de bestelling bij de bevestiging aangemaakt en komt de betaling later, dan registreert de module alleen de nieuwe betalingen op de bestaande factuur.

Creditnota’s bij terugbetaling

Bij het genereren van een PrestaShop-creditnota maakt de module een Sellsy-creditnota aan op basis van de terugbetaalde regels (producten en verzending), valideert die als de optie actief is, en koppelt die daarna aan de oorspronkelijke factuur wanneer die aan Sellsy-zijde bestaat.

Productsynchronisatie

De productsynchronisatie is optioneel. Eenmaal ingeschakeld worden de producten bij aanmaak en wijziging naar de Sellsy-catalogus gestuurd. U kunt ook een bulksynchronisatie starten vanaf de pagina “Sellsy Connector” (verwerking in batches van 20).

Geplande taken (cron)

Een ingebouwde cron haalt in wat de realtimehooks eventueel hebben gemist. Plan de URL’s in die op de configuratiepagina worden getoond:

• .../module/dfsellsy/cron?token=UW_TOKEN&job=orders
• ...&job=customers
• ...&job=products
• ...&job=retry (probeert de nog niet gekoppelde entiteiten met fouten opnieuw)

De parameter limit (standaard 20, max 100) bepaalt de batchgrootte per uitvoering.

Synchronisatielogboek

De pagina “Sellsy Connector” toont een filterbaar logboek (per entiteit en per status) van elke operatie, met bij fouten de melding die Sellsy teruggeeft. Een knop Fouten opnieuw proberen speelt de mislukkingen met één klik opnieuw af.

Probleemoplossing

• “Verbinding mislukt”: controleer de Client ID / het Client Secret en of de benodigde scopes in Sellsy zijn aangevinkt.
• Een fout op een documentveld (HTTP 422): sommige Sellsy-accounts hebben specifieke vereisten (e-invoicing-vermeldingen, verplichte velden). Raadpleeg de melding in het logboek om het betreffende veld te vinden.
• Dubbele relaties: de module zoekt op e-mail vóór de aanmaak; zorg dat het klant-e-mailadres is ingevuld.
• Er wordt niets gesynchroniseerd: controleer of de betreffende opties actief zijn en test de API-verbinding.