Arcalotls API
Ett publikt REST-API och signerade webhooks över samma prenumerationer, medlemmar, förmåner och statistik som din dashboard visar. Nycklar med scope, cursor-paginering, idempotenta skrivningar och fel som problem details.
Varje Arcalotl-community har ett publikt API på https://api.arcalotl.com/v1. Dina egna system kan läsa prenumerationer, plannivåer, medlemmar, förmåner, engångsköp, rabattkoder och statistik, skapa kassalänkar, byta, säga upp och återuppta prenumerationer, öppna medlemsportalen för en medlem, och hantera webhook-endpoints.
Webhooks skickar samma händelser som API:et serverar, signerade enligt specifikationen Standard Webhooks, så att din tjänst kan reagera på en betalning eller en återkallad förmån utan att polla. Händelseflödet finns också, för avstämning efter driftstopp.
API:et ingår i produktpriset. Arcalotl tar $0/månad plus 2 % av varje genomförd betalning, som dras på kreatörens eget Stripe-konto genom direktbetalningar via Stripe Connect. Det finns ingen utvecklarnivå och ingen avgift per anrop.
En bas-URL, avgränsad per community
Alla resurser ligger under https://api.arcalotl.com/v1. Varje resurs är avgränsad till den community som äger API-nyckeln som anropar den. Ett id som tillhör en annan community svarar 404 i stället för 403, så svaren kan inte användas för att kartlägga en annan communitys data.
Bearer-nycklar med uttryckliga scopes
Varje anrop bär en Authorization-header med en bearer-nyckel som skapats i dashboarden under Developers och sedan API Keys. En nyckel bär de scopes som valdes när den skapades, och ett anrop utan det scope en route kräver svarar 403 med koden missing_scope. Hela nyckeln visas exakt en gång vid skapandet, därefter sparas bara ett visningsprefix.
Läsningarna täcker hela faktureringsbilden
GET-endpoints returnerar prenumerationer med filter på status, plan och nivå, plannivåer med sina underliggande faktureringsplaner, medlemmar med sina plattformskonton, en medlems uträknade förmåner, engångsköp, rabattkoder med antal inlösningar, och en statistiksammanfattning med MRR, aktiva prenumeranter och senaste nya och uppsagda.
Skrivningarna är få och medvetna
Skrivningarna täcker hela prenumerationens livscykel: skapa en kassalänk för en viss köpare, byta plan på en prenumeration, säga upp den vid periodens slut eller återuppta den, öppna medlemsportalen för en medlem, koppla ditt eget användar-id till en medlem, och hantera webhook-endpoints. Kassalänkar tar emot ett anslutet plattformskonto, ett befintligt medlems-id, eller ett namnrymdat externt användar-id som du äger, vilket är så en applikation du styr säljer genom Arcalotl.
Pagineringen bygger på cursor
Listendpoints tar emot en opak cursor och en limit, med högst 100 och 25 som standard, och returnerar en next_cursor. Fältet är null eller saknas på sista sidan. Skicka tillbaka värdet ordagrant; en cursors inre form ingår inte i kontraktet, så konstruera eller tolka den inte.
Idempotensnycklar gör omförsök ofarliga
Anrop för uppsägning och kassalänkar tar emot en Idempotency-Key-header. Samma nyckel med samma body inom 24 timmar spelar upp det ursprungliga svaret och lägger till Idempotent-Replayed: true. Samma nyckel med en annan body svarar 422 idempotency_key_reuse, och att återanvända den medan första anropet fortfarande pågår svarar 409 request_in_flight. Skapa en ny nyckel per logisk operation.
Fel är problemdokument enligt RFC 9457
Fel returnerar application/problem+json med ett stabilt code-fält, till exempel unauthorized, missing_scope, not_found, invalid_request, conflict, not_eligible eller rate_limited. Matcha på code. Fälten title och detail är skrivna för människor och deras formuleringar kan ändras utan förvarning.
Anropsgränserna står i varje svar
Autentiserad trafik begränsas per nyckel till 300 anrop per minut med en burst på 60. Anrop med saknad eller ogiltig nyckel begränsas per klient-IP till 20 per minut med en burst på 10, och påverkar inte anrop som autentiseras korrekt. Varje svar bär RateLimit-Limit, RateLimit-Remaining och RateLimit-Reset, och en 429 lägger till Retry-After i sekunder.
Webhooks följer specifikationen Standard Webhooks
Varje leverans bär headrarna webhook-id, webhook-timestamp och webhook-signature. Signaturen är HMAC-SHA256 över id, tidsstämpel och rå body sammanfogade med punkter, med den avkodade delen av din whsec_-hemlighet som nyckel. Verifiera mot den råa bodyn innan du tolkar JSON, acceptera vilken som helst av de mellanslagsseparerade v1-tokenen så att hemlighetsrotation fungerar, och avvisa en tidsstämpel som ligger mer än fem minuter från din klocka.
Leverans sker minst en gång, med omförsök och automatisk avstängning
Vilken 2xx som helst räknas som lyckad. Allt annat görs om enligt ett fast schema på ungefär tio försök utspridda över cirka 2,3 dagar innan leveransen markeras som uttömd. En endpoint med tio uttömda leveranser i rad stängs av automatiskt, och en lyckad leverans nollställer räknaren. En community kan registrera upp till fem HTTPS-endpoints, granska försöksloggen och köa om en viss leverans.
Händelseflödet täcker det webhooks missar
GET /v1/events returnerar samma kuvert som dina endpoints tar emot, nyast först, filtrerbara på typ och på after_id så att du kan följa en checkpoint i stället för en tidsstämpel. Projicerade händelser sparas i 90 dagar och leveransloggar i 30, så du kan stämma av långt efter att en leveranslogg har åldrats ut.
Ändringar inom en version är bara tillägg
API:et och webhook-kuvertet delar en versionssträng. Inom en version får du nya fält, nya frivilliga parametrar, nya händelsetyper och nya endpoints, och befintliga fält ändrar varken form eller betydelse. Ignorera fält du inte känner igen, så går din integration aldrig sönder av ett tillägg.
Kontraktet publiceras som OpenAPI 3.1
Hela kontraktet för anrop och svar är ett OpenAPI 3.1-dokument som serveras från sajten, och referenssidorna genereras ur samma dokument, så referensen kan inte glida ifrån specifikationen din kodgenerator läser.
Scopes för API-nycklar
| Scope | Ger |
|---|---|
| subscriptions:read | Lista och hämta prenumerationer |
| subscriptions:write | Byta plan, säga upp och återuppta |
| plans:read | Lista och hämta plannivåer |
| members:read | Lista medlemmar, slå upp på plattformskonto eller ditt eget användar-id, läsa förmåner |
| members:write | Koppla dina användar-id, öppna medlemsportalen, skapa länkkoder |
| purchases:read | Lista och hämta engångsköp |
| analytics:read | Läsa statistiksammanfattningen |
| events:read | Polla händelseflödet |
| discounts:read | Lista rabattkoder och deras användning |
| checkout:write | Skapa en kassalänk |
| webhooks:read | Lista webhook-endpoints och deras leveranser |
| webhooks:write | Skapa, ändra, ta bort, rotera, skicka om och testa endpoints |
Välja mellan webhooks, händelseflödet och MCP
Använd webhooks när din tjänst kan exponera en HTTPS-mottagare och behöver agera snabbt på en ändring. Verifiera signaturen, avdubblera på kuvertets id, och svara 2xx snabbt. Behandla kuvertet som en signal: dess data är en ögonblicksbild från när händelsen projicerades, så hämta resursen på nytt när du behöver aktuell sanning.
Använd händelseflödet när du inte kan exponera en mottagare, eller när du återhämtar dig efter driftstopp. Polla med after_id från din senast behandlade händelse, bläddra tills markören är tom, och flytta sedan fram din checkpoint.
Använd MCP-servern när konsumenten är en AI-agent snarare än en tjänst. Den exponerar samma läsningar och samma skrivning för kassalänkar som verktyg, upprätthåller samma scopes, och anropar samma interna tjänst som REST-handlarna anropar.
För en applikation som själv upprätthåller tillgång, prenumerera på member.entitlement.granted, updated och revoked. De händelserna kommer från det auktoritativa förmånsregistret och bär en stabil nyckel och ett stigande revisionsnummer, vilket är vad du vill ha i ett auktorisationssystem.
Frågor
Läs vidare
Bygg på din egen faktureringsdata
Skapa en API-nyckel med scope i dashboarden, peka den mot https://api.arcalotl.com/v1, och registrera en webhook-endpoint för de händelser du bryr dig om.
Skapa ett konto