Repull para plataformas: como funciona quando os teus clientes são os anfitriões

Na prática, a plataforma nunca pede aos seus utilizadores que assinem nada connosco, nunca lhes mostra a nossa marca a não ser uma ligação de atribuição na página Connect e nunca lhes entrega uma credencial. O teu utilizador clica em “ligar Airbnb” dentro do teu produto, completa um fluxo alojado com a tua marca e volta. A conta dele é agora mais uma conta ligada no teu espaço de trabalho.

// One workspace — yours — and one key for every user you onboard.
// 1. Mint a Connect session for this user, with your user id as state.
const res = await fetch('https://api.repull.dev/v1/connect', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.REPULL_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    redirectUrl: 'https://your-product.com/channels/done',
    state: userId,                      // comes back to you
    allowedProviders: ['airbnb', 'booking', 'vrbo-login'],
  }),
})
const { url } = await res.json()

// 2. Redirect the user. They connect on your branded Connect page and
//    come back with ?status=connected&state=<userId>. The
//    connect.session.completed webhook carries the same state and the
//    account they connected — store that account against the user.

• Muitas contas por canal. As contas de anfitrião do Airbnb, as propriedades do Booking.com e as contas do Vrbo de todos os teus utilizadores convivem no teu espaço de trabalho. GET /v1/connect/{provider} lista-as em accounts, e DELETE /v1/connect/{provider} aceita um accountId para desligar a conta de um utilizador sem mexer nas outras.
• Cada evento indica a sua conta. As entregas de webhook trazem um bloco account — provider e externalAccountId, o id do próprio fornecedor — e a mesma conta nos cabeçalhos X-Repull-Account e X-Repull-Account-Id.
• Cada registo indica a sua conta. GET /v1/reservations, /v1/conversations e /v1/reviews trazem account em cada linha e /v1/properties traz accounts; os quatro aceitam ?account=provider:externalAccountId para ler os dados de um utilizador.
• Uma chave para todo o espaço de trabalho. A chave é tua e lê todas as contas ligadas. Os âmbitos limitam o que pode fazer, não o que pode ver — que é exatamente o que queres quando a chave só vive nos teus servidores.

// Every webhook event names the connected account it came from.
app.post('/repull/webhooks', (req, res) => {
  const event = verify(req)                 // HMAC over the raw body
  const { provider, externalAccountId } = event.account ?? {}
  const userId = accountsToUsers.get(provider + ':' + externalAccountId)
  // …hand event.data to that user's inbox, calendar or CRM
  res.sendStatus(200)
})
// The provider's account id is also on the X-Repull-Account header,
// so you can shard before parsing the body.

Os dois funcionam tecnicamente. O segundo é mesmo melhor num caso: um cliente suficientemente grande para querer a sua própria relação, a sua própria fatura e a sua própria continuidade se um dia deixar o teu produto. Para todos os outros, o primeiro tem menos atrito e menos credenciais na tua base de dados.

Configuras uma vez em /dashboard/settings/connect e aplica-se a todos os canais que os teus utilizadores ligam. O fluxo em si tem a mesma forma do Stripe Connect ou do Plaid Link: o teu servidor cria uma sessão e lê um estado, e nunca toca numa credencial de canal.

• Pagina com cursores. Os endpoints de listagem pesados são paginados por chave, por isso o custo por página mantém-se constante por mais fundo que vás. ?offset= existe como alias para paginação curta e é a ferramenta errada para uma passagem completa.
• Escreve em lote. PATCH /v1/availability/batch para valores de calendário em muitas propriedades, POST /v1/listings/pricing/bulk para decisões de preço e POST /v1/listings/status para a ativação. Uma chamada, muitas propriedades, com as falhas parciais reportadas item a item em vez de fazer falhar o lote.
• Envia uma chave de idempotência. Toda a escrita que cria algo aceita Idempotency-Key. Com volume de plataforma, um timeout não é um caso raro: é uma terça-feira qualquer.
• Subscreve, não consultes. Um endpoint POST /v1/webhooks para o teu espaço de trabalho, com registo de entregas, reenvio e um endpoint de teste por tipo de evento, para construíres o handler antes do primeiro evento real.

# What is connected, for a support screen.
curl https://api.repull.dev/v1/connect \
  -H 'Authorization: Bearer sk_live_...'

# What this workspace has consumed, for your own metering.
curl https://api.repull.dev/v1/usage/summary \
  -H 'Authorization: Bearer sk_live_...'

Não haver nenhum número nesta página não é timidez. Os acordos com plataformas variam numa ordem de grandeza conforme quantos clientes finais há por trás, que canais usam e quem assegura o suporte de primeira linha, e um número publicado para um desses casos é ativamente enganador para os outros. O que podes verificar tu mesmo antes de qualquer conversa é o consumo: os endpoints de utilização mostram o que um espaço de trabalho usou e a que tem direito, por isso podes modelar a tua própria economia com números reais em vez dos nossos.

1. 1Regista-te uma vez. O teu espaço de trabalho e a sua chave de API são as únicas credenciais da Repull no teu sistema; guarda a chave nos teus servidores.
2. 2Para cada utilizador, cria uma sessão do Connect com POST /v1/connect, limitando allowedProviders aos canais que o teu produto suporta.
3. 3Passa o teu id de utilizador como state. Quando termina, connect.session.completed devolve esse state com a conta que ligou: guarda a conta associada ao utilizador.
4. 4Subscreve um endpoint de webhook com POST /v1/webhooks e encaminha cada evento pelo seu bloco account. Usa os endpoints de teste e de reenvio para construíres o handler antes de chegar um evento real.
5. 5Lê através dos endpoints entre canais sempre que puderes, para que adicionar um canal mais tarde seja uma alteração de configuração e não uma reescrita.

A versão técnica mais aprofundada — autenticação, tipos de eventos de webhook, sandbox, cobertura por canal — está nas perguntas e respostas para plataformas SaaS. O detalhe canal a canal está nos guias do Airbnb, do Booking.com e do Vrbo, e a referência completa está na documentação.

A maioria das plataformas herda o que os seus clientes já usam, o que na prática significa vários sistemas de gestão de propriedades e não apenas um. Cada um tem o seu modelo de autenticação, os seus nomes de campos e os seus limites: os guias do Guesty, Hostaway, Hospitable, Lodgify, OwnerRez, Smoobu e Beds24 explicam o que cada sistema expõe e o que te custa mantê-lo, e a matriz de cobertura compara-os lado a lado.