Kutoka ufunguo wa Sandbox hadi urejeshaji uliokamilika

Anza na mwongozo wa kuanza kutumia API. Tumia mradi mmoja maalumu wa Sandbox kwa taratibu hizi. Alkax hurekodi maendeleo ya kimwili ya uwasilishaji na urejeshaji. Mfumo wako wa biashara unasimamia urejeshaji wa fedha, bidhaa kwenye hifadhi, ubadilishanaji na salio la mteja.

Vitambulisho na mazingira

Anwani ya seva ya API ni https://api.alkax.io. Sandbox au Production huchaguliwa kwa mazingira ya kitambulisho, si kwa njia ya URL. Usiweke kamwe ufunguo wa Developer katika msimbo wa kivinjari au simu. Tokeni ya ufikiaji ya akaunti ya Alkax ni tofauti na kitambulisho cha X-Alkax-Key.

Kitendo	Ruhusa
Unda shehena au urejeshaji rasmi	delivery:create
Soma hali binafsi ya shehena/urejeshaji	delivery:read
Wasilisha matukio ya uwasilishaji/urejeshaji; rekodi kupokea mzigo ulioachwa kituoni	delivery:events
Wasilisha ushahidi au faili za ushahidi wa urejeshaji	delivery:proof
Uthibitisho wa anwani, kuidhinisha/kukataa/kughairi urejeshaji rasmi, ufikiaji wa kuchukua, suluhisho la RTS	delivery:write

Uunganishaji kamili wa uwasilishaji na urejeshaji unahitaji ruhusa zinazotakiwa na vitendo unavyofanya. Kubadilisha ufunguo huhifadhi ruhusa za ufunguo wa awali, hivyo kutoa ufunguo mpya hakubadilishi seti ya ruhusa zilizoidhinishwa. Kukosekana kwa ruhusa ya ushahidi kunaweza kuzuia tukio la ukamilishaji linaloutegemea kufanikiwa. Nakili ufunguo ghafi pekee. Tazama utatuzi wa matatizo.

Mzunguko wa maisha ya shehena ya kwenda

Baada ya uthibitisho wa anwani, tumia nakala isiyobadilika iliyothibitishwa kama destination katika POST /api/v1/deliveries. Toa Idempotency-Key na activationEventId thabiti. Kuunda hurudisha id, trackingNumber na hali. Usidhani rejeleo la nje la agizo ni namba ya ufuatiliaji ya Alkax.

Tuma POST /api/v1/deliveries/{id}/events yenye UUID thabiti ya eventId, muhuri halisi wa muda wa occurredAt na mojawapo ya amri hizi:

Amri	Matokeo
MarkInTransit	InTransit
MarkAtLocalDepot	AtLocalDepot
MarkOutForDelivery	OutForDelivery
RecordDeliveryAttempt	DeliveryAttempted
CompleteDelivery	Delivered

Jaribu tena tukio lilelile baada ya kushindwa kwa usafirishaji. 409 inahitaji ukaguzi wa hali rasmi; usibuni kitambulisho kipya kukwepa ukaguzi wa migongano. Mihuri ya muda iliyo zaidi ya dakika tano mbele inakataliwa. Vitambulisho vya matukio ni tofauti na vitambulisho vya maombi vinavyotumika kwa uchunguzi. Usitegemee sentensi za hitilafu zilizotafsiriwa.

Kwa ushahidi wa shehena ya kwenda, kwanza tuma POST /api/v1/deliveries/{id}/proofs yenye proofId thabiti, method, occurredAt na sehemu zinazohitajika za mpokeaji/rejeleo. Toa proofId hii kwa CompleteDelivery. Wasilisha ushahidi kabla ya tukio linaloutegemea. Ushahidi lazima uwe wa shehena/mazingira yale yale; ushahidi wa urejeshaji ni mkataba tofauti.

Ufikiaji wa mpokeaji

Ufuatiliaji usio na utambulisho huonesha maendeleo ya jumla pekee. Namba ya ufuatiliaji haiwezi kuidhinisha kuunganisha akaunti, maombi ya urejeshaji, maelekezo binafsi au ufikiaji wa ushahidi. Kuunganisha akaunti huhakiki mawasiliano ya mpokeaji. Kulingana kwa maandishi ya barua pepe ambayo haijathibitishwa si njia ya kutoa idhini. Mawasiliano ya uthibitisho wa anwani si moja kwa moja mawasiliano rasmi ya mpokeaji wa shehena.

Mpokeaji aliyeunganishwa anaweza kuomba urejeshaji baada tu ya shehena kuwa Delivered. Katika My deliveries (Uwasilishaji wangu), chagua kuchukuliwa au kuacha kituoni na uwasilishe sababu. Ombi hubaki linasubiri hadi liidhinishwe au likataliwe. Kuacha kituoni kulikoidhinishwa bado kunahitaji kurekodi kupokea mzigo kimwili. Ombi moja linaruhusiwa kwa kila kifurushi cha kwenda, na maamuzi ni ya mwisho.

Idhini ya urejeshaji ya mfanyabiashara

POST /api/v1/returns hukubali originalShipmentId, eventId, type, reason, destination, origin/maelekezo ya hiari na mahitaji ya ushahidi wa kuchukua/kupokea. Tumia type: RecipientReturn, reason: RecipientChangedMind kwa utaratibu wa msingi wa mteja. Urejeshaji wa mteja unahitaji shehena ya kwenda ya Delivered. Chanzo kisipotolewa huanza kwenye nakala ya shehena ya kwenda, si kutoka utafutaji wa anwani inayoweza kubadilika.

Idhini ni tofauti na usafirishaji. Urejeshaji wa mteja ulioombwa unahitaji POST /api/v1/returns/{id}/approve?eventId={uuid}. Kukataa na kughairi hutumia kanuni hiyo hiyo ya kitambulisho kwenye query. Kughairi kunaruhusiwa kabla ya makabidhiano ya kimwili tu. Urejeshaji ulioidhinishwa huanza kwenye AwaitingHandover; idhini yenyewe haipangi msafirishaji.

Thibitisha kuchukua na uwasilishe ushahidi wa urejeshaji

1. Ita POST /api/v1/returns/{id}/pickup-confirmation kwa delivery:write.
2. Fikisha URL ya mpokeaji iliyorudishwa kwa usalama. Kutoa mbadala hubatilisha kiungo cha awali ambacho hakijakamilika. Usiweke tokeni yake kwenye kumbukumbu au kuionesha katika ufuatiliaji wa umma.
3. Mpokeaji hukagua/husahihisha kuchukuliwa kupitia utaratibu wa umma wa tokeni. Nakala iliyothibitishwa hubaki tofauti na mahali pa awali pa shehena ya kwenda.
4. Ushahidi ukihitajika, rekodi sahihi/picha halisi ya PNG. Pakia kwa PUT /api/v1/returns/{id}/proof-assets/{proofId}/signature (au /photo) yenye { "dataUrl": "data:image/png;base64,..." }. Upeo ni MB 2, pikseli 2048 kwa 2048.
5. Tumia reference iliyorudishwa katika POST /api/v1/returns/{id}/proofs yenye proofId ileile, purpose: Pickup au Receipt, mbinu na muhuri wa muda. Mbinu za sahihi zinahitaji taarifa za mpokeaji. Maandishi yoyote au URL za mfanyabiashara si mbadala halali wa faili za urejeshaji zilizopakiwa.
6. Jumuisha kitambulisho hicho cha ushahidi katika tukio linalolingana la makabidhiano/ukamilishaji.

Majaribio ya kurudia kupakia faili lazima yatumie baiti zilezile. Ushahidi wa kuchukua urejeshaji hauwezi kutimiza sharti lake la kupokea, na hakuna unaoweza kutumia tena ushahidi wa shehena ya kwenda. Faili binafsi zinahitaji delivery:proof na mradi/mazingira yanayolingana wakati wa kusoma na kuandika.

Usafirishaji wa kurudisha na RTS ya uwasilishaji ulioshindwa

Wasilisha matukio ya urejeshaji yenye vitambulisho thabiti kwa /api/v1/returns/{id}/events: SchedulePickup, MarkPickedUp, MarkAtReturnHub, MarkInTransit, Complete. Complete huzalisha DeliveredToMerchant kwa urejeshaji wa mteja na ReturnedToSender kwa uwasilishaji ulioshindwa. RecordException hurekodi tatizo la usafirishaji; si ruhusa ya kuandika upya historia.

Kwa shehena ya DeliveryAttempted, ita POST /api/v1/deliveries/{id}/resolution yenye evaluationId thabiti, failureReason iliyosanifishwa, attemptCount chanya na returnDestination iliyothibitishwa pale RTS inapowezekana. Sera iliyoandikwa huchagua RTS kwa kukataliwa, mpokeaji kutopatikana baada ya majaribio matatu au tatizo la malipo baada ya mawili. Matatizo ya anwani yanahitaji usahihishaji; kushindwa kusikojulikana hupelekwa kwa ukaguzi wa mtu. Ushahidi uliosanifishwa unaorudiwa huondolewa urudiaji. Usitumie maandishi ghafi ya msafirishaji kuhusu kushindwa kama sababu rasmi.

Usomaji binafsi wa urejeshaji hutumia /api/v1/returns/{id} au /by-tracking/{trackingNumber}. /api/public/returns/{trackingNumber} isiyo na utambulisho haijumuishi mawasiliano, eneo sahihi, maelekezo na ushahidi.

Mipaka ya uwajibikaji na uaminifu

Merchant server -- scoped environment key --> Alkax API
Recipient      -- expiring capability ----> Confirm address / pickup
Recipient      -- verified account -------> Linked delivery / return request
Public viewer  -- tracking number --------> Coarse progress only
Alkax webhook  -- signed raw body --------> Merchant webhook receiver
Merchant system -- own business policy ---> Refund / inventory system

Sandbox na Production zina vitambulisho, rasilimali na usajili wa webhook tofauti. Webhook haihamishi ruhusa kwenda mazingira mengine. Tazama mwongozo wa webhook na orodha ya kuanza matumizi halisi.

Tumia jedwali la majaribio ya Sandbox kwa hali za usahihishaji, kuisha muda, kukataliwa, ruhusa zisizo sahihi na kurudia matukio.