Conecte su herramienta a The Big One.

En The Big One, un administrador crea un token desde Configuración › Integraciones › Acceso para desarrolladores, eligiendo sus permisos: read (lectura), write (escritura), import (envío por lotes), billing (facturación, nunca marcada por defecto). El token solo se muestra una vez; cree uno por herramienta para poder revocarlos por separado.

Cada llamada lleva el token en la cabecera Authorization. La empresa se deduce del token: no hay que enviar ningún identificador de empresa.

Token limitado a algunos alojamientos. Para dar una clave a un cliente o a un socio, elija «Algunos alojamientos» en la ventana del token: un cliente (los alojamientos de los que es cliente hoy, que se actualizan solos), edificios, etiquetas o alojamientos elegidos; las opciones se suman. El token solo lee entonces lo que afecta a esos alojamientos (servicios, reservas, incidencias, opiniones, entregas, ropa) y solo los edificios de esos alojamientos. El equipo, las ausencias, los pedidos de ropa y el registro de envíos responden 403; los sectores se limitan a los de sus alojamientos; un servicio o un alojamiento fuera del límite responde 404. Un token limitado nunca tiene import, y billing exige un cliente: entonces solo lee la ficha, las tarifas y los informes de ese cliente.

Esquema completo. El esquema OpenAPI 3.1 de toda la API (rutas, parámetros, respuestas, notificaciones) se descarga sin token: https://thebigone.io/api/public/v1/openapi.json. Su versión es la fecha del último cambio, descrito en el historial al final de esta página.

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

Los campos están en inglés y en camelCase, idénticos al enviar y al leer. Cada elemento que envía lleva su propio identificador, externalId: reenviar el mismo identificador actualiza el elemento en lugar de crear un duplicado.

Fotos del anuncio. En el envío por lotes, cada alojamiento puede llevar photos: enlaces https:// (o { url, caption, thumbnailUrl }), la primera es la foto principal, 60 como máximo. Se muestran en la ficha del alojamiento, para la oficina y para el personal de limpieza. Sin el campo, no cambia nada; [] las retira.

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

Las listas devuelven { data, nextOffset, limit, offset }. Mientras nextOffset no sea nulo, vuelva a llamar con offset=nextOffset (100 elementos por defecto, 500 como máximo). Para una sincronización, guarde la hora de su última llamada y pásela en updatedSince.

Filtros de los servicios: from, to, status (created, assigned, in_progress, completed, cancelled), type, propertyExternalId, validated, updatedSince. Los servicios cancelados (cancelled, ausentes de la planificación) solo se devuelven con status=cancelled o includeCancelled=true; cada servicio lleva inPlanning. Añada include=report,checklist,comments para recibir en una sola llamada el contenido del informe, la lista de tareas y los comentarios de cada servicio (50 servicios por página como máximo con 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"
}

Horas, informe y huéspedes. Cada servicio lleva timezone (zona horaria del alojamiento), startAt y plannedEndAt (fecha y hora completas con su desfase, por ejemplo 2026-11-07T11:00:00+01:00), plannedDurationMinutes, completedAt y validatedAt. endedAt es el final fichado por el limpiador/a; si no, el momento en que el servicio pasó a terminado. En cuanto un servicio está terminado, reportUrl se rellena y reportReadyAt indica desde cuándo se puede consultar el informe. reservation da la estancia vinculada (code de reserva, platform: software de origen, checkinAt, checkoutAt) y nextArrival la próxima llegada de huéspedes al alojamiento.

Ficha de un servicio. GET /api/public/v1/tasks/:id lo da todo de una vez: report (contenido del informe), checklist (cada línea de la lista de tareas con done, note, value, sus photos y sus referencePhotos) y comments. Los enlaces de las fotos son válidos durante 7 días; el enlace del informe (reportUrl) sigue siendo válido 90 días.

Contenido del informe. report.summary.status vale ok o to_report, y toReport cuenta los puntos obligatorios no hechos, las incidencias comunicadas durante el servicio y un control que repetir. Sigue el detalle: notDone, notes, issues, inspection (control hecho, result: compliant o redo, nota y observación), inventory (lencería y consumibles contados durante el servicio: faltantes, manchados, rotos) y 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": []
  } ]
}

Servicios eliminados. GET /api/public/v1/tasks/deleted?since=… lista los servicios eliminados desde ese momento (conservados 90 días): un servicio ausente de una página nunca se confunde con un servicio eliminado. Un servicio restaurado desde la papelera sale de esta lista y vuelve a /tasks.

Filtros de las reservas: from, to, status (confirmed, cancelled, blocked — fechas cerradas sin huésped), propertyExternalId, updatedSince. Incidencias comunicadas: from, to (día de la comunicación), status (new, in_progress, resolved), urgent, taskId, propertyExternalId, updatedSince. Reseñas de huéspedes: from, to, taskId, propertyExternalId, updatedSince; las notas se expresan sobre 5 y la nota original se conserva en ratingRaw y 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://…" } ]
}

Categorías de una incidencia (category): damage (rotura), breakdown (avería), dirt (suciedad), linen (ropa de cama y toallas), pests (plagas), access (acceso), leak (fuga), other (otro).

Equipo. GET /api/public/v1/people devuelve para cada persona id, name (nombre en la planificación), email, role y roles, activities (cleaning, linen, inspection, delivery, maintenance), sectors y availability: días del 1 (lunes) al 7 (domingo), horas de inicio y de fin, maxHours cuando se ha fijado un tope para la persona. Filtros: role, activity. El teléfono, la dirección, el contrato y la nómina nunca se devuelven. GET /api/public/v1/time-off: from, to (vacaciones que se solapan con el periodo), status (requested, approved, refused), personId, updatedSince; una solicitud de modificación o de anulación pendiente está en 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 } ]
}

Alojamientos. Cada alojamiento incluye propertyType, capacity, bedrooms, bathrooms, timezone, sector, building, tags y client (el cliente actual, según las tarifas, como en la factura). Filtros de la lista: active, sectorId, tag, updatedSince. GET /api/public/v1/properties/:id añade amenities, listingPhotos y sheet: las secciones de la ficha y sus campos rellenados. La sección «Acceso» (códigos, caja de llaves…) no sale por la API.

Dirección. Cada alojamiento lleva también addressDetails: street, postalCode, city y full, la dirección del propio alojamiento leída en su ficha, nunca la del edificio.

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

Lencería y entregas. Cada línea de lencería incluye place (type: depot, building o property), article y source (company, laundry, client). GET /api/public/v1/linen/stock: filtros placeType, article, updatedSince. GET /api/public/v1/linen/moves: from, to, kind (count, delivery, taken, office, prepared, cleaning, move, receipt), placeType, article; cada movimiento da before, after y delta. GET /api/public/v1/linen/orders: from, to, status (draft, sent, received), sin precios. GET /api/public/v1/deliveries: from y to obligatorios (31 días como máximo), driver, propertyExternalId; cada entrega da arrivedAt, departedAt, completedAt y sus proofs (enlaces válidos durante 7 días).

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

Facturación. Estos puntos de acceso solo responden a un token con la casilla billing (Facturación) marcada; nunca lo está por defecto: márquela solo para sus propias herramientas o su contable. GET /api/public/v1/clients: identidad, contacto, direcciones de facturación (billingEmails), SIREN, número de IVA y tipo impositivo del día (tax.source: client, company, exempt o reverseCharge); includeDeleted=true añade los clientes enviados a la papelera. GET /api/public/v1/prices: tarifa base de cada alojamiento, sus periodos y, en onDate, la tarifa que se aplica el día date (hoy por defecto); filtro clientId. GET /api/public/v1/reports: informes y facturas (filtros from y to en formato AAAA-MM, clientId), con status (checked, invoiced, sent, paid), totales, abonos validados, neto a pagar y payment (null mientras la factura no esté validada). GET /api/public/v1/reports/:id añade las líneas tal como se facturaron. Los importes son los del software, nunca recalculados.

{
  "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 crea un servicio con los mismos campos que la importación (externalId, propertyExternalId, date, type, startTime, durationHours, assigneeName, notes…). Respuesta 201 si se crea, 200 si ya existía y se ha actualizado.

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 modifica date, startTime, durationHours, assigneeName, notes, needsDelivery o needsKit. Un servicio ya empezado, terminado o validado nunca se modifica: la respuesta es entonces 409.

Añada la dirección HTTPS de su herramienta en Acceso para desarrolladores y elija los eventos. The Big One le envía una solicitud POST en JSON en el minuto siguiente:

• task.created — servicio creado
• task.assigned — servicio asignado
• task.started — servicio iniciado
• task.completed — servicio terminado
• task.validated — servicio validado por un responsable
• task.updated — servicio modificado: fecha, hora, duración, limpiador/a, notas, alojamiento… (data.changes)
• task.cancelled — servicio cancelado (sale de la planificación)
• task.deleted — servicio eliminado (data.task: su última forma conocida)
• task.comment_added — comentario añadido a un servicio (data.comment)
• report.ready — informe del servicio disponible (reportUrl y report)
• inspection.completed — control de calidad realizado (resultado, nota y observación en report.inspection)
• issue.reported — incidencia comunicada por un/a limpiador/a (data.issue)
• issue.updated — incidencia atendida o resuelta (data.issue)
• issue.resolved — incidencia resuelta: puede decir al cliente «está resuelto»
• reservation.created — reserva creada (data.reservation)
• reservation.updated — reserva modificada: fechas, horas, alojamiento o número de huéspedes
• reservation.cancelled — reserva cancelada, o retirada por el programa de gestión (removed: true)
• property.created — alojamiento creado (data.property)
• property.updated — alojamiento modificado, incluido su cliente según las tarifas (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… } } }

Responda con un código 2xx en menos de 10 segundos. Si no, el envío se reintenta tras 1, 5, 15, 60 y luego 240 minutos, y después se abandona. X-TheBigOne-Delivery identifica el envío: úselo para ignorar un duplicado.

Verifique la firma con el secreto mostrado al crear la dirección: HMAC-SHA256 de <t>.<cuerpo sin procesar>, y rechace una marca de tiempo de más de 5 minutos.

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

Registro de envíos. GET /api/public/v1/webhook-deliveries lista los envíos (pendientes, enviados, abandonados), con el número de intentos, la última respuesta de su servidor y la hora del próximo intento. En Acceso para desarrolladores, «Enviar una prueba» envía un evento test.ping a la dirección elegida.

• Por dirección: 1200 lecturas y 300 escrituras cada 10 minutos. Por token, todas las direcciones juntas: 1200 llamadas cada 10 minutos. Por encima, la respuesta 429 incluye el encabezado Retry-After (segundos de espera). Para hacer menos llamadas: include= en la lista de servicios, y las notificaciones.
• Importación: 5 MB por llamada, 2000 elementos por tipo, 60 llamadas cada 10 minutos y por empresa.
• Fechas en formato AAAA-MM-DD. Las horas solas (HH:MM) están en la hora local del alojamiento (campo timezone); startAt, plannedEndAt, checkinAt y las demás marcas de tiempo son completas, con su desfase o en UTC (ISO 8601).

400 parámetros o cuerpo no válidos · 401 token ausente o no válido · 403 falta el permiso · 404 no encontrado · 409 servicio bloqueado · 413 cuerpo demasiado grande · 422 línea rechazada · 429 demasiadas llamadas · 503 servicio no disponible temporalmente. Todos los errores tienen la forma { "error": "…" }.

¿Una pregunta sobre la integración? Vea la página Fuente personalizada o escríbanos mediante el formulario de abajo.

Todo cambio que pueda afectar a una herramienta conectada se fecha aquí. La versión del esquema OpenAPI (info.version) es la fecha del último.

• 7 de noviembre de 2026. Servicios cancelados: estado cancelled, ya no se devuelven por defecto (antes salían como created); campo inPlanning. reportUrl siempre relleno para un servicio terminado; completedAt, reportReadyAt; endedAt relleno incluso sin fichaje. Horas completas con zona horaria (timezone, startAt, plannedEndAt), estancia vinculada (reservation) y próxima llegada (nextArrival). include=report,checklist,comments y contenido del informe como datos. Rutas /tasks/deleted, /webhook-deliveries y /openapi.json. Dirección del alojamiento (addressDetails). Diez notificaciones nuevas. Enlaces de las fotos válidos durante 7 días. /sectors abierto al token limitado (sus sectores). Límites más altos.
• 3 de noviembre de 2026. Lista de tareas y fotos de un servicio, incidencias comunicadas, opiniones de los huéspedes, equipo y ausencias, alojamientos completos, sectores y edificios, lencería y entregas, facturación (autorización billing); token limitado a algunos alojamientos; cuatro notificaciones (incidencia comunicada, reserva creada, modificada, cancelada); límite por token.
• 27 de septiembre de 2026. Primera versión: importación por lotes, lectura de servicios, alojamientos y reservas, creación y modificación de un servicio, tokens por uso, notificaciones firmadas.