Naar hoofdinhoud

Memly API

Koppel je eigen systemen aan Memly. De API geeft toegang tot de gegevens van één omgeving en is alleen-lezen: je kunt er niets mee aanmaken of wijzigen. Dat is een bewuste keuze, want een sleutel die alleen mag lezen kan bij verlies niets kapotmaken.

Alles loopt over HTTPS en antwoorden zijn JSON. De omgeving volgt uit de sleutel zelf, dus er staat geen omgevings-id in het adres en een sleutel kan nooit gegevens van een andere omgeving teruggeven.

Een sleutel krijgen

Sleutels maakt de eigenaar van de omgeving zelf aan, onder Instellingen, Ontwikkelaar. Die pagina verschijnt zodra Memly API-toegang voor de omgeving heeft aangezet, dus vraag je beheerder eerst of dat gebeurd is. De volledige uitleg staat in de kennisbank.

Een sleutel is na het aanmaken één keer te zien. Memly bewaart er alleen een versleutelde afdruk van, dus opzoeken kan niet en kwijt betekent een nieuwe. Bewaar hem in de omgeving van je eigen toepassing, nooit in code die je deelt en nooit in een browser, want dan heeft iedereen die de pagina opent hem ook.

Aanroepen

De basis-URL van deze omgeving:

https://scintillating-wolf-799.eu-west-1.convex.site/v1

De sleutel gaat mee als Bearer-token:

curl "https://scintillating-wolf-799.eu-west-1.convex.site/v1/me" \
  -H "Authorization: Bearer <je sleutel>"

De omgeving volgt uit de sleutel zelf, dus er is geen omgevings-id in het adres. Een sleutel is alleen-lezen; schrijven kan via deze API niet.

Bladeren door lijsten

Elk lijst-endpoint geeft items en nextCursor. Geef die cursor mee om de volgende pagina te halen, en stop pas als hij null is.

Let op dat een pagina minder rijen kan bevatten dan je vroeg terwijl er nog meer is, omdat sommige endpoints binnen een pagina nog filteren. Stoppen zodra een pagina niet vol zit levert dus een onvolledig antwoord op.

Rechten

Bij het aanmaken van een sleutel kies je welke soorten gegevens hij mag lezen. Vraagt hij iets waarvoor hij geen recht heeft, dan krijgt hij insufficient_scope.

Scope Geeft toegang tot Over personen
finance:read Bestellingen, facturen en abonnementen lezen Ja
members:read Leden en hun toegang lezen Ja
catalog:read Producten en prijzen lezen Nee
learning:read Trainingen en voortgang van leden lezen Ja

Alle endpoints

Aan de slag

Financieel

Leden

Aanbod

Trainingen

Foutmeldingen

Elke fout heeft dezelfde vorm: { "error": { "code": "...", "message": "..." } }. De code ligt vast en verandert niet, dus programmeer daarop en niet op de tekst.

Code HTTP Betekenis
unauthorized 401 De sleutel ontbreekt of klopt niet. Ook een ingetrokken sleutel geeft dit.
api_access_disabled 403 De sleutel klopt, maar API-toegang staat uit voor deze omgeving of de omgeving is niet actief.
insufficient_scope 403 De sleutel mag dit soort gegevens niet lezen.
invalid_status 400 Onbekende status opgegeven.
invalid_limit 400 limit valt buiten 1 tot en met 500.
invalid_id 400 Een id-parameter heeft niet de juiste vorm.
invalid_timestamp 400 Een tijdstempel is leeg of geen epoch-milliseconden.
invalid_combination 400 De parameters spreken elkaar tegen, bijvoorbeeld since zonder status=paid.
missing_parameter 400 Een verplichte parameter ontbreekt.
not_found 404 Het gevraagde bestaat niet in deze omgeving.
internal_error 500 Er ging iets mis aan onze kant. Probeer het later opnieuw.

Werkt een geldige sleutel toch niet, dan zijn er twee verklaringen die je van buitenaf niet ziet: API-toegang staat uit voor de omgeving, of de omgeving is niet actief. Allebei geven ze api_access_disabled. De beheerder ziet het staan op zijn ontwikkelaarspagina in Memly.

Deze documentatie machinaal lezen

Alles op deze pagina's komt uit de API zelf, en dat kun jij ook ophalen: 

curl https://scintillating-wolf-799.eu-west-1.convex.site/v1/spec

Dat endpoint vraagt geen sleutel en beschrijft de scopes, de endpoints, hun parameters, de velden in het antwoord en de foutcodes.