Konverto til n8n (community node, ikke udgivet)

Det her er Konvertos officielle n8n-node: to noder i én npm-pakke, som lader et
n8n-workflow læse og oprette leads i Konverto og starte automatisk når der sker
noget på et lead. Den taler udelukkende med Konvertos åbne API (api-v1) med en
API-nøgle brugeren selv indsætter, og den har ingen anden vej ind i systemet.

Pakken er IKKE udgivet på npm. Der findes ingen n8n-nodes-konverto i
npm-registret, ingen npm-organisation og ingen udgivet version. Første
npm publish er også første gang npm ser pakken, og den kommando er din egen
hånd (se afsnittet om udgivelse).

Bygget mod @n8n/node-cli 0.47.1. Pakken har ingen runtime-afhængigheder
(kun n8n-workflow som peer), hvilket er et krav hvis den en dag skal
verificeres af n8n.

---

De to noder

Konverto er handlings-noden: den henter og skriver data. Den er markeret
usableAsTool, så den også kan hænges på en AI-agent i n8n.

Konverto Trigger starter workflowet når Konverto sender en hændelse. Den
registrerer selv webhook-abonnementet hos Konverto når workflowet slås til, og
sletter det igen når det slås fra.

Begge noder bruger den samme credential, Konverto API, som har præcis ét
felt: API-nøglen. Base-URL'en er bevidst ikke et felt, så en forkert
indtastning ikke kan sende nøglen til en fremmed vært. Nøglen sendes som
Authorization: Bearer, og knappen der tester forbindelsen kalder
GET /v1/ping.

Alt går til:
https://pkmeytthmqthhyoiicnv.supabase.co/functions/v1/api-v1/v1

---

Hvad noden kan

Ressource	Operation i n8n	Kald mod API'et
Lead	Create or Update	POST /v1/leads (med Idempotency-Key)
Lead	Get	GET /v1/leads/{id}
Lead	Get Many	GET /v1/leads
Lead	Get Messages	GET /v1/leads/{id}/messages
Lead	Update Status	PATCH /v1/leads/{id}
Customer	Get Many	GET /v1/customers
Booking	Get Many	GET /v1/bookings
Summary	Get	GET /v1/stats
Konverto Trigger	slår workflowet til	GET /v1/webhooks og POST /v1/webhooks
Konverto Trigger	slår workflowet fra	DELETE /v1/webhooks/{id}
Credential-test	knappen i credential-vinduet	GET /v1/ping

Detaljer der er værd at kende:

• Create or Update kræver mail eller telefon (gerne begge). Noden stopper
  selv kaldet hvis begge felter er tomme, så du får svaret med det samme i
  stedet for en 400 fra serveren. Findes personen allerede på kunden,
  opdateres leadet i stedet for at der oprettes et nyt.
• Idempotency-Key sættes automatisk som
  n8n:<kørsels-id>:<node-id>:<item-nummer>. Den er den samme når n8n selv
  prøver noden igen efter en fejl, og forskellig for alt andet. Det betyder
  noget i kroner: et oprettet lead koster kunden 15 kr, og headeren er det der
  gør at et genforsøg ikke bliver til to leads. Du kan overskrive den i
  Options hvis du vil styre den selv.
• Update Status sender de danske værdier aktiv, kold, Kontaktet og
  inaktiv, fordi det er dem produktet og API'et bruger. I n8n står de med en
  engelsk forklaring foran, fx "Active (Aktiv)", men værdien der sendes er den
  danske.
• Return All bladrer selv videre med API'ets cursor. Konverto svarer med
  højst 100 rækker pr. kald, så en Limit på 250 giver 250 rækker og ikke en
  fejl.
• Simplify på Get og Get Many skærer leadets 22 felter ned til ti: id,
  customer_id, created_at, name, email, phone, status, source,
  channel, meeting_status. Felterne er altid med, også når de er tomme.
• Summary hedder Summary og ikke Stats fordi n8n's linter kræver at et
  ressourcenavn er ental. Værdien i workflowets JSON er stadig stats, og
  kaldet går stadig til /v1/stats.
• Fejl oversættes til noget man kan handle på. En 403 bliver fx til
  "This API key can only read. Create a key with the write scope", ikke til et
  nøgent HTTP-nummer.

---

Trigger-noden

Ét abonnement, uanset hvor mange hændelser du vælger

Noden opretter præcis ét webhook-abonnement pr. node, med alle de valgte
hændelser samlet i det ene abonnement. Det er ikke en detalje: Konverto tillader
højst 5 abonnementer pr. API-nøgle, så ni separate abonnementer ville ramme
loftet ved den sjette og gøre det umuligt at tænde flere workflows på samme
nøgle. Med ét abonnement pr. node kan den samme nøgle bære fem workflows, uanset
hvor mange hændelser hvert af dem lytter på.

Konverto kan ikke rette et abonnement. Ændrer du fluebenene, sletter noden
derfor det gamle abonnement og opretter et nyt, så serveren ikke bliver ved med
at sende det gamle udvalg. Er abonnementet slået fra af Konverto efter mange
fejlede leveringer, bliver det også ryddet og bygget op igen.

De ni hændelser

lead.created, lead.message, lead.call, lead.meeting_booked,
lead.purchased, lead.status_changed, lead.graded, lead.handover,
lead.archived.

Alle ni er valgt fra start, så en ny bruger ser at der sker noget i stedet for
at sidde med en trigger der aldrig fyrer. Fravælg det du ikke vil have.

Der findes en tiende, lead.message_sync. Den er intern og kan ikke vælges:
den findes kun i CRM-køen, hvor den lægger den samme besked ind i Pipedrives
Messaging-indbakke ved siden af tidslinjen. En fremmed modtager ville få den
samme besked to gange uden at kunne se hvorfor, så den står ikke på listen.

Hvad triggeren sender videre i workflowet

Leveringen sendes videre præcis som Konverto sender den, som ét item. Ingen
udfladning, ingen omdøbning:

{
  "id": "whd_10423",
  "event": "lead.message",
  "occurred_at": "2026-09-07T09:14:02.114Z",
  "sent_at": "2026-09-07T09:14:02.472Z",
  "lead_id": "8f14e45f-ceea-467a-9c1f-2ba1cd3b21d2",
  "data": { "id": "8f14e45f-...", "name": "...", "email": "...", "status": "aktiv" },
  "source": { "...": "kun når hændelsen hænger på en anden række end leadet" }
}

• id er leverancens id (whd_...), ikke leadets. Leadets id står i
  lead_id og i data.id.
• data har præcis samme form som GET /v1/leads/{id}.
• source findes kun ved besked, opkald, vurdering og overdragelse, og
  udelades helt (ikke sat til null) ved de øvrige.
• Leadet ligger altså i $json.data, ikke på øverste niveau. Det er med vilje:
  konvolutten har sit eget id, og en udfladning ville lade det ene overskrive
  det andet.

Triggeren filtrerer desuden selv en levering fra hvis dens event ikke længere
er valgt i noden. Den kvitterer stadig med 200, den starter bare ikke workflowet.

---

Byg og prøv den lokalt

cd /var/www/konverto/integrations/n8n-nodes-konverto

npm install      # node_modules ligger ikke i git
npm run build    # oversætter TypeScript til dist/ og kopierer ikoner med
npm run lint     # n8n's egen node-linter, ikke bare eslint
npm run dev      # starter en n8n med noden koblet på

npm run dev (altså n8n-node dev) bygger pakken og starter en lokal n8n
gennem npm med noden indlæst. Åbn localhost:5678, log ind, og noden ligger i
node-panelet som var den installeret. Det er måden at prøve den uden at udgive
noget og uden at røre Konvertos egen n8n.

To ting om npm run dev her på serveren: den henter en hel n8n ned første gang,
og trigger-noden kan ikke afprøves gennem den, fordi Konverto kun accepterer
en offentlig https-adresse som webhook-URL. Handlings-noden kan prøves fint.

eslint.config.mjs skal blive ved med at være ordret som n8n's skabelon (tre
linjer, ingen kommentarer). "strict": true i package.json får npm run lint
til at afvise enhver ændring i den fil, også en kommentar.

---

Udgivelse på npm (Tier 3, din egen hånd)

cd /var/www/konverto/integrations/n8n-nodes-konverto

npm pack --dry-run          # viser hvad der ville ryge med, uden at sende noget
npm pack                    # laver n8n-nodes-konverto-0.1.0.tgz lokalt

npm login
npm publish --access public # den rigtige udgivelse

Det er Tier 3, og du kører det selv. En udgivelse på npm kan ikke rulles
tilbage: npm unpublish er kun tilladt i 72 timer, og et versionsnummer kan
aldrig genbruges. Navnet n8n-nodes-konverto er heller ikke reserveret endnu,
så det første npm publish er også det der tager navnet.

npm pack tager kun dist/, package.json, LICENSE.md og README.md med.
Blandt filerne i dist/ ligger tsconfig.tsbuildinfo på cirka 213 kB, som er
ren byggeinformation. Den kommer fra n8n's egen tsconfig.json-skabelon, og
den er bevidst ikke fjernet: vi holder skabelonen ordret, så pakken ikke
afviger fra den n8n forventer.

---

Hvis den skal verificeres af n8n

Verificerede community nodes er dem brugerne kan finde direkte i node-panelet.
Det kræver en indsendelse i n8n's Creator Portal, og tre ting skal være på plads
først (tjekket mod n8n's egen dokumentation 7. september 2026):

1. Fra 1. maj 2026 skal pakken være udgivet gennem en GitHub Actions-workflow
   med en provenance-erklæring. n8n tager ikke imod verificerede noder der er
   udgivet fra en lokal maskine. Provenance er en kryptografisk kvittering på at
   netop den workflow byggede pakken, fra netop det repo og den commit.
2. @n8n/node-cli skal være version 0.23.0 eller nyere som devDependency,
   fordi ældre versioner ikke understøtter det provenance-flag workflowen
   bruger. Vi kører 0.47.1, så det krav er opfyldt.
3. publish.yml hentes fra n8n-nodes-starter og lægges i repoet som
   .github/workflows/publish.yml
   (https://github.com/n8n-io/n8n-nodes-starter/blob/master/.github/workflows/publish.yml).
   Den fil findes ikke i dette repo endnu. Derudover skal npm sættes op til
   at stole på workflowen: på pakkens side på npmjs.com under
   Publish access, Trusted Publishers, tilføjes GitHub Actions med
   repo-ejer, repo-navn og workflow-navnet publish.yml.

n8n kræver desuden at en verificeret node ikke har runtime-afhængigheder (det
har denne ikke), og at der findes en README i pakken (den læser du nu).

---

Installation i Konvertos egen n8n

Når pakken ligger på npm, installeres den i en n8n under Settings og
Community nodes, hvor man indsætter pakkenavnet n8n-nodes-konverto.

ADVARSEL: Konvertos n8n på n8n.konverto.dk kører produktion for alle
kunder. En community node installeres på hele instansen, ikke i ét workflow,
og n8n genstarter i forbindelse med installationen. Det er din beslutning, og
det er ikke noget der skal gøres for at prøve noden: til det er npm run dev
den rigtige vej. Skal den alligevel installeres der, så gør det på et tidspunkt
hvor et kort stop ikke rammer en kundes flow.

---

API-nøglen

Noden virker ikke uden en nøgle der starter med kv_live_. Klarteksten vises
én gang og kan aldrig hentes frem igen, så kopiér den med det samme.

Nøglen skal have write-scope hvis noden skal oprette leads, opdatere
status eller bruges som trigger. Et webhook-abonnement er en skrivning, så en
læse-nøgle kan ikke tænde trigger-noden. Med en ren læse-nøgle virker kun Get,
Get Many, Get Messages og Summary.

To steder udstedes nøgler i dag:

• Kundens egen side: Indstillinger, fanen "API og Endpoints". Her er der en
  kontakt der hedder "Tillad at oprette henvendelser", og den er den eneste
  flade i dag der kan udstede en nøgle med write.
• Admin: siden for API-nøgler, /admin/api-noegler. Kan udstede en nøgle
  til hvilken som helst konto, men den giver i dag altid kun read
  (scopes: ["read"] står fast i
  supabase/functions/admin-api-keys/index.ts). En nøgle derfra kan altså ikke
  bruges til trigger-noden eller til at oprette leads.

---

Grænser du skal kende

• 5 webhook-abonnementer pr. nøgle. Det sjette svarer 409. Grænsen hører til
  nøglens ejer, så en partner-nøgle deler de fem på tværs af alle sine kunder.
• 60 kald i minuttet pr. nøgle som standard. Rammes den, svarer API'et 429,
  og noden oversætter det til en besked om at lægge en Wait-node ind.
• 100 rækker pr. kald. Noden bladrer selv videre.
• 1000 API-oprettede leads pr. kunde pr. døgn. Rammes loftet, oprettes og
  faktureres ingenting.
• Statistik-vinduet er højst 366 dage. Uden datoer: de seneste 30 døgn.
• Trigger-noden kræver en offentlig https-adresse. En n8n på localhost kan
  ikke registrere abonnementet.

---

Hvad der ikke er testet

Vær klar over præcis hvor lidt der er bevist:

• Ingen n8n har kørt noden. Den er aldrig indlæst i en n8n, hverken gennem
  npm run dev eller som installeret community node. Node-panelet, felterne,
  ikonerne og credential-vinduet er aldrig set af et menneske.
• Ingen webhook er registreret. checkExists, create og delete har
  aldrig ramt /v1/webhooks. Vi ved ikke af erfaring at abonnementet oprettes
  og slettes korrekt, kun at koden gør det den skal ifølge API'ets kontrakt.
• Ingen rigtig hændelse er modtaget. Formen på det triggeren sender videre
  er læst ud af supabase/functions/api-webhook-dispatch/policy.ts, ikke set
  komme ind.
• Intet kald har ramt Konvertos API. Der er ikke oprettet et lead, ikke
  hentet en liste og ikke hentet en statistik gennem noden.
• Signaturen på leveringer verificeres ikke. Konverto signerer hver levering
  med X-Webhook-Signature: v1=... og X-Webhook-Timestamp, men noden tjekker
  dem ikke, og signeringsnøglen gemmes bevidst ikke. Beskyttelsen er alene at
  n8n's webhook-URL er svær at gætte. Vil vi have ægte verifikation, skal den
  bygges.
• Der er ingen tests i pakken. Ingen unit-tests, ingen fixtures.

Det ER kørt, med Node v20.20.0 og npm 10.8.2, den 7. september 2026:

• npm run build: TypeScript build successful, Copied static files, Build
  successful (exit 0)
• npm run lint: 0 fejl, 0 advarsler (exit 0)
• npm pack --dry-run: 45 filer, 85,3 kB pakket, 314,4 kB udpakket (exit 0),
  og README.md er med i pakken

Første gang lint blev kørt gav den 13 fejl, som alle er rettet: en kommentar i
eslint.config.mjs (strict mode kræver filen ordret), ressourcen "Stats" der
skulle være ental (nu "Summary"), fem steder hvor en rå fejl blev kastet videre
i stedet for en n8n-fejl (samlet i asNodeError i shared/transport.ts), og
otte beskrivelser der manglede et punktum.

Første gang du selv prøver

1. npm install og npm run dev i mappen.
2. Opret credentialen med en write-nøgle og tryk på knappen der tester
   forbindelsen. Den skal svare grønt (det er GET /v1/ping).
3. Byg et workflow med Konverto-noden, ressource Lead, operation Get Many. Det
   er det billigste rigtige kald.
4. Trigger-noden kan først prøves når n8n har en offentlig https-adresse. Slå
   workflowet til, og tjek i Konverto under Indstillinger, API og Endpoints at
   abonnementet dukkede op. Slå det fra igen og tjek at det forsvandt: gør det
   ikke det, tæller det stadig mod de fem.