Pakketten bestellen met de API

Bouw je websites voor je klanten? Dan kun je hun webhosting bestellen via de Site.nl API. Je script betaalt uit je portemonnee en de bestelling start meteen.

Met de API kun je een nieuw pakket bestellen, een pakket verlengen en een pakket herstellen. Elke aanroep is één bestelling voor één pakket. Wil je ook domeinnamen bestellen? Lees hoe je domeinnamen bestelt met de API. Werk je voor het eerst met onze API? Lees dan eerst hoe je aan de slag gaat met de API.

Wat je nodig hebt

Een API-sleutel. Maak er een aan in je dashboard onder Instellingen, op het tabblad API-sleutels. Vink onder API-eindpunten alleen de rechten aan die je nodig hebt:

• plans.order.create: pakketten bestellen, verlengen en herstellen.
• domains.view: de ID's van je pakketten en domeinnamen opzoeken.

Geld in je portemonnee. Bestellingen via de API betaal je altijd uit je online portemonnee. Het saldo moet de hele bestelling dekken, inclusief btw.

Bestellen via de API kan alleen met een API-sleutel. In je browser gebruik je gewoon de winkelwagen.

Zo werkt een bestelling

Je stuurt een POST-verzoek naar de API. Zet je API-sleutel in de header X-API-Key en de gegevens van de bestelling als JSON in de body. Bijvoorbeeld om een nieuw pakket te bestellen:

POST https://backend.site.nl/v2/plans/order
X-API-Key: your API key
Content-Type: application/json

In de body stuur je minstens plan_name mee, bijvoorbeeld starter. Dan gebeurt dit:

• Dezelfde prijs. Je betaalt hetzelfde als wanneer je op onze website bestelt.
• Er wordt niets afgeschreven als er iets mis is. Je krijgt een foutcode die zegt waarom.
• Test het eerst. Stuur dry_run: true mee. Het antwoord toont de prijs, de btw en of het saldo van je portemonnee genoeg is. Er wordt niets besteld of afgeschreven.
• We starten de bestelling binnen ongeveer een minuut. Vanaf dan gaat alles zoals bij elke andere bestelling, met dezelfde e-mails.
• De bestelling komt op je maandfactuur, met de vermelding "Via API". Dat gebeurt ook als maandelijks factureren uitstaat.

In de API-documentatie staan alle velden, met voorbeelden van elk verzoek en elk antwoord.

Een nieuw pakket bestellen

POST https://backend.site.nl/v2/plans/order

Deze velden kun je meesturen:

• plan_name (verplicht): de naam van het pakket in kleine letters, zoals starter of power.
• order_period: het aantal jaren, 1 tot 5. Standaard is dat 1.
• domain_name_ids: de ID's van domeinnamen die je al bij ons hebt en die je in het nieuwe pakket wilt zetten. Die vind je met GET /v2/domain_names.
• external_domain_name_ids: de ID's van domeinnamen die ergens anders geregistreerd zijn, maar die je aan je account hebt toegevoegd. Die vind je met GET /v2/external_domain_names.
• expected_price: de prijs in centen, zonder btw, die je accepteert. Is de prijs anders? Dan plaatsen we de bestelling niet.
• dry_run: true controleert de bestelling alleen en berekent de prijs.

De domeinnamen moeten actief zijn en mogen nog niet in een ander pakket zitten. En in elk pakket past een maximaal aantal domeinnamen. Heb je voor het pakket een nieuwe domeinnaam nodig? Bestel die dan eerst en wacht tot hij actief is.

Een pakket verlengen of herstellen

POST https://backend.site.nl/v2/plans/91/renew
POST https://backend.site.nl/v2/plans/91/restore

Hier is 91 het ID van het pakket. Dat vind je met GET /v2/plans. In de body kun je order_period (in jaren), expected_price en dry_run meesturen.

• Verlengen: voor een actief pakket. Lees hoe de verlenging van een pakket werkt.
• Herstellen: voor een pakket dat is verlopen of opgezegd, tot 14 dagen nadat het is verlopen.

Wordt het pakket op dit moment naar een andere gebruiker verplaatst? Dan kun je het pas verlengen als de verplaatsing klaar is.

Het antwoord

Is de bestelling gelukt? Dan krijg je het order_id, met order_status paid. Je krijgt ook de prijzen in centen: amount_excluding_vat_in_cents, vat_amount_in_cents en total_including_vat_in_cents. Onder payment zie je bij wallet_balance_in_cents wat er nog in je portemonnee staat.

Volg de bestelling met het ID:

GET https://backend.site.nl/v2/orders/5926

Elke regel van de bestelling heeft een status: unprocessed, processing, processed, failed of cancelled.

Nooit twee keer betalen

Soms valt de verbinding weg vlak nadat je een bestelling verstuurt. Is die nu wel of niet doorgekomen? Stuur voor de zekerheid bij elke bestelling de header Idempotency-Key mee. Dat is een unieke code van maximaal 255 tekens, zoals een UUID.

Stuur je dezelfde bestelling nog een keer met dezelfde code? Dan krijg je het eerste antwoord terug en betaal je nooit twee keer. Gebruik je de code voor een andere bestelling? Dan krijg je de fout ORDER_005.

Foutcodes

Bij elke fout wordt er niets afgeschreven. Dit zijn de meest voorkomende:

• ORDER_001: het saldo van je portemonnee is te laag. Onder top_up geeft het antwoord het bedrag dat je moet bijstorten en een link om je portemonnee op te waarderen.
• ORDER_002: de prijs is niet je expected_price. In het antwoord staat de huidige prijs.
• ORDER_003: deze bestelling is niet mogelijk. Het veld reason zegt waarom. Bijvoorbeeld: er passen niet zoveel domeinnamen in het pakket, een domeinnaam zit al in een pakket, of de herstelperiode is voorbij.
• ORDER_004: betalen uit de portemonnee is voor jouw account niet mogelijk.
• ORDER_005: je hebt deze Idempotency-Key al gebruikt voor een andere bestelling.
• GENERAL_001: er is geen pakket met deze naam, of het pakket-ID is niet van jou.
• DOMAIN_NOT_FOUND: een van de domeinnaam-ID's is niet van jou.

Goed om te weten

• Er is geen testomgeving. Elke bestelling is echt. Test dus eerst met dry_run.

Hulp nodig? Neem contact met ons op via WhatsApp, Telegram of e-mail.