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.
12345Figur 1 — Fliken Inställningar API-nycklar med företags- och filial-ID
Skärmelement
Öppna Inställningar och välj API-nycklar för att hantera integrationsuppgifter.
Kopiera företags-ID för din integration. Matchar företaget som valts i instrumentpanelens rubrik.
Kopiera filial-ID för din integration. Matchar den gren som valts i instrumentpanelens rubrik.
Starta flödet för att skapa nyckel.
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ält | Beskrivning |
|---|---|
| Namn | Människoläsbar etikett (minst 3 tecken), t.ex. `Production ERP` |
| Beskrivning | Valfri notering om vad integrationen gör |
| Offentlig nyckel | Identifierare som du kan referera till i loggar; alltid synlig i instrumentpanelen |
| Hemlig nyckel | Autentiseringsuppgifter används för att autentisera API-förfrågningar; maskerad som standard, avslöja med ögatikonen |
| Behörigheter | Finkorniga omfattningar (se nedan) |
| Användningsstatistik | Totalt antal förfrågningar och senast använda tidsstämpel |
Skapa en API-nyckel
- Logga in med ett Admin- eller Super Admin-konto.
- Välj rätt företag och filial i instrumentpanelens rubrik.
- Gå till Inställningar → API-nycklar.
- Klicka på Skapa API-nyckel.
- Ange ett namn (minst 3 tecken) och valfri beskrivning.
- Välj behörigheter. Ge bara det som integrationen behöver (minst privilegium).
- Klicka på Skapa nyckel.
- 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.
1234Figur 2 — Skapa API-nyckel: namn, beskrivning och behörighetsomfång
Skärmelement
Obligatorisk etikett för nyckeln (minst 3 tecken).
Valfri anteckning som beskriver vad denna integration gör.
Välj omfång efter enhetsgrupp. Ge bara det som integrationen behöver.
Generera det offentliga och hemliga nyckelparet.
Tillgängliga behörigheter
Behörigheterna är grupperade efter enhet. Växla en hel grupp eller individuella omfattningar:| Entitet | Behörigheter |
|---|---|
| Produkter | Visa, skapa, uppdatera, ta bort, hantera lager, hantera prissättning |
| Kategorier | Visa, skapa, uppdatera, ta bort, hantera hierarki |
| Beställningar | Visa, 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 |
| Kund | Visa, skapa |
| Belöningar | Visa, skapa, uppdatera, ta bort, hantera poäng, hantera inlösen |
| Användare | Visa, skapa, uppdatera, ta bort, hantera roller, hantera åtkomst |
| Inventering | Visa |
| Rapporter och analys | Visa, exportera, skapa anpassade rapporter, hantera schemalagda rapporter |
| Systeminställningar | Visa, 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:Inkludera företaget och filialen från ditt val av instrumentpanel:GET /api/v1/products HTTP/1.1 Host: openapi.bizaldo.com Authorization: Bearer YOUR_SECRET_KEY Content-Type: application/json
Typiska användningsfall:x-company-id: YOUR_COMPANY_ID x-branch-id: YOUR_BRANCH_ID
- 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ärd | Effekt |
|---|---|
| Kopiera offentlig/hemlig | Använd kopieringsikonen bredvid varje nyckelfält |
| Visa/dölj hemlighet | Ögonikon växlar synligheten |
| Återskapa hemlighet | Skapar en ny hemlighet; den gamla slutar fungera direkt. Uppdatera din integration innan du återkallar den gamla hemligheten. |
| Inaktivera | Nyckeln blir inaktiv; API-anrop med den hemligheten misslyckas |
| Aktivera | Återaktiverar en tidigare avaktiverad nyckel |
| Visa avaktiverad | Växla för att lista inaktiva nycklar för granskning |
Vrid nycklar på ett säkert sätt
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ändelse | När det brinner |
|---|---|
product.created | En ny produkt läggs till |
product.updated | Produktdetaljerna ändras |
product.deleted | En produkt tas bort |
product.stock_updated | Lagernivåerna förändras |
category.created | En ny kategori läggs till |
category.updated | Kategoridetaljer ändras |
category.deleted | En 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
- Välj rätt företag och filial i instrumentpanelens rubrik.
- Gå till Inställningar → Webhooks.
- Klicka på Registrera Webhook.
- Fyll i formuläret:
| Fält | Obligatoriskt | Anteckningar |
|---|---|---|
| Slutpunktsadress | Ja | Offentlig HTTPS-URL, t.ex. `https://your-server.com/webhooks/bizaldo` |
| Beskrivning | Nej | Hjälper till att identifiera slutpunkten senare |
| API-nyckel | Din 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. | |
| Event | Ja | En eller flera från tabellen ovan |
- Klicka på Registrera Webhook.
12345Figur 3 — Registrera en webhook-slutpunkt och prenumerera på händelser
Skärmelement
Växla från API-nycklar till Webhooks i Inställningar.
Aktuell företags- och filialkontext för den webhook som registreras.
Offentlig HTTPS-URL som tar emot POST-förfrågningar.
Hemlig sträng som används för att verifiera inkommande webhook-nyttolaster.
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ärd | Beskrivning |
|---|---|
| Redigera | Ändra URL, beskrivning, händelser eller API-nyckel |
| Leveranshistorik | Visa de senaste 100 leveransförsöken (händelsenamn, HTTP-status, försöksnummer, tidsstämpel) |
| Radera | Tar 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
- Företagsinställningar — Företagsprofil, filialer och fakturering
- Orderhantering — Orderlivscykel (separat från aktuell webhook-händelsekatalog)
- Plattformsöversikt — Bizaldo-arkitektur och appar
- FAQ — Vanliga integrationsfrågor