Platformen
CCV Shop koppeling met ERP, boekhouding, kassa en magazijn
Een CCV Shop koppeling stuurt orders en klanten naar je ERP of boekhouding en schrijft voorraad, prijzen en levertijden terug in je webshop. De REST API van CCV Shop staat 150 leesverzoeken en 100 schrijfverzoeken per minuut toe en verstuurt webhooks die een mislukte aflevering niet opnieuw proberen.
Wat is CCV Shop en wie gebruikt het?
CCV Shop is webshopsoftware die als dienst draait: CCV host de shop, jij beheert hem in de backend. Er is geen eigen server en geen databank waar een koppeling rechtstreeks in kan. Alles wat een koppeling doet, loopt via de REST API en de webhooks van CCV Shop.
Voor een koppeling betekent dat twee dingen. De API is bij elke shop dezelfde, met dezelfde velden en dezelfde limieten. En wat de API niet heeft, kan ook niet: een veld dat in de backend bestaat maar niet in de API, is voor een koppeling onbereikbaar.
Wat je met CCV Shop koppelt
De webshop is leidend voor orders en nieuwe klanten. Artikelen, voorraad, prijzen en levertijden komen uit het systeem erachter.
| Stroom | Richting | Resource in CCV Shop |
|---|---|---|
| Orders en orderregels | CCV Shop naar ERP of boekhouding | orders, orders/:id/orderrows |
| Facturen | CCV Shop naar boekhouding | invoices |
| Klanten | CCV Shop naar ERP | users, of de klantgegevens op de order |
| Voorraad | ERP of magazijn naar CCV Shop | stock op products of attributecombinations |
| Levertijd | ERP of leverancier naar CCV Shop | stock_delivery_number, stock_delivery_type |
| Prijzen en staffels | ERP naar CCV Shop | products, productstaggeredprices |
| Orderstatus | ERP of magazijn naar CCV Shop | status op de order |
De levertijd zit in twee velden: een getal van 1 tot 31 en een eenheid (days, weeks, months, quarters, years) of een status zoals outofstock, ordered of onrequest. Een levertijd van "5 werkdagen" uit het ERP wordt 5 en days; het verschil tussen werkdagen en kalenderdagen kent het veld niet. Zie levertijd synchroniseren. De stromen in het algemeen staan op voorraad en beschikbaarheid en orders, klanten en verzending.
Hoe CCV Shop data vrijgeeft
Drie headers en een handtekening per verzoek
Elk verzoek draagt drie headers: x-public met de publieke sleutel, x-date met het tijdstip in UTC en x-hash. De hash is een HMAC met SHA512 over publieke sleutel, methode, pad, inhoud en tijdstip, berekend met de geheime sleutel:
x-public|PATCH|/api/rest/v1/products/1234567890|{"stock":14}|2026-10-03T09:15:00Z
Het tijdstip mag niet meer dan 5 minuten afwijken van de servertijd van CCV Shop. Een server met een klok die meer dan 5 minuten afwijkt, krijgt op elk verzoek een 401 met de foutcode voor een onjuiste x-date. Wij synchroniseren de klok van de koppeling en loggen de afwijking bij een 401.
150 lezen, 100 schrijven per minuut
De documentatie geeft een rate limit per methode per resource: 150 per minuut voor GET en 100 per minuut voor POST, PATCH, PUT en DELETE. Daarnaast is er een totale limiet over alle resources, met een eigen foutcode: 429.10 voor de limiet per methode, 429.11 voor het totaal. Het getal van de totale limiet staat niet in de documentatie. Een lijst komt standaard terug in pagina's van 25, met start en size.
Er is geen batch-endpoint voor voorraad in de documentatie: elk product of elke combinatie is een eigen PATCH. De rekensom voor een shop met 3.000 producten:
| Ronde | Rekensom | Tijd bij 100 per minuut |
|---|---|---|
| Alle producten lezen, pagina's van 25 | 3.000 / 25 = 120 GET's | 120 / 150 = 0,8 minuut |
| Volledige voorraadronde | 3.000 PATCH's | 3.000 / 100 = 30 minuten |
| Alleen wijzigingen, 140 producten | 140 PATCH's | 1,4 minuut |
| 800 producten met elk 4 combinaties | 3.200 PATCH's | 32 minuten |
De koppeling vergelijkt daarom eerst met de vorige stand en schrijft alleen wat veranderd is. Hoe je zo'n ronde doorrekent staat in doorvoer berekenen.
Webhooks: snel antwoorden, controleren
CCV Shop heeft webhooks voor onder meer orders, products, invoices, returns en attributecombinations, met specifieke varianten zoals orders.updated.status. Elke callback heeft een x-hash: HMAC SHA512 over het adres en de inhoud, met de geheime sleutel van die webhook, een tekenreeks van 32 posities. Drie regels uit de documentatie bepalen het ontwerp:
- De verbinding heeft een timeout van 2 seconden, het antwoord van 5 seconden.
- 200, 201, 202 en 204 zijn geslaagd. 307, 408, 503 en 504 houden een callback open; die gaat opnieuw mee bij de volgende aflevering. Elke andere code telt als mislukt.
- Het bericht zegt niet van welke webshop het komt. Een koppeling voor meer dan één shop zet een eigen kenmerk in het adres.
Waar het bij CCV Shop op vastloopt
| Wat er misgaat | Oorzaak in CCV Shop | Wat de koppeling doet |
|---|---|---|
| Order zonder ordernummer | ordernumber is null zolang is_completed false is |
Order opslaan op id, nummer later aanvullen |
| Statuswijziging niet gezien | Orders filteren alleen op aanmaakdatum, niet op wijzigingsdatum | Webhook orders.updated.status plus controleronde |
| Huisnummer met letter geweigerd | housenumber is een geheel getal |
Letter naar housenumber_suffix |
| Voorraad schrijft maar verandert niets | stocktype staat op Attribute, de koppeling schrijft op het product |
Per product stocktype lezen |
| Tekst in de verkeerde taal opgeslagen | Geen Accept-Language bij het schrijven |
Per taal een verzoek met header |
Ordernummers en statussen
Een order krijgt pas een ordernumber, ordernumber_prefix en ordernumber_full als hij is afgerond. Daarvoor zijn ze null. De koppeling bewaart elke order op zijn vaste id en gebruikt ordernumber_full, met het voorvoegsel en een streepje, als referentie in het ERP. Is er een voorvoegsel ingesteld, dan botst order 10482 niet met dezelfde reeks uit een ander kanaal.
De orderlijst filtert op status, is_paid, min_create_date en max_create_date. Een filter op laatste wijziging is er niet. Een order van gisteren die vandaag betaald wordt, vind je dus niet met een filter op vandaag. De koppeling luistert naar orders.updated.status en vraagt daarnaast elke ronde de open orders van de afgelopen dagen opnieuw op.
Adressen
Een adres heeft twee vormen: address_line_1 en address_line_2, of street, housenumber en housenumber_suffix. housenumber is een geheel getal. "Dorpsstraat 12 A" wordt Dorpsstraat, 12 en A; een huisnummer "12A" in één veld past er niet in. De postcode (zipcode) is tekst van maximaal 20 tekens. Komt het adres uit de shop als twee regels, dan splitst de koppeling het voor een ERP dat drie velden wil. Zie adresvelden mappen.
Voorraad en nabestellen
Per product staat stockenabled aan of uit, en ordering_without_stock op allow, disallow of global_setting. Bij global_setting volgt het product de instelling van de hele shop. Een product met voorraad 0 kan daardoor bestelbaar blijven zonder dat het in het product zichtbaar is. De koppeling leest bij de bouw welke producten de shopinstelling volgen en legt vast wat er bij 0 moet gebeuren. Zie backorders.
Systemen die we aan CCV Shop koppelen
De koppeling wordt gebouwd op jouw shop en jouw systemen. Per combinatie staat op een eigen pagina wat er specifiek speelt:
De systemen zelf: Exact Online koppeling, AFAS webshop koppeling, SnelStart koppeling, Mplus koppeling en Picqer-koppeling. Het overzicht van alle stromen en systemen staat op koppelingen.
Wij bouwen de koppeling voor een vaste prijs, en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor de livegang draait hij als dry run: je ziet per product welke voorraad, prijs en levertijd er in CCV Shop zou komen en per order wat er naar je ERP zou gaan, zonder dat er iets wijzigt. Vertel welke systemen achter je shop staan, dan hoor je wat een volledige ronde bij 100 verzoeken per minuut kost.
Veelgestelde vragen
Hoe krijg ik API-sleutels voor CCV Shop?
In de backend van je webshop onder Mijn webshop, Instellingen, API-instellingen. Staat die optie er niet, dan installeer je eerst de API-app uit de App Store van CCV Shop. Je krijgt een publieke sleutel en een geheime sleutel. De geheime sleutel gaat nooit mee in een verzoek; hij dient alleen om de handtekening te berekenen.
Probeert CCV Shop een mislukte webhook opnieuw?
Alleen als de ontvanger antwoordt met 307, 408, 503 of 504. Zo'n callback blijft open en gaat opnieuw mee bij de volgende aflevering. Elke andere foutcode, zoals een 500, telt als mislukt. Daarom zet de koppeling elk bericht direct in een wachtrij, antwoordt met 200 en draait er een controleronde naast.
Kan de koppeling voorraad per maat en kleur bijwerken?
Ja, als het product zo is ingericht. Het veld stocktype bepaalt of de voorraad op het product staat (Product) of op de attribuutcombinaties (Attribute). In het tweede geval schrijft de koppeling per combinatie met PATCH /attributecombinations/:id, en telt elke combinatie als een verzoek binnen de limiet van 100 per minuut.
Werkt het met klantgroepen en staffelprijzen?
De API heeft eigen resources voor klantgroepen (usergroups), staffelprijzen per product (productstaggeredprices) en prijsafspraken per klantgroep of klant, zoals usergroupproductadjustments en userproductadjustments. De koppeling zet de prijsafspraken uit je ERP daarin. Zie klantspecifieke prijzen.
Kan ik een webshop met meerdere talen koppelen?
Ja. De header Accept-Language bepaalt in welke taal een antwoord komt en in welke taal een POST, PUT of PATCH wordt opgeslagen, met een tweeletterige code zoals nl of fr. De koppeling stuurt per taal een eigen verzoek met de juiste header. Een Franse tekst die zonder Accept-Language: fr wordt geschreven, komt niet in de Franse vertaling terecht.
Vertel wat je nodig hebt
Vertel welke systemen je gebruikt en wat je wilt verbeteren. Je krijgt binnen één werkdag een persoonlijk antwoord. We helpen je de werkzaamheden helder te krijgen en spreken de prijs en planning af voordat je iets toezegt.
- Je weet de prijs en de doorlooptijd voordat je iets toezegt
- Wij zoeken uit welke koppeling het werk uit handen neemt
- Wij verzorgen de bouw, hosting, bewaking en het onderhoud
- Je team krijgt minder overtypwerk en minder uitzoekwerk