📡 PRO API Reference¶

REST API für manniPhone PRO Backend.

Base URL: https://api.manniphone.app/v1

🔐 Authentication¶

Alle API-Endpunkte (außer /auth/*) erfordern einen JWT Token.

Authorization: Bearer <access_token>

Auth Endpoints¶

POST /auth/register¶

Neuen Account erstellen.

RequestResponse

{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "Max Mustermann"
}

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "Max Mustermann"
  },
  "accessToken": "eyJhbG...",
  "refreshToken": "eyJhbG..."
}

POST /auth/login¶

Einloggen.

RequestResponse

{
  "email": "user@example.com",
  "password": "securePassword123"
}

{
  "success": true,
  "accessToken": "eyJhbG...",
  "refreshToken": "eyJhbG...",
  "expiresIn": 900
}

POST /auth/refresh¶

Access Token erneuern.

RequestResponse

{
  "refreshToken": "eyJhbG..."
}

{
  "accessToken": "eyJhbG...",
  "expiresIn": 900
}

Voice Token¶

POST /token/voice¶

Twilio Access Token für WebRTC generieren.

RequestResponse

curl -X POST https://api.manniphone.app/v1/token/voice \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

{
  "token": "eyJhbG...",
  "identity": "user_abc123",
  "expiresIn": 3600
}

Token Lebensdauer

Der Voice Token ist 1 Stunde gültig. Die App sollte ihn rechtzeitig erneuern.

Calls¶

GET /calls¶

Anrufhistorie abrufen.

Query Parameter

Parameter	Type	Default	Description
`limit`	number	20	Max. Anzahl
`offset`	number	0	Pagination Offset
`from`	date	-	Start-Datum
`to`	date	-	End-Datum

RequestResponse

curl https://api.manniphone.app/v1/calls?limit=10 \
  -H "Authorization: Bearer <token>"

{
  "calls": [
    {
      "id": "call_xyz789",
      "to": "+49170123456",
      "from": "+4915123456789",
      "direction": "outbound",
      "status": "completed",
      "duration": 125,
      "credits_used": 5,
      "started_at": "2026-01-23T14:32:00Z",
      "ended_at": "2026-01-23T14:34:05Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

GET /calls/:id¶

Einzelnen Anruf abrufen.

Response

{
  "id": "call_xyz789",
  "to": "+49170123456",
  "from": "+4915123456789",
  "direction": "outbound",
  "status": "completed",
  "duration": 125,
  "credits_used": 5,
  "started_at": "2026-01-23T14:32:00Z",
  "ended_at": "2026-01-23T14:34:05Z",
  "recording": {
    "id": "rec_abc123",
    "url": "https://...",
    "duration": 125
  }
}

DELETE /calls/:id¶

Anruf aus Historie löschen.

Response

{
  "success": true,
  "message": "Call deleted"
}

Billing¶

GET /billing/credits¶

Aktuelles Guthaben abrufen.

Response

{
  "credits": 450,
  "currency": "EUR",
  "equivalent": 45.00
}

GET /billing/transactions¶

Transaktionshistorie.

Response

{
  "transactions": [
    {
      "id": "txn_123",
      "type": "purchase",
      "amount": 250,
      "description": "Credit Purchase",
      "created_at": "2026-01-20T10:00:00Z"
    },
    {
      "id": "txn_124",
      "type": "usage",
      "amount": -5,
      "description": "Call to +49170123456",
      "call_id": "call_xyz789",
      "created_at": "2026-01-23T14:34:05Z"
    }
  ]
}

POST /billing/checkout¶

Stripe Checkout Session erstellen.

RequestResponse

{
  "product": "credits_250",
  "successUrl": "https://app.manniphone.app/success",
  "cancelUrl": "https://app.manniphone.app/cancel"
}

{
  "checkoutUrl": "https://checkout.stripe.com/..."
}

Produkte

ID	Credits	Preis
`credits_100`	100	10 €
`credits_250`	250	25 €
`credits_500`	550	45 €
`credits_1000`	1200	80 €

GET /billing/subscription¶

Aktives Abo abrufen.

Response

{
  "subscription": {
    "id": "sub_abc123",
    "plan": "pro",
    "status": "active",
    "current_period_end": "2026-02-23T00:00:00Z",
    "cancel_at_period_end": false,
    "minutes_included": 300,
    "minutes_used": 42
  }
}

Recordings¶

GET /recordings¶

Aufnahmen abrufen.

Response

{
  "recordings": [
    {
      "id": "rec_abc123",
      "call_id": "call_xyz789",
      "duration": 125,
      "size_bytes": 1048576,
      "format": "mp3",
      "url": "https://...",
      "created_at": "2026-01-23T14:34:05Z",
      "expires_at": "2026-02-22T14:34:05Z"
    }
  ]
}

GET /recordings/:id/download¶

Aufnahme herunterladen.

Response

Content-Type: audio/mpeg
Content-Disposition: attachment; filename="recording_abc123.mp3"

DELETE /recordings/:id¶

Aufnahme löschen.

Webhooks (Server-to-Server)¶

Diese Endpunkte werden von Twilio aufgerufen.

POST /webhook/voice/outbound¶

TwiML für ausgehende Anrufe.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="+4915123456789">
    <Number>+49170123456</Number>
  </Dial>
</Response>

POST /webhook/call-status¶

Status-Updates für Anrufe.

Status-Werte

Status	Beschreibung
`initiated`	Anruf gestartet
`ringing`	Zieltelefon klingelt
`in-progress`	Verbunden
`completed`	Beendet
`busy`	Besetzt
`no-answer`	Keine Antwort
`failed`	Fehler

Error Responses¶

Format¶

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this call",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

Error Codes¶

Code	HTTP	Description
`UNAUTHORIZED`	401	Token ungültig/fehlt
`FORBIDDEN`	403	Keine Berechtigung
`NOT_FOUND`	404	Ressource nicht gefunden
`INSUFFICIENT_CREDITS`	402	Nicht genug Guthaben
`RATE_LIMITED`	429	Zu viele Anfragen
`INTERNAL_ERROR`	500	Server-Fehler

Rate Limits¶

Endpoint	Limit
`/auth/*`	10 req/min
`/token/*`	30 req/min
`/calls/*`	60 req/min
`/billing/*`	30 req/min

Bei Überschreitung:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

SDKs¶

JavaScript¶

import { ManniPhoneClient } from '@manniphone/sdk';

const client = new ManniPhoneClient({
  accessToken: 'your-access-token'
});

// Anruf starten
await client.calls.create({
  to: '+49170123456'
});

// Guthaben abrufen
const balance = await client.billing.getCredits();

cURL¶

# Alle Anrufe abrufen
curl https://api.manniphone.app/v1/calls \
  -H "Authorization: Bearer <token>"

# Guthaben abrufen
curl https://api.manniphone.app/v1/billing/credits \
  -H "Authorization: Bearer <token>"