# Takardun API na AfricaProxies

> AfricaProxies REST API a africaproxies.com/api: maɓallan API, kurakurai, iyaka, saura, cika crypto, oda, proxy da sauya IP na mobile.

- URL: https://africaproxies.com/ha/docs/api/
- An sabunta ƙarshe: 2026-10-15
- Mai wallafa: AfricaProxies (https://africaproxies.com)

Za ka iya rubuta script don duk abin da kake yi a asusunka: duba saura, cika da crypto, sayi tsari, ƙirƙiri bayanan shiga proxy, sauya IP na mobile. JSON ta HTTPS, maɓallin API ɗaya, misalai a curl, Python da Node.js.

**Amsar gaggawa — Ta yaya zan yi amfani da API na AfricaProxies?**

Aika buƙatun HTTPS zuwa `https://africaproxies.com/api/v1` da maɓallinka na API a taken `Authorization: Bearer API_KEY`. Ƙirƙiri maɓallin a [shafin masu haɓakawa](/app/developer?lang=ha) na asusunka (ko da `POST /v1/api-keys`), ka ba shi izinin da yake buƙata kawai. Buƙatu da amsoshi JSON ne; kurakurai koyaushe suna dawowa a matsayin `{ "error": { "code", "message" } }`.

## A taƙaice

| Siffa | Daraja |
| --- | --- |
| URL na asali | `https://africaproxies.com/api/v1` |
| Tsari | JSON ta HTTPS, UTF-8 |
| Tabbatar da shiga | Maɓallin API: `Authorization: Bearer API_KEY` |
| Iyakokin izinin maɓallin API | `read`, `proxies`, `billing` |
| Kuɗi | USD a igiyar rubutu mai wuraren goma 2 (`"29.00"`) |
| Adadin crypto | Igiyoyin rubutun adadi mai digo, ba floats ba (`"0.00045210"`) |
| Traffic | Bytes (1 GB = 1,000,000,000 bytes) |
| Kwanaki | ISO 8601 cikin UTC (`2026-10-05T14:03:11Z`) |
| Siga | `/v1` a kowace hanya |

## Tabbatar da shiga

Kowace buƙata banda kundin jama'a tana ɗauke da maɓallin API: `Authorization: Bearer API_KEY`. Ana nuna maɓalli cikakke **sau ɗaya**, lokacin ƙirƙirarsa: adana shi kamar kalmar sirri. Soke maɓalli a kowane lokaci; buƙatun da aka yi da shi daga nan suna mayar da `401 unauthorized`.

### Iyakokin izini

Ka ba kowane maɓalli abin da script ɗinka yake buƙata kawai. Maɓallin da ba shi da izinin da ake buƙata yana samun `403 forbidden`.

| Iyakacin izini | Abin da yake ba da dama |
| --- | --- |
| `read` | karanta komai (asusu, saura, ayyuka, amfani). |
| `proxies` | sauya saitunan proxy da bayanan shiga (lakabi, sabuntawa ta atomatik, sabbin kalmomin sirri), sarrafa ƙananan masu amfani, jerin IP da aka amince da su, da sauya toshin mobile (har da hanyar sauyawa). |
| `billing` | ƙirƙiri oda da cika asusu, biya daga saura. |

Banda haka sai **hanyar sauya mobile**, da aka yi don kiranta daga alamar shafin browser ko `curl` kawai: `GET https://africaproxies.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (maɓalli mai izinin `proxies`). Duba [Toshin mobile da sauya IP](/ha/docs/api/mobile/).

*Duba sauran kuɗinka*

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

## Buƙatu da amsoshi

- **JSON shiga, JSON fita**: aika `Content-Type: application/json` tare da jiki.
- **Jerin bayanai** masu iya ƙaruwa ana raba su shafuka da `page` (daga 1) da `perPage` (1–100, tsohon saiti 20), suna mayar da `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Gajerun jerin suna mayar da `{ "data": [...] }`.
- **Alamomin ganewa** igiyoyin rubutu ne marasa ma'anar da za a fassara, masu farkon alamar nau'i: `ord_` (oda), `top_` (cika asusu), `txn_` (motsin kuɗin asusu), `res_` (biyan traffic), `mob_` (toshin mobile), `key_` (maɓallin API) da `ipw_` (shigar jerin IP da aka amince da su).
- **Sake gwadawa cikin aminci**: `POST /v1/orders` da `POST /v1/topups` suna karɓar taken `Idempotency-Key` (kowace igiyar rubutu ta musamman, ana riƙe ta 24 h). Sake amfani da maɓallin ɗaya yana mayar da amsar farko maimakon sake saye ko cika asusu sau biyu.
- **Misalai** suna nuna tsarin kowace amsa: alamomin ganewa, adiresoshi, adadi da kwanakin cikinsu na misali ne; alamomin tsare-tsare da farashinsu na gaskiya ne.

## Kurakurai

Kowane kuskure yana da jiki iri ɗaya. `code` tabbatacce ne don shirinka; `message` jimlar Turanci ce mai iya sauyawa. Kurakuran tabbatarwa suna jera kowane filin da bai inganta ba a `fields`. Ana iya ƙara sabbin lambobin kuskure: ɗauki wanda ba a sani ba a matsayin gazawa gaba ɗaya.

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

### Lambobin matsayi

| Matsayi | Ma'ana |
| --- | --- |
| `422` | `validation_failed`: filaye ɗaya ko fiye ba su inganta ba. |
| `401` | `unauthorized`: token ya ɓace, bai inganta ba ko ya ƙare. |
| `402` | `insufficient_balance`: saura bai kai kuɗin oda ba. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: maɓallin API ba shi da izinin da ake buƙata, ko an dakatar da asusun. |
| `404` | `not_found`: albarkatun ba su wanzu ko na wani asusun ne. |
| `409` | `conflict` (ko takamaiman lambar kuskure): ba za a iya yin aikin a halin yanzu ba. |
| `429` | `rate_limited` ko `rotation_too_soon`. |

## Iyakokin yawan kira

Kowace amsa tana ɗauke da `RateLimit-Limit`, `RateLimit-Remaining` da `RateLimit-Reset`. Idan an wuce iyaka, API yana amsa `429 rate_limited` tare da taken `Retry-After` (daƙiƙa): jira wannan lokacin, sannan sake gwadawa. Ana iya sauya IP na toshin mobile aƙalla tazarar daƙiƙa 30 (`429 rotation_too_soon`, tare da `Retry-After`).

## Bayanin API

- **[Asusu da saura](/ha/docs/api/account/)** — Karanta saitunan asusunka, saura na USD da aka riga aka biya da kowane motsin sauran (cika asusu, saye, kuɗin da aka maido).
- **[Cika asusu da crypto](/ha/docs/api/top-ups/)** — Cika saura da crypto: karɓi adireshin ajiya da adadi daidai, aika wannan adadin, sanar cewa an aika kuɗi (ID na ciniki zaɓi ne), sannan bibiyi cika asusun har sai an ƙara kuɗin. Ana biyan kowane tsarinmu daga wannan saura.
- **[Oda](/ha/docs/api/orders/)** — Jera tsare-tsare da farashinsu, sayi tsari daga saura (sabon aiki, ƙarin traffic ko tsawaita toshi), ka karanta odarka ta baya.
- **[Proxy na gida da bayanan shiga](/ha/docs/api/residential/)** — Sarrafa biyan traffic (na gida da 4G/5G mai sauyawa bisa GB): bayanan shiga proxy, ƙananan masu amfani masu bayanan shiga da iyakar traffic nasu, amfani na rana da wuraren da za ka zaɓa a sunan mai amfani na proxy.
- **[Toshin mobile da sauya IP](/ha/docs/api/mobile/)** — Keɓaɓɓen toshin 4G/5G: sauya IP yanzu ko da agogo, yi amfani da hanyar sauyawa, ka karanta traffic na rana.
- **[Maɓallan API da jerin IP da aka amince da su](/ha/docs/api/api-keys/)** — Ƙirƙira da soke maɓallan API masu iyakacin izini, ka sarrafa jerin IP da aka amince da su: har adiresoshin tushe 10 za su iya amfani da proxy ba tare da sunan mai amfani da kalmar sirri ba.

> **Biya daga script** Koyaushe ana biyan tsare-tsare daga saura na USD da aka riga aka biya. Cika da crypto (mafi ƙaranci $ 25) ta POST /v1/topups, sannan saya da POST /v1/orders. Ana iya yin duka a kira ɗaya: cika asusu na iya ɗauke da odar a purchase, kuma ana sayen tsarin da zarar an ƙara kuɗin cika asusun.

---

AfricaProxies: AfricaProxies mai samar da proxy na IP na gida ne ga Afirka kudu da Sahara; ana biya da kirifto ba tare da loda katin shaida ba.