Documentos API

Autenticación

Envíe la clave API de su cuenta en Autorización: Bearer YOUR_API_KEY o como campo de solicitud de clave. Elija un método; el campo de clave funciona con los paneles de revendedor comunes. Guarde las claves en variables de entorno del servidor y rote desde Cuenta.

Todas las acciones usan POST https://smm.africa/api/v3.. Cuerpos admitidos: application/json, application/x-www-form-urlencoded y multipart/form-data con campos de texto únicamente. Las respuestas son JSON. El campo de acción selecciona la operación.

curl --fail-with-body --silent --show-error --max-time 60 \
  -X POST https://smm.africa/api/v3 \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "action=balance"

Todos los saldos, cargos y montos de pedidos en la versión 3 se devuelven en USD para garantizar la compatibilidad.

Errores y reintentos

Verifique el estado HTTP y el campo de error JSON. Los errores de autenticación utilizan HTTP 400; quienes llaman a la API no son redirigidos al inicio de sesión. Registre los errores técnicos de forma privada y muestre a los clientes un mensaje neutral.

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "request_id": "request-123",
  "retryable": false
}

Añadir respuesta de repetición durante 24 horas. Después del vencimiento, la misma clave puede crear otra orden: conciliar primero. REQUEST_IN_PROGRESS permite la misma solicitud/clave después de Reintentar después. IDEMPOTENCY_CONFLICT requiere restaurar la carga útil original. ACTION_OUTCOME_UNCONFIRMED requiere revisión de soporte: nunca cambie las claves para evitarlo. PRICE_LIMIT_EXCEEDED significa que no se realizó ningún débito ni pedido. Registre request_id (también X-Request-Id) para obtener asistencia.

Reintente un pedido sin cobrar dos veces

1. Cree y guarde una clave de idempotencia única para cada pedido lógico antes de enviar la solicitud. Reemplace la clave de ejemplo con su propio valor único.
2. Espere hasta 60 segundos para la solicitud del servidor. Después de 20 segundos, muestre un mensaje de espera al cliente mientras continúa la solicitud al servidor.
3. Si no llega respuesta, reintente la misma carga útil con la misma clave después de un tiempo. No genere una nueva clave. Un reintento completado reproduce la respuesta con X-Idempotent-Replay: true.
4. Una vez que reciba un ID de pedido, guárdelo y use el estado para realizar el seguimiento de ese pedido. Una respuesta en cola significa que se ha aceptado para su procesamiento, no que la entrega se ha completado.

También se admiten los encabezados Idempotency-Key y X-Idempotency-Key. Sin una clave de cliente, aún se puede enviar un pedido, pero reintentar después de un tiempo de espera no permite identificar de forma segura el intento original.

Límites de tarifas

Los límites son específicos de la acción y configurables en la implementación. En HTTP 429, respete Retry-After (segundos). Sin ese encabezado, utilice un retroceso exponencial con fluctuación, por ejemplo, 2, 4, 8 y luego 16 segundos, más un pequeño retraso aleatorio. Limite los reintentos y notifique los fallos persistentes a su operador.

Almacene en caché el catálogo obtenido con POST /api/v3 y action=services. Actualícelo periódicamente y verifique los ID de servicio, las tarifas y las restricciones mínimas/máximas actuales antes de realizar el pedido.

Ciclo de vida del pedido

Envíe action=status con un ID de pedido por solicitud. Como política inicial para el cliente, realice sondeos cada 30 segundos y aumente el intervalo para pedidos de larga duración; respete los límites de velocidad. Distribuya las solicitudes entre los pedidos. Actualmente no se admiten webhooks.

queued → pending → processing

Estados activos: continúe el sondeo. Los pedidos pueden omitir estados intermedios.

completed · partial · refunded · canceled

Estados terminales: detenga el sondeo de entrega rutinario. "Parcial" significa que la entrega fue incompleta; revise el cargo y el saldo restante. Las solicitudes de recarga y cancelación están sujetas a la elegibilidad del servicio y del pedido.

unknown

Estado no reconocido: no lo considere un éxito ni genere un pedido de reemplazo automáticamente. Reintente el estado con retroceso y contacte con soporte si persiste.