Repull para plataformas SaaS: 20 perguntas, respondidas

Sim. É exatamente para isto que o fluxo Connect alojado foi feito: cada um dos teus utilizadores finais autoriza a sua própria conta de canal (por exemplo, a sua própria conta de anfitrião do Airbnb) no teu espaço de trabalho da Repull. Cada conta ligada tem o seu próprio acompanhamento, os seus próprios tokens e a sua própria monitorização de estado.

Docs: Connect (multicanal), OAuth Connect, Connect Widget.

Não há limite técnico de contas ligadas. Os planos são cobrados por anúncio: o Free cobre até 3 anúncios, o Starter custa 99 $/mês com 10 anúncios incluídos e 5 $ por anúncio a partir do 11.º até 100, e acima de 100 anúncios (onde chega uma plataforma que serve muitos anfitriões) é um plano Custom com preço por volume e um único espaço de trabalho de parceiro para todos os teus clientes.

Docs: Preços, Repull para plataformas.

Sim. Os tokens de acesso e de atualização ficam guardados por conta ligada, totalmente isolados. Se um utilizador revogar o acesso, só a conta dele é afetada: recebes um webhook account.disconnected para essa conta com um motivo legível por máquina, e todas as outras continuam a sincronizar.

Sim. Passa o teu id interno de utilizador como state ao criar a sessão do Connect. Quando o utilizador termina, o webhook connect.session.completed devolve-te esse state juntamente com a conta ligada, por isso associas os dois uma única vez. A partir daí, cada entrega de webhook traz um bloco account (provider e externalAccountId, o id do próprio fornecedor) e os cabeçalhos X-Repull-Account e X-Repull-Account-Id, e as reservas, conversas e avaliações trazem a mesma conta em cada registo.

Docs: OAuth Connect, Webhooks.

Sim. GET /v1/connect lista todas as ligações do teu espaço de trabalho (id, fornecedor, estado, id da conta externa). Existe também um endpoint de estado dedicado por canal, por exemplo GET /v1/channels/airbnb/connection, que devolve cada conta do Airbnb ligada com o seu estado e o motivo da última desligação, pensado para ser consultado a partir de um ecrã de estado.

Docs: Referência da API, Connect.

Sim, tal e qual:

1. 1POST /v1/connect devolve o URL de uma sessão alojada (validade de 30 minutos)
2. 2Redirecionas o teu utilizador para lá
3. 3O utilizador autoriza o Airbnb (ou escolhe outro canal no seletor)
4. 4O utilizador volta ao teu redirectUrl com status=connected&accountId=… e o teu state
5. 5Disparam os webhooks account.created e connect.session.completed
6. 6A ligação está ativa; a sincronização inicial arranca sozinha em segundo plano
7. 7Lês os dados pela API e recebes webhooks contínuos

Docs: Connect, Quickstart.

Sim, do início ao fim: o início de sessão no Airbnb, a gestão de permissões e scopes (só leitura, mensagens ou acesso total), a troca de tokens, os tokens de atualização e a expiração são tratados pela Repull. Quando uma atualização é rejeitada ou o acesso é revogado na origem, a conta é sinalizada e recebes account.disconnected com um motivo (refresh_token_rejected, auth_expired, revoked_upstream, manual_disconnect) para poderes levar o utilizador de volta ao mesmo fluxo alojado e voltar a autenticar-se.

Docs: Canal Airbnb.

Sim. Não há uma sandbox à parte: cada conta recebe uma chave sk_live_* no registo (plano gratuito, sem cartão), por isso testas diretamente contra a API real: crias propriedades, reservas e subscrições de webhook reais e apagas tudo quando terminares. O sistema de webhooks tem ferramentas de teste próprias: POST /v1/webhooks/{id}/test/{event_type} dispara payloads de exemplo realistas para qualquer tipo de evento, além de endpoints de ping e reenvio e registos completos de entregas.

Uma ressalva honesta: o Airbnb não oferece contas de anfitrião de sandbox, por isso um teste OAuth completo precisa de um início de sessão real no Airbnb, seja qual for o ambiente. Tudo o que vem depois (webhooks, formatos de dados, tratamento de erros) testa-se por completo com eventos de exemplo, sem ligação real ao Airbnb.

Docs: Gerir webhooks.

Sim.As páginas Connect alojadas são em marca branca por espaço de trabalho: nome da app, logótipo (versões clara e escura), cores principal e de destaque para os dois temas, email de suporte no rodapé, os teus próprios URLs de termos e privacidade, um URL de redirecionamento por defeito e um idioma por defeito. O URL continua em connect.repull.dev e a página tem uma ligação “Powered by Repull”.

Docs: Connect Widget.

Sim. Um utilizador pode ter várias ligações ao mesmo tempo (Airbnb, Booking.com, Vrbo e um PMS), e um espaço de trabalho pode ter muitas contas por canal: muitos anfitriões do Airbnb, muitas propriedades do Booking.com, muitas contas do Vrbo. O único limite hoje é uma ligação por sistema de gestão de propriedades por espaço de trabalho. A sessão alojada pode mostrar um seletor multicanal ou ficar limitada a fornecedores específicos com allowedProviders.

Docs: Connect (multicanal), Cobertura de PMS.

Sim. DELETE /v1/connect/{provider} revoga o token OAuth quando o canal o permite, apaga as credenciais guardadas e para todas as tarefas de sincronização dessa ligação. Passa um accountId para desligar uma conta sem mexer nas outras do mesmo canal.

Sim. GET /v1/listings tem paginação por cursor e filtra-se com ?channel=airbnb|booking|vrbo. Cada anúncio traz um array channels[] com a plataforma, o id original da propriedade no canal (externalId) e o estado de ativação e sincronização, por isso sabes sempre a que canal pertence cada propriedade e qual é o seu id nativo. Expansões opcionais com ?include=content,details,amenities.

Docs: Listar propriedades, Detalhes da propriedade, Conteúdo e detalhes do anúncio.

Airbnb: sim, com POST /v1/reviews/{id}/reply, quando o anfitrião se ligou com acesso total. O Airbnb só permite escrever em avaliações com a sua permissão de gestão de propriedades, por isso as ligações só de leitura e de mensagens leem avaliações mas não lhes respondem. Booking.com e Vrbo: em teste. As respostas passam pelo mesmo endpoint, mas ainda não foram comprovadas numa avaliação real.

Docs: Avaliações, OAuth Connect.

Sim. GET /v1/reviews é um fluxo unificado de avaliações de todos os canais (Airbnb, Booking.com, Vrbo) com filtros por plataforma, anúncio, intervalo de classificação, respondidas ou por responder, e avaliações de hóspede ou de anfitrião. As atualizações, incluindo as respostas do anfitrião, refletem-se nos mesmos registos.

Os webhooks review.created e review.responded avisam-te quando chega uma avaliação ou quando recebe resposta. O endpoint é servido a partir da nossa base de dados, nunca de uma chamada em direto ao canal, por isso consultá-lo também sai barato.

Docs: Listar avaliações.

O catálogo atualizado está em Tipos de eventos de webhook e em formato legível por máquina em GET /v1/webhooks/event-types (com payloads de exemplo). Eventos atuais:

As entregas são assinadas com HMAC-SHA256 (ao estilo do Stripe), com novas tentativas, reenvio e registos completos: Verificar assinaturas, Novas tentativas, Gerir webhooks.

As sincronizações são tarefas em segundo plano. Ligar uma conta lança em paralelo vários pipelines (anúncios, calendário e preços, mensagens, avaliações, transações) na nossa infraestrutura de filas; não tens de gerir nada disso. A duração da sincronização inicial depende sobretudo dos limites do próprio canal, por isso cresce com o tamanho da conta: as carteiras grandes terminam em segundo plano enquanto a ligação já está utilizável.

As leituras têm paginação por cursor até 100 itens por página (estável a qualquer profundidade), por isso 100 000 avaliações são cerca de 1000 chamadas, nada face ao limite por defeito de 600 pedidos por minuto. As alterações chegam por webhooks, por isso nunca tens de voltar a percorrer tudo.

Docs: Limites de pedidos, Idempotência.

São sincronizados. A Repull sincroniza os dados dos canais na nossa própria base de dados e serve a API a partir daí. É uma decisão de desenho central: leituras rápidas e consistentes que nunca ficam bloqueadas pela API do Airbnb nem esbarram nos seus limites, e a tua app continua a funcionar mesmo quando a origem falha. As respostas incluem um bloco data_freshness (last_synced_at, indicador de dados desatualizados) para saberes sempre quão frescos estão os dados.

Por anúncio, com uma quota de chamadas à API por plano, não por reserva, avaliação, webhook ou conta ligada. Free: 0 $, até 3 anúncios, 1000 chamadas/mês. Starter: 99 $/mês, 10 anúncios incluídos, 5 $ por anúncio a partir do 11.º até 100, 100 000 chamadas/mês, webhooks incluídos. Custom: mais de 100 anúncios com preço por volume e limites de API à medida da tua integração.

Docs: Preços, Créditos e utilização.

Isso é território do plano Custom. O preço a essa escala depende dos anúncios por utilizador e do volume de API, e tratamo-lo como uma parceria de plataforma, não como uma tarifa por lugar. Envia-nos os teus números e recebes uma proposta concreta: como funcionam os preços para plataformas.

O Starter inclui suporte por email; o Custom inclui suporte prioritário por email e, para uma integração de plataforma grande, podemos abrir um canal partilhado com a nossa equipa de engenharia.

No dia a dia, a API foi pensada para te desenrascares sozinho: cada resposta de erro traz um request_id, um código legível por máquina, um campo fix com o passo seguinte exato e uma ligação direta para a documentação de erros.