API/Idempotens
Kom i gång
Idempotens
Idempotensnycklar gör det säkert att skicka om en begäran utan att riskera att samma utbetalning skapas två gånger.
Skicka headern Idempotency-key på begäranden som har sidoeffekter. Nyckeln lagras på ert partnerkonto och API:et använder den för att känna igen en begäran som det redan har behandlat.
Reglerna
| Situation | Resultat |
|---|---|
| Headern utelämnas | Begäran behandlas som vanligt. Headern är valfri. |
| Värdet är inte ett giltigt UUID | 400 – nyckeln avvisas innan begäran körs. |
| Nyckeln är redan lagrad för partnern | 400 – nyckeln är redan använd. Sidoeffekten körs inte igen. |
| Nytt, giltigt UUID | Begäran körs och nyckeln lagras. |
Kontrollen mot lagret görs för alla rutter så snart nyckeln finns där. Använd därför ett färskt UUID per logisk operation – återanvänd inte samma nyckel för olika anrop.
Särskilt för utbetalningar
Headern är rekommenderas på POST /payouts. Det är här en upprepning gör mest skada: utan idempotensnyckel kan ett nätverksavbrott som gör att ni försöker igen leda till att samma utbetalningar skapas två gånger. Vid rena läsoperationer behöver du den normalt inte.
curl --location --request POST 'https://app.easyfreelance.no/api/v1/payouts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --header 'API-key: <api-nyckel>' \ --header 'Idempotency-key: 6922d7be-c098-11ec-9d64-0242ac120004' \ --data '{"due_date":"2026-09-15","payouts":[...]}'
Rekommenderat mönster
Generera nyckeln före första försöket
Skapa ett enda UUID när ni bestämmer er för att skicka utbetalningen, och lagra det tillsammans med utbetalningsraden i ert eget system.
Använd samma nyckel vid upprepning
Får ni timeout eller ett 5XX-svar, försök igen med exakt samma nyckel. Då vet API:et att det är samma operation.
Behandla 400 som ”redan utfört”
Svarar API:et
400eftersom nyckeln redan är använd betyder det att den första begäran kom fram. Verifiera gärna medGET /payoutsinnan ni markerar raden som misslyckad.
Nycklar har begränsad livslängd. Om det har gått lång tid sedan förra försöket bör ni kontrollera resultatet med GET /payouts i stället för att lita på att nyckeln fortfarande finns lagrad.