Verbinden Sie Ihr Tool mit The Big One.

In The Big One erstellt ein Administrator ein Token unter Einstellungen › Integrationen › Entwicklerzugang und wählt dessen Berechtigungen: read (Lesen), write (Schreiben), import (Sammelimport), billing (Abrechnung, nie standardmäßig angekreuzt). Das Token wird nur einmal angezeigt; erstellen Sie eines pro Tool, um sie einzeln widerrufen zu können.

Jeder Aufruf enthält das Token im Header Authorization. Das Unternehmen ergibt sich aus dem Token: Es ist keine Unternehmenskennung zu senden.

Auf bestimmte Unterkünfte beschränktes API-Token. Um einem Kunden oder Partner einen Schlüssel zu geben, wählen Sie im Token-Fenster „Bestimmte Unterkünfte“: einen Kunden (die Unterkünfte, deren Kunde er heute ist, die automatisch folgen), Gebäude, Etiketten oder gewählte Unterkünfte; die Auswahl addiert sich. Das API-Token liest dann nur, was diese Unterkünfte betrifft (Einsätze, Buchungen, Probleme, Bewertungen, Lieferungen, Wäsche), und nur die Gebäude dieser Unterkünfte. Team, Abwesenheiten, Wäschebestellungen und das Versandprotokoll antworten mit 403; Sektoren beschränken sich auf die seiner Unterkünfte; ein Einsatz oder eine Unterkunft außerhalb der Grenze antwortet mit 404. Ein beschränktes API-Token hat nie import, und billing erfordert einen Kunden: Es liest dann nur die Angaben, Preise und Berichte dieses Kunden.

Vollständiges Schema. Das OpenAPI-3.1-Schema der gesamten API (Routen, Parameter, Antworten, Benachrichtigungen) lässt sich ohne Token herunterladen: https://thebigone.io/api/public/v1/openapi.json. Seine Version ist das Datum der letzten Änderung, beschrieben im Änderungsverlauf unten auf dieser Seite.

curl https://thebigone.io/api/public/v1/tasks?from=2026-10-01&to=2026-10-07 \
  -H "Authorization: Bearer cnimp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Die Felder sind auf Englisch und in camelCase, beim Senden und Lesen identisch. Jedes Element, das Sie senden, trägt Ihre eigene Kennung, externalId: Wird dieselbe Kennung erneut gesendet, wird das Element aktualisiert, statt ein Duplikat anzulegen.

Fotos des Inserats. Beim Sammelimport kann jede Unterkunft photos enthalten: https://-Links (oder { url, caption, thumbnailUrl }), das erste ist das Hauptfoto, höchstens 60. Sie erscheinen im Unterkunftsprofil, für das Büro und für die Reinigungskräfte. Ohne das Feld ändert sich nichts; [] entfernt sie.

{ "properties": [ {
  "externalId": "LOG-12",
  "name": "Bastille — 3 pièces",
  "photos": [
    { "url": "https://photos.votre-outil.fr/log-12/salon.jpg", "caption": "Salon" },
    "https://photos.votre-outil.fr/log-12/chambre.jpg"
  ]
} ] }

Listen liefern { data, nextOffset, limit, offset }. Solange nextOffset nicht null ist, rufen Sie erneut mit offset=nextOffset auf (standardmäßig 100 Elemente, höchstens 500). Für eine Synchronisierung merken Sie sich die Uhrzeit Ihres letzten Aufrufs und übergeben sie in updatedSince.

Filter für Einsätze: from, to, status (created, assigned, in_progress, completed, cancelled), type, propertyExternalId, validated, updatedSince. Stornierte Einsätze (cancelled, nicht in der Planung) werden nur mit status=cancelled oder includeCancelled=true zurückgegeben; jeder Einsatz trägt inPlanning. Fügen Sie include=report,checklist,comments hinzu, um mit einem einzigen Aufruf den Berichtsinhalt, die Checkliste und die Kommentare jedes Einsatzes zu erhalten (mit checklist höchstens 50 Einsätze pro Seite).

{
  "id": "0b9d2c7e-4a6f-4c1e-9f2a-1d3e5b7c9a01",
  "externalId": "MEN-881",
  "type": "cleaning",
  "date": "2026-11-07",
  "startTime": "11:00:00",
  "timezone": "Europe/Paris",
  "startAt": "2026-11-07T11:00:00+01:00",
  "plannedDurationMinutes": 150,
  "plannedEndAt": "2026-11-07T13:30:00+01:00",
  "status": "completed",
  "inPlanning": true,
  "assignees": ["Camille"],
  "startedAt": "2026-11-07T10:12:00Z",
  "endedAt": "2026-11-07T12:05:00Z",
  "completedAt": "2026-11-07T12:05:04Z",
  "validated": true,
  "validatedAt": "2026-11-07T14:20:00Z",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "reservation": { "id": "…", "code": "HMX4K2", "platform": "guesty", "checkoutAt": "2026-11-07T11:00:00+01:00" },
  "nextArrival": { "id": "…", "code": "HMQ81Z", "platform": "guesty", "checkinAt": "2026-11-07T15:00:00+01:00", "guests": 4 },
  "reportUrl": "https://thebigone.io/task/report/…",
  "reportReadyAt": "2026-11-07T12:05:04Z",
  "report": { "summary": { "status": "to_report", "toReport": 2, "checklistItems": 38, "checklistDone": 37 },
    "notDone": [ { "label": "Four : intérieur", "section": "Cuisine", "required": true } ],
    "issues": [ { "category": "leak", "status": "new", "urgent": true } ],
    "inspection": null, "inventory": [], "linenMoves": [] },
  "updatedAt": "2026-11-07T14:20:01Z"
}

Uhrzeiten, Bericht und Gäste. Jeder Einsatz trägt timezone (Zeitzone der Unterkunft), startAt und plannedEndAt (vollständiges Datum und Uhrzeit mit ihrem Versatz, zum Beispiel 2026-11-07T11:00:00+01:00), plannedDurationMinutes, completedAt und validatedAt. endedAt ist das von der Reinigungskraft gestempelte Ende, sonst der Zeitpunkt, an dem der Einsatz abgeschlossen wurde. Sobald ein Einsatz abgeschlossen ist, ist reportUrl gefüllt, und reportReadyAt gibt an, seit wann der Bericht einsehbar ist. reservation liefert den verknüpften Aufenthalt (Buchungs-code, platform: Ursprungssoftware, checkinAt, checkoutAt) und nextArrival die nächste Gästeankunft in der Unterkunft.

Einsatzdetails. GET /api/public/v1/tasks/:id liefert alles auf einmal: report (Berichtsinhalt), checklist (jede Zeile der Checkliste mit done, note, value, ihren photos und referencePhotos) und comments. Fotolinks sind 7 Tage gültig; der Berichtslink (reportUrl) bleibt 90 Tage gültig.

Berichtsinhalt. report.summary.status ist ok oder to_report, und toReport zählt die nicht erledigten Pflichtpunkte, die während des Einsatzes gemeldeten Probleme und eine zu wiederholende Kontrolle. Danach folgen die Einzelheiten: notDone, notes, issues, inspection (Kontrolle erfolgt, result: compliant oder redo, Note und Bemerkung), inventory (während des Einsatzes gezählte Wäsche und Verbrauchsartikel: fehlend, fleckig, kaputt) und linenMoves.

"checklist": {
  "name": "Ménage classique",
  "items": [ {
    "id": "…", "label": "Salle de bains : miroir et robinetterie", "section": "Salle de bains",
    "required": true, "kind": "checklist", "done": true, "note": null, "value": null,
    "photos": [ { "url": "https://…", "thumbnailUrl": "https://…", "takenAt": "2026-10-05T12:41:00Z" } ],
    "referencePhotos": []
  } ]
}

Gelöschte Einsätze. GET /api/public/v1/tasks/deleted?since=… listet die seit diesem Zeitpunkt gelöschten Einsätze auf (90 Tage aufbewahrt): Ein Einsatz, der auf einer Seite fehlt, wird nie mit einem gelöschten verwechselt. Ein aus dem Papierkorb wiederhergestellter Einsatz verlässt diese Liste und erscheint wieder in /tasks.

Filter für Buchungen: from, to, status (confirmed, cancelled, blocked — gesperrte Tage ohne Gast), propertyExternalId, updatedSince. Gemeldete Probleme: from, to (Meldetag), status (new, in_progress, resolved), urgent, taskId, propertyExternalId, updatedSince. Gästebewertungen: from, to, taskId, propertyExternalId, updatedSince; Noten werden auf 5 umgerechnet, die ursprüngliche Note bleibt in ratingRaw und ratingScale.

{
  "id": "7c1e…",
  "category": "leak",
  "urgent": true,
  "description": "Fuite d'eau sous le lavabo",
  "status": "new",
  "reporterName": "Camille",
  "reportedAt": "2026-10-05T12:50:00Z",
  "taskId": "0b9d2c7e-4a6f-4c1e-9f2a-1d3e5b7c9a01",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "photos": [ { "url": "https://…", "thumbnailUrl": "https://…" } ]
}

Kategorien eines Problems (category): damage (Bruch), breakdown (Defekt), dirt (Verschmutzung), linen (Wäsche), pests (Schädlinge), access (Zugang), leak (Leck), other (Sonstiges).

Team. GET /api/public/v1/people liefert für jede Person id, name (Planungsname), email, role und roles, activities (cleaning, linen, inspection, delivery, maintenance), sectors und availability: Tage von 1 (Montag) bis 7 (Sonntag), Beginn- und Endzeit, maxHours, wenn für die Person eine Obergrenze eingestellt ist. Filter: role, activity. Telefonnummer, Adresse, Vertrag und Lohn werden nie ausgegeben. GET /api/public/v1/time-off: from, to (Urlaub, der sich mit dem Zeitraum überschneidet), status (requested, approved, refused), personId, updatedSince; ein offener Änderungs- oder Stornierungsantrag steht in changeRequest.

{
  "id": "5d2f…",
  "name": "Camille",
  "planningName": "Camille",
  "fullName": "Camille Martin",
  "email": "camille@…",
  "role": "agent",
  "roles": ["agent"],
  "activities": ["cleaning", "linen"],
  "sectors": [ { "id": "…", "name": "Paris Est" } ],
  "availability": [ { "weekday": 1, "startTime": "08:00", "endTime": "16:00", "maxHours": 7 } ]
}

Unterkünfte. Jede Unterkunft enthält propertyType, capacity, bedrooms, bathrooms, timezone, sector, building, tags und client (den aktuellen Kunden laut Tarifen, wie auf der Rechnung). Filter der Liste: active, sectorId, tag, updatedSince. GET /api/public/v1/properties/:id ergänzt amenities, listingPhotos und sheet: die Rubriken des Unterkunftsprofils und ihre ausgefüllten Felder. Die Rubrik „Zugang“ (Codes, Schlüsselbox …) wird nicht über die API ausgegeben.

Adresse. Jede Unterkunft trägt außerdem addressDetails: street, postalCode, city und full, die Adresse der Unterkunft selbst aus ihrem Unterkunftsprofil, nie die des Gebäudes.

{
  "id": "…",
  "externalId": "LOG-12",
  "name": "Bastille — 3 pièces",
  "address": "17 rue de la Roquette",
  "addressDetails": { "street": "17 rue de la Roquette", "postalCode": "75011", "city": "Paris", "full": "17 rue de la Roquette 75011 Paris" },
  "propertyType": "apartment",
  "capacity": 6, "bedrooms": 2, "bathrooms": 1,
  "sector": { "id": "…", "name": "Paris Est" },
  "building": { "id": "…", "name": "12 rue de la Roquette", "address": "12 rue de la Roquette, 75011 Paris" },
  "tags": ["Premium"],
  "client": { "id": "…", "name": "Habitat Parisien" },
  "sheet": [ { "label": "Le logement", "role": "housing",
    "fields": [ { "id": "…", "label": "Surface", "value": "65 m²", "role": "surface" } ] } ]
}

Wäsche und Lieferungen. Jede Wäschezeile enthält place (type: depot, building oder property), article und source (company, laundry, client). GET /api/public/v1/linen/stock: Filter placeType, article, updatedSince. GET /api/public/v1/linen/moves: from, to, kind (count, delivery, taken, office, prepared, cleaning, move, receipt), placeType, article; jede Bewegung liefert before, after und delta. GET /api/public/v1/linen/orders: from, to, status (draft, sent, received), ohne Preise. GET /api/public/v1/deliveries: from und to erforderlich (höchstens 31 Tage), driver, propertyExternalId; jede Lieferung liefert arrivedAt, departedAt, completedAt und ihre proofs (Links 7 Tage gültig).

{
  "id": "…",
  "date": "2026-11-04",
  "time": "09:30",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "driver": "Yanis",
  "arrivedAt": "2026-11-04T08:41:00Z",
  "departedAt": "2026-11-04T08:47:00Z",
  "completedAt": "2026-11-04T08:47:10Z",
  "proofs": [ { "url": "https://…", "takenAt": "2026-11-04T08:46:00Z", "note": null } ]
}

Abrechnung. Diese Endpunkte antworten nur einem Token, bei dem das Kästchen billing (Abrechnung) angekreuzt ist; es ist nie standardmäßig angekreuzt: kreuzen Sie es nur für Ihre eigenen Tools oder Ihre Buchhaltung an. GET /api/public/v1/clients: Identität, Kontakt, Rechnungsadressen (billingEmails), SIREN, USt-IdNr. und heute geltender Steuersatz (tax.source: client, company, exempt oder reverseCharge); includeDeleted=true fügt Kunden aus dem Papierkorb hinzu. GET /api/public/v1/prices: Basistarif jeder Unterkunft, ihre Zeiträume und in onDate der am Tag date geltende Tarif (standardmäßig heute); Filter clientId. GET /api/public/v1/reports: Berichte und Rechnungen (Filter from und to im Format JJJJ-MM, clientId), mit status (checked, invoiced, sent, paid), Summen, bestätigten Gutschriften, offenem Nettobetrag und payment (null, solange die Rechnung nicht bestätigt ist). GET /api/public/v1/reports/:id liefert zusätzlich die Zeilen, so wie sie abgerechnet wurden. Die Beträge sind die der Software, nie neu berechnet.

{
  "id": "…",
  "number": 12,
  "clientId": "…",
  "month": "2026-10",
  "period": null,
  "status": "sent",
  "currency": "EUR",
  "totals": { "ht": 1250, "tax": 250, "ttc": 1500 },
  "net": { "invoicedHt": 1250, "invoicedTtc": 1500, "creditHt": 50, "creditTtc": 60, "netHt": 1200, "netTtc": 1440 },
  "creditNotes": [ { "id": "…", "number": "AV-2026-014", "date": "2026-11-03", "amountHt": 50 } ],
  "sentOn": "2026-11-02",
  "payment": { "status": "toPay", "paidOn": null, "dueDate": "2026-12-02", "daysLate": 0 },
  "lines": [ { "apartment": "Bastille — 3 pièces", "date": "2026-10-05", "description": "Ménage",
    "quantity": 1, "amountHt": 100, "baseHt": 80,
    "adjustments": { "linen": { "count": 2, "amount": 20 }, "hours": null, "other": 0 },
    "manual": false, "taskId": "0b9d2c7e-…" } ]
}

POST /api/public/v1/tasks legt einen Einsatz mit denselben Feldern wie beim Import an (externalId, propertyExternalId, date, type, startTime, durationHours, assigneeName, notes…). Antwort 201, wenn er angelegt wurde, 200, wenn er bereits existierte und aktualisiert wurde.

curl -X POST https://thebigone.io/api/public/v1/tasks \
  -H "Authorization: Bearer cnimp_…" -H "Content-Type: application/json" \
  -d '{"externalId":"MEN-882","propertyExternalId":"LOG-12","date":"2026-10-06","type":"cleaning","startTime":"11:00"}'

PATCH /api/public/v1/tasks/:id ändert date, startTime, durationHours, assigneeName, notes, needsDelivery oder needsKit. Ein bereits begonnener, beendeter oder bestätigter Einsatz wird nie geändert: Die Antwort lautet dann 409.

Tragen Sie die HTTPS-Adresse Ihres Tools unter Entwicklerzugang ein und wählen Sie die Ereignisse. The Big One sendet innerhalb der folgenden Minute eine POST-Anfrage in JSON dorthin:

• task.created — Einsatz angelegt
• task.assigned — Einsatz zugewiesen
• task.started — Einsatz begonnen
• task.completed — Einsatz beendet
• task.validated — Einsatz von einer Leitung bestätigt
• task.updated — Einsatz geändert: Datum, Uhrzeit, Dauer, Reinigungskraft, Notizen, Unterkunft … (data.changes)
• task.cancelled — Einsatz storniert (er verschwindet aus dem Dienstplan)
• task.deleted — Einsatz gelöscht (data.task: sein letzter bekannter Stand)
• task.comment_added — Kommentar zu einem Einsatz hinzugefügt (data.comment)
• report.ready — Einsatzbericht verfügbar (reportUrl und report)
• inspection.completed — Qualitätskontrolle durchgeführt (Ergebnis, Note und Bemerkung in report.inspection)
• issue.reported — Problem von einer Reinigungskraft gemeldet (data.issue)
• issue.updated — Problem übernommen oder gelöst (data.issue)
• issue.resolved — Problem gelöst: Sie können dem Kunden „erledigt“ melden
• reservation.created — Buchung erstellt (data.reservation)
• reservation.updated — Buchung geändert: Daten, Uhrzeiten, Unterkunft oder Anzahl der Gäste
• reservation.cancelled — Buchung storniert oder von der Verwaltungssoftware entfernt (removed: true)
• property.created — Unterkunft erstellt (data.property)
• property.updated — Unterkunft geändert, einschließlich ihres Kunden laut Tarifen (data.property, data.changes)

POST https://votre-outil.fr/hooks/thebigone
X-TheBigOne-Event: task.completed
X-TheBigOne-Delivery: 5f1c…
X-TheBigOne-Signature: t=1790000000,v1=9a3f…

{ "id": "5f1c…", "type": "task.completed", "createdAt": "2026-10-05T13:05:02Z",
  "data": { "task": { …la mission, au format de la lecture… } } }

Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Code. Andernfalls wird der Versand nach 1, 5, 15, 60 und dann 240 Minuten wiederholt und danach abgebrochen. X-TheBigOne-Delivery kennzeichnet den Versand: Nutzen Sie es, um ein Duplikat zu ignorieren.

Prüfen Sie die Signatur mit dem Geheimnis, das beim Anlegen der Adresse angezeigt wird: HMAC-SHA256 von <t>.<Rohinhalt>, und lehnen Sie einen Zeitstempel ab, der älter als 5 Minuten ist.

import crypto from "node:crypto";

function signatureValide(secret, corpsBrut, entete) {
  const t = /t=(\d+)/.exec(entete)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(entete)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const attendu = crypto.createHmac("sha256", secret).update(`${t}.${corpsBrut}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

Versandprotokoll. GET /api/public/v1/webhook-deliveries listet den Versand auf (ausstehend, gesendet, aufgegeben), mit der Zahl der Versuche, der letzten Antwort Ihres Servers und der Uhrzeit des nächsten Versuchs. Unter Entwicklerzugang sendet „Test senden“ ein Ereignis test.ping an die gewählte Adresse.

• Pro Adresse: 1.200 Lese- und 300 Schreibaufrufe pro 10 Minuten. Pro Token, alle Adressen zusammen: 1.200 Aufrufe pro 10 Minuten. Darüber enthält die Antwort 429 den Header Retry-After (Wartezeit in Sekunden). Für weniger Aufrufe: include= in der Einsatzliste und die Benachrichtigungen.
• Import: 5 MB pro Aufruf, 2.000 Elemente pro Typ, 60 Aufrufe pro 10 Minuten und Unternehmen.
• Datumsangaben im Format JJJJ-MM-TT. Uhrzeiten allein (HH:MM) sind in der Ortszeit der Unterkunft (Feld timezone); startAt, plannedEndAt, checkinAt und die übrigen Zeitstempel sind vollständig, mit ihrem Versatz oder in UTC (ISO 8601).

400 ungültige Parameter oder ungültiger Body · 401 Token fehlt oder ist ungültig · 403 Berechtigung fehlt · 404 nicht gefunden · 409 Einsatz gesperrt · 413 Body zu groß · 422 Zeile abgelehnt · 429 zu viele Aufrufe · 503 Dienst vorübergehend nicht verfügbar. Alle Fehler haben die Form { "error": "…" }.

Eine Frage zur Integration? Seite „Eigene Quelle“ ansehen oder schreiben Sie uns über das Formular unten.

Jede Änderung, die ein angebundenes Tool betreffen kann, ist hier datiert. Die Version des OpenAPI-Schemas (info.version) ist das Datum der letzten.

• 7. November 2026. Stornierte Einsätze: Status cancelled, standardmäßig nicht mehr zurückgegeben (vorher erschienen sie als created); Feld inPlanning. reportUrl bei einem abgeschlossenen Einsatz immer gefüllt; completedAt, reportReadyAt; endedAt auch ohne Zeiterfassung gefüllt. Vollständige Uhrzeiten mit Zeitzone (timezone, startAt, plannedEndAt), verknüpfter Aufenthalt (reservation) und nächste Ankunft (nextArrival). include=report,checklist,comments und Berichtsinhalt als Daten. Routen /tasks/deleted, /webhook-deliveries und /openapi.json. Adresse der Unterkunft (addressDetails). Zehn neue Benachrichtigungen. Fotolinks 7 Tage gültig. /sectors für beschränkte API-Token geöffnet (ihre Sektoren). Höhere Limits.
• 3. November 2026. Checkliste und Fotos eines Einsatzes, gemeldete Probleme, Gästebewertungen, Team und Abwesenheiten, vollständige Unterkünfte, Sektoren und Gebäude, Wäsche und Lieferungen, Abrechnung (Berechtigung billing); auf bestimmte Unterkünfte beschränktes API-Token; vier Benachrichtigungen (Problem gemeldet, Buchung erstellt, geändert, storniert); Limit pro Token.
• 27. September 2026. Erste Version: Stapelimport, Lesen von Einsätzen, Unterkünften und Buchungen, Erstellen und Ändern eines Einsatzes, Token nach Verwendung, signierte Benachrichtigungen.