API och webhooks

Med API och webhooks arbetar dina egna system (affärssystem, datalager, webbplatsens backend, automatiseringsverktyg) med din NextCRM-arbetsyta:

• REST-API:et läser och ändrar leads, kontakter, uppgifter och anteckningar, och läser trattar, formulärinskick, kampanjer och teammedlemmar;
• webhooks meddelar din server så fort något händer, till exempel ett nytt lead eller ett stegbyte.

Obs: Bara arbetsyteadministratörer kan öppna Inställningar > API och webhooks. API-åtkomst ingår i abonnemangen Business, Agency och Enterprise. I andra abonnemang syns befintliga nycklar och slutpunkter fortfarande, men nya kan inte skapas och API-anrop avvisas.

Var du hittar varje värde

Allt kommer från NextCRM självt; inget konto hos tredje part behövs.

Värde	Var du hittar det
API-nyckel	Inställningar > API och webhooks > Skapa API-nyckel. Hela nyckeln visas bara en gång; kopiera den till din integration (till exempel n8n, Zapier, Make eller din egen kod) som Bearer-token.
Signeringshemlighet	Visas en gång när du lägger till en webhook-slutpunkt, och igen efter Byt hemlighet. Spara den på servern som tar emot webhooks.
Slutpunktens URL	Kommer från ditt eget system eller automatiseringsverktyg, till exempel produktions-URL:en för en Webhook-nod i n8n. Den måste använda https.

Konfigurationsordning: skapa en API-nyckel med de behörigheter du behöver > gör ett första anrop > lägg till en webhook-slutpunkt med dess händelser > verifiera signaturen på din server > skicka en testhändelse.

Skapa en API-nyckel

1. Klicka på ditt profilkort längst ned i sidofältet, välj Inställningar och öppna kortet API och webhooks (öppna API och webhooks) och stanna på fliken API-nycklar.
2. Klicka på Skapa API-nyckel.
3. Ange ett Namn som visar var nyckeln används, till exempel "ERP-synk".
4. Under Behörigheter väljer du Läsa och/eller Skriva per område. Välj bara det integrationen verkligen behöver.
5. Ange vid behov ett utgångsdatum under Upphör (30, 90 eller 365 dagar, eller ett datum).
6. Klicka på Skapa nyckel och kopiera nyckeln direkt med Kopiera.

Varning: Nyckeln visas bara en gång. NextCRM sparar bara ett fingeravtryck (hash) av den, så ingen - inte ens supporten - kan visa den igen. Om den kommer bort, återkalla den och skapa en ny.

Listan visar varje nyckel med sitt prefix (till exempel ncrm_live_1a2b3c4d), behörigheterna, vem som skapade den, när den senast användes och när den upphör. Återkalla spärrar en nyckel direkt.

Vad en nyckel får göra

En nyckel agerar för din arbetsyta med en arbetsyteadministratörs rättigheter, begränsat till de valda behörigheterna:

Behörighet	Tillåter
Leads (läsa / skriva)	Lista och läsa leads; skapa, ändra, flytta till ett steg, tilldela, flytta till papperskorgen och återställa
Kontakter (läsa / skriva)	Lista, läsa, skapa, ändra och ta bort kontakter
Uppgifter (läsa / skriva)	Lista och läsa uppgifter; skapa, ändra, slutföra och arkivera
Trattar och steg (läsa)	Läsa trattar med deras steg
Formulärinskick (läsa)	Läsa formulär och deras inskick
Kampanjer (läsa)	Läsa kampanjer och deras resultat
Anteckningar och aktiviteter (läsa / skriva)	Läsa ett leads anteckningar och tidslinje; lägga till anteckningar och logga samtal
Teammedlemmar (läsa)	Läsa namn, e-post och roller för teammedlemmar (för att tilldela leads och uppgifter)
Webhooks (läsa / skriva)	Läsa, registrera och ta bort webhook-slutpunkter

Samma regler gäller som i appen: abonnemangsgränser (ett nytt lead över din gräns för aktiva leads hamnar i Lead-inkorgen), papperskorgen (leads i papperskorgen måste återställas innan de kan ändras; borttagning via API:et flyttar alltid till papperskorgen) och data hamnar aldrig i en annan arbetsyta. Det som bara personer får göra - hantera team, roller, fakturering eller API-nycklar och ta bort permanent - går inte med en nyckel. En nyckel slutar också fungera när personen som skapade den inte längre är arbetsyteadministratör.

Varje ändring som görs med en nyckel visas i leadets tidslinje som API key <namn>.

Ditt första anrop

Skicka nyckeln i headern Authorization. Bas-URL:en är https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Skapa ett lead:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

Den fullständiga referensen med alla slutpunkter, fält och ett curl-exempel finns på fliken API-dokumentation, offentligt på https://…/api/v1/docs och som OpenAPI 3.1-fil på https://…/api/v1/openapi.json.

Regler för alla integrationer

• Svar har formen { "data": ..., "meta": { ... } }, fel { "error": { "code", "message", "details" } } med en fältlista vid valideringsfel. Datum anges i ISO 8601, UTC.
• Sidindelning: listor returnerar meta.next_cursor; skicka det som cursor för att hämta nästa sida (limit upp till 100).
• Idempotens: skicka en Idempotency-Key-header med POST-förfrågningar. Ett nytt försök med samma nyckel ger det första resultatet i stället för en dubblett (i 24 timmar).
• Hastighetsgränser: 120 förfrågningar per minut och nyckel och 600 per arbetsyta. Däröver svarar API:et 429 med headern Retry-After - vänta så många sekunder.
• Underhåll: under en uppdatering av NextCRM svarar API:et 503 MAINTENANCE med Retry-After. Webhooks hålls kvar och levereras efteråt.
• Bara från servern: anropa API:et från din server. Webbläsare kan inte anropa det (ingen CORS), och en API-nyckel får aldrig ligga i en webbplats eller app.

Webhooks

1. Öppna fliken Webhooks och klicka på Lägg till slutpunkt.
2. Ange Slutpunktens URL för din server. Den måste börja med https:// och vara nåbar från internet; interna, privata och molnmetadata-adresser avvisas.
3. Välj de Händelser du vill ha och klicka på Spara slutpunkt.
4. Kopiera signeringshemligheten (visas en gång) och spara den på din server.
5. Klicka på Skicka testhändelse för att kontrollera att din server svarar.

Tillgängliga händelser: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined och automation.webhook.

Offerthändelser anger belopp som heltal i valutans minsta enhet (till exempel cent): subtotal_minor är summan av raderna efter radrabatter, discount_minor rabatten på hela offerten, tax_minor momsen och total_minor beloppet att betala. En rads total_minor är dess belopp efter radrabatten, före offertrabatten och momsen.

Leads som skapas av en filimport skickar en lead.created per importerad lead när importen är klar, med "context": { "source": "import", "import_batch_id": "..." } bredvid data.

Varje leverans är en POST med händelsen som JSON (id, type, created_at, actor, data) och dessa headers: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp och X-NextCRM-Signature.

Verifiera signaturen

X-NextCRM-Signature ser ut som t=1760860800,v1=5f2b.... Beräkna HMAC-SHA256 av <t>.<rå request-body> med din signeringshemlighet och jämför med v1. Avvisa förfrågningar vars tidsstämpel är äldre än 5 minuter.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Nya försök, leveranslogg och byte av hemlighet

• Svara med valfri 2xx-status inom 10 sekunder. Annars försöker NextCRM igen med allt längre pauser (1, 2, 4, ... minuter), upp till 8 försök.
• Leveransloggen visar varje leverans med status, försök och svarskod. Skicka igen köar en leverans en gång till.
• Efter många misslyckanden i rad inaktiveras slutpunkten automatiskt och alla arbetsyteadministratörer får en avisering. Åtgärda slutpunkten och klicka sedan på Aktivera.
• Byt hemlighet skapar en ny signeringshemlighet. Den gamla fortsätter att signera i 24 timmar så att du kan byta utan att förlora händelser.

Lora och API:et

Lora kan förklara API:et, öppna den här sidan och lista dina webhook-slutpunkter. Hon skapar, visar eller återkallar aldrig API-nycklar och ser aldrig en signeringshemlighet - det gör du själv på den här sidan.

Felsökning

Svar	Betydelse
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	Nyckeln är fel, återkallad eller utgången. Skapa en ny.
403 INSUFFICIENT_SCOPE	Nyckeln saknar behörighet för anropet. Skapa en nyckel med den behörighet som behövs.
403 API_KEY_OWNER_NOT_ADMIN	Personen som skapade nyckeln är inte längre arbetsyteadministratör. En nuvarande administratör måste skapa en ny nyckel.
402 FEATURE_NOT_IN_PLAN	Abonnemanget omfattar inte API-åtkomst.
409 LEAD_IN_TRASH	Återställ leadet först (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Fält och orsak står i error.details.
429 RATE_LIMITED	Vänta Retry-After-sekunderna och fortsätt sedan.