API/Idempotens
Kom i gang
Idempotens
Idempotensnøkler gjør det trygt å prøve en forespørsel på nytt uten å risikere at den samme utbetalingen opprettes to ganger.
Send headeren Idempotency-key på forespørsler som har sideeffekter. Nøkkelen lagres på partnerkontoen deres, og API-et bruker den til å kjenne igjen en forespørsel den allerede har behandlet.
Reglene
| Situasjon | Resultat |
|---|---|
| Headeren utelates | Forespørselen behandles som normalt. Headeren er valgfri. |
| Verdien er ikke en gyldig UUID | 400 – nøkkelen avvises før forespørselen kjøres. |
| Nøkkelen er allerede lagret for partneren | 400 – nøkkelen er brukt. Sideeffekten kjøres ikke på nytt. |
| Ny, gyldig UUID | Forespørselen kjøres, og nøkkelen lagres. |
Kontrollen mot lageret gjøres for alle ruter så snart nøkkelen finnes der. Bruk derfor én fersk UUID per logisk operasjon – ikke gjenbruk samme nøkkel på tvers av ulike kall.
Særlig for utbetalinger
Headeren er anbefalt på POST /payouts. Det er her en gjentakelse gjør mest skade: uten idempotensnøkkel kan et nettverksbrudd som gjør at dere prøver på nytt, føre til at de samme utbetalingene opprettes to ganger. På rene leseoperasjoner trenger du den normalt ikke.
curl --location --request POST 'https://app.easyfreelance.no/api/v1/payouts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --header 'API-key: <api-nøkkel>' \ --header 'Idempotency-key: 6922d7be-c098-11ec-9d64-0242ac120004' \ --data '{"due_date":"2026-09-15","payouts":[...]}'
Anbefalt mønster
Generer nøkkelen før første forsøk
Lag én UUID når dere bestemmer dere for å sende utbetalingen, og lagre den sammen med utbetalingsraden i deres eget system.
Bruk samme nøkkel ved gjentakelse
Får dere timeout eller et 5XX-svar, prøv igjen med nøyaktig samme nøkkel. Da vet API-et at det er samme operasjon.
Behandle 400 som «allerede utført»
Svarer API-et
400fordi nøkkelen er brukt, betyr det at den første forespørselen kom fram. Verifiser gjerne medGET /payoutsfør dere markerer raden som feilet.
Nøkler har begrenset levetid. Er det gått lang tid siden forrige forsøk, bør dere kontrollere resultatet med GET /payouts framfor å stole på at nøkkelen fortsatt ligger lagret.