Codevoorbeelden in vier talen

• Python · Markdown
• JavaScript / TypeScript · Markdown
• PHP · Markdown
• C# · Markdown

Starten

Kies één taal hierboven. Iedere taalgids bevat een volledige herbruikbare HTTP-client en dezelfde belangrijke taken. De bronbestanden staan in docs/examples/; het zijn controleerbare voorbeelden, geen afzonderlijk officieel SDK-pakket. Python en JavaScript gebruiken alleen de standaardbibliotheek; PHP vraagt cURL en C# gebruikt .NET 10. Gebruik JavaScript aan de serverkant, ook als je applicatie verder TypeScript gebruikt.

Maak in Account → API en integraties een eigen serviceverbinding met minimale scopes. Laat je secretmanager BINADIT_CLIENT_ID en BINADIT_CLIENT_SECRET beschikbaar maken. De client vraagt daarmee één kortdurend token aan via POST /oauth/token met grant_type=client_credentials. Hij bewaart of print het geheim en token niet. Een door je eigen OAuth-applicatie verkregen persoonlijk token kan via BINADIT_ACCESS_TOKEN worden gebruikt. Haal geen persoonlijke tokens uit de sleutelkluis van de CLI. Voor gewone interactieve bediening gebruik je binadit login.

Een servicesleutel kan geen recente menselijke verificatie vervangen. Teamuitnodigingen, webhookbeheer, Send As inschakelen en ruimtes verwijderen kunnen een bevoegde, recent sterk geverifieerde persoon vereisen. Gebruik daarvoor een eigen goedgekeurde persoonlijke OAuth-verbinding of de bestaande CLI. De snippets omzeilen geen bedrijfsbeleid of featureflags. Exchange en oude saldo-opwaarderingen blijven buiten de release.

De clients gebruiken uitsluitend https://my.binadit.com, normale TLS-controle, een timeout en geen redirects of automatische herhaling. Het vaste origin voorkomt dat een pagina- of betaal-URL onbedoeld een Bearer-token ontvangt. Voor een eigen testinstallatie pas je de constante origin bewust aan; zet certificaatcontrole niet uit. De voorbeelden lezen maximaal 8 MiB per response. Gebruik voor grotere bestanden een afzonderlijke begrensde streamingimplementatie.

Waarden en versies invullen

Alle adressen op example.test, documentatie-IP's, IDs en UUID's zijn fictief. Vervang ze door resources die je via dezelfde bedrijfsverbinding hebt opgehaald. 123 is het bedrijf, 7 een Workspace, 23/24 mailboxen, 8 een DNS-zone en 12 een maildomein. Een ID van een ander bedrijf geeft geen bevoegdheid.

Volg bij pagineren meta.next_cursor, ook als een door rechten gefilterde data-lijst leeg is. De taalgidsen tonen een begrensde lus met controle op een herhaalde cursor. Volg geen willekeurige volgende URL met je token.

De client retourneert etag en data; data is de volledige JSON-envelope, dus bijvoorbeeld result.data.data in JavaScript. C# gebruikt ETag, Data en voor een PDF Bytes. Bewaar een ETag bij de exacte resource. Voor mutaties met versiecontrole geeft de taalgids aan welke GET je eerst moet doen. Zet de bekeken ETag of expliciete planversie in BINADIT_RESOURCE_VERSION. Gebruik geen verzonnen hash en geen versie van een ander object.

Voor iedere beoordeelde schrijfactie bewaar je vóór verzending de oorspronkelijke principal, methode, URL, exacte JSON, resourceversie en een willekeurige Idempotency-Key van 16–128 veilige tekens. Geef de oorspronkelijke sleutel door als BINADIT_REQUEST_KEY. Een UUID is geschikt; genereer hem één keer in je eigen duurzame aanvraagopslag, niet opnieuw bij iedere scriptstart. De voorbeeldclients eisen uit voorzorg ook bij leesgerichte POST-aanroepen een sleutel; die maakt zo'n endpoint niet alsnog een mutatie.

De schrijfvoorbeelden gebruiken waar relevant dry_run: true. Een dry-run bewaart geen uitvoerbare bestelling, machtiging of DNS-plan. Voor echte uitvoering beoordeel je eerst de preview, leest actuele versies en bewaart de uiteindelijke JSON zonder dry_run met zijn eigen sleutel. Plak niet alle voorbeelden achter elkaar: elke snippet is een afzonderlijke taak met zijn eigen invoer en sleutel. Een dry-run voor een gevoelige taak heft de menselijke verificatieregel niet op.

Bestellen, betalen en opzeggen

1. Lees producten, de eigen houder en capabilities. Vraag de prijs aan de server; bereken geen eigen verkoopprijs.
2. Beoordeel een offerte-preview. Vraag daarna bewust een bewaarde offerte aan door dry_run weg te laten. Gebruik de echte data.id en controleer dezelfde offerte met GET. Een preview-ID mag niet als echte offerte worden behandeld.
3. Preview het bevestigen met orders en dry_run: true. Alleen na goedkeuring verstuur je diezelfde offerte-ID zonder dry_run, met een daarvoor duurzaam vastgelegde sleutel. Dit kan een factuur en bestelling aanmaken. orders:commit en de geldende bestel-/bestedingsrechten blijven vereist.
4. De bestelling kan checkout_url teruggeven. Open die afzonderlijk in de browser voor de betaalbevestiging. Stuur nooit het Binadit-token naar de betaalprovider en haal deze URL niet met de voorbeeldclient op.
5. Volg de oorspronkelijke operatie en lees het domein opnieuw. queued of awaiting_payment bewijst geen registratie. Controleer registrarstatus, DNS-publicatie en abonnement/automatisch verlengen afzonderlijk.

Een domein opzeggen stopt automatische verlenging; het is geen onmiddellijke verwijdering. Lees daarna opnieuw domains/{id}/subscription en controleer de vastgelegde einddatum en facturatiestatus. Hosting en andere diensten hebben eigen opzeggingsintenties; een domein en een hostingpakket zijn afzonderlijke overeenkomsten.

DNS en Workspace

DNS verloopt altijd via de Binadit API en de bestaande portaalverwerking. Lees records, maak een plan, beoordeel records en versie en pas het oorspronkelijke plan afzonderlijk toe. Een template-plan is ook een voorstel. Gebruik nooit rechtstreeks PowerDNS-, NS1- of Cloudflare-sleutels in deze clients. De recordwaarde heet value; CNAME-doelen volgen de portaalnotatie zonder afsluitende punt. Werk bij verwijderen/bewerken met de werkelijk gelezen record-ID's, niet met de positie in een nieuw gesorteerde lijst.

Gewone en gedeelde mailboxen zijn betaalde producten. Bestel een normale mailbox via een offerte van het type workspace_mailbox; voor gedeelde mailboxen geldt het eigen betaalde contract. De voorbeelden voor gemachtigden, agenda's, verzendlijsten en ruimtes zijn gratis en vragen geen product of factuur. full geeft ook versturen namens; send_as is een afzonderlijke gevoelige keuze. De ontvanger ziet na uitschakelen van Send As weer de gemachtigde zolang full blijft bestaan. Een lijstlid is een bestaand typed ID zoals mailbox-24, geen extern adres of geneste lijst. Ruimtes hebben geen inlogwachtwoord; bij herhaling wordt alleen het eerste voorkomen gecontroleerd. Zie het volledige mailcontract.

Fouten, onzekerheid en voortgang

operation.request_status: succeeded bevestigt het HTTP-ontvangstbewijs, niet automatisch de leveranciersactie. Volg operation.status: onder meer queued, running, awaiting_payment, requires_approval, requires_reconciliation, failed en succeeded. Een vastgehouden gratis mailtaak is requires_reconciliation, geen betaalverzoek. Een fout in een medewerker-/DNS-taak is geen reden voor een tweede betaalde bestelling.

Bewaar ontvangen operation-, plan- en intent-ID's bij je oorspronkelijke aanvraag. Lees met operations:read dezelfde operatie met een begrensde pollfrequentie, bijvoorbeeld elke vijf seconden en maximaal twee minuten per scriptuitvoering. Stop bij een controle- of betaalstatus; druk die niet door. Na een nieuwe persoonlijke aanmelding kan de oorspronkelijke principal zijn veranderd: gebruik dan het oorspronkelijke ontvangstbewijs, niet een automatische replay onder de nieuwe verbinding.

De clients geven fouten bewust zonder ongefilterde responsebody door. Log geen Bearer-token, clientgeheim, eenmalige claim, persoonsgegevens, mailinhoud of PDF. Eenmalige wachtwoord- en sleutelclaims hebben een afzonderlijk protocol en horen niet in een generieke retrylus.

Webhooks ontvangen

De taalgidsen bevatten een HMAC-controle voor de ongewijzigde raw body en de drie headers Binadit-Webhook-Id, Binadit-Webhook-Timestamp en Binadit-Webhook-Signature. De verwachte sleutel-ID en het geheim komen uit je eigen secretmanager. Gebruik TLS, controleer het tijdvenster, vergelijk constant-time en voorkom daarna replay met een unieke delivery-ID in duurzame opslag. Een geldige handtekening alleen voorkomt geen dubbele uitvoering.

Na verificatie: leg de delivery-ID en een werkitem atomair vast in één databasetransactie met een unieke constraint. Beantwoord pas daarna 2xx. Een al duurzaam ontvangen, geldig ondertekende delivery krijgt opnieuw 2xx zonder het werk te herhalen. Verwerk bijvoorbeeld een factuurmelding nooit tweemaal. Houd bij sleutelrotatie uitsluitend bewust toegestane eigen sleutel-ID's bij; vertrouw geen onbekende key_id uit een header.

Contract en controle

De voorbeelden worden gegenereerd uit de werkelijke operatiecatalogus en gedeelde recepten. Routes, scopes, methoden en JSON-bodies worden lokaal tegen OpenAPI gecontroleerd. De clientcode wordt apart uitgevoerd tegen een lokale testontvanger; hierbij worden geen klantgegevens of betaalde acties op productie gebruikt. De PHP-/Python-/Node-versies en .NET-buildcontrole staan in de ontwikkelnotities bij de broncode. Dit is geen claim dat iedere getoonde betaalde actie in alle vier talen op productie is besteld.

De voorbeelden volgen het actuele releasebereik, de API-referentie en de agenthandleiding. Technische standaardbibliotheken: HttpClient redirects, Node fetch en timeouts.

Onderwerpen in iedere taal