# Amadokhumenti e-API ye-AfricaProxies

> I-REST API ye-AfricaProxies ku-africaproxies.com/api: izikhiye ze-API, amaphutha, imikhawulo, imali esele, crypto, ama-oda, proxy nokushintsha i-IP yeselula.

- URL: https://africaproxies.com/zu/docs/api/
- Kuvini okugcwele: 2026-10-15
- UmphRhizisheli: AfricaProxies (https://africaproxies.com)

Konke okwenzayo ku-akhawunti kungabhalwa kusikripthi: hlola imali esele, wengeze nge-crypto, uthenge iphakheji, udale imininingwane yokungena ye-proxy, ushintshe i-IP yeselula. I-JSON nge-HTTPS, ukhiye owodwa we-API, izibonelo ze-curl, Python ne-Node.js.

**Impendulo esheshayo — Ngiyisebenzisa kanjani i-API ye-AfricaProxies?**

Thumela izicelo ze-HTTPS ku-`https://africaproxies.com/api/v1` ngokhiye wakho we-API esihlokweni esithi `Authorization: Bearer API_KEY`. Dala ukhiye [ekhasini lonjiniyela](/app/developer?lang=zu) le-akhawunti yakho (noma nge-`POST /v1/api-keys`), uwunike izimvume ezidingekayo kuphela. Izicelo nezimpendulo ziyi-JSON; amaphutha ahlala ebuya njenge-`{ "error": { "code", "message" } }`.

## Ngamafuphi

| Isici | Iqiniso |
| --- | --- |
| I-URL eyisisekelo | `https://africaproxies.com/api/v1` |
| Ifomethi | I-JSON nge-HTTPS, UTF-8 |
| Ukuqinisekisa ukungena | Ukhiye we-API: `Authorization: Bearer API_KEY` |
| Imingcele yezimvume zokhiye we-API | `read`, `proxies`, `billing` |
| Imali | I-USD njengentambo enezindawo zedesimali 2 (`"29.00"`) |
| Amanani e-crypto | Izintambo zombhalo zedesimali, kungabi izinombolo ze-float (`"0.00045210"`) |
| Idatha | Ama-byte (u-1 GB = ama-byte angu-1,000,000,000) |
| Izinsuku | I-ISO 8601 nge-UTC (`2026-10-05T14:03:11Z`) |
| Inguqulo | I-`/v1` kuyo yonke indlela |

## Ukuqinisekisa ukungena

Zonke izicelo ngaphandle kwekhathalogi esobala ziqukethe ukhiye we-API: `Authorization: Bearer API_KEY`. Ukhiye uboniswa ugcwele **kanye** lapho uwudala: wugcine njengephasiwedi. Ungawuhoxisa noma nini; izicelo ezenziwa ngawo zibe sezibuyisa `401 unauthorized`.

### Imingcele yezimvume

Nikeza ukhiye ngamunye lokho okudingwa yisikripthi sakho kuphela. Ukhiye ongenayo imvume edingekayo uthola `403 forbidden`.

| Umkhawulo wezimvume | Lokho ekuvumelayo |
| --- | --- |
| `read` | funda konke (i-akhawunti, imali esele, amasevisi, ukusetshenziswa). |
| `proxies` | shintsha izilungiselelo nemininingwane yokungena ye-proxy (amagama, ukuvuselela okuzenzakalelayo, amaphasiwedi amasha), uphathe abasebenzisi abangaphansi nohlu lwe-IP oluvunyelwe, ushintshe amakheli ama-port eselula (kufaka isixhumanisi sokushintsha). |
| `billing` | dala ama-oda nokwengezwa kwemali, ukhokhe ngemali esele. |

Okuhlukile kuphela **yisixhumanisi sokushintsha ikheli leselula**, esenzelwe ukubizwa ngebhukumaka lesiphequluli noma nge-`curl` elula: `GET https://africaproxies.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (ukhiye onemvume ye-`proxies`). Bheka [Ama-port eselula nokushintsha i-IP](/zu/docs/api/mobile/).

*Hlola imali yakho esele*

```bash
curl -s "https://africaproxies.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

## Izicelo nezimpendulo

- **I-JSON iyangena, i-JSON iyaphuma**: thumela `Content-Type: application/json` uma kunomzimba wesicelo.
- **Izinhla** ezingakhula zihlukaniswa ngamakhasi nge-`page` (kusukela ku-1) ne-`perPage` (1–100, okuzenzakalelayo 20), zibuyise `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Izinhla ezimfushane zibuyisa `{ "data": [...] }`.
- **Izihlonzi** ziyizintambo zombhalo okungafanele uhlaziye ukwakheka kwazo, ezinesiqalo sohlobo: `ord_` (i-oda), `top_` (ukwengeza imali), `txn_` (ukushintsha kwemali esele), `res_` (ukubhalisa kwedatha), `mob_` (i-port yeselula), `key_` (ukhiye we-API) no-`ipw_` (irekhodi lohlu lwe-IP oluvunyelwe).
- **Ukuphinda uzame ngokuphepha**: i-`POST /v1/orders` ne-`POST /v1/topups` zamukela isihloko se-`Idempotency-Key` (noma iyiphi intambo ehlukile, igcinwa amahora 24). Ukuphinda usebenzise ukhiye ofanayo kubuyisa impendulo yokuqala kunokuthenga noma ukwengeza imali kabili.
- **Izibonelo** zibonisa ukwakheka kwempendulo ngayinye: izihlonzi, amakheli, amanani nezinsuku kukhombisa izibonelo, izihlonzi zamaphakheji namanani kuyiqiniso.

## Amaphutha

Wonke amaphutha anomzimba ofanayo. I-`code` ayiguquki futhi yenzelwe ikhodi yakho; i-`message` ingumusho wesiNgisi ongashintsha. Amaphutha okuqinisekisa abhala zonke izinkundla ezingavumelekile ku-`fields`. Kungangezwa amakhodi amasha: phatha amakhodi ongawazi njengephutha elijwayelekile.

*422 validation_failed*

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}
```

### Amakhodi esimo

| Isimo | Incazelo |
| --- | --- |
| `422` | `validation_failed`: inkundla eyodwa noma ngaphezulu ayivumelekile. |
| `401` | `unauthorized`: i-token ayikho, ayivumelekile noma iphelelwe isikhathi. |
| `402` | `insufficient_balance`: imali esele ayanele ukukhokhela i-oda. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: ukhiye we-API awunayo imvume edingekayo, noma i-akhawunti imisiwe. |
| `404` | `not_found`: insiza ayikho noma ingeyenye i-akhawunti. |
| `409` | `conflict` (noma ikhodi ecacisa kakhulu): isenzo asikwazi ukwenziwa esimweni samanje. |
| `429` | `rate_limited` noma `rotation_too_soon`. |

## Imikhawulo yezicelo

Yonke impendulo iqukethe `RateLimit-Limit`, `RateLimit-Remaining` no-`RateLimit-Reset`. Uma kudlulwe umkhawulo, i-API iphendula ngo-`429 rate_limited` nesihloko se-`Retry-After` (imizuzwana): linda leso sikhathi, uphinde uzame. I-IP ye-port yeselula ingashintshwa kungabi ngaphezu kokukodwa njalo ngemizuzwana 30 (`429 rotation_too_soon`, no-`Retry-After`).

## Inkomba ye-API

- **[I-akhawunti nemali esele](/zu/docs/api/account/)** — Funda izilungiselelo ze-akhawunti yakho, imali yakho ye-USD ekhokhelwe nalo lonke ushintsho lwemali esele (ukwengeza, ukuthenga, izimbuyiselo).
- **[Ukwengeza imali nge-crypto](/zu/docs/api/top-ups/)** — Engeza imali nge-crypto: thola ikheli lokufaka nenani eliqondile, uthumele lelo nani, ubike inkokhelo njengethunyelwe (i-ID yenkokhelo ayiphoqelekile), ulandele ukwengeza imali kuze kube imali isifakiwe. Imali esele ikhokhela noma yiliphi iphakheji lethu.
- **[Ama-oda](/zu/docs/api/orders/)** — Bhala uhlu lwamaphakheji namanani, uthenge iphakheji ngemali esele (isevisi entsha, idatha eningi noma ukwengeza isikhathi se-port), ufunde ama-oda angaphambili.
- **[Ama-proxy asekhaya nemininingwane yokungena](/zu/docs/api/residential/)** — Phatha ukubhalisa kwedatha (yasekhaya neye-4G/5G enamakheli ashintshayo nge-GB): imininingwane yokungena ye-proxy, abasebenzisi abangaphansi abanemininingwane yabo nomkhawulo wedatha, ukusetshenziswa kwansuku zonke nezindawo ongazikhetha egameni lomsebenzisi le-proxy.
- **[Ama-port eselula nokushintsha i-IP](/zu/docs/api/mobile/)** — Ama-port e-4G/5G abekelwe amakhasimende: shintsha i-IP manje noma ngesikhathi esibekiwe, usebenzise isixhumanisi sokushintsha, ufunde idatha yansuku zonke.
- **[Izikhiye ze-API nohlu lwe-IP oluvunyelwe](/zu/docs/api/api-keys/)** — Dala uphinde uhoxise izikhiye ze-API ezinemingcele yezimvume, uphathe uhlu lwe-IP oluvunyelwe: amakheli omthombo angafika ku-10 avunyelwe ukusebenzisa ama-proxy ngaphandle kwegama lomsebenzisi nephasiwedi.

> **Ukukhokha ngesikripthi** Amaphakheji ahlala ekhokhwa ngemali ye-USD ekhokhelwe ku-akhawunti. Engeza nge-crypto (okungenani $25) nge-POST /v1/topups, bese uthenga nge-POST /v1/orders. Kokubili kungenziwa ngesicelo esisodwa: ukwengeza imali kungafaka i-oda ku-purchase, iphakheji ithengwe lapho imali eyengeziwe isifakiwe.

---

AfricaProxies: AfricaProxies ingumhlinzeki wama-proxy e-IP yasekhaya e-Afrika eseningizimu yeSahara; kukhokhwa nge-crypto ngaphandle kokulayisha umazisi.