Automatisering

Gebeurtenissen melden via de API

Laat je eigen app gebeurtenissen bij 1plek melden, zodat 1plek de berichten verzorgt.

Je eigen app weet wát er gebeurt — een bestelling is betaald, een cursus zit vol. 1plek weet wat je team daaraan gekoppeld heeft: welk bericht, in welke huisstijl, naar wie. De intake-API is de plek waar die twee elkaar raken.

Een sleutel maken

Ga naar het bedrijf, tabblad Integraties, en maak een API-sleutel met het recht events:write. De sleutel hoort bij één bedrijf en wordt gehasht opgeslagen — je ziet 'm één keer.

Een gebeurtenis melden

bash

curl -X POST \
  https://iam.1plek.com/api/platform/companies/14voices/events/order.paid \
  -H "Authorization: Bearer $ONEPLEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "email": "klant@example.com",
      "orderNumber": "14V-1234",
      "amount": "129,00"
    },
    "idempotencyKey": "order-1234-paid"
  }'

Veld	Betekenis
`payload`	Vrij van vorm. Elk veld is beschikbaar als `{token}` in het bericht
`idempotencyKey`	Dezelfde sleutel binnen 24 uur wordt maar één keer afgevuurd
`label`	Alleen bij een nieuwe gebeurtenis: de naam in het overzicht

Het adres van de ontvanger wordt standaard uit het veld email gehaald.

Aanmelden hoeft niet

Meld je een gebeurtenis die 1plek nog niet kent, dan wordt die bij de eerste melding vanzelf geregistreerd onder de naam van je merk. Hij staat daarna in het overzicht, klaar om er een bericht aan te koppelen.

Tot die koppeling er is, gaat er niets uit. Je krijgt dan gewoon een 200 terug met "dispatched": 0 — dat is geen fout, dat is de normale volgorde.

Antwoorden

Status	Betekenis
`200`	Aangenomen. `dispatched` telt hoeveel berichten er daadwerkelijk uitgingen
`401`	Sleutel ontbreekt, is ingetrokken of mist het recht `events:write`
`404`	Het bedrijf in het pad hoort niet bij je sleutel, of bestaat niet
`429`	Te veel meldingen achter elkaar

Een sleutel die bij een ander bedrijf hoort geeft 404, niet 403. We verklappen niet welke merken er bestaan.

Grenzen

Een gebeurtenis van het ene merk kan nooit de koppelingen van een ander merk raken: het merk zit in het pad, en je sleutel moet bij datzelfde merk horen.

Zet je sleutel in de omgevingsvariabelen van je app, nooit in code die naar de browser gaat. Met deze sleutel kan iemand namens jouw merk berichten laten uitgaan.