Thibitisha mahali kabla ya kutuma mzigo

Delivery Intelligence humruhusu mfanyabiashara kupendekeza mahali, kumwomba mpokeaji apathibitishe au apasahihishe, na kupokea matokeo ya kuaminika kabla ya kutimiza agizo.

Utaratibu kutoka mwanzo hadi mwisho

1. Backend yako inaunda ombi la uthibitisho.
2. Katika Production, Alkax humtumia mpokeaji kiungo salama chenye muda. Sandbox huhifadhi arifa iliyozuiwa kwenye hifadhi yake ya majaribio; fungua kiungo kilichorudishwa mwenyewe.
3. Mpokeaji anakagua mahali palipopendekezwa bila kuhitaji akaunti ya Alkax.
4. Anakubali, anachagua mahali pengine pa Alkax panapotumika au anaunda panapokosekana.
5. Anaweza kuongeza picha binafsi ya kiingilio, ambayo haipatikani hadi ikubaliwe na ukaguzi.
6. Alkax inarekodi nakala iliyothibitishwa au iliyosahihishwa.
7. Backend yako inapata matokeo au inapokea webhook iliyotiwa sahihi.

Kabla ya kuanza

Unda mradi katika Developer Console na utoe kitambulisho mahususi cha mazingira chenye ruhusa zinazohitajika:

• delivery:write kuunda, kughairi, kutuma tena na kurudia tukio;
• delivery:read kupata matokeo.

Vitambulisho vya Sandbox vina umbo la ak_test_<key-id>.<secret> na vya Production hutumia ak_live_<key-id>.<secret>. Hifadhi thamani kamili katika kidhibiti cha siri. Inaoneshwa mara moja na haipaswi kuwekwa kamwe katika msimbo wa kivinjari au simu.

export ALKAX_BASE_URL="https://api.alkax.io"
export ALKAX_API_KEY="ak_test_<key-id>.<secret>"

1. Andaa webhook yako

Tumia endpoint ya umma ya HTTPS inayorudisha 2xx baada tu ya tukio kukubaliwa na kuhifadhiwa kwa kudumu:

POST https://merchant.example/webhooks/alkax

Alkax hukataa anwani zisizo za HTTPS, za loopback na za mitandao binafsi na haifuati uelekezaji mwingine.

2. Unda uthibitisho

Badilisha expiresAt kwa muhuri wa muda wa UTC wa baadaye na recipientContact kwa kisanduku cha barua cha majaribio unachodhibiti kabla ya kutuma ombi hili. Kiolezo cha data hapa chini hakiwezi kutekelezwa hadi thamani hizo zitolewe.

Zalisha ufunguo mmoja wa idempotency kwa kila jaribio la kimantiki la anwani ya agizo. Utumie tena tu unapojaribu ombi linalofanana kabisa.

Mfano wa Sandbox hautumi barua. Production inaweza kutuma barua; pata ridhaa ya mpokeaji kwanza.

curl --request POST "$ALKAX_BASE_URL/api/v1/address-confirmations" \
  --header "X-Alkax-Key: $ALKAX_API_KEY" \
  --header "Idempotency-Key: order-1042-address-v1" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: fr" \
  --data '{
    "merchantReference": "ORDER-1042",
    "recipientContact": "[email protected]",
    "locale": "fr",
    "expiresAt": "<UTC timestamp in the future>",
    "proposedAddress": {
      "placeId": null,
      "title": "Bonaberi depot",
      "plusCode": "6GCR+8J",
      "settlement": "Douala",
      "locality": "Bonaberi",
      "country": "CM",
      "buildingName": null,
      "floor": null,
      "unit": null,
      "latitude": 4.08,
      "longitude": 9.66
    },
    "callbackUrl": "https://merchant.example/webhooks/alkax"
  }'

Jibu la awali la 201 linajumuisha:

• id, kitambulisho cha ombi cha Alkax;
• recipientUrl, kinachorudishwa tu wakati wa kuunda mara ya kwanza;
• webhookSigningSecret, kinachorudishwa tu wakati wa kuunda mara ya kwanza Alkax inapotengeneza siri ya callback.

Hifadhi siri ya kutia sahihi mara moja. Alkax haiwezi kuirudisha tena.

3. Soma mzunguko wa maisha

curl "$ALKAX_BASE_URL/api/v1/address-confirmations/<request-id>" \
  --header "X-Alkax-Key: $ALKAX_API_KEY" \
  --header "Accept-Language: en"

Hali	Maana
Pending	Imeundwa; mpokeaji bado hajafungua kiungo kinachotumika
Opened	Mpokeaji amefungua mchakato wa uthibitisho
Confirmed	Mpokeaji amekubali mahali
Corrected	Mpokeaji amechagua au kuunda mahali tofauti
Expired	Ombi lenye muda maalumu limeisha bila kukamilishwa
Cancelled	Mfanyabiashara amekatisha ombi

Tumia nakala isiyobadilika iliyothibitishwa kwa utimizaji wa agizo. Usiijenge upya kutoka maandishi ya kuonesha au pendekezo la awali. Tathmini ikifanywa, jibu linaweza pia kuwa na confidenceScore, confidenceBand na confidencePolicyVersion.

4. Hakiki sahihi za webhook

Kila webhook inajumuisha:

X-Alkax-Event-Id: <UUID>
X-Alkax-Timestamp: <Unix seconds>
X-Alkax-Signature: v1=<hex HMAC-SHA256>

Baiti zinazotiwa sahihi ni:

<timestamp>.<raw HTTP request body>

Mfano wa Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAlkaxWebhook({ rawBody, timestamp, signature, secret }, nowSeconds = Math.floor(Date.now() / 1000)) {
  if (!Buffer.isBuffer(rawBody) || typeof timestamp !== "string" || !/^\d{1,12}$/.test(timestamp) ||
      Math.abs(nowSeconds - Number(timestamp)) > 300 || typeof signature !== "string" ||
      !/^v1=[a-f0-9]{64}$/.test(signature) || typeof secret !== "string" || !secret) return false;
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`, "utf8")
    .update(rawBody)
    .digest();
  const supplied = Buffer.from(signature.slice(3), "hex");
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

Chakata tukio kwa mpangilio huu:

1. Kataa mihuri ya muda iliyo nje ya dirisha la dakika tano la usasa.
2. Hakiki sahihi kwa kutumia mwili ghafi usiobadilishwa, kisha linganisha eventId iliyochanganuliwa na kichwa.
3. Hifadhi utambulisho wa mazingira/tukio na hash ya mwili ghafi kwa sharti la upekee.
4. Utambulisho ukiwa tayari upo na hash ileile, rudisha 2xx bila kurudia athari. Hash tofauti ni hitilafu ya uadilifu; usibadilishe hali.
5. Hifadhi tukio na mabadiliko yako ya biashara kwa kudumu kabla ya kurudisha 2xx.

Alkax hujaribu tena kwa kuisha muda wa kusubiri, 408, 425, 429 na 5xx. Kitambulisho cha tukio na data hubaki vilevile katika majaribio ya kurudia na urudiaji wa mkono.

Vitendo vya uendeshaji

Kitendo	Endpoint	Ruhusa inayohitajika
Ghairi	POST /api/v1/address-confirmations/{id}/cancel	write
Tuma tena kiungo cha mpokeaji	POST /api/v1/address-confirmations/{id}/resend	write
Rudia webhook iliyoshindwa kabisa	POST /api/v1/address-confirmations/webhooks/{eventId}/replay	write

Kutuma tena hubadilisha tokeni ya mpokeaji na kuna kikomo cha kasi. Ombi lililoghairiwa, lililokamilika au lililoisha muda haliwezi kutuma arifa inayoweza kutekelezwa.

Hitilafu na majaribio ya kurudia

• 400: sahihisha ombi; usijaribu tena bila kulibadilisha.
• 401: kitambulisho kinakosekana, hakijaundwa vizuri, ni batili, kimeisha muda au kimebatilishwa.
• 403: kitambulisho hakina ruhusa inayohitajika au ufikiaji wa Production.
• 404: ombi halipo katika tenant huyu wa mfanyabiashara.
• 409: kagua mgongano wa mzunguko wa maisha au idempotency.
• 429: heshimu Retry-After na uongeze muda wa kusubiri wenye utofauti wa nasibu.
• 5xx: jaribu tena kwa muda wa kusubiri unaoongezeka kwa hatua za kizidishi na ufunguo uleule wa idempotency.

Hitilafu zinazoeleweka kwa watu zinapatikana kwa Kiingereza, Kifaransa, Kiarabu, Kireno na Kiswahili. Hifadhi misimbo inayosomeka na mashine badala ya kulinganisha maandishi yaliyotafsiriwa.

Orodha ya ukaguzi wa kuanza matumizi halisi

• Hifadhi vitambulisho vya mradi na siri za kutia sahihi katika kidhibiti cha siri.
• Ficha mawasiliano ya mpokeaji, URL za mpokeaji, maelekezo binafsi na picha za kiingilio kwenye kumbukumbu.
• Hifadhi mwili ghafi wa webhook bila kuubadilisha.
• Ondoa urudiaji kwa kitambulisho cha tukio.
• Toa tahadhari kuhusu majibu endelevu ya 429/5xx na mrundikano wa webhook.
• Jaribu uthibitisho, usahihishaji, kuisha muda, kughairi, kutuma tena na uwasilishaji rudufu wa webhook.

Mkataba wa callback unaoweza kurejeshwa

Ili kurejesha uundaji, tengeneza na usimbe siri ya kila jaribio kwa hifadhi ya kudumu kabla ya kuita Alkax. Weka sehemu ya hiari callbackSigningSecret kuwa herufi 64 ndogo za heksadesimali kutoka baiti 32 za nasibu; inahitaji callbackUrl. Siri hutumiwa kama maandishi ya UTF-8 kwa HMAC na hairudishwi kamwe. Ikiachwa, Alkax hutengeneza siri na kuirudisha mara moja kama webhookSigningSecret.

Weka callbackSchemaVersion kuwa v2 ili kupokea callback ndogo iliyo wazi hapa chini. Iache au chagua v1 kuhifadhi callback ya awali yenye sehemu za ndani za PascalCase na hali ya namba. Majibu ya HTTP ya uthibitisho hutumia camelCase na hali za maandishi; miundo hii mitatu ni tofauti. Toleo linalotumika huhifadhiwa, na kurudia huhifadhi kitambulisho cha tukio na baiti kamili za data iliyowekwa foleni.

Majaribio yanayofanana kabisa ya kuunda huhifadhi ombi lilelile na kurudisha sehemu za matumizi ya mara moja zikiwa tupu, hata baada ya muda wa kiungo cha awali. Operesheni mpya bado inahitaji muda wa kuisha wa baadaye. Hifadhi data kamili ya awali na ufunguo wa idempotency; chaguo zilizobadilishwa husababisha mgongano. Kila jaribio jipya linahitaji rejea yake fiche katika mradi na mazingira. Jibu binafsi la msingi lina deliveryInstructions, createdAt na cancelledAt; si mwonekano wa umma wa kazi.

Katika callback hapa chini, linganisha eventId na kichwa, hakiki sahihi ghafi na usasa wake, ondoa marudio kwa kudumu, kisha pata matokeo ya msingi kwa uthibitishaji. Callback ndogo haina viwianishi, maelekezo au viungo vya ufikiaji. Matukio ya usajili wa mradi hubaki njia tofauti. Vitambulisho vyake vya kuunda na kughairi ni thabiti kwa kila uthibitisho na mabadiliko; hili haliondoi marudio ya maana katika njia ya awali ya callback kwa uthibitisho.

{
  "schemaVersion": "v2",
  "eventId": "11111111-1111-4111-8111-111111111111",
  "type": "address_confirmation.confirmed",
  "occurredAt": "2026-10-25T12:00:00+00:00",
  "request": {
    "id": "22222222-2222-4222-8222-222222222222",
    "merchantReference": "opaque-attempt-reference",
    "status": "Confirmed",
    "expiresAt": "2026-10-26T12:00:00+00:00"
  }
}

Sandbox huhifadhi arifa kwenye hifadhi ya majaribio na haitumi barua pepe kwa mpokeaji. Jaribu kiungo kilichorudishwa mwenyewe; kuwasha Production kunahitaji uthibitishaji kwenye huduma iliyowekwa.

Weka toleo linalolingana la mtoa huduma kabla ya kutumia chaguo za nyongeza. Hali ya msingi iliyohifadhiwa inaweza kubaki Pending au Opened baada ya muda hadi kugunduliwa kwa kuisha; upatanisho wa kuisha nyuma ya pazia unabaki sharti la kutolewa. Muda wa kiungo haubatilishi nakala iliyokamilika. Mabadiliko ya pini binafsi yanaweza kubaki Confirmed pale vitambulisho vya mahali havibadiliki: linganisha nakala sahihi ya msingi na hifadhi toleo la eneo badala ya kutegemea uainishaji pekee. Mkataba wa urejeshaji pekee hautekelezi ridhaa au ufichuzi wa VolXpr. Mwonekano binafsi uliopangishwa huwashwa kando kupitia chaguo la muktadha hapa chini.

Ziara binafsi za jumuiya

Kwa ziara binafsi ya nyumbani, ongeza sehemu hizi kwenye ombi la kawaida la kuunda:

{ "presentationContext": "private_visit", "locale": "fr" }

presentationContext ni ya hiari; kutoiweka huhifadhi utaratibu wa kawaida wa uwasilishaji. Thamani pekee inayokubaliwa ni private_visit. Huhifadhiwa pamoja na uthibitisho na inashiriki katika idempotency: kuibadilisha kunahitaji jaribio na rejea mpya. Majibu ya kuunda/GET yaliyoidhinishwa hurudisha thamani hii iliyofungwa kwenye seva ili kutambua mtoa huduma wa zamani anayepuuza chaguo.

Ukurasa unaeleza kuwa nyumba inabaki binafsi, unaficha uundaji wa eneo la umma na ukusanyaji wa picha, na unaruhusu pini maalum sahihi au eneo la umma la kukutana lililopo kwa hiari. Kukamilisha hakuundi wala kusasisha eneo la umma. Seva inakataa entranceImageReference kwa ziara binafsi, hata kwa maombi nje ya kiolesura.

Jibu la umma lina effectiveLocale, iliyorekebishwa kuwa en, fr, ar, pt au sw (Kiingereza kama mbadala). Barua pepe na ukurasa wa kwanza hutumia lugha ileile iliyoombwa. Kubadilisha lugha hakufuti taarifa na Kiarabu kina RTL. Hitilafu za muda hutoa nafasi ya kujaribu tena badala ya kusema kiungo si sahihi.

Hadi muda wa kiungo cha awali uishe, kurudia kukamilisha kwa tokeni iliyotumika hurudisha risiti tu: proposedAddress, confirmedAddress na picha ni tupu. GET haipatikani baada ya kukamilisha; risiti haifungui tena eneo wala kubadilisha matokeo. Mipaka mingine ya mzunguko wa maisha na mabadiliko ya mwisho yanayoshindana inabaki kama ilivyoelezwa hapo juu.