API-nycklar & Webhooks

API-nycklar och Webhooks låter dig ansluta Bizaldo till externa system för ERP-synkronisering, anpassade instrumentpaneler, lagerautomatisering eller interna verktyg utan att dela personalens inloggningsuppgifter.
Var du hittar det: Öppna Inställningar i Bizaldo-instrumentpanelens sidofält. Använd fliken API-nycklar för att skapa nycklar och fliken Webhooks för att registrera slutpunkter. Avsnittet Allmänt överst i Inställningar visar ditt nuvarande Företags-ID och Branch-ID, som många integrationer behöver tillsammans med nyckeln.

Vem kan hantera integrationer

Endast användare med rollen Admin eller Super Admin ser API-nycklarna och Webhooks-flikarna. Andra roller (chef, kassörska, personal) kan använda inställningar för profil- och beställningssida men kan inte skapa eller återkalla nycklar.

Företag och filial

API-nycklar och webhooks skapas för företaget och filialen som valts i instrumentpanelens rubrik när du skapar dem. Välj rätt företag och filial innan du skapar inloggningsuppgifter. Kopiera Företags-ID och Branch-ID från Inställningar → Allmänt när du konfigurerar din integration.
Inställningar API-nycklar sida med företag och filial sammanhang12345

Figur 1 — Fliken Inställningar API-nycklar med företags- och filial-ID

Skärmelement

1
Fliken API-nycklar

Öppna Inställningar och välj API-nycklar för att hantera integrationsuppgifter.

2
Företags-ID

Kopiera företags-ID för din integration. Matchar företaget som valts i instrumentpanelens rubrik.

3
Filial ID

Kopiera filial-ID för din integration. Matchar den gren som valts i instrumentpanelens rubrik.

4
Skapa API-nyckel

Starta flödet för att skapa nyckel.

5
Användningsstatistik

Totalt antal nycklar, aktiva nycklar, totalt antal förfrågningar och förfrågningar idag.


API-nycklar

Vad en API-nyckel innehåller

Varje API-nyckel har:
FältBeskrivning
NamnMänniskoläsbar etikett (minst 3 tecken), t.ex. `Production ERP`
BeskrivningValfri notering om vad integrationen gör
Offentlig nyckelIdentifierare som du kan referera till i loggar; alltid synlig i instrumentpanelen
Hemlig nyckelAutentiseringsuppgifter används för att autentisera API-förfrågningar; maskerad som standard, avslöja med ögatikonen
BehörigheterFinkorniga omfattningar (se nedan)
AnvändningsstatistikTotalt antal förfrågningar och senast använda tidsstämpel
Instrumentpanelen visar samlad statistik: Totalt antal nycklar, Aktiva nycklar, Totalt antal förfrågningar och Begäranden idag.

Skapa en API-nyckel

  1. Logga in med ett Admin- eller Super Admin-konto.
  2. Välj rätt företag och filial i instrumentpanelens rubrik.
  3. Gå till Inställningar → API-nycklar.
  4. Klicka på Skapa API-nyckel.
  5. Ange ett namn (minst 3 tecken) och valfri beskrivning.
  6. Välj behörigheter. Ge bara det som integrationen behöver (minst privilegium).
  7. Klicka på Skapa nyckel.
  8. Kopiera den offentliga nyckeln och hemliga nyckeln omedelbart. Lagra hemligheten i en lösenordshanterare eller miljövariabel (t.ex. `BIZALDO_API_SECRET`). Begå aldrig hemligheter för källkontroll eller bädda in dem i kod på klientsidan.
Skapa API-nyckelmodal med namn, beskrivning och behörigheter1234

Figur 2 — Skapa API-nyckel: namn, beskrivning och behörighetsomfång

Skärmelement

1
Nyckelnamn

Obligatorisk etikett för nyckeln (minst 3 tecken).

2
Beskrivning

Valfri anteckning som beskriver vad denna integration gör.

3
Behörigheter

Välj omfång efter enhetsgrupp. Ge bara det som integrationen behöver.

4
Skapa nyckel

Generera det offentliga och hemliga nyckelparet.

Tillgängliga behörigheter

Behörigheterna är grupperade efter enhet. Växla en hel grupp eller individuella omfattningar:
EntitetBehörigheter
ProdukterVisa, skapa, uppdatera, ta bort, hantera lager, hantera prissättning
KategorierVisa, skapa, uppdatera, ta bort, hantera hierarki
BeställningarVisa, skapa, uppdatera, ta bort, hantera status, bearbeta betalningar, hantera återbetalningar
Bord *(endast restaurang)*Visa, skapa, uppdatera, ta bort, hantera reservationer, hantera status
Bokning *(endast restaurang)*Visa, Skapa, Uppdatera, Ta bort
KundVisa, skapa
BelöningarVisa, skapa, uppdatera, ta bort, hantera poäng, hantera inlösen
AnvändareVisa, skapa, uppdatera, ta bort, hantera roller, hantera åtkomst
InventeringVisa
Rapporter och analysVisa, exportera, skapa anpassade rapporter, hantera schemalagda rapporter
SysteminställningarVisa, uppdatera, hantera integrationer, hantera API-nycklar
Restaurangföretag ser även Tabell och Bokning behörighetsgrupper. Det gör inte detaljhandeln och andra branscher.

Använder en API-nyckel

Skicka server-till-server-förfrågningar till Bizaldo Open API-server med din hemliga nyckel:
GET /api/v1/products HTTP/1.1
Host: openapi.bizaldo.com
Authorization: Bearer YOUR_SECRET_KEY
Content-Type: application/json
Inkludera företaget och filialen från ditt val av instrumentpanel:
x-company-id: YOUR_COMPANY_ID
x-branch-id: YOUR_BRANCH_ID
Typiska användningsfall:
  • Katalogsynkronisering: Dra eller tryck på produkter och kategorier
  • Lagerautomatisering: Reagera på lagernivåförändringar
  • Anpassad rapportering: Bygg rapporter från din filialdata
  • Exporter per natt: Dra slutförda beställningar till bokföringsverktyg

Hantera befintliga nycklar

ÅtgärdEffekt
Kopiera offentlig/hemligAnvänd kopieringsikonen bredvid varje nyckelfält
Visa/dölj hemlighetÖgonikon växlar synligheten
Återskapa hemlighetSkapar en ny hemlighet; den gamla slutar fungera direkt. Uppdatera din integration innan du återkallar den gamla hemligheten.
InaktiveraNyckeln blir inaktiv; API-anrop med den hemligheten misslyckas
AktiveraÅteraktiverar en tidigare avaktiverad nyckel
Visa avaktiveradVäxla för att lista inaktiva nycklar för granskning

Vrid nycklar på ett säkert sätt

Skapa en ny nyckel, distribuera den nya hemligheten till din integration, bekräfta att trafiken lyckas, inaktivera eller återskapa sedan den gamla nyckeln. Förnyelse sker omedelbart. Det finns ingen frist.

Webhooks

Webhooks skickar HTTP-meddelanden till din server när Bizaldo-händelser inträffar, så du behöver inte fråga API:et.

Events som stöds

Instrumentpanelen låter dig prenumerera på dessa händelsetyper (samma uppsättning för restaurang-, detaljhandels- och standardbranscher):
HändelseNär det brinner
product.createdEn ny produkt läggs till
product.updatedProduktdetaljerna ändras
product.deletedEn produkt tas bort
product.stock_updatedLagernivåerna förändras
category.createdEn ny kategori läggs till
category.updatedKategoridetaljer ändras
category.deletedEn kategori tas bort
Välj en eller flera händelser när du registrerar eller redigerar en webhook. Minst en händelse krävs.

Registrera en webhook

  1. Välj rätt företag och filial i instrumentpanelens rubrik.
  2. Gå till Inställningar → Webhooks.
  3. Klicka på Registrera Webhook.
  4. Fyll i formuläret:
FältObligatorisktAnteckningar
SlutpunktsadressJaOffentlig HTTPS-URL, t.ex. `https://your-server.com/webhooks/bizaldo`
BeskrivningNejHjälper till att identifiera slutpunkten senare
API-nyckelDin valda hemliga sträng som används för att verifiera inkommande nyttolaster. Vid redigering lämnar du tomt för att behålla den befintliga nyckeln.
EventJaEn eller flera från tabellen ovan
  1. Klicka på Registrera Webhook.
Webhooks inställningssida med registrera nytt webhook-formulär12345

Figur 3 — Registrera en webhook-slutpunkt och prenumerera på händelser

Skärmelement

1
Fliken Webhooks

Växla från API-nycklar till Webhooks i Inställningar.

2
Företag och filial

Aktuell företags- och filialkontext för den webhook som registreras.

3
Slutpunktens URL

Offentlig HTTPS-URL som tar emot POST-förfrågningar.

4
API-nyckel

Hemlig sträng som används för att verifiera inkommande webhook-nyttolaster.

5
Prenumerera på evenemang

Välj en eller flera händelsetyper att ta emot.

Efter registrering visar Bizaldo en signeringshemlighet i en gul banner: "API Key - Save this now!" Detta värde visas endast en gång. Kopiera den innan du stänger bannern.
Använd denna hemlighet för att verifiera rubriken `X-Bizaldo-Signature` vid varje inkommande webhook-förfrågan.

Verifierar webhook-signaturer

Varje leverans inkluderar ett `X-Bizaldo-Signature`-huvud. Beräkna en HMAC för råbegäran med din signeringshemlighet och jämför den med rubrikvärdet. Avvisa förfrågningar som inte stämmer överens. Din slutpunkt bör:
  • Svara med 2xx inom några sekunder
  • Var idempotent. Samma evenemang kan levereras mer än en gång; deduplicera med händelse-ID om det finns i nyttolasten
  • Använd HTTPS i produktionen

Hantera webhooks

Listan Registered Webhooks visar varje slutpunkt med:
  • URL och beskrivning
  • Prenumererade händelser
  • Aktiv / Inaktiv status
  • Skapat datum
Åtgärder per webhook:
ÅtgärdBeskrivning
RedigeraÄndra URL, beskrivning, händelser eller API-nyckel
LeveranshistorikVisa de senaste 100 leveransförsöken (händelsenamn, HTTP-status, försöksnummer, tidsstämpel)
RaderaTar bort webhook och dess leveranshistorik; händelser slutar skickas

Lokal utveckling

För lokal testning, exponera din maskin med en tunnel (ngrok, Cloudflare Tunnel, etc.) och registrera tunnelns HTTPS URL som webhook-slutpunkt. Använd leveranshistorik i instrumentpanelen för att felsöka misslyckade försök.

Bästa metoder för säkerhet

  • Utfärda separata nycklar per miljö (staging kontra produktion) och per integration.
  • Tillämpa minst behörighet-behörigheter. En skrivskyddad katalogsynkronisering behöver inte `orders:delete`.
  • Begränsa webbhook-adresser till HTTPS och validera `X-Bizaldo-Signature` på varje begäran.
  • Avslöja inte API-hemligheter i webbläsarens JavaScript, mobilappar eller offentliga arkiv.
  • Aktivera tvåfaktorsautentisering på administratörskonton som kan hantera nycklar.
  • Om en hemlighet äventyras, återskapa eller avaktivera nyckeln omedelbart och granska den senaste användningsstatistiken.

Relaterad dokumentation