API aberta do Guesty: Guia rápido e solução de problemas

Este guia destina-se a desenvolvedores que estão integrando a API aberta da Guesty pela primeira vez. Referência completa: open-api-docs.guesty.com

Início rápido

1. Obtenha suas credenciais

Comece por garantir que a sua conta Guesty tenha acesso à API aberta. Você precisará obter suas credenciais OAuth: client_id e client_secret. Para obter instruções passo a passo, consulte a seção 'Vamos começar'.

2. Autenticar

Troque suas credenciais por um token de portador: POST https://open-api.guesty.com/oauth2/token com grant_type=client_credentials, scope=open-api, client_id, e client_secret. O token é válido por 24 horas.

Mantenha seu token seguro e monitore sua expiração. Cada client_id pode solicitar um novo token até cinco vezes em 24 horas. Se você atingir esse limite, não poderá obter um novo token até que o período seja reiniciado. Para evitar problemas, planeje atualizar seu token alguns minutos antes de ele expirar. Para exemplos de código em Node.js, Python e PHP, consulte a receita de Gestão de Token de Acesso. Para mais detalhes, consulte Autenticação.

3. Faça sua primeira chamada

Envie o token como um cabeçalho Bearer em todas as solicitações:

GET https://open-api.guesty.com/v1/listings Authorization: Bearer {access_token}

4. Gerenciar paginação

A maioria dos endpoints usa os parâmetros de consulta limit e skip para paginação e retorna items, count, limit, e skip na resposta. Alguns endpoints podem usar offset ou cursor, ou retornar um formato de resposta diferente. Se os parâmetros padrão não funcionarem, avalie a página de referência do endpoint específico. Por exemplo:

offset Em vez de skip: GET /properties-api/groups/group
cursor-baseado em: GET /communication/conversations, GET /communication/conversations/{conversationId}/posts
results + um aninhado pagination objeto: GET /reservations-v3/search (o mesmo endpoint de pesquisa de Reservas v3 usado em outras partes deste guia)
results/count em vez de items/count: GET /vendors, GET /users, GET /property-logs/{id}

Solução de problemas e perguntas frequentes

Antes de tentar novamente uma solicitação, verifique o código de status. Somente os erros 429 e 5xx devem ser repetidos automaticamente. Outros códigos de status indicam que a solicitação precisa ser modificada antes de ser tentada novamente.

Por código de resposta

401/403 — "Não autorizado" logo após a autenticação: Seu token expirou (eles duram 24 horas) ou não foi enviado corretamente. Observação: a API do Guesty retorna um 403 mesmo quando a mensagem indica "Não autorizado" — isso é esperado e não é um bug do seu lado. Solução: autentique-se novamente e armazene o token em cache; confirme se o cabeçalho está exatamente Authorization: Bearer <token>. O endpoint do token também expõe os cabeçalhos x-ratelimit-remaining-day / x-ratelimit-limit-day caso você queira monitorar seu limite diário de tokens diretamente. Mais informações: Autenticação.

404 — recurso não encontrado, mas o ID parece correto: Normalmente, o ID pertence a uma conta/escopo diferente do seu token, ou o registro ainda não foi sincronizado, ou vem de um canal com visibilidade limitada da API. Confirme o ID no painel de controle da mesma conta à qual suas credenciais pertencem. Por exemplo, GET /reservations-v3/group/{groupId} retorna 404 tanto para um ID aparentemente válido em uma conta incorreta quanto para um ID inexistente. Mais informações: Códigos de Resposta.

410 — Cotação expirada: As cotações têm um prazo de validade fixo. Após expirar, essa cotação não pode ser modificada ou reservada — crie uma nova em vez de tentar novamente com o ID antigo.

400 / 422 — erro de validação: Verifique o corpo da requisição em relação ao esquema do endpoint na página de referência. As respostas de erro do Guesty não seguem um formato consistente em toda a API — algumas aninham campos em `erro, outras não, e os nomes dos campos variam — portanto, não assuma que o nome de um campo de erro de um endpoint se aplica a outro. Por exemplo, POST /reservations-v3 ( reserva rápida) retorna tanto o código 400 quanto 422 dependendo se a própria requisição está malformada ou viola uma regra de reserva (por exemplo, datas indisponíveis) — verifique qual código você recebeu antes de presumir a correção.

429 — Limite de tarifa: Isso significa que você atingiu o limite de toda a conta de 15 solicitações por segundo, 120 por minuto ou 5.000 por hora, compartilhado entre todos os tokens. Aguarde o tempo especificado no cabeçalho Retry-After antes de enviar outra solicitação. Monitore os cabeçalhos X-RateLimit-Remaining-Second, X-RateLimit-Remaining-Minute, e X-RateLimit-Remaining-Hour para acompanhar seu uso. Você também pode ver os cabeçalhos ratelimit-limit, ratelimit-remaining, e ratelimit-reset, que refletem a janela por segundo. Antes de solicitar um limite maior, considere o processamento em lote, o armazenamento em cache, a filtragem ou o uso de webhooks para otimizar sua integração. Se você perceber um limite menor após um uso excessivo prolongado, isso pode indicar que um aumento anterior foi revertido. Para obter mais detalhes, consulte Limites de Tarifa.

"Não consigo criar outro aplicativo OAuth / client_id": Este é um limite separado — o número de aplicativos OAuth por conta é cinco — distinto do limite de taxa de solicitações mencionado acima. Se precisar de mais, entre em contato com o suporte e explique seu caso.

5xx — erro do servidor: Tente novamente com espera exponencial e intervalo de tempo variável (jitter) em vez de iniciar um loop imediatamente. A maioria dos erros 5xx são transitórios; se um endpoint falhar repetidamente, inclua o cabeçalho de resposta x-request-id ao entrar em contato com o suporte. Exceção: para uma solicitação de pagamento ou alteração de reserva, verifique primeiro o status real resultante — não tente novamente cegamente, ou você corre o risco de cobrar o hóspede duas vezes. Mais informações: Como lidar com solicitações com falha.

Por sintoma

Se uma reserva ou Anúncio não aparecer nos resultados da sua busca ou listagem, verifique primeiro os parâmetros de filtro e escopo. Essa é a causa mais comum. Para registros recentes, aguarde a sincronização, especialmente para reservas de canais como Airbnb, Vrbo ou Booking.com. É exatamente para isso que serve GET /reservations-v3/search — confirme se você está usando-o (com os parâmetros filter[...] corretos) em vez de um endpoint mais antigo ou com escopo mais restrito. Se o registro ainda estiver faltando, entre em contato com o suporte com o ID específico e a solicitação exata que você utilizou.

Se o seu webhook não estiver sendo disparado ou se você não conseguir se inscrever em um, verifique o seguinte: (1) Confirme se você está inscrito no nome de evento v2 correto, pois os webhooks legados e v2 não são intercambiáveis. (2) Certifique-se de que seu endpoint retorne uma resposta 2xx, pois o Guesty interromperá as tentativas caso contrário. (3) Em contas de teste ou sandbox, verifique se a inscrição foi criada com sucesso. A entrega pode sofrer atrasos durante períodos de alta demanda. O evento listing.calendar.updated é acionado apenas para edições diretas no calendário, tarifa ou estadia mínima, não para reservas novas ou alteradas. Para verificar a autenticidade de um webhook, recupere o segredo de assinatura do seu endpoint usando GET /webhooks-v2/secret. Para obter mais informações, consulte a Visão geral dos webhooks.

Se você atualizou o título ou a descrição de um anúncio por meio da API e não vê a alteração no Airbnb, verifique se o campo foi editado diretamente no Airbnb. Caso tenha sido, o Airbnb bloqueia o campo e as atualizações da API não serão sincronizadas até que você o desbloqueie no Airbnb. Atualizações feitas usando PUT /marketing/description-sets/{id} ou POST /marketing/description-sets não serão sincronizadas com o Airbnb até que o campo seja desbloqueado. Outros canais, como Booking.com e Vrbo, podem ter requisitos semelhantes. Para obter mais informações, consulte Campos de Marketing e Traduções.

O GuestyPay retorna 402 ERR_BAD_REQUEST: Se a resposta incluir "A solicitação contradiz a configuração da interface de limpeza" ou "Desconexão inválida do Bin ou anfitrião", a própria conta do GuestyPay apresenta um problema de configuração ou está offline — isso não é algo que você possa corrigir na sua integração. Entre em contato com a Experiência do Cliente.

O formato do erro não corresponde ao que vi em outro endpoint: Esperado — não há um único envelope error em toda a API. Embora um padrão seja o mais comum: uma mensagem aninhada sob uma única chave de erro, por exemplo, GET /accounting-api/reservations/{id}/balance → {"error": {"message": "...", "status": 404}}. No entanto, isso não é universal — alguns endpoints são planos, com a mensagem como um array de strings (GET /guest-folio/invoice-items → {"statusCode": 400, "message": [...]}), e alguns incluem seu próprio campo requestId no corpo da requisição, separado do cabeçalho x-request-id (GET /availability-pricing/api/calendar/listings/{id}). Um bom número de endpoints não documenta o formato do corpo do erro — apenas uma descrição em texto. Em vez de codificar um formato específico, verifique o esquema de erro documentado do endpoint em vez de usar um formato predefinido.

Preciso de uma "conta de teste" ou de uma "conta sandbox"? Aqui vai uma regra prática: use uma conta de teste para quase toda a integração e desenvolvimento iniciais, a menos que você esteja testando especificamente fluxos relacionados ao Stripe, caso em que precisará de um ambiente sandbox. Use o ambiente de produção somente quando estiver pronto para entrar em operação com dados reais. As contas de teste são o padrão para novas solicitações de integração e funcionam exatamente como o seu ambiente de produção, apenas com dados de teste separados. Os ambientes sandbox são ambientes separados (procure por "sandbox" na URL) usados para testes de integração com o Stripe, pois o Guesty não aceita chaves de teste do Stripe em contas de produção ou de teste regulares. O GuestyPay não possui um ambiente de teste — ele funciona apenas em produção, portanto, você deve usar um cartão real para testar o GuestyPay, independentemente do tipo de conta que estiver usando.

Uma conta de teste é um recurso adicional pago e é separada do seu ambiente de produção. Os dados não são transferidos do ambiente de produção, portanto, você precisará configurar anúncios, reservas e outras informações do zero. Para obter uma conta de teste, entre em contato com seu gerenciador de contas.

Servidor MCP (Beta)

O Guesty MCP Server permite que assistentes de IA compatíveis com MCP — atualmente Cursor, Claude Desktop, VS Code (Copilot) e Google Antigravity — leiam dados do Guesty por meio de uma interface de ferramenta controlada. Na versão beta, o recurso é somente leitura: os assistentes podem consultar e resumir dados, mas ainda não podem criar, atualizar ou excluir registros. A compatibilidade com outras ferramentas ainda pode mudar antes da disponibilidade geral.

Conectando

Atualmente, você pode se conectar usando o método local ou hospedado. Uma implantação totalmente gerenciada com credenciais fornecidas automaticamente ainda não está disponível.

Local (stdio, recomendado): Execute usando npx -y @guestyorg/sdk mcp. Você pode usar uma variável de ambiente BEARER_TOKEN para um token de acesso estático ou as variáveis de ambiente CLIENT_ID e CLIENT_SECRET. O servidor MCP trocará essas credenciais para você, portanto, nenhuma etapa manual de token é necessária.
Hospedado (HTTP, https://mcp.guesty.com/v1): Autentique-se usando um cabeçalho Authorization no início da sessão ou use a ferramenta set_token após a conexão.

Solução de problemas

Erro 401 em todas as chamadas de ferramentas: Isso indica que nenhum token foi definido. Para conexões hospedadas ou HTTP, certifique-se de definir o token usando set_token ou o cabeçalho Authorization antes de usar qualquer outra ferramenta.

Erro 403, inconsistente: Este erro pode ocorrer com tokens expirados ou quando os clientes OAuth possuem escopos para acesso à API Open padrão, mas não para MCP. Primeiro, autentique-se novamente com um novo token. Se o problema persistir, confirme se o cliente OAuth possui escopos MCP provisionados, além do acesso à API Open v1.

Conectado via Claude.ai (web), mas nenhuma ferramenta aparece: Claude.ai web não é um cliente suportado no momento. Adicioná-lo como um conector somente de URL faz com que ele use a descoberta OAuth por padrão, que este servidor não suporta. Use um cliente compatível através do stdio para obter todas as funcionalidades.

Problemas com limite de requisições ou erros 401 repetidos após reiniciar o MCP: Ao usar CLIENT_ID e CLIENT_SECRET, cada reinicialização solicita um novo token, o que conta para o limite de 5 tokens por 24 horas. Para evitar isso, reutilize um token em cache entre as reinicializações ou use um BEARER_TOKEN estático, que não requer troca adicional.

Se os resultados da reserva ou lançamento contábil estiverem incompletos, confirme se você está usando a v3 Search Reservations tool, que suporta filter[confirmationCode]. A ferramenta de busca antiga está sendo descontinuada e pode não retornar todos os resultados. Para consultas de lançamentos contábeis (Get recognized journal entries / Get all journal entries), se você continuar vendo resultados inesperados, abra um ticket com informações detalhadas.

Pedi ao assistente para criar, atualizar ou cancelar algo, e ele não fez isso: Comportamento esperado na versão beta — o servidor MCP está em modo somente leitura por enquanto.

Abrir um ticket

Primeiro, verifique seu próprio sistema. A Guesty não consegue diagnosticar problemas em aplicativos externos. Se o problema estiver no seu código, peça ao seu desenvolvedor web ou fornecedor técnico para avaliá-lo antes de entrar em contato com a Guesty. Se um parceiro do marketplace criou sua integração, entre em contato com ele primeiro. Ele entrará em contato com a Guesty, se necessário.

Depois de descartar problemas da sua parte, entre em contato com a Experiência do Cliente ou use o Chat ao Vivo. Ambos estão disponíveis no Painel de Controle da Guesty e no Centro de Ajuda. Fornecer contexto nos ajuda a resolver seu problema mais rapidamente, portanto, inclua:

O que você estava tentando realizar (o objetivo real, não apenas a chamada que falhou — por exemplo, "sincronizar o status de pagamento de uma nova reserva", não apenas "POST retornou 422")
Os passos que levaram ao erro, em ordem, para que o suporte possa reproduzi-lo — não apenas a solicitação final que falhou.
Quando aconteceu — um registro de data e hora exato, se tiver; caso contrário, uma data ou intervalo de datas; esta é uma das informações mais úteis que você pode fornecer.
O URL e o método de requisição completos no formato cURL.
A mensagem de erro exata e o código de status.
O valor do cabeçalho de resposta x-request-id
O cabeçalho x-gst-kong-dc, se presente (ajuda a identificar qual centro de dados atendeu à solicitação).
Informar se esse comportamento é novo ou se sempre falhou.
Para problemas com o MCP: qual cliente e modo de conexão (stdio/HTTP) e se a autenticação foi feita via BEARER_TOKEN, CLIENT_ID/CLIENT_SECRET ou set_token

Para leitura adicional

Relativo a:

GFP: Open Api