Schnellstart

Diese Anleitung führt Sie in 5 Minuten durch die Integration der CheckYout Partner API. Am Ende empfangen Sie Checkout-Events und können WhatsApp-Benachrichtigungen auslösen.

1. API-Key generieren

Erstellen Sie im CheckYout-Dashboard unter Einstellungen → API-Keys einen neuen API-Key. Der Key wird im Format cyo_xxxxxxxxxxxx angezeigt.

Wichtig

Der API-Key wird nur einmal im Klartext angezeigt. Speichern Sie ihn sofort in einer sicheren Umgebungsvariable.

2. Webhook-URL hinterlegen

Hinterlegen Sie beim Erstellen des API-Keys (oder nachträglich via API) die URL Ihres Webhook-Endpoints. CheckYout sendet bei jedem Gast-Checkout ein POST-Request an diese URL.

Optional können Sie ein Webhook-Secret setzen. Damit signiert CheckYout jedes Event per HMAC-SHA256. Details dazu finden Sie unter Authentifizierung.

3. Webhook-Endpoint bauen

Erstellen Sie in Ihrer Software einen HTTP-Endpoint, der POST-Requests von CheckYout entgegennimmt:

// Express.js — Webhook empfangen
app.post('/webhooks/checkyout', (req, res) => {
  const event = req.body;

  console.log('Checkout-Event empfangen:', event);
  // { event: "checkout", device_id: "...", property_name: "...", ... }

  // Hier Ihre Logik: Reinigungsauftrag erstellen, etc.

  res.status(200).json({ received: true });
});

4. Notify API aufrufen

Nachdem Sie den Checkout verarbeitet haben, können Sie über die Notify API eine WhatsApp-Nachricht an die zuständige Reinigungskraft senden:

curl -X POST https://checkyout.app/api/v1/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cyo_IhrApiKey" \
  -d '{
    "device_id": "ihre-device-uuid",
    "phone": "+41791234567",
    "name": "Ferienwohnung Alpenblick"
  }'

const response = await fetch('https://checkyout.app/api/v1/notify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CHECKYOUT_API_KEY,
  },
  body: JSON.stringify({
    device_id: 'ihre-device-uuid',
    phone: '+41791234567',
    name: 'Ferienwohnung Alpenblick',
  }),
});

const data = await response.json();
console.log(data); // { success: true, message_sid: "SM..." }

import requests

response = requests.post(
    "https://checkyout.app/api/v1/notify",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": CHECKYOUT_API_KEY,
    },
    json={
        "device_id": "ihre-device-uuid",
        "phone": "+41791234567",
        "name": "Ferienwohnung Alpenblick",
    },
)

print(response.json())  # {"success": True, "message_sid": "SM..."}

$ch = curl_init('https://checkyout.app/api/v1/notify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('CHECKYOUT_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'device_id' => 'ihre-device-uuid',
        'phone' => '+41791234567',
        'name' => 'Ferienwohnung Alpenblick',
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response; // {"success":true,"message_sid":"SM..."}

5. Testen

Testen Sie Ihre Integration, indem Sie im CheckYout-Dashboard einen Test-Checkout auslösen. Ihr Webhook-Endpoint sollte das Event empfangen und verarbeiten.

Tipp

Verwenden Sie während der Entwicklung einen Tunnel-Service wie ngrok, um Ihren lokalen Endpoint für CheckYout erreichbar zu machen.

Vollständiges Beispiel

Ein vollständiges Node.js/Express-Beispiel, das Webhooks empfängt, die Signatur verifiziert und die Notify API aufruft:

server.js

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.CHECKYOUT_WEBHOOK_SECRET;
const API_KEY = process.env.CHECKYOUT_API_KEY;

// Webhook empfangen und Signatur prüfen
app.post('/webhooks/checkyout', (req, res) => {
  const signature = req.headers['x-checkyout-signature'];

  if (WEBHOOK_SECRET && signature) {
    const expected = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(JSON.stringify(req.body))
      .digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(signature, 'hex')
    )) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }

  const { event, device_id, property_name } = req.body;
  console.log(`Event: ${event}, Property: ${property_name}`);

  // Beispiel: Reinigungskraft benachrichtigen
  if (event === 'checkout') {
    notifyCleaner(device_id, property_name);
  }

  res.status(200).json({ received: true });
});

async function notifyCleaner(deviceId, propertyName) {
  const cleanerPhone = await getCleanerPhone(propertyName); // Ihre Logik

  await fetch('https://checkyout.app/api/v1/notify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({
      device_id: deviceId,
      phone: cleanerPhone,
      name: propertyName,
    }),
  });
}

app.listen(3000, () => console.log('Listening on :3000'));

Nächster Schritt: Authentifizierung im Detail