API atsauce

API atsauce ir Swipelux API oficiālais līgums. Katra operācija parāda tās pieprasījuma, atbildes, drošības, statusa un kļūdas shēmas. Katram pieprasījumam izmantojiet https://platform.swipelux.com. Nosūtiet vides atslēgu X-API-Key no aizsargātas aizmugursistēmas.

Padariet ierakstus drošus atkārtošanai

Ja operācija norāda Idempotency-Key kā obligātu, ģenerējiet vienu atslēgu katrai paredzētajai operācijai un saglabājiet to kopā ar vietējo pieprasījuma ierakstu.

curl --request POST \
  'https://platform.swipelux.com/v3/customers' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Idempotency-Key: customer-order-1001' \
  --header 'Content-Type: application/json' \
  --data '{"type":"individual","externalId":"customer-order-1001"}'

Ja atbilde ir neskaidra, atkārtojiet identisku metodi, ceļu un pamattekstu ar to pašu atslēgu. Neizmantojiet šo atslēgu citai operācijai vai izmainītam pamattekstam. Dažas operācijas atgriež Idempotency-Replayed: true, ja atbilde nāca no agrāka pieprasījuma ar to pašu atslēgu. Uztveriet šo atbildi kā sākotnējās operācijas rezultātu, nevis kā otru operāciju.

Apstrādājiet kļūdas

API kļūdas izmanto application/problem+json. Veidojiet klienta uzvedību ap šiem stabilajiem laukiem:

Lauks	Lietojums
`status`	Ar problēmu saistītais HTTP statuss.
`code`	Stabils mašīnlasāms kļūdas kods.
`detail`	Praktisks skaidrojums pašreizējam pieprasījumam.
`retryable`	Vai tā paša pieprasījuma atkārtošana var būt veiksmīga, ja norādīts.
`errors[].pointer`	JSON Pointer uz nederīgu pieprasījuma lauku.
`correlationId`	Pieprasījuma identifikators, ko saglabāt žurnālos un atbalsta ierakstos.

Atbildes correlationId atspoguļo X-Request-Id. Reģistrējiet gan operāciju, gan šo vērtību, taču neatklājiet noslēpumus vai pilnu finanšu informāciju.

{
  "type": "https://docs.swipelux.com/problems/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "The request contains invalid fields.",
  "correlationId": "01JERRORVALIDATION",
  "errors": [
    {
      "pointer": "/externalId",
      "code": "invalid_format",
      "message": "Use a valid external identifier."
    }
  ]
}

Izmantojiet operācijas dokumentētās problēmas shēmas, lai izlemtu, vai koriģēt ievadi, atsvaidzināt resursa stāvokli, pabeigt uzdevumu vai atkārtot mēģinājumu. Uzturiet pilnu statusu un kļūdu katalogu API atsaucē, nevis kodējiet nedokumentētus gadījumus.

Sekojiet asinhronām operācijām

Veiksmīga izveides atbilde uzsāk daudzas darbplūsmas; tā negarantē pabeigšanu. Saglabājiet no atbildes iegūtos resursu ID, nolasiet pašreizējo resursu un izmantojiet verificētus webhook izsaukumus, lai reaģētu uz izmaiņām. Sāciet ar POST /v3/customers vai sekojiet ātrajam startam, lai iegūtu pilnu smilšu kastes pieredzi.

Pārskats

Versiju pārvaldība

Padariet ierakstus drošus atkārtošanai

Apstrādājiet kļūdas

Sekojiet asinhronām operācijām

​Padariet ierakstus drošus atkārtošanai

​Apstrādājiet kļūdas

​Sekojiet asinhronām operācijām

Padariet ierakstus drošus atkārtošanai

Apstrādājiet kļūdas

Sekojiet asinhronām operācijām