Koppel je app in 30 minuten

Je app koppelen betekent: drie kleine routes die alleen lezen. 1plek roept ze aan, jouw app antwoordt. Meer is het niet.

Wat je nodig hebt

• Een app die op een openbaar https-adres draait.
• Iemand die er een route in kan zetten: een ontwikkelaar, of een AI-chatbot zoals ChatGPT of Claude met de opdracht uit 1plek.
• Het mailadres en telefoonnummer van één echte klant, om te testen.

Stap 1 · Sleutel (2 minuten)

Bedrijfsinstellingen → Koppelingen → Je app → voeg je app toe met z'n adres → Sleutel maken. Zet de sleutel in je app als geheime instelling, bij voorkeur ONEPLEK_READ_KEY (dat leest het pakket vanzelf). Je ziet hem maar één keer. 1plek stuurt hem bij elke vraag mee als Authorization: Bearer <sleutel>; een verkeerde sleutel krijgt 401.

Stap 2 · Drie routes (20 minuten)

Kopieer in 1plek de opdracht bij stap 2 en geef die aan je chatbot of ontwikkelaar. Daarin staat alles. In het kort:

Node.js of TypeScript? Gebruik dan het pakket @1plek/app-sdk (npm install @1plek/app-sdk). Je schrijft twee kleine functies (klant zoeken op e-mail en op telefoon) en kiest wat er op de kaart staat; het pakket doet de sleutelcheck, de schrijfwijzen van telefoonnummers, de beslisregel en de grenzen. Het werkt met Next.js-routes en Express. De regels hieronder regelt het dan voor je.

Zo ziet een antwoord eruit:

{ "match": "one", "customer": { "id": "8123", "label": "Ronald Bakker", "matched_on": "email",
  "fields": [{ "key": "orders", "label": "Bestellingen", "value": "12" }] } }

Niemand gevonden:  { "match": "none" }
Twijfel:           { "match": "multiple", "candidates": [{ "id": "8123", "label": "Ronald Bakker" }, { "id": "9001", "label": "R. Bakker" }] }
Kennis:            { "items": [{ "id": "faq-12", "title": "Hoe kan ik betalen?", "text": "Online of op factuur. Prijzen zijn zonder btw." }] }

Vijf regels waar het in de praktijk op misgaat:

1. Geen treffer is geen fout. Antwoord 200 met {"match":"none"} of {"items":[]}, nooit 404.
2. Elke waarde is tekst. "12", niet 12; "€ 4.280,00", niet 4280. Geen HTML.
3. Telefoon: vergelijk cijfers. 1plek stuurt phone_digits mee met alle schrijfwijzen. Cijfers uit je eigen kolom halen en vergelijken is genoeg.
4. Klantnummer is nooit een e-mailadres. Gebruik je eigen id.
5. Snel. Binnen 2 seconden. Te laat, 401 of 500: 1plek toont dan geen kaart (en schrijft een AI-concept zonder jullie kennis) en vraagt het de volgende keer gewoon opnieuw.

Wie kijkt er? 1plek stuurt bij elke vraag mee welke medewerker kijkt (x-business-actor-email). Toon gevoelige velden, zoals betalingen, alleen als die persoon dat bij jullie ook mag zien; bij een onbekende kijker laat je ze weg. Het pakket doet dit met resolveViewer (zie de README).

Stap 3 · Controleren (5 minuten)

Eerst lokaal? Draai dezelfde keuring vanaf je eigen machine, ook tegen localhost:

npx @1plek/app-sdk check http://localhost:3000 --key <sleutel> --email <klant> --phone <nummer>

Daarna in 1plek: vul het mailadres en telefoonnummer van je proefklant in en klik op Controleren. Je krijgt per punt groen, oranje of rood, met een zin die je zo aan je chatbot kunt geven. Alles groen? Klik Deze functies aanzetten.

Wat 1plek níét doet

• Niets bewaren. De klantgegevens worden opgehaald als iemand een gesprek opent en hooguit een minuut onthouden, per medewerker.
• Niets wijzigen. De routes zijn alleen-lezen; aanpassen doe je in je app.
• Niet in je database. Alles loopt over https, met een sleutel die jij intrekt.

Alle details, zoals velden, plafonds en doelgroepen, staan bij Je app koppelen.