help-icon
icon

Public-API-Anleitung

helpDetails-time-icon2026-09-23T15:37:56+08:00

Mit einem persönlichen API-Schlüssel Geräte, Proxys und Apps abfragen sowie Reset, Proxy-Zuordnung und Installation anfordern. Diese Anleitung umfasst sechs Kundenschnittstellen unter https://api.foxphone.com mit /public_api/v1.

Schnittstellen

HTTP/public_api/v1Beschreibung
GET/phonesGeräte abfragen
GET/proxiesProxys abfragen
POST/phones/actions/resetBatch-Reset
POST/proxies/{proxy_id}/bindProxy zuordnen
GET/appsApps und Versionen abfragen
POST/phones/actions/install-appApps im Batch installieren

API-Schlüssel vorbereiten

Öffnen Sie Settings im Profilmenü und API Key im persönlichen Bereich. Pro Konto gilt ein aktiver Schlüssel. Neuerzeugung macht den alten sofort ungültig; der vollständige Wert erscheint einmal. Senden Sie X-API-Key und bei POST Content-Type: application/json. Website-JWT, Cookie, Device-ID, hash und platform sind nicht nötig. Bearer ersetzt den Header nicht.

X-API-Key: <your_api_key>

Schlüssel nur serverseitig in Umgebungsvariablen oder Secret-Manager speichern, nie in Frontend, öffentlichen Repositories oder Clients. Nicht in URL, Body, Logs oder Tickets. Beispiele nutzen API_KEY. Bei Offenlegung sofort ersetzen oder deaktivieren und alle Aufrufer aktualisieren.

export API_KEY="<your_api_key>"

Konventionen und Antworten

Verwenden Sie HTTPS. Erfolg: HTTP 200 mit Daten in data. Fehler: 4xx/5xx und Zeichenfolge reason. Prüfen Sie Status, reason und Einzelergebnisse statt nur message. Fehler-data kann null sein; speichern Sie request_id. Partnerzugänge unter /open_api/v1 sind getrennt.

Ein Schlüssel teilt 60 Aufrufe pro Minute. Fehlende oder nichtpositive page_num/page_size werden 1/20; page_size über 100 ergibt 400. Geräte und Proxys nutzen search, Apps app_name. pod_ids ist ein String-Array mit nach Bereinigung und Deduplizierung 1–100 IDs. Ergebnisse nach pod_id zuordnen, nicht nach Reihenfolge.

pod_id bleibt String. proxy_id, total, Versions-id und version_code sind JSON-Zahlen; große Ganzzahlen verlustfrei lesen, besonders in JavaScript. Nullwerte und leere Zeichenfolgen bleiben erhalten; leere Listen können [] oder null sein.

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 0,
    "phones": []
  },
  "message": "success"
}

Geräte abfragen

Listet eigene Geräte; search sucht Namen oder pod_id. data.phones liefert pod_id, name, online_status, operating_status, proxy_id; data.total zählt. proxy_id=0 bedeutet keine Zuordnung. Eine lokale Zuordnung bestätigt keine abgeschlossene Cloud-Konfiguration.

online_status: 0 startet, 1 läuft, 2 gestoppt, 3 stoppt, 4 startet neu, 5 Streaming, 6 Stream bereit. operating_status: 0 startet, 1 läuft, 2 gestoppt, 3 stoppt, 4 Neustart, 5 Reset; 6 undefiniert. Nicht gleichsetzen.

FeldTyp
pod_idstring
namestring
online_statusinteger
operating_statusinteger
proxy_idnumber
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "phones": [
      {
        "pod_id": "pod-example-001",
        "name": "test-phone",
        "online_status": 1,
        "operating_status": 1,
        "proxy_id": 42
      }
    ]
  },
  "message": "success"
}

Proxys abfragen

Proxys nach Name oder ID suchen. data.proxies enthält proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. Port ist String; keine Zugangsdaten oder Aktualisierungs-URLs. check_status: unchecked, success, failed; Altwerte können leer sein. Frühere erfolgreiche Tests garantieren keine aktuelle Verfügbarkeit.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "proxies": [
      {
        "proxy_id": 42,
        "name": "example-proxy",
        "proxy_type": "socks5",
        "proxy_ip": "203.0.113.42",
        "proxy_port": "1080",
        "check_status": "success"
      }
    ]
  },
  "message": "success"
}

Batch-Reset

Reset löscht Daten: sichern und Ziele prüfen. Nur pod_ids senden. Geräte müssen laufen, bedienbar und kontoeigen sein; gestoppte oder kollidierende Geräte werden abgelehnt. phone_template_mode, auch 0, sowie phone_template_id, auch leer, ergeben 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. Zufälliges Modell, ohne Alternative kein Template. Simulation bleibt, vorheriger Proxy wird nach Verfügbarkeitsprüfung nach Möglichkeit wiederhergestellt. Keine Proxy-Auswahl oder Käufe für ungebundene Geräte.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/reset" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"pod_ids":["pod-example-001"]}'

Proxy zuordnen

Positive proxy_id aus der Liste im Pfad, nur pod_ids im Body. Proxy und Geräte müssen dem Konto gehören; Proxy gültig, nicht abgelaufen und frisch geprüft. Gestoppte Geräte speichern die Konfiguration und bleiben gestoppt; Anwendung beim nächsten Start. Laufende Geräte werden asynchron aktualisiert und können neu starten. Konflikte werden abgelehnt; ungültiger Proxy: 409 / BATCH_PRECHECK_FAILED mit PRECHECK_FAILED im Detail.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies/42/bind" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"pod_ids":["pod-example-001"]}'

Batch-Ergebnisse und Fehler

Nur Reset und Bindung nutzen successful_pod_ids/failed_items. Gesamte Vorprüfung fehlgeschlagen: 409 mit data.failed_items, nicht metadata auf oberster Ebene. Teilannahme ist möglich; angenommene Arbeit ist nicht systemübergreifend rückrollbar. Die Erfolgsliste bedeutet Annahme oder Speicherung, nicht Abschluss, und kann null sein. Nicht den ganzen Batch wiederholen.

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "successful_pod_ids": [
      "pod-example-001"
    ],
    "failed_items": [
      {
        "pod_id": "pod-example-002",
        "code": "PROVIDER_REJECTED",
        "message": "provider rejected the operation"
      }
    ]
  },
  "message": "success"
}
{
  "request_id": "example-request-id",
  "code": 409,
  "data": {
    "failed_items": [
      {
        "pod_id": "pod-example-002",
        "code": "PHONE_NOT_RUNNING",
        "message": "phone is not running"
      }
    ]
  },
  "message": "batch precheck failed",
  "reason": "BATCH_PRECHECK_FAILED"
}
FeldBeschreibung
RESOURCE_NOT_OWNEDRessource gehört nicht zum aktuellen Konto
RESET_IN_PROGRESSTelefon wird gerade zurückgesetzt
OPERATION_IN_PROGRESSEin anderer Vorgang verursacht einen Konflikt
PHONE_NOT_RUNNINGTelefon läuft nicht
RESOURCE_UNAVAILABLERessource fehlt oder ist nicht verfügbar
PRECHECK_FAILEDProxy-Prüfung oder andere Vorprüfung fehlgeschlagen
PROVIDER_REJECTEDCloud-Anbieter hat die Anfrage abgelehnt oder die Übermittlung ist fehlgeschlagen

Apps und Versionen abfragen

source ist Pflicht: official oder user. Filter app_name und optionaler ganzzahliger app_type, übliche Paginierung. Gruppiert nach package_name; total zählt Apps. Pakete aufsteigend, versions nach version_code absteigend. Installation verwendet package_name/version_code, nicht version_id/version_name. Dies ist kein Verzeichnis installierter Geräte-Apps.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/apps?source=official&page_num=1&page_size=20&app_name=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "apps": [
      {
        "app_id": "app-example",
        "app_name": "Example App",
        "package_name": "com.example.app",
        "app_type": 1,
        "icon_url": "",
        "source": "official",
        "versions": [
          {
            "id": 101,
            "version_id": "version-example",
            "version_name": "1.0.0",
            "version_code": 100
          }
        ]
      }
    ]
  },
  "message": "success"
}

Apps im Batch installieren

Nichtleere package_name, positive version_code und gültige pod_ids verwenden; eigene laufende Geräte wählen. source ausdrücklich setzen. Fehlender/leerer Wert sucht zuerst eigene, dann offizielle Apps; feste Quelle hat keinen Fallback. Keine APK-URL. data.items enthält pod_id/job_id nur zur Übermittlung. Kein Ergebnis-Abfrageendpunkt; keine gemeinsame Status-Vorprüfungsantwort wie Reset/Bindung.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/install-app" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"source":"official","package_name":"com.example.app","version_code":100,"pod_ids":["pod-example-001"]}'
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "items": [
      {
        "pod_id": "pod-example-001",
        "job_id": "job-example-001"
      }
    ]
  },
  "message": "success"
}

Fehler und Wiederholungen

400: Parameter korrigieren; 401/403: Schlüssel/Konto prüfen; 409: Konflikt lösen; 429: verzögert wiederholen. Abfragen innerhalb Quote wiederholbar. Keine veröffentlichte Idempotenz für Schreibanfragen: nach Timeout/500 Annahme zuerst prüfen. Fehlende Apps, falsche Versionen oder Übermittlungsfehler können ebenfalls 500 / PUBLIC_API_INTERNAL_ERROR erzeugen; kein Beweis für Nichtausführung.

HTTPreason
400INVALID_ARGUMENT
400PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED
401INVALID_API_KEY
403API_KEY_DISABLED
403USER_ACCOUNT_UNAVAILABLE
409BATCH_PRECHECK_FAILED
429RATE_LIMIT_EXCEEDED
500PUBLIC_API_INTERNAL_ERROR
500PUBLIC_API_AUTH_ERROR

API-Schlüssel schützen

Schlüssel nur serverseitig in Umgebungsvariablen oder Secret-Manager speichern, nie in Frontend, öffentlichen Repositories oder Clients. Nicht in URL, Body, Logs oder Tickets. Beispiele nutzen API_KEY. Bei Offenlegung sofort ersetzen oder deaktivieren und alle Aufrufer aktualisieren.

Validierung und Support

Support benötigt request_id, Pfad, HTTP-Status, reason, Zeitpunkt und bereinigte Parameter, nie den Schlüssel. Erst Lesezugriffe testen, dann autorisierte Testgeräte für Schreibvorgänge verwenden und Ergebnisse vor größeren Batches prüfen.

Verwandte Artikel

Email contact
Cookie notification iconCookie-Hinweis
Diese Website verwendet Cookies, um die Benutzererfahrung zu verbessern. Um mehr über unsere Cookie-Richtlinie zu erfahren oder Ihre Zustimmung zu widerrufen, lesen Sie bitte unsere Datenschutzrichtlinie und Cookie-Richtlinie.