Guia de Instalação e Utilização do Syncfaro

1. Visão geral e requisitos

O Syncfaro é um plugin WordPress que liga o MotoPress Hotel Booking ao Channex.io, uma plataforma certificada de channel management que distribui para Booking.com, Airbnb, Expedia e mais de 60 canais. Depois de configurado, o Syncfaro mantém preços, disponibilidade, estadia mínima e reservas sincronizados, nos dois sentidos, automaticamente.

Como funciona, num parágrafo

O Syncfaro escuta o que acontece de facto no seu site: uma reserva é criada, o preço de uma temporada muda, uma regra de estadia mínima é editada. Recalcula apenas as datas afectadas e envia só as alterações ao Channex (nunca fotografias completas), respeitando os limites de pedidos do Channex. As reservas feitas em qualquer canal entram no MotoPress como reservas nativas, e a disponibilidade actualiza-se em todo o lado.

Requisitos

• WordPress com o MotoPress Hotel Booking instalado e configurado (tipos de alojamento, tarifas, temporadas).
• PHP 8.0 ou mais recente.
• Uma conta Channex com uma propriedade criada (quartos e planos de tarifa que correspondam à estrutura do MotoPress).
• A sua chave de API do Channex.

2. Instalação

1. No WordPress, vá a Plugins → Adicionar novo → Carregar plugin.
2. Carregue o ficheiro .zip do Syncfaro e clique em Instalar agora.
3. Clique em Activar. Aparece uma nova entrada Syncfaro no menu lateral do administrador.
4. Introduza a sua chave de licença quando for pedida (recebeu-a com a compra). A licença, o plano e a data de renovação ficam visíveis em Syncfaro → Account.

Actualizações

As actualizações chegam automaticamente através da licença e aparecem no ecrã normal de actualizações do WordPress. Se uma versão nova foi anunciada mas ainda não aparece na lista de Plugins, abra Syncfaro → Account: a versão actual está lá indicada com um botão Install Update Now que a descarrega directamente.

3. Ligar ao Channex

Abra a página de administração do Syncfaro e preencha a secção Connection:

1. Cole a sua chave de API do Channex.
2. Seleccione ou cole o Property ID da sua propriedade no Channex.
3. Guarde. Use Probe Channex para confirmar a ligação: lista os quartos e os planos de tarifa encontrados na propriedade.

Uma definição obrigatória no Channex

Nas definições da propriedade no Channex, ponha o Min Stay Type em arrival. O Syncfaro gere a estadia mínima como min-stay arrival e envia-a com a chave simplificada min_stay, que é o que o Channex espera neste modo.

Definições recomendadas da propriedade no Channex

• Min Stay Type: arrival (obrigatório, ver acima).
• Auto Availability: New Booking ON, Modified OFF, Cancelled OFF. O Syncfaro trata ele próprio das modificações e cancelamentos, e o Channex não deve interferir.
• Email de contacto da propriedade: preenchido (Properties → Contacts), para o Channex o poder contactar se for preciso.

Modo dry-run

Enquanto testa, pode activar o dry-run: o Syncfaro prepara cada actualização e escreve o payload exacto no Registo de Actividade, mas nada é enviado ao Channex. Desligue-o para entrar em produção.

4. Mapear quartos e tarifas

A secção Mapping mostra, de um lado, os tipos de alojamento do MotoPress e as suas tarifas e, do outro, listas com os quartos e os planos de tarifa do Channex.

1. Para cada tipo de alojamento do MotoPress, escolha o room type correspondente no Channex.
2. Para cada tarifa do MotoPress, escolha o rate plan correspondente no Channex.
3. Guarde o mapeamento.

Só os quartos e tarifas mapeados são sincronizados. O que ficar por mapear é simplesmente ignorado, o que é útil se alguns produtos devem ficar fora dos canais.

5. Preços por pessoa (OBP)

Muitos alojamentos locais cobram por ocupação: um preço base para, por exemplo, 2 pessoas, mais um valor fixo por cada pessoa extra. O MotoPress suporta isto nativamente (ocupação base + preço por adulto extra nos preços de temporada da tarifa). O Channex chama-lhe Occupancy-Based Pricing e modela-o com um rate plan per_person cujas opções de ocupação derivam de uma ocupação primária.

O Syncfaro faz a ponte entre os dois automaticamente, em três passos.

1. Detecção

Quando uma tarifa mapeada do MotoPress tem preço por pessoa extra, o Syncfaro reconhece-a como OBP e mostra uma linha azul por baixo da tarifa na tabela de Mapping com a estrutura detectada, por exemplo: OBP · base 2 + 58,00€/extra guest · 1p: +0 · 2p: +0 · 3p: +58 · 4p: +116 · 5p: +174 · 6p: +232. Os incrementos são acumulados, um por ocupação, exactamente como o Channex espera. As tarifas de preço fixo não mostram nada e não são afectadas.

2. Diagnóstico

Por baixo dessa linha, o Syncfaro lê o rate plan mapeado no Channex e diz-lhe se corresponde:

• Channex rate plan OK (per_person, increments match): nada a fazer, os preços por pessoa chegam aos canais.
• NOT per_person: o rate plan vende um preço fixo, por isso os valores por pessoa extra não chegam aos canais.
• Mismatch: é per_person mas algum incremento ou a ocupação primária difere do MotoPress.

A mesma verificação corre em cada full sync e escreve linhas obp_ok ou obp_warning no Registo de Actividade.

3. Apply OBP to Channex (um clique)

Quando o diagnóstico não está verde, aparece um botão Apply OBP to Channex. Cria um rate plan per_person novo no Channex (com o nome da sua tarifa e "(OBP)" no fim) com as ocupações e incrementos exactos detectados, verifica-o relendo-o, e aponta o mapeamento dessa tarifa ao plano novo. Nada é alterado em silêncio: você confirma, e o resultado fica registado como obp_applied.

Como cada canal trata os preços por pessoa

• A Booking.com aplica-os nativamente: com a propriedade em modo "Pricing per guest", deriva todas as ocupações a partir do preço base que o Syncfaro envia. Nada mais a configurar.
• O Airbnb usa um preço único por anúncio mais uma taxa por hóspede extra. O Channex envia só o preço base. Defina a taxa por hóspede extra manualmente no anúncio do Airbnb (Pricing → Fees), como número inteiro: o seu valor por pessoa multiplicado pelo markup do canal, se existir (ex.: 58 × 1,20 ≈ 69). Limpe primeiro valores manuais antigos, e depois verifique com uma simulação real de reserva a 2, 3 e 4 pessoas.

6. Estadia mínima por tarifa

O Channex modela a estadia mínima por rate plan: dois planos do mesmo quarto podem ter valores diferentes. O MotoPress define-a por tipo de alojamento. O Syncfaro faz a ponte com as suas próprias regras de estadia mínima, uma funcionalidade que o MotoPress por si só não oferece.

Adicionar regras

1. Abra a secção Min-stay per rate plan da página do Syncfaro.
2. Clique em + Add rule por cada regra que precisar: escolha o rate plan, o intervalo de datas e o número mínimo de noites.
3. Acrescente as linhas que quiser e clique uma vez em Save min-stay rules. Todas as alterações são enviadas juntas numa única actualização.

Como as regras se comportam

• As datas sem regra levam min_stay 1 (sem restrição).
• Regras sobrepostas: a que estiver mais abaixo na lista ganha nas datas em comum.
• Apagar uma regra repõe automaticamente essas datas a 1 no Channex; não fica resíduo.
• Alterações de preço e de estadia mínima nas mesmas datas são enviadas fundidas numa só chamada, como o Channex exige.

7. Sincronização do dia-a-dia

Depois da configuração não há nada para operar. Trabalhe no MotoPress como sempre fez; o Syncfaro reage:

Cada evento e cada payload fica visível no Registo de Actividade no fundo da página do Syncfaro: o que entrou, o que foi calculado, o que foi enviado, e a resposta do Channex (incluindo o task ID). Se alguma vez se perguntar "isto sincronizou?", o registo responde num relance.

8. Full sync e o espelho de estado

Um full sync envia o quadro completo, 500 dias de disponibilidade, preços e restrições para todos os quartos e tarifas mapeados, em exactamente duas chamadas de API. Use o botão Full sync (500 days):

• logo a seguir a terminar a configuração inicial;
• depois de restaurar uma cópia de segurança ou de fazer alterações em massa fora do fluxo normal;
• sempre que quiser a tranquilidade de uma base limpa. Um full sync diário em segundo plano corre também automaticamente como rede de segurança.

O espelho de estado

O espelho é a memória do Syncfaro sobre o que o Channex já sabe. O botão Clear state mirror apaga essa memória, por isso o full sync seguinte reenvia absolutamente tudo.

Outros botões de manutenção

9. Receber reservas

As reservas feitas em qualquer canal ligado (Booking.com, Airbnb, …) viajam pelo Channex até ao seu site:

• Reserva nova: criada no MotoPress como reserva nativa, com quarto atribuído e marcada com o canal de origem. A disponibilidade actualiza-se automaticamente e é reenviada a todos os outros canais.
• Modificação: a reserva existente no MotoPress é actualizada no lugar, nunca duplicada.
• Cancelamento: a reserva é cancelada no MotoPress e as datas libertadas voltam a estar à venda em todo o lado.

Cada revisão processada é confirmada de volta ao Channex, para nada ser entregue duas vezes. Pode ver todas as reservas recebidas no Registo de Actividade, com o ID de reserva do Channex.

O que o Syncfaro faz com cada reserva de canal

• Pagamento registado como completo. O hóspede já pagou ao canal, por isso o Syncfaro regista na reserva do MotoPress um pagamento completo do valor total, identificado com o nome do canal. As regras de depósito do seu site (por exemplo "depósito de 50%" nas reservas directas) não são tocadas e continuam a aplicar-se só às reservas directas. Sem isto, o MotoPress mostraria as reservas de canal como "a pagar".
• Administrador avisado por email. Como as reservas de canal chegam já confirmadas, os emails de "nova reserva" do próprio MotoPress não disparariam. O Syncfaro dispara ele próprio a notificação de administrador, por isso recebe um email por cada reserva de canal, tal como nas directas. Cada reserva é notificada uma vez (procure admin_notified no Registo de Actividade).
• Origem e totais mantidos. A reserva traz o nome do canal, o ID de reserva do próprio canal e os valores, para poder conferir com o extranet.

10. Resolução de problemas

Os preços chegam errados por um factor de 100

O Channex espera valores em unidades menores (cêntimos): 333,00 viaja como 33300. O Syncfaro converte automaticamente; se um valor parecer errado, verifique se o preço original no MotoPress usa ponto como separador decimal (456.23, não 456,23).

Aparecem valores para o ano seguinte que nunca definiu

As temporadas do MotoPress repetem-se anualmente por omissão. Uma temporada para 15 Nov 2026 aplica-se silenciosamente também a 15 Nov 2027. Edite a temporada e desligue a recorrência anual se quiser que se aplique só a um ano.

Uma alteração não sincronizou

1. Veja o Registo de Actividade: há um evento para a sua alteração? Se diz "nothing changed since last send", o valor no Channex já está correcto (o espelho está a fazer o seu trabalho).
2. Se o item está em fila, clique em Process queue.
3. Para forçar o reenvio de um valor que já está no Channex: mude-o para outro, guarde, volte a pôr o original, guarde. O espelho detecta as duas edições.

O intervalo de disponibilidade parece um dia curto

Uma reserva do dia 10 ao dia 16 ocupa as noites de 10 a 15; o dia de check-out fica livre e continua à venda. É o comportamento hoteleiro padrão, não um erro de sincronização.

Actualizações de estadia mínima rejeitadas pelo Channex

Confirme que o Min Stay Type da propriedade no Channex está em arrival (ver secção 3).

Chegou uma reserva de canal mas não recebi email

Procure a reserva no Registo de Actividade: uma linha admin_notified significa que o Syncfaro disparou o email, e o problema está no envio de correio do seu site (teste com o "enviar email de teste" do seu plugin de SMTP). Se a linha não existir, confirme que tem a versão mais recente do Syncfaro. Como rede de segurança pode também ligar o email de notificação do próprio Channex no canal.

O webhook aparece desactivado no Channex

Algumas firewalls de alojamento bloqueiam os servidores do Channex, e o Channex desactiva um webhook após falhas repetidas. O Syncfaro verifica o webhook em cada execução agendada e reactiva-o automaticamente, e as reservas são também puxadas do feed em agenda, por isso nada se perde. Se continuar a acontecer, peça ao seu alojamento para permitir os endereços IP do Channex (listados na documentação do Channex) na firewall.

O canal Booking.com dá "Undefined Error" ao ser criado

A ordem importa. No extranet da Booking.com, aceite primeiro o Channex como fornecedor de conectividade (Conta → Fornecedor de conectividade, procure "Channex" e aceite a ligação XML). Só depois crie o canal Booking.com no Channex. Criar o canal primeiro produz este erro.

Os preços aparecem por pessoa na Expedia

Nas definições do rate plan da Expedia, "Occupants included" tem de ser igual à sua capacidade total. Se ficar em 1, a Expedia trata o seu preço como preço por pessoa.

Recomeçar do zero

Clear state mirror → Full sync (500 days). Isto reconstrói o Channex a partir da verdade dos seus dados no MotoPress e repõe o espelho. Lembre-se da regra de ouro: primeiro o full sync, depois as edições de preços.

11. Perguntas frequentes

O Syncfaro substitui as ligações iCal do MotoPress?

Sim, e deve removê-las nos canais geridos pelo Channex, senão terá dois sistemas a disputar os mesmos calendários. O Syncfaro sincroniza preços e restrições além da disponibilidade, o que o iCal não consegue.

Que canais posso alcançar?

Todos os que o Channex suporta: Booking.com, Airbnb, Expedia, VRBO e dezenas mais. A activação e o mapeamento dos canais do lado da OTA fazem-se no seu painel do Channex.

Posso sincronizar só alguns dos meus tipos de alojamento?

Sim. Só os quartos e tarifas mapeados sincronizam; deixe o resto por mapear.

O que acontece se o meu site estiver offline algum tempo?

O full sync diário realinha tudo assim que o site voltar. As revisões de reservas pendentes são puxadas e confirmadas no ciclo seguinte; nada se perde.

O Syncfaro sincroniza descontos de estadia longa (semanais, mensais)?

Não, e nenhum channel manager consegue: o Channex não expõe promoções por duração de estadia na sua API, e no Airbnb entram em conflito com os preços por rate plan. Configure-os em dois sítios: no seu site, o MotoPress permite definir um preço por noite diferente a partir de N noites dentro do preço de cada temporada (o "+" ao lado de Nights nos preços de temporada da tarifa); em cada canal, use o desconto semanal/mensal nativo (extranet da Booking.com, descontos do anúncio no Airbnb). O Syncfaro envia o preço base por noite; cada lado aplica o seu desconto.

Posso cobrar uma taxa de limpeza?

Sim, mas não é sincronizada, porque as taxas não fazem parte dos dados de disponibilidade/preços/restrições que um channel manager transporta. Defina-a no seu site (Services do MotoPress, como valor fixo obrigatório por reserva) e separadamente em cada canal (encargos no extranet da Booking.com, taxas do anúncio no Airbnb, taxas no VRBO). O mesmo se aplica a qualquer taxa por hóspede extra, impostos e extras semelhantes.

O Airbnb só me deixa escolher uma política de cancelamento reembolsável. Posso ser não reembolsável lá?

Não totalmente. O Airbnb exige sempre uma política base reembolsável (Flexível, Moderada, Firme, Rígida…) e oferece "não reembolsável" só como opção adicional com 10% de desconto. Para minimizar cancelamentos, escolha a política base mais rígida. A política define-se no Channex: abra o canal Airbnb → Listing → Actions do anúncio → Booking settings → Cancellation Policy Category. A Booking.com e a Expedia, pelo contrário, permitem uma única tarifa não reembolsável.

Os preços nos canais devem ser mais altos que no site (para cobrir a comissão). Como?

Defina um markup por canal no Channex (Channel Settings → Derived Rates → "Increase by percent", tipicamente +15% na Booking.com/Expedia e +5 a 10% no Airbnb). Aplique o markup antes de mapear os rate plans do canal, e volte a verificá-lo depois de activar o canal ou de concluir uma ligação OAuth, porque esses passos podem repô-lo. O Syncfaro envia sempre os preços base do seu site; o Channex acrescenta o markup.

Os preços têm de usar ponto, não vírgula

O MotoPress só aceita o ponto como separador decimal (456.23). A vírgula (456,23) é rejeitada pelo próprio campo do MotoPress e nunca chega ao Syncfaro.

Onde obtenho apoio?

Através da sua conta em syncfaro.com. Inclua as linhas relevantes do seu Registo de Actividade; costumam conter a história toda.