Documentation de l'API

Télécharger la doc de l'API (Markdown)

kartesim fournit aux partenaires de vrais numéros de téléphone et des IP mobiles via deux services : la location de numéros et de proxys de longue durée et les sessions OTP à l'usage. Les deux sont disponibles via le protocole HANDLER_API et l'API REST native.

Sessions OTPà l'usage

Demandez un numéro temporaire, attendez un SMS, recevez le code OTP — en un seul cycle d'appels API. Facturé par session, remboursé si vous annulez avant l'arrivée du code.

Location de numérosCartes SIM

Louez un numéro de téléphone dédié à la journée, à la semaine ou au mois. Tous les SMS reçus sur ce numéro sont transférés sur votre compte en temps réel.

Location de proxysIP mobiles

Louez un proxy mobile HTTP/SOCKS5 avec une vraie IP d'opérateur. Chaque proxy fonctionne sur un appareil dédié (Android ou modem 4G) avec une carte SIM active.

Les locations sont mises en place par votre gestionnaire de compte. Contactez-nous pour configurer votre location — une fois active, votre numéro de téléphone et vos identifiants de proxy apparaissent dans le portail partenaire et peuvent être interrogés via l'API. Les sessions OTP sont en libre-service via l'API — aucune configuration requise.

Authentification

Toutes les requêtes API nécessitent votre clé API partenaire. La façon de la transmettre dépend de votre protocole.

Handler API — paramètre de requête

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

API REST native — en-tête HTTP

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

Gardez votre clé API secrète. Votre clé est visible dans le portail partenaire, rubrique API. Utilisez le bouton Régénérer la clé pour la renouveler instantanément.

Référence de la Handler API

URL de base : /api/stubs/handler_api.php — Toutes les requêtes utilisent GET. Toutes les réponses sont en texte brut.

GET/api/stubs/handler_api.php?action=getBalance

Renvoie votre solde prépayé actuel en USD.

Paramètres

Nom	Type	Requis	Description
api_key	string	requis	Votre clé API
action	string	requis	Doit valoir "getBalance"

Réponses

45.00Votre solde en USD

999999Valeur fixe renvoyée pour les comptes à solde illimité — ce n'est pas un vrai solde, et elle ne varie pas avec l'utilisation

BAD_KEYClé API invalide ou révoquée

Exemple de requête

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

Exemple de réponse

45.00

GET/api/stubs/handler_api.php?action=getCountries

Liste les pays pris en charge avec leurs codes numériques.

Paramètres

Nom	Type	Requis	Description
api_key	string	requis	Votre clé API
action	string	requis	Doit valoir "getCountries"

Réponses

JSON array[{ "id": 7, "name": "Russia" }, ...]

Exemple de requête

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

Exemple de réponse

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

Obtenez les tarifs actuels et le stock actif disponible par pays et par service.

Paramètres

Nom	Type	Requis	Description
api_key	string	requis	Votre clé API
action	string	requis	Doit valoir "getPrices"
country	number	facultatif	Filtrer par identifiant numérique de pays
hide_empty	integer	facultatif	Mettez 1 pour exclure de la réponse les pays sans stock

Réponses

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

Exemple de requête

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

Exemple de réponse

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

Demande un numéro de téléphone temporaire pour une vérification OTP. Renvoie un identifiant de session et le numéro attribué. La session expire au bout de 10 minutes si aucun SMS n'arrive.

Paramètres

Nom	Type	Requis	Description
api_key	string	requis	Votre clé API
action	string	requis	Doit valoir "getNumber"
service	string	facultatif	Nom du service (par ex. "telegram", "whatsapp") — à titre indicatif uniquement
country	integer	facultatif	Indicatif téléphonique du pays (par ex. 212 pour le Maroc). Omettez-le ou utilisez 0 pour n'importe quel pays.

Réponses

ACCESS_NUMBER:id:numberSession créée — id sert pour getStatus/setStatus, number est le numéro de téléphone attribué

NO_NUMBERSAucun port en ligne ne correspond à votre demande

NO_BALANCESolde insuffisant pour couvrir les frais OTP

Exemple de requête

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

Exemple de réponse

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

Interrogez une session active pour obtenir le code OTP. Interrogez toutes les 5 à 10 secondes jusqu'à recevoir STATUS_OK ou STATUS_CANCEL.

Paramètres

Nom	Type	Requis	Description
api_key	string	requis	Votre clé API
action	string	requis	Doit valoir "getStatus"
id	string	requis	Identifiant de session issu de la réponse ACCESS_NUMBER

Réponses

STATUS_WAIT_CODELa session est active — SMS pas encore reçu. Continuez d'interroger.

STATUS_OK:84729OTP reçu — le code suit les deux-points

STATUS_CANCELLa session a expiré ou a été annulée

Exemple de requête

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

Exemple de réponse

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

Confirmez la réception de l'OTP (status=1) ou annulez la session pour un remboursement intégral (status=8). Seules les sessions PENDING peuvent être annulées.

Paramètres

Nom	Type	Requis	Description
api_key	string	requis	Votre clé API
action	string	requis	Doit valoir "setStatus"
id	string	requis	Identifiant de la session concernée
status	integer	requis	1 = confirmer la réception, 8 = annuler et rembourser

Réponses

ACCESS_READYConfirmé — session prise en compte

ACCESS_CANCELAnnulé — solde remboursé

BAD_ACTIONSession introuvable ou déjà terminée

Exemple de requête

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

Exemple de réponse

ACCESS_CANCEL

API REST native

Pour les intégrations modernes, utilisez notre API REST native plutôt que l'ancienne Handler API. Transmettez votre clé API dans l'en-tête HTTP x-api-key.

Sessions OTP

à l'usage

Les sessions OTP vous permettent de demander un numéro de téléphone temporaire, de recevoir un code à usage unique et de libérer le numéro — entièrement via l'API. Chaque session est facturée une seule fois, à sa création. Si vous annulez avant l'arrivée du code, les frais sont intégralement remboursés.

POST/api/v1/otp/request

Demande un numéro de téléphone temporaire pour une vérification OTP. Renvoie un sessionId et le numéro attribué. Les frais OTP_PER_USE sont prélevés immédiatement.

Paramètres

Nom	Type	Requis	Description
country	integer	facultatif	Indicatif téléphonique du pays pour filtrer (par ex. 212). Omettez-le pour n'importe quel pays.
service	string	facultatif	Nom du service, par ex. "telegram" — enregistré sur la session pour votre information
webhookUrl	string	facultatif	URL HTTPS appelée en POST à l'arrivée de l'OTP (au lieu d'interroger)
expiresIn	integer	facultatif	Durée de vie de la session en secondes (60–1800, 600 par défaut)

Réponses

200 OKSession créée — le corps contient sessionId, number et expiresAt

402 Payment RequiredSolde insuffisant

503 Service UnavailableAucun numéro en ligne disponible

Exemple de requête

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

Exemple de réponse

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

Interrogez le statut et le code d'une session OTP. Renvoie le code OTP extrait dès l'arrivée du SMS. Interrogez toutes les 5 à 10 secondes.

Réponses

200 OK — PENDINGstatus: "PENDING", otp: null — toujours en attente

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — code prêt

200 OK — EXPIREDstatus: "EXPIRED" — aucun SMS dans le délai imparti

200 OK — CANCELLEDstatus: "CANCELLED" — vous avez annulé la session

Exemple de requête

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

Exemple de réponse

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

Annule une session PENDING. Rembourse intégralement les frais OTP. Les sessions ayant déjà reçu un OTP ne peuvent pas être annulées.

Réponses

200 OKstatus: "CANCELLED", refunded: 0.10 — solde crédité

409 ConflictLa session n'est pas à l'état PENDING — annulation impossible

404 Not FoundSession introuvable ou appartenant à un autre compte

Exemple de requête

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

Exemple de réponse

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTVotre URL de webhook (push serveur)

À l'arrivée d'un OTP, nous envoyons un POST au webhookUrl fourni lors de la création de la session. C'est une alternative à l'interrogation : votre serveur reçoit l'OTP automatiquement, sans avoir à appeler getStatus.

Contenu

POST vers votre webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

Sécurité

En production, votre URL de webhook doit être en HTTPS — les URL HTTP sont refusées.
Nous envoyons un en-tête X-Webhook-Signature: sha256=... (HMAC-SHA256). Vérifiez-le pour confirmer que la requête est authentique.
En cas de 5xx, nous réessayons une fois après 2 secondes. Votre endpoint doit renvoyer 200 rapidement.
Votre endpoint doit être idempotent — une double livraison est possible lors d'un nouvel essai.

GET/api/partner/rentals

Récupère toutes les locations de numéros actives de votre compte.

Réponses

200 OKTableau JSON des locations de numéros actives

401 UnauthorizedClé API invalide ou manquante

Exemple de requête

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Exemple de réponse

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/proxies

Récupère toutes les locations de proxys actives de votre compte, avec leur adresse IP actuelle et leurs identifiants.

Réponses

200 OKTableau JSON des locations de proxys actives

401 UnauthorizedClé API invalide ou manquante

Exemple de requête

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/proxies

Exemple de réponse

[
  {
    "id": "cuid...",
    "port": "Port A",
    "host": "192.168.1.10",
    "socks5Port": 1080,
    "username": "user",
    "password": "pwd",
    "expiresAt": "2026-06-25T10:00:00.000Z"
  }
]

GET/api/partner/sms?simNumber=1234567890

Récupère les derniers SMS reçus par vos numéros loués. Filtre facultatif sur un simNumber précis.

Paramètres

Nom	Type	Requis	Description
simNumber	string	facultatif	Filtrer les SMS d'un numéro loué précis

Réponses

200 OKTableau JSON des SMS récents

401 UnauthorizedClé API invalide ou manquante

Exemple de requête

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

Exemple de réponse

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

Location de numéros

La location de numéros vous donne l'usage exclusif d'une vraie carte SIM pendant une durée de location fixe. Chaque SMS reçu sur ce numéro est livré sur votre compte en temps réel. Vous pouvez louer des numéros directement via l'API ou le portail partenaire.

Période	Durée	Description
Journalière	24 heures	Idéal pour les campagnes de vérification de courte durée
Hebdomadaire	7 jours	Idéal pour un accès continu à un numéro stable
Mensuelle	30 jours	Idéal pour un numéro dédié sur le long terme

Fonctionnement

Appelez GET /api/v1/numbers/available pour parcourir les numéros disponibles (masqués).
Choisissez un numéro et un cycle de facturation, puis appelez POST /api/v1/numbers/rent pour le louer instantanément.
Votre solde est débité immédiatement. Le numéro de téléphone complet, non masqué, est renvoyé dans la réponse.
Tous les SMS reçus sur votre numéro loué apparaissent dans Journaux SMS en temps réel.
À l'expiration, le numéro est libéré automatiquement. Aucun remboursement n'est accordé pour le temps non utilisé.

GET/api/v1/numbers/available

Parcourez les numéros disponibles à la location. Les numéros sont masqués (par ex. +212 6** *** **7) pour que vous puissiez voir le pays et l'opérateur avant de vous engager. Filtre facultatif par indicatif pays.

Paramètres

Nom	Type	Requis	Description
country	number	facultatif	Indicatif pays UIT (par ex. 212). Omettez-le ou utilisez 0 pour n'importe quel pays.

Réponses

200 OKJSON avec la liste des numéros disponibles et leur nombre total

401 UnauthorizedClé API invalide ou manquante

429 Too Many RequestsLimite de débit dépassée (30 requêtes/min)

Exemple de requête

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

Exemple de réponse

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

Louez un numéro vous-même. Débite votre solde et crée une location exclusive en une seule opération atomique. Renvoie le numéro de téléphone complet (non masqué) en cas de succès.

Paramètres

Nom	Type	Requis	Description
phoneId	string	requis	Identifiant du port issu de /api/v1/numbers/available
billingCycle	string	requis	DAILY \| WEEKLY \| MONTHLY
cycles	number	facultatif	Nombre de cycles de facturation à payer d'avance (1–12, 1 par défaut)
autoRenew	boolean	facultatif	Renouvellement automatique à l'expiration (false par défaut)

Réponses

200 OKLocation créée — numéro de téléphone complet dans la réponse

402 Payment RequiredSolde insuffisant ou aucun tarif configuré pour ce cycle

409 ConflictLe numéro vient d'être loué par un autre partenaire — réessayez avec un autre numéro

401 UnauthorizedClé API invalide ou manquante

Exemple de requête

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

Exemple de réponse

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

Récupère toutes les locations de numéros actives de votre compte.

Réponses

200 OKTableau JSON des locations de numéros actives

401 UnauthorizedClé API invalide ou manquante

Exemple de requête

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

Exemple de réponse

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

Les numéros sont dédiés à votre compte. Le numéro n'est jamais partagé ni réattribué pendant votre période de location. Le solde nécessaire pour toute la période est prélevé au moment de la location. Si un numéro demandé est pris entre la consultation et la location, vous recevrez une erreur 409 — réessayez avec un autre numéro.

Location de proxys

Chaque port du parc expose un proxy HTTP et SOCKS5 sur sa connexion de données mobiles. Les partenaires peuvent faire transiter leur trafic par ces proxys pour obtenir une vraie IP mobile d'un pays donné.

Protocole	Port par défaut	Remarques
HTTP	propre à l'appareil	Proxy HTTP CONNECT — port affiché dans le portail partenaire et dans `/api/partner/proxies`
SOCKS5	1080	Proxy SOCKS5 — prend en charge le tunneling TCP et UDP

Proxy HTTP — curl

curl --proxy http://USER:PASS@PHONE_IP:8888 https://api.ipify.org

Proxy SOCKS5 — curl

curl --proxy socks5://USER:PASS@PHONE_IP:1080 https://api.ipify.org

Les identifiants et l'IP du proxy sont fournis par votre gestionnaire de compte. L'IP du port se met à jour automatiquement à chaque heartbeat — le portail partenaire affiche toujours la dernière IP. L'accès au proxy nécessite une authentification — les connexions non authentifiées sont refusées.

Consulter vos proxys actifs

Vos abonnements proxy actifs — avec l'IP actuelle, le port et la date d'expiration — sont visibles dans le portail partenaire, rubrique Proxys. Le champ IP est mis à jour en direct dès que le port communique son adresse.

Pays pris en charge

Utilisez getCountries pour obtenir la liste à jour. Indicatifs courants :

Code	Pays	Code	Pays
0	N'importe lequel (attribution automatique)	7	Russia
212	Maroc	33	France
1	États-Unis	44	Royaume-Uni
49	Allemagne	34	Espagne
966	Arabie saoudite	971	Émirats arabes unis
20	Égypte	216	Tunisie

Référence des erreurs

Réponse	Signification
BAD_KEY	Clé API invalide, révoquée ou manquante
BAD_ACTION	Action inconnue ou paramètres obligatoires manquants
TOO_MANY_REQUESTS	Limite de débit dépassée — 120 requêtes par minute
NO_NUMBERS	Aucun port en ligne ne correspond à votre demande OTP
NO_BALANCE	Solde insuffisant pour créer une session OTP
STATUS_WAIT_CODE	OTP pas encore reçu — continuez d'interroger
STATUS_OK:code	OTP reçu — le code chiffré suit les deux-points
STATUS_CANCEL	La session a expiré ou a été annulée
ACCESS_NUMBER:id:num	Session OTP créée — suivent l'identifiant de session et le numéro de téléphone
ACCESS_CANCEL	Session annulée, solde remboursé
ACCESS_READY	Session prise en compte / confirmée

Documentation partenaire kartesim — Pour toute demande de clé API ou de location, contactez votre gestionnaire de compte.