Je eigen systemen koppelen met de API

Met de Beam API lees en beheer je artikelen, locaties en voorraad vanuit je eigen systemen, en maak en volg je orders en taken. De API is bedoeld voor koppelingen die op een server draaien.

Voor je begint

• Je hebt beheerrechten op de organisatie nodig. Heb je die niet, vraag dan je organisatiebeheerder om toegang.
• Een API-key hoort bij één organisatie en kan alleen die organisatie bereiken.

Een API-key aanmaken

1. Open het instellingenmenu en kies Organisatie-instellingen.
2. Kies API-keys en daarna Nieuwe API-key. Is je laatste inlog te lang geleden, dan vraagt Beam je eerst opnieuw in te loggen.
3. Vul een Naam in, kies bij Toegang wat je koppeling nodig heeft en kies bij Geldig 30, 90, 180 of 365 dagen.
4. Kies Key genereren.
5. Beam toont Bewaar deze key nu. Kopieer de key met Kopiëren en zet hem in de geheimenopslag van je server. Noteer ook het Organisatiepad: dat gebruik je in elke aanroep.
6. Bevestig dat je begrijpt dat de waarde niet terug te halen is en kies Ik heb de key opgeslagen.

Beam toont de volledige key maar één keer. Ben je hem kwijt, dan krijg je met Roteren een nieuwe waarde.

Welke toegang kies je?

Kies de minste toegang die je koppeling nodig heeft. Bij elk endpoint in de API-referentie staat welke toegang je nodig hebt.

Toegang	Wat de key mag
Alleen lezen	Artikelen, locaties, voorraad en orders lezen.
Voorraadsync	Artikelen en locaties lezen, voorraad lezen en wijzigen.
Ordersync	Artikelen, locaties en voorraad lezen, orders lezen en wijzigen en taken beheren.
Volledige API-toegang	Alle handelingen uit de API-referentie, inclusief artikelen en locaties aanmaken en wijzigen.

Taken lezen vraagt Ordersync of Volledige API-toegang. Alleen lezen geeft geen toegang tot taken. Met Ordersync kun je de voorraad lezen, maar niet wijzigen.

Je eerste aanroep

Stuur de key bij elke aanroep mee in de Authorization-header. Vervang YOUR_ORGANIZATION_ID door het ID uit je organisatiepad.

curl 'https://connect.beamtracking.com/v1/organizations/YOUR_ORGANIZATION_ID/locations' \
  -H "Authorization: Bearer <jouw API-key>"

Bij een geslaagde aanroep krijg je een items-lijst met locaties. Bewaar het locationId dat je voor voorraad, orders en taken wilt gebruiken. Zijn er geen locaties, dan is de lijst leeg.

Zet een key nooit in een website of mobiele app. De API werkt alleen vanaf een server: een browserpagina kan hem niet rechtstreeks aanroepen.

De API-referentie

De beschikbare endpoints, velden, foutafhandeling en limieten staan in de API-referentie, in het Engels. Wil je de API in Postman of een codegenerator laden, gebruik dan het OpenAPI-bestand.

Betrouwbaar gegevens bijwerken

• Gebruik bij elke schrijfactie een nieuwe UUID in Idempotency-Key. Herhaal na een timeout dezelfde aanroep met dezelfde key om dubbele wijzigingen te voorkomen.
• Stuur bij updates die If-Match vereisen de laatste ETag mee. Bij een conflict lees je het record opnieuw voordat je een nieuwe wijziging verstuurt.
• Een voorraadcorrectie zet het totale aantal. Gebruik een voorraadverplaatsing als goederen fysiek naar een andere locatie gaan.
• Stuur bij een orderupdate het volledige gewenste orderplan. Een weggelaten, nog niet uitgevoerde regel wordt geannuleerd.
• Een geaccepteerde wijziging kan nog worden verwerkt. Volg de instructies voor achtergrondverwerking in de API-referentie en controleer de uiteindelijke records.

Een key beheren

Tik op een key onder Bestaande keys.

• Roteren geeft een nieuwe waarde met dezelfde looptijd. De huidige key stopt direct, dus werk je koppeling meteen bij.
• Pauzeren stopt de toegang vanaf de eerstvolgende aanroep. Na Activeren kan een eerder geweigerde key tot vijf minuten nodig hebben voordat hij weer werkt.
• Definitief intrekken kun je niet ongedaan maken.

Na de verloopdatum stopt een key vanzelf. De app waarschuwt 30 dagen van tevoren.