Eine eigene Domain einrichten (CNAME)

Was du tun kannst

Eine eigene Domain (CNAME) erlaubt es, ein Flipbook über einen Hostnamen auszuliefern, der dir gehört, etwa docs.example.com. Sobald eine Domain im Web-Dashboard hinzugefügt und verifiziert wurde, lassen dich diese drei Endpunkte die Bindung zwischen dieser Domain und deinen Flipbooks über die API verwalten:

• Hinzufügen einer CNAME-Bindung zu einem Flipbook.
• Auflisten jedes CNAME deines Kontos, mit den Flipbooks, an die er jeweils gebunden ist.
• Löschen einer CNAME-Bindung von einem Flipbook oder von allen auf einmal.

Bevor du loslegst

• Einen API-Schlüssel – wird bei jeder Anfrage als X-Api-Key-Header (oder als Authorization: Bearer YOUR_API_KEY) gesendet.
• Alle Anfragen gehen an die Basis-URL https://go.fliplink.me.
• Add CNAME zielt über das Pfadsegment {flipbookId} auf ein bestimmtes Flipbook – die numerische ID, die von create-by-file / create-by-url oder von list zurückgegeben wird. List und Delete verwenden keinen {flipbookId}-Pfadparameter.
• Der CNAME muss bereits existieren und auf deinem Konto aktiviert sein – über das Web-Dashboard hinzugefügt und verifiziert, das DNS und SSL bereitstellt. Die API speichert nur die Bindung; sie verifiziert kein DNS und stellt keine Zertifikate aus.
• Für Add CNAME ist der Request-Body form-urlencoded (kein JSON).

Einen CNAME zu einem Flipbook hinzufügen

Verknüpft eine bereits aktivierte eigene Domain mit einem Flipbook. Übergib den vollständigen Hostnamen als CNAME. IsCloudflare ist optional und standardmäßig 0; übergib 1, wenn deinem DNS der Proxy von Cloudflare vorgeschaltet ist.

curl -X POST 'https://go.fliplink.me/api/add-cname/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'CNAME=docs.example.com' \
  --data-urlencode 'IsCloudflare=0'

Antwort:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

Wenn die Domain nicht zuvor auf deinem Konto aktiviert wurde, wird die Anfrage abgelehnt mit: Please add CNAME <domain> to your account using the web dashboard. Only activated CNAMEs are allowed to be created via API.

Deine CNAMEs auflisten

Gibt alle eigenen CNAMEs des Aufrufers zurück. Jedes Item meldet den Hostnamen, die Anzahl der aktiven Flipbooks, die an ihn gebunden sind (Documents), und die Liste dieser aktiven Flipbook-IDs (FlipbookIDs).

curl -X GET 'https://go.fliplink.me/api/list-cnames' \
  -H 'X-Api-Key: YOUR_API_KEY'

Antwort:

{
  "Result": "OK",
  "Items": [
    {
      "CNAME": "ttr.antifragile.ae",
      "Documents": 1,
      "FlipbookIDs": [
        93270
      ]
    }
  ]
}

Eine CNAME-Bindung löschen

Entfernt eine Bindung an eine eigene Domain von einem oder allen deiner Flipbooks. Es gibt zwei Modi:

• Bulk (Standard): übergib CNAME=<host> und lass FlipbookID leer – entfernt diesen CNAME von jedem Flipbook, das dir gehört.
• Pro Flipbook: übergib FlipbookID=<id> (größer als 0) – der CNAME wird aus diesem Flipbook nachgeschlagen und nur von diesem einen entfernt.

Übergib den CNAME als Query-Parameter (nicht als URL-Segment), um Probleme mit den Punkten im Hostnamen zu vermeiden.

curl -X DELETE 'https://go.fliplink.me/api/delete-cname?CNAME=docs.example.com&FlipbookID=' \
  -H 'X-Api-Key: YOUR_API_KEY'

Das curl oben läuft im Bulk-Modus (FlipbookID leer gelassen), daher lautet seine Antwort:

{
  "Result": "OK",
  "Message": "CNAME removed successfully"
}

Im Modus pro Flipbook (FlipbookID größer als 0) lautet die Nachricht stattdessen { "Result": "OK", "Message": "CNAME removed from flipbook successfully" }. Wenn du weder CNAME noch FlipbookID übergibst, lautet die Antwort { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Mögliche Fehler

• Fehlender oder ungültiger API-Schlüssel → HTTP 401. Das gibt eine reine Unauthorized-HTML-Seite zurück – es gibt keinen JSON-Body. Prüfe, ob der X-Api-Key-Header vorhanden und korrekt ist.
• Unbekannte flipbookId (oder eine, die nicht zu deinem Schlüssel gehört), bei Add CNAME → HTTP 200 mit { "Result": "ERROR", "Message": "Item not found" }.
• Unbekanntes oder falsch geschriebenes Body-Feld, bei Add CNAME → HTTP 200 mit { "Result": "ERROR", "Message": "Unknown field(s) '…'. Expected: …" }.
• Löschen ohne CNAME und ohne FlipbookID → { "Result": "ERROR", "Message": "CNAME or FlipbookID is required" }.

Hinweise

• Einen CNAME über die API hinzuzufügen speichert nur die Bindung – es verifiziert kein DNS und stellt keine Zertifikate aus. Füge die Domain zuerst im Web-Dashboard hinzu und verifiziere sie.
• Der CNAME muss innerhalb des CNAME-Limits deines Tarifs liegen.