Ligue a sua ferramenta ao The Big One.

No The Big One, um administrador cria um token em Definições › Integrações › Acesso para programadores, escolhendo as respetivas autorizações: read (leitura), write (escrita), import (envio em lote), billing (faturação, nunca assinalada por predefinição). O token só é mostrado uma vez; crie um por ferramenta para os poder revogar separadamente.

Cada chamada leva o token no cabeçalho Authorization. A empresa é deduzida do token: não é preciso enviar nenhum identificador de empresa.

Token limitado a alguns alojamentos. Para dar uma chave a um cliente ou a um parceiro, escolha «Alguns alojamentos» na janela do token: um cliente (os alojamentos de que é cliente hoje, que se atualizam sozinhos), edifícios, etiquetas ou alojamentos escolhidos; as escolhas somam-se. O token só lê então o que diz respeito a esses alojamentos (serviços, reservas, problemas, avaliações, entregas, roupa) e só os edifícios desses alojamentos. A equipa, as ausências, as encomendas de roupa e o registo de envios respondem 403; os setores limitam-se aos dos seus alojamentos; um serviço ou um alojamento fora do limite responde 404. Um token limitado nunca tem import, e billing exige um cliente: só lê então a ficha, as tarifas e os relatórios desse cliente.

Esquema completo. O esquema OpenAPI 3.1 de toda a API (rotas, parâmetros, respostas, notificações) descarrega-se sem token: https://thebigone.io/api/public/v1/openapi.json. A sua versão é a data da última alteração, descrita no histórico no fim desta página.

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

Os campos estão em inglês e em camelCase, idênticos no envio e na leitura. Cada elemento que envia leva o seu próprio identificador, externalId: reenviar o mesmo identificador atualiza o elemento em vez de criar um duplicado.

Fotografias do anúncio. No envio em lote, cada alojamento pode incluir photos: ligações https:// (ou { url, caption, thumbnailUrl }), sendo a primeira a fotografia principal, 60 no máximo. Aparecem na ficha do alojamento, para o escritório e para os profissionais de limpeza. Sem o campo, nada muda; [] remove-as.

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

As listas devolvem { data, nextOffset, limit, offset }. Enquanto nextOffset não for nulo, volte a chamar com offset=nextOffset (100 elementos por predefinição, 500 no máximo). Para uma sincronização, guarde a hora da sua última chamada e passe-a em updatedSince.

Filtros dos serviços: from, to, status (created, assigned, in_progress, completed, cancelled), type, propertyExternalId, validated, updatedSince. Os serviços cancelados (cancelled, ausentes do planeamento) só são devolvidos com status=cancelled ou includeCancelled=true; cada serviço traz inPlanning. Acrescente include=report,checklist,comments para receber numa só chamada o conteúdo do relatório, a lista de tarefas e os comentários de cada serviço (50 serviços por página no máximo com 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, relatório e hóspedes. Cada serviço traz timezone (fuso horário do alojamento), startAt e plannedEndAt (data e hora completas com o seu desvio, por exemplo 2026-11-07T11:00:00+01:00), plannedDurationMinutes, completedAt e validatedAt. endedAt é o fim registado pelo profissional de limpeza; caso contrário, o momento em que o serviço passou a concluído. Assim que um serviço está concluído, reportUrl fica preenchido e reportReadyAt indica desde quando o relatório pode ser consultado. reservation dá a estadia ligada (code da reserva, platform: software de origem, checkinAt, checkoutAt) e nextArrival a próxima chegada de hóspedes ao alojamento.

Ficha de um serviço. GET /api/public/v1/tasks/:id dá tudo de uma vez: report (conteúdo do relatório), checklist (cada linha da lista de tarefas com done, note, value, as suas photos e referencePhotos) e comments. As ligações das fotografias são válidas durante 7 dias; a ligação do relatório (reportUrl) continua válida durante 90 dias.

Conteúdo do relatório. report.summary.status vale ok ou to_report, e toReport conta os pontos obrigatórios não feitos, os problemas comunicados durante o serviço e um controlo a repetir. Segue-se o detalhe: notDone, notes, issues, inspection (controlo feito, result: compliant ou redo, nota e observação), inventory (roupa e consumíveis contados durante o serviço: em falta, manchados, partidos) e 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": []
  } ]
}

Serviços eliminados. GET /api/public/v1/tasks/deleted?since=… lista os serviços eliminados desde esse momento (guardados 90 dias): um serviço ausente de uma página nunca é confundido com um serviço eliminado. Um serviço restaurado a partir da reciclagem sai desta lista e volta a /tasks.

Filtros das reservas: from, to, status (confirmed, cancelled, blocked — datas fechadas sem hóspede), propertyExternalId, updatedSince. Problemas comunicados: from, to (dia da comunicação), status (new, in_progress, resolved), urgent, taskId, propertyExternalId, updatedSince. Avaliações dos hóspedes: from, to, taskId, propertyExternalId, updatedSince; as notas são convertidas para 5, a nota original fica em ratingRaw e 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://…" } ]
}

Categorias de um problema (category): damage (quebra), breakdown (avaria), dirt (sujidade), linen (roupa), pests (pragas), access (acesso), leak (fuga), other (outro).

Equipa. GET /api/public/v1/people devolve para cada pessoa id, name (nome no planeamento), email, role e roles, activities (cleaning, linen, inspection, delivery, maintenance), sectors e availability: dias de 1 (segunda-feira) a 7 (domingo), horas de início e de fim, maxHours quando está definido um limite para a pessoa. Filtros: role, activity. O telefone, a morada, o contrato e a remuneração nunca são devolvidos. GET /api/public/v1/time-off: from, to (férias que se sobrepõem ao período), status (requested, approved, refused), personId, updatedSince; um pedido de alteração ou de anulação pendente está em 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 } ]
}

Alojamentos. Cada alojamento inclui propertyType, capacity, bedrooms, bathrooms, timezone, sector, building, tags e client (o cliente atual, segundo as tarifas, como na fatura). Filtros da lista: active, sectorId, tag, updatedSince. GET /api/public/v1/properties/:id acrescenta amenities, listingPhotos e sheet: as rubricas da ficha e os campos preenchidos. A rubrica «Acesso» (códigos, caixa de chaves…) não sai pela API.

Morada. Cada alojamento traz também addressDetails: street, postalCode, city e full, a morada do próprio alojamento lida na sua ficha, nunca a do edifício.

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

Roupa e entregas. Cada linha de roupa inclui place (type: depot, building ou property), article e 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 movimento dá before, after e delta. GET /api/public/v1/linen/orders: from, to, status (draft, sent, received), sem preços. GET /api/public/v1/deliveries: from e to obrigatórios (no máximo 31 dias), driver, propertyExternalId; cada entrega dá arrivedAt, departedAt, completedAt e os proofs (ligações válidas durante 7 dias).

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

Faturação. Estes pontos de acesso só respondem a um token com a caixa billing (Faturação) assinalada; nunca está assinalada por predefinição: assinale-a apenas para as suas próprias ferramentas ou o seu contabilista. GET /api/public/v1/clients: identidade, contacto, endereços de faturação (billingEmails), SIREN, número de IVA e taxa de imposto do dia (tax.source: client, company, exempt ou reverseCharge); includeDeleted=true acrescenta os clientes enviados para a reciclagem. GET /api/public/v1/prices: tarifa base de cada alojamento, os seus períodos e, em onDate, a tarifa aplicável no dia date (hoje por predefinição); filtro clientId. GET /api/public/v1/reports: relatórios e faturas (filtros from e to no formato AAAA-MM, clientId), com status (checked, invoiced, sent, paid), totais, notas de crédito validadas, líquido a pagar e payment (null enquanto a fatura não estiver validada). GET /api/public/v1/reports/:id acrescenta as linhas tal como foram faturadas. Os montantes são os do 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 cria um serviço com os mesmos campos da importação (externalId, propertyExternalId, date, type, startTime, durationHours, assigneeName, notes…). Resposta 201 se for criado, 200 se já existia e foi atualizado.

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 altera date, startTime, durationHours, assigneeName, notes, needsDelivery ou needsKit. Um serviço já iniciado, terminado ou validado nunca é alterado: a resposta é então 409.

Adicione o endereço HTTPS da sua ferramenta em Acesso para programadores e escolha os eventos. O The Big One envia-lhe um pedido POST em JSON no minuto seguinte:

• task.created — serviço criado
• task.assigned — serviço atribuído
• task.started — serviço iniciado
• task.completed — serviço terminado
• task.validated — serviço validado por um responsável
• task.updated — serviço alterado: data, hora, duração, profissional de limpeza, notas, alojamento… (data.changes)
• task.cancelled — serviço cancelado (sai do planeamento)
• task.deleted — serviço eliminado (data.task: a sua última forma conhecida)
• task.comment_added — comentário adicionado a um serviço (data.comment)
• report.ready — relatório do serviço disponível (reportUrl e report)
• inspection.completed — controlo de qualidade feito (resultado, nota e observação em report.inspection)
• issue.reported — problema comunicado por um profissional de limpeza (data.issue)
• issue.updated — problema em tratamento ou resolvido (data.issue)
• issue.resolved — problema resolvido: pode dizer ao cliente «está resolvido»
• reservation.created — reserva criada (data.reservation)
• reservation.updated — reserva alterada: datas, horas, alojamento ou número de hóspedes
• reservation.cancelled — reserva cancelada, ou retirada pelo software de gestão (removed: true)
• property.created — alojamento criado (data.property)
• property.updated — alojamento alterado, incluindo o seu cliente segundo as 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 com um código 2xx em menos de 10 segundos. Caso contrário, o envio é repetido após 1, 5, 15, 60 e depois 240 minutos, e depois abandonado. X-TheBigOne-Delivery identifica o envio: use-o para ignorar um duplicado.

Verifique a assinatura com o segredo mostrado na criação do endereço: HMAC-SHA256 de <t>.<corpo em bruto>, e recuse um carimbo de data/hora com mais 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));
}

Registo de envios. GET /api/public/v1/webhook-deliveries lista os envios (pendentes, enviados, abandonados), com o número de tentativas, a última resposta do seu servidor e a hora da próxima tentativa. Em Acesso para programadores, «Enviar um teste» envia um evento test.ping para o endereço escolhido.

• Por endereço: 1200 leituras e 300 escritas por 10 minutos. Por token, todos os endereços juntos: 1200 chamadas por 10 minutos. Acima disso, a resposta 429 traz o cabeçalho Retry-After (segundos de espera). Para fazer menos chamadas: include= na lista de serviços, e as notificações.
• Importação: 5 MB por chamada, 2000 elementos por tipo, 60 chamadas por 10 minutos e por empresa.
• Datas no formato AAAA-MM-DD. As horas sozinhas (HH:MM) estão na hora local do alojamento (campo timezone); startAt, plannedEndAt, checkinAt e os outros carimbos de data/hora são completos, com o seu desvio ou em UTC (ISO 8601).

400 parâmetros ou corpo inválidos · 401 token ausente ou inválido · 403 autorização em falta · 404 não encontrado · 409 serviço bloqueado · 413 corpo demasiado grande · 422 linha recusada · 429 demasiadas chamadas · 503 serviço temporariamente indisponível. Todos os erros têm a forma { "error": "…" }.

Uma questão de integração? Ver a página Fonte personalizada ou escreva-nos através do formulário abaixo.

Qualquer alteração que possa afetar uma ferramenta ligada é datada aqui. A versão do esquema OpenAPI (info.version) é a data da última.

• 7 de novembro de 2026. Serviços cancelados: estado cancelled, deixam de ser devolvidos por predefinição (antes saíam como created); campo inPlanning. reportUrl sempre preenchido para um serviço concluído; completedAt, reportReadyAt; endedAt preenchido mesmo sem registo de horas. Horas completas com fuso horário (timezone, startAt, plannedEndAt), estadia ligada (reservation) e próxima chegada (nextArrival). include=report,checklist,comments e conteúdo do relatório em dados. Rotas /tasks/deleted, /webhook-deliveries e /openapi.json. Morada do alojamento (addressDetails). Dez novas notificações. Ligações das fotografias válidas durante 7 dias. /sectors aberto ao token limitado (os seus setores). Limites mais altos.
• 3 de novembro de 2026. Lista de tarefas e fotografias de um serviço, problemas comunicados, avaliações dos hóspedes, equipa e ausências, alojamentos completos, setores e edifícios, roupa e entregas, faturação (autorização billing); token limitado a alguns alojamentos; quatro notificações (problema comunicado, reserva criada, alterada, cancelada); limite por token.
• 27 de setembro de 2026. Primeira versão: importação em lote, leitura de serviços, alojamentos e reservas, criação e alteração de um serviço, tokens por utilização, notificações assinadas.