Branchez votre outil à The Big One.

Dans The Big One, un administrateur crée un jeton depuis Paramètres › Intégrations › Accès développeurs, en choisissant ses autorisations : read (lecture), write (écriture), import (envoi en lot), billing (facturation, jamais cochée d'office). Le jeton n'est affiché qu'une fois ; créez-en un par outil pour pouvoir les révoquer séparément.

Chaque appel porte le jeton dans l'en-tête Authorization. La société est déduite du jeton : aucun identifiant de société à envoyer.

Jeton limité à certains logements. Pour donner une clé à un client ou à un partenaire, choisissez « Certains logements » dans la fenêtre du jeton : un client (les logements dont il est le client du jour, qui suivent tout seuls), des immeubles, des étiquettes ou des logements choisis ; les choix s'additionnent. Le jeton ne lit alors que ce qui touche ces logements (missions, réservations, problèmes, avis, livraisons, linge), et seulement les immeubles de ces logements. L'équipe, les congés, les commandes de linge et le journal des envois répondent 403 ; les secteurs se limitent à ceux de ses logements ; une mission ou un logement hors limite répond 404. Un jeton limité n'a jamais import, et billing exige un client : il ne lit alors que la fiche, les tarifs et les rapports de ce client.

Schéma complet. Le schéma OpenAPI 3.1 de toute l'API (routes, paramètres, réponses, notifications) se télécharge sans jeton : https://thebigone.io/api/public/v1/openapi.json. Sa version est la date du dernier changement, décrit dans l'historique en bas de cette page.

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

Les champs sont en anglais et en camelCase, identiques à l'envoi et à la lecture. Chaque élément que vous envoyez porte votre propre identifiant, externalId : renvoyer le même identifiant met à jour l'élément au lieu d'en créer un doublon.

Photos de l'annonce. Dans l'envoi en lot, chaque logement peut porter photos : des liens https:// (ou { url, caption, thumbnailUrl }), la première étant la photo principale, 60 au plus. Elles s'affichent dans la fiche de propriété, pour le bureau et pour les agents. Sans le champ, rien ne change ; [] les retire.

{ "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"
  ]
} ] }

Les listes renvoient { data, nextOffset, limit, offset }. Tant que nextOffset n'est pas nul, rappelez avec offset=nextOffset (100 éléments par défaut, 500 au maximum). Pour une synchronisation, mémorisez l'heure de votre dernier appel et passez-la dans updatedSince.

Filtres des missions : from, to, status (created, assigned, in_progress, completed, cancelled), type, propertyExternalId, validated, updatedSince. Les missions annulées (cancelled, absentes du planning) ne sortent qu'avec status=cancelled ou includeCancelled=true ; chaque mission porte inPlanning. Ajoutez include=report,checklist,comments pour recevoir en un seul appel le contenu du rapport, la liste de tâches et les commentaires de chaque mission (50 missions par page au plus avec checklist).

{
  "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"
}

Heures, rapport et voyageurs. Chaque mission porte timezone (fuseau du logement), startAt et plannedEndAt (date et heure complètes avec leur décalage, par exemple 2026-11-07T11:00:00+01:00), plannedDurationMinutes, completedAt et validatedAt. endedAt est la fin pointée par l'agent, sinon le moment où la mission est passée terminée. Dès qu'une mission est terminée, reportUrl est rempli et reportReadyAt dit depuis quand le rapport se consulte. reservation donne le séjour relié (code de réservation, platform : logiciel d'origine, checkinAt, checkoutAt) et nextArrival la prochaine arrivée de voyageur dans le logement.

Fiche d'une mission. GET /api/public/v1/tasks/:id donne tout d'un coup : report (contenu du rapport), checklist (chaque ligne de la liste de tâches avec done, note, value, ses photos et ses referencePhotos) et comments. Les liens des photos sont valables 7 jours ; le lien du rapport (reportUrl) reste valable 90 jours.

Contenu du rapport. report.summary.status vaut ok ou to_report, et toReport compte les points obligatoires non faits, les problèmes signalés pendant la mission et un contrôle à reprendre. Le détail suit : notDone, notes, issues, inspection (contrôle fait, result : compliant ou redo, note et remarque), inventory (linge et consommables comptés pendant la mission : manquants, tachés, cassés) et 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": []
  } ]
}

Missions supprimées. GET /api/public/v1/tasks/deleted?since=… liste les missions supprimées depuis ce moment (gardées 90 jours) : une mission absente d'une page n'est jamais confondue avec une mission supprimée. Une mission restaurée depuis la corbeille sort de cette liste et revient dans /tasks.

Filtres des réservations : from, to, status (confirmed, cancelled, blocked — dates fermées sans voyageur), propertyExternalId, updatedSince. Problèmes signalés : from, to (jour du signalement), status (new, in_progress, resolved), urgent, taskId, propertyExternalId, updatedSince. Avis des voyageurs : from, to, taskId, propertyExternalId, updatedSince ; les notes sont ramenées sur 5, la note d'origine reste dans ratingRaw et 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://…" } ]
}

Catégories d'un problème (category) : damage (casse), breakdown (panne), dirt (saleté), linen (linge), pests (nuisibles), access (accès), leak (fuite), other (autre).

Équipe. GET /api/public/v1/people renvoie pour chaque personne id, name (nom de planning), email, role et roles, activities (cleaning, linen, inspection, delivery, maintenance), sectors et availability : jours de 1 (lundi) à 7 (dimanche), heures de début et de fin, maxHours quand un plafond est réglé pour la personne. Filtres : role, activity. Le téléphone, l'adresse, le contrat et la paie ne sortent jamais. GET /api/public/v1/time-off : from, to (congés qui chevauchent la période), status (requested, approved, refused), personId, updatedSince ; une demande de modification ou d'annulation en attente est dans 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 } ]
}

Logements. Chaque logement porte propertyType, capacity, bedrooms, bathrooms, timezone, sector, building, tags et client (le client du jour, d'après les tarifs, comme la facture). Filtres de la liste : active, sectorId, tag, updatedSince. GET /api/public/v1/properties/:id ajoute amenities, listingPhotos et sheet : les rubriques de la fiche et leurs cases remplies. La rubrique « Accès » (codes, boîte à clés…) ne sort pas par l'API.

Adresse. Chaque logement porte aussi addressDetails : street, postalCode, city et full, l'adresse du logement lui-même lue dans sa fiche, jamais celle de l'immeuble.

{
  "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" } ] } ]
}

Linge et livraisons. Chaque ligne de linge porte place (type : depot, building ou property), article et source (company, laundry, client). GET /api/public/v1/linen/stock : filtres placeType, article, updatedSince. GET /api/public/v1/linen/moves : from, to, kind (count, delivery, taken, office, prepared, cleaning, move, receipt), placeType, article ; chaque mouvement donne before, after et delta. GET /api/public/v1/linen/orders : from, to, status (draft, sent, received), sans prix. GET /api/public/v1/deliveries : from et to obligatoires (31 jours au plus), driver, propertyExternalId ; chaque livraison donne arrivedAt, departedAt, completedAt et ses proofs (liens valables 7 jours).

{
  "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 } ]
}

Facturation. Ces points d'accès ne répondent qu'à un jeton où la case billing (Facturation) est cochée ; elle ne l'est jamais d'office : ne la cochez que pour vos propres outils ou votre comptable. GET /api/public/v1/clients : identité, contact, adresses de facturation (billingEmails), SIREN, numéro de TVA et taux de taxe du jour (tax.source : client, company, exempt ou reverseCharge) ; includeDeleted=true ajoute les clients mis à la corbeille. GET /api/public/v1/prices : tarif de base de chaque logement, ses périodes et, dans onDate, le tarif qui s'applique au jour date (aujourd'hui par défaut) ; filtre clientId. GET /api/public/v1/reports : rapports et factures (filtres from et to au format AAAA-MM, clientId), avec status (checked, invoiced, sent, paid), totaux, avoirs validés, net à payer et payment (null tant que la facture n'est pas validée). GET /api/public/v1/reports/:id ajoute les lignes telles qu'elles ont été facturées. Les montants sont ceux du logiciel, jamais recalculés.

{
  "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 crée une mission avec les mêmes champs que l'import (externalId, propertyExternalId, date, type, startTime, durationHours, assigneeName, notes…). Réponse 201 si elle est créée, 200 si elle existait déjà et a été mise à jour.

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 modifie date, startTime, durationHours, assigneeName, notes, needsDelivery ou needsKit. Une mission déjà commencée, terminée ou validée n'est jamais modifiée : la réponse est alors 409.

Ajoutez l'adresse HTTPS de votre outil dans Accès développeurs et choisissez les événements. The Big One y envoie une requête POST en JSON dans la minute qui suit :

• task.created — mission créée
• task.assigned — mission assignée
• task.started — mission démarrée
• task.completed — mission terminée
• task.validated — mission validée par un responsable
• task.updated — mission modifiée : date, heure, durée, agent, notes, logement… (data.changes)
• task.cancelled — mission annulée (elle sort du planning)
• task.deleted — mission supprimée (data.task : sa dernière forme connue)
• task.comment_added — commentaire ajouté à une mission (data.comment)
• report.ready — rapport de la mission disponible (reportUrl et report)
• inspection.completed — contrôle qualité fait (résultat, note et remarque dans report.inspection)
• issue.reported — problème signalé par un agent (data.issue)
• issue.updated — problème pris en charge ou réglé (data.issue)
• issue.resolved — problème réglé : de quoi dire « c'est réglé » au client
• reservation.created — réservation créée (data.reservation)
• reservation.updated — réservation modifiée : dates, heures, logement ou nombre de voyageurs
• reservation.cancelled — réservation annulée, ou retirée par le logiciel de gestion (removed: true)
• property.created — logement créé (data.property)
• property.updated — logement modifié, dont son client d'après les tarifs (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… } } }

Répondez par un code 2xx sous 10 secondes. Sinon, l'envoi est retenté après 1, 5, 15, 60 puis 240 minutes, puis abandonné. X-TheBigOne-Delivery identifie l'envoi : servez-vous-en pour ignorer un doublon.

Vérifiez la signature avec le secret affiché à la création de l'adresse : HMAC-SHA256 de <t>.<corps brut>, et refusez un horodatage de plus de 5 minutes.

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));
}

Journal des envois. GET /api/public/v1/webhook-deliveries liste les envois (en attente, envoyés, abandonnés), avec le nombre d'essais, la dernière réponse de votre serveur et l'heure du prochain essai. Dans Accès développeurs, « Envoyer un test » envoie un événement test.ping à l'adresse choisie.

• Par adresse : 1 200 lectures et 300 écritures par 10 minutes. Par jeton, toutes adresses confondues : 1 200 appels par 10 minutes. Au-delà, la réponse 429 porte l'en-tête Retry-After (secondes à attendre). Pour faire moins d'appels : include= sur la liste des missions, et les notifications.
• Import : 5 Mo par appel, 2 000 éléments par type, 60 appels par 10 minutes et par société.
• Dates au format AAAA-MM-JJ. Les heures seules (HH:MM) sont à l'heure locale du logement (champ timezone) ; startAt, plannedEndAt, checkinAt et les autres horodatages sont complets, avec leur décalage ou en UTC (ISO 8601).

400 paramètres ou corps invalides · 401 jeton absent ou invalide · 403 autorisation manquante · 404 introuvable · 409 mission figée · 413 corps trop volumineux · 422 ligne refusée · 429 trop d'appels · 503 service momentanément indisponible. Toutes les erreurs ont la forme { "error": "…" }.

Une question d'intégration ? Voir la page Source personnalisée ou écrivez-nous via le formulaire ci-dessous.

Tout changement qui peut toucher un outil branché est daté ici. La version du schéma OpenAPI (info.version) est la date du dernier.

• 7 novembre 2026. Missions annulées : état cancelled, plus renvoyées par défaut (avant, elles sortaient en created) ; champ inPlanning. reportUrl toujours rempli pour une mission terminée ; completedAt, reportReadyAt ; endedAt rempli même sans pointage. Heures complètes avec fuseau (timezone, startAt, plannedEndAt), séjour relié (reservation) et prochaine arrivée (nextArrival). include=report,checklist,comments et contenu du rapport en données. Routes /tasks/deleted, /webhook-deliveries et /openapi.json. Adresse du logement (addressDetails). Dix nouvelles notifications. Liens des photos valables 7 jours. /sectors ouvert au jeton limité (ses secteurs). Limites relevées.
• 3 novembre 2026. Liste de tâches et photos d'une mission, problèmes signalés, avis des voyageurs, équipe et congés, logements complets, secteurs et immeubles, linge et livraisons, facturation (autorisation billing) ; jeton limité à certains logements ; quatre notifications (problème signalé, réservation créée, modifiée, annulée) ; limite par jeton.
• 27 septembre 2026. Première version : import en lot, lecture des missions, logements et réservations, création et modification d'une mission, jetons par usage, notifications signées.