# Nyaraka za API za AfricaProxies

> REST API ya AfricaProxies katika africaproxies.com/api: funguo za API, hitilafu, vikomo na vituo vya salio, crypto, maagizo, proxy na kubadili IP ya simu.

- URL: https://africaproxies.com/sw/docs/api/
- Iliyoruushwa mwisho: 2026-10-15
- Mchapishi: AfricaProxies (https://africaproxies.com)

Kila unachofanya kwenye akaunti kinaweza kuendeshwa kwa programu: kagua salio, ongeza kwa crypto, nunua mpango, unda vitambulisho vya proxy na ubadilishe IP ya simu. JSON kupitia HTTPS, ufunguo mmoja wa API, mifano ya curl, Python na Node.js.

**Jibu la haraka — Ninatumiaje API ya AfricaProxies?**

Tuma maombi ya HTTPS kwa `https://africaproxies.com/api/v1` ukiweka ufunguo wako wa API kwenye kichwa `Authorization: Bearer API_KEY`. Unda ufunguo kwenye [ukurasa wa wasanidi](/app/developer?lang=sw) wa akaunti (au kwa `POST /v1/api-keys`), na uupe ruhusa zinazohitajika tu. Maombi na majibu ni JSON; hitilafu daima hurudi kama `{ "error": { "code", "message" } }`.

## Kwa ufupi

| Sifa | Thamani |
| --- | --- |
| URL ya msingi | `https://africaproxies.com/api/v1` |
| Muundo | JSON kupitia HTTPS, UTF-8 |
| Uthibitishaji | Ufunguo wa API: `Authorization: Bearer API_KEY` |
| Wigo wa ruhusa za ufunguo wa API | `read`, `proxies`, `billing` |
| Fedha | USD kama maandishi yenye nafasi 2 za desimali (`"29.00"`) |
| Kiasi cha crypto | Maandishi ya desimali, si namba za float kamwe (`"0.00045210"`) |
| Data | Baiti (1 GB = baiti 1,000,000,000) |
| Tarehe | ISO 8601 katika UTC (`2026-10-05T14:03:11Z`) |
| Toleo | `/v1` kwenye kila njia |

## Uthibitishaji

Kila ombi isipokuwa katalogi ya umma lina ufunguo wa API: `Authorization: Bearer API_KEY`. Ufunguo unaonyeshwa kamili **mara moja** unapouunda: uhifadhi kama nenosiri. Unaweza kuubatilisha wakati wowote; maombi yanayoutumia kisha hurudisha `401 unauthorized`.

### Wigo wa ruhusa

Pea kila ufunguo ruhusa zinazohitajika na programu yako tu. Ufunguo usio na ruhusa inayohitajika hupata `403 forbidden`.

| Wigo wa ruhusa | Inachoruhusu |
| --- | --- |
| `read` | soma vyote (akaunti, salio, huduma, matumizi). |
| `proxies` | badilisha mipangilio na vitambulisho vya proxy (majina, kujiongeza muda kiotomatiki, nywila mpya), dhibiti watumiaji wadogo na orodha ya IP zinazoruhusiwa, na ubadilishe anwani za porti za simu (pamoja na kiungo cha kubadilisha). |
| `billing` | unda maagizo na nyongeza za salio, lipa kwa salio. |

Isipokuwa pekee ni **kiungo cha kubadilisha anwani ya simu**, kilichoundwa kuitwa kwa alamisho la kivinjari au `curl` ya kawaida: `GET https://africaproxies.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (ufunguo wenye ruhusa ya `proxies`). Angalia [Porti za simu na kubadilisha IP](/sw/docs/api/mobile/).

*Kagua salio lako*

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

## Maombi na majibu

- **JSON ndani, JSON nje**: tuma `Content-Type: application/json` ukiwa na mwili wa ombi.
- **Orodha** zinazoweza kukua zinagawanywa kwa kurasa kwa `page` (kuanzia 1) na `perPage` (1–100, chaguo-msingi 20), na zinarudisha `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Orodha fupi zinarudisha `{ "data": [...] }`.
- **Vitambulisho** ni maandishi yasiyopaswa kuchanganuliwa, yenye kiambishi cha aina: `ord_` (agizo), `top_` (nyongeza ya salio), `txn_` (mabadiliko ya salio), `res_` (usajili wa data), `mob_` (porti ya simu), `key_` (ufunguo wa API) na `ipw_` (ingizo la orodha ya IP zinazoruhusiwa).
- **Kurudia salama**: `POST /v1/orders` na `POST /v1/topups` zinakubali kichwa cha `Idempotency-Key` (maandishi yoyote ya kipekee, yanahifadhiwa saa 24). Kutuma ufunguo uleule kunarudisha jibu la kwanza badala ya kununua au kuongeza salio mara mbili.
- **Mifano** inaonyesha muundo wa kila jibu: vitambulisho, anwani, kiasi na tarehe ni vya mfano; vitambulisho vya mipango na bei ni halisi.

## Hitilafu

Kila hitilafu ina mwili uleule. `code` haibadiliki na inalenga msimbo wako; `message` ni sentensi ya Kiingereza inayoweza kubadilika. Hitilafu za uthibitishaji zinaorodhesha kila sehemu isiyo sahihi katika `fields`. Misimbo mipya inaweza kuongezwa: shughulikia isiyojulikana kama hitilafu ya jumla.

*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"
  }
}
```

### Misimbo ya hali

| Hali | Maana |
| --- | --- |
| `422` | `validation_failed`: sehemu moja au zaidi si sahihi. |
| `401` | `unauthorized`: token haipo, si sahihi au imeisha muda. |
| `402` | `insufficient_balance`: salio halitoshi kulipia agizo. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: ufunguo wa API hauna ruhusa inayohitajika, au akaunti imesimamishwa. |
| `404` | `not_found`: rasilimali haipo au ni ya akaunti nyingine. |
| `409` | `conflict` (au msimbo maalumu zaidi): hatua haiwezekani katika hali ya sasa. |
| `429` | `rate_limited` au `rotation_too_soon`. |

## Vikomo vya maombi

Kila jibu lina `RateLimit-Limit`, `RateLimit-Remaining` na `RateLimit-Reset`. Kikomo kikizidiwa, API inarudisha `429 rate_limited` na kichwa cha `Retry-After` (sekunde): subiri muda huo, kisha ujaribu tena. IP ya porti ya simu inaweza kubadilishwa si zaidi ya mara moja kila sekunde 30 (`429 rotation_too_soon`, pamoja na `Retry-After`).

## Rejea ya API

- **[Akaunti na salio](/sw/docs/api/account/)** — Soma mipangilio ya akaunti, salio lako la USD la kulipia kabla na kila mabadiliko ya salio (nyongeza, manunuzi, marejesho).
- **[Nyongeza za salio kwa crypto](/sw/docs/api/top-ups/)** — Ongeza salio kwa crypto: pata anwani ya kupokea na kiasi halisi, tuma kiasi hicho kamili, ripoti malipo kuwa yametumwa (ID ya muamala si lazima), kisha fuatilia nyongeza hadi salio liwekwe. Salio linalipia mpango wetu wowote.
- **[Maagizo](/sw/docs/api/orders/)** — Orodhesha mipango na bei, nunua mpango kwa salio (huduma mpya, data zaidi au kuongeza muda wa porti) na usome maagizo ya zamani.
- **[Proxy za makazi na vitambulisho](/sw/docs/api/residential/)** — Dhibiti usajili wa data (za makazi na za 4G/5G zenye anwani zinazobadilika kwa GB): vitambulisho vya proxy, watumiaji wadogo wenye vitambulisho na kikomo chao cha data, matumizi ya kila siku na maeneo unayoweza kuchagua kwenye jina la mtumiaji la proxy.
- **[Porti za simu na kubadilisha IP](/sw/docs/api/mobile/)** — Porti maalumu za 4G/5G: badilisha IP sasa au kwa muda uliowekwa, tumia kiungo cha kubadilisha na usome data za siku.
- **[Funguo za API na orodha ya IP zinazoruhusiwa](/sw/docs/api/api-keys/)** — Unda na ubatilishe funguo za API zenye wigo mdogo wa ruhusa, na udhibiti orodha ya IP zinazoruhusiwa: anwani chanzo zisizozidi 10 zinaweza kutumia proxy bila jina la mtumiaji na nenosiri.

> **Kulipa kwa hati ya programu** Mipango daima inalipwa kutoka salio la USD la kulipia kabla. Ongeza kwa crypto (angalau US$ 25) kwa POST /v1/topups, kisha nunua kwa POST /v1/orders. Vyote vinaweza kuwa katika ombi moja: nyongeza inaweza kuwa na agizo katika purchase, na mpango unanunuliwa mara salio linapoongezwa.

---

AfricaProxies: AfricaProxies ni mtoa huduma za proxy za IP za nyumbani kwa Afrika kusini mwa Sahara, zinazolipiwa kwa kripto bila kupakia kitambulisho.