WellFred — Services in Costa Rica

npx add-mcp 'https://app.wellfred.com/api/agent/mcp'

Guia do agente WellFred

A WellFred conecta clientes a serviços e prestadores na Costa Rica. Agentes públicos podem pesquisar, navegar, inspecionar ofertas, enviar RFQs de visitante e preparar solicitações de reserva sem chave de integração.

Visão geral do cliente: Usando assistentes de IA na WellFred.

Índice de descoberta de habilidades de agentes publica a habilidade wellfred-services para download usando descoberta v0.2.0 e um resumo de artefato SHA-256.

Leia o contrato primeiro

Descoberta de autenticação e registro documenta o acesso anônimo de agentes, provisionamento de clientes e uso de credenciais para o handoff de verificação por e-mail.

JSON do OpenAPI contém os esquemas de solicitação e resposta gerados a partir do código do aplicativo. Referência da API renderiza esse mesmo contrato. Combine a URL do servidor com cada caminho de operação. Esses endpoints públicos ficam sob /api/agent. Envie Accept: application/json; corpos de POST usam Content-Type: application/json.

Catálogo da API (/.well-known/api-catalog, RFC 9727 application/linkset+json) vincula o contrato, a documentação e o endpoint de status desta API para descoberta automatizada.

Descoberta ACP lista os serviços REST públicos: descoberta de serviços, solicitações de cotação de visitante e intenções de reserva. Use o contrato OpenAPI vinculado para seus formatos de solicitação e resposta. Sessões de checkout ACP e processamento de pagamentos não são suportados; intenções de reserva exigem confirmação do cliente na WellFred.

Use apenas as operações listadas neste contrato público. Descoberta e RFQs não exigem conta; intenções de reserva retornam um link de confirmação para o cliente.

Agentes de navegador (WebMCP)

As páginas da WellFred expõem as mesmas operações públicas a navegadores compatíveis por meio de document.modelContext (ou navigator.modelContext onde esse é o local do navegador para isso). Nenhuma chave de integração ou conexão de conta é necessária. As entradas das ferramentas vêm do contrato OpenAPI gerado. O document.modelContext.executeTool() nativo serializa o objeto de resultado do callback em uma string JSON; analise-o uma vez para ler o resultado da API existente mais httpStatus e, quando fornecido, retryAfter.

Ferramenta	Operação pública
wellfred_search_services	POST /search
wellfred_list_categories	GET /categories
wellfred_resolve_location	GET /locations
wellfred_list_providers	GET /providers
wellfred_search_providers	GET /providers/search
wellfred_get_provider	POST /providers/profile
wellfred_check_availability	POST /availability
wellfred_get_quote_questions	POST /rfq/questions
wellfred_request_quotes	POST /rfqs
wellfred_prepare_booking	POST /booking-intents

O WebMCP usa o mesmo acesso público mesmo quando alguém está conectado. Ele não expõe reservas privadas, ferramentas de conta, pagamentos ou criação direta de reservas. A busca de prestadores aceita um array ids; o adaptador lida com a codificação de consulta HTTP. Solicitações de cotação exigem um idempotencyKey. Obtenha a permissão do cliente antes de enviar a solicitação; retorne links de confirmação de reserva para o cliente concluir na WellFred. Essas ferramentas não navegam nem concluem a confirmação em nome do cliente.

O cancelamento interrompe a solicitação do navegador, mas não pode desfazer o trabalho já recebido pelo servidor. Se uma resposta de escrita não estiver disponível, seu resultado é desconhecido: siga as orientações de nova tentativa abaixo. O adaptador nunca tenta novamente automaticamente. Navegadores sem WebMCP continuam usando o site regular e a API REST.

Encontre um serviço

Busca de descoberta A2A

O Cartão de Agente A2A anuncia a interface JSON-RPC em /api/agent/a2a. Use sua URL supportedInterfaces e versão de protocolo. Envie A2A-Version: 1.0 e Content-Type: application/json com uma solicitação JSON-RPC SendMessage contendo um id único e params.message (messageId, role: "ROLE_USER" e parts). Uma parte de texto como {"text":"massage"} fornece a consulta de busca; uma parte de dados carrega as restrições de busca estruturadas abaixo. Os resultados retornam em result.message.parts, com dados estruturados e uma recomendação em texto.

Esta interface suporta busca de descoberta síncrona. Operações de catálogo, RFQs e intenções de reserva usam as operações REST abaixo. Streaming, notificações push e Cartões de Agente estendidos não são suportados.

Busca de descoberta REST

• GET /categories: IDs de categoria e subcategoria para navegação.
• GET /locations?query=Uvita: locais candidatos com coordenadas. Resolva ambiguidades com o cliente. O centro de uma cidade é adequado para busca, não um endereço exato de reserva.
• POST /search: ofertas de serviços classificadas, seus prestadores, preços estruturados e uma breve recomendação. Omita query para navegar com filtros de categoria/local.
• GET /providers e GET /providers/search: navegue por prestadores ou resolva nomes/IDs de prestadores.
• POST /providers/profile: inspecione um prestador público por UUID comercial.
• POST /availability: inspecione os slots disponíveis de um serviço para uma data explícita. Serviços baseados em solicitação podem exigir um RFQ ou acompanhamento do prestador em vez de expor slots.

Interprete linguagem natural em restrições explícitas antes de buscar. A busca textual/semântica existente da WellFred classifica a necessidade do serviço; ela não extrai de forma confiável datas, moedas ou números de pessoas de prosa. Para "massagem móvel em Uvita amanhã para 2 pessoas, abaixo de ₡40k cada", resolva o local e a data de amanhã em America/Costa_Rica, então envie:

{
  "query": "massage",
  "delivery": "in-home",
  "partySize": 2,
  "maxPrice": 40000,
  "currency": "CRC",
  "priceUnit": "person",
  "limit": 5
}

Adicione lat, lng do local selecionado e date como YYYY-MM-DD. Nenhuma data de amostra ou coordenadas adivinhadas são padrões. Informe ao cliente a data real que você usou.

Filtros de moeda correspondem à moeda da oferta; eles não convertem preços. priceUnit distingue preços por pessoa de preços por sessão. price é o mesmo preço inicial que a página da oferta mostra, então citá-lo não contradirá a página para a qual você vincula; para uma oferta com opções, é a opção mais barata, e maxPrice filtra contra esse mesmo número. Um preço inicial não é uma cotação final. Verificações de data não estabelecem capacidade do grupo, e prestadores próximos não são prova de cobertura para um endereço exato. Explique requisitos não resolvidos em vez de afirmar que todas as restrições foram verificadas. Uma busca examina um conjunto limitado de candidatos classificados; um resultado filtrado vazio não é prova de que nenhum prestador existe.

A busca retorna até limit entradas comerciais distintas. Cada entrada mantém sua oferta representativa e um array alternativeOfferings com no máximo uma oferta primária correspondente adicional desse negócio. Cada oferta tem seu próprio ID, URL, preço, unidade e nextAction; estes são serviços separados, não opções de preço da oferta representativa. Buscas por data verificam a oferta adicional de forma independente. Se a verificação falhar, ela é omitida em vez de substituída por outro candidato.

matchQuality usa a classificação do marketplace: strong significa primário, loose significa relacionado e discovery significa sugestões de navegação/categoria. Isso descreve correspondência, não adequação, disponibilidade ou avaliação. Apresente ofertas primárias antes de sugestões relacionadas claramente rotuladas. strongResultCount conta ofertas primárias realmente retornadas, incluindo alternativas; não é um total de catálogo nem uma contagem de negócios.

Retorne algumas opções relevantes com suas URLs canônicas. Siga nextAction: serviços com opções devem ser abertos em sua página de oferta para seleção de opções; serviços suportados de oferta única podem usar intenções de reserva. Nunca invente IDs, cotações ou disponibilidade.

Solicitações de cotação de visitante

Um RFQ não precisa de conta de cliente:

1. POST /rfq/questions com requestedService ou subcategoryUuid. Use as chaves/opções de perguntas retornadas, IDs de taxonomia e as respostas do usuário. Nenhum conjunto de perguntas significa usar entrada de texto livre, não "serviço indisponível".
2. Colete nome, código do país do telefone e número de telefone, trabalho solicitado, local e horário. E-mail e orçamento são opcionais. Um orçamento fornecido exige uma moeda explícita.
3. Mostre o resumo da solicitação e obtenha permissão para enviá-la à WellFred para acompanhamento do prestador.
4. POST /rfqs. Preserve requestedService, taxonomia resolvida, respostas e qualquer preferredProviderUuid. Forneça um idempotencyKey e reutilize a mesma chave e payload em novas tentativas.
5. Dê ao cliente a referência retornada. Um RFQ inicia o acompanhamento de cotação assistido por equipe; não é um compromisso confirmado.

Exemplo de solicitação de texto livre após o cliente fornecer esses detalhes e autorizar o envio:

{
  "requestedService": "Repair a leaking kitchen pipe",
  "location": "Uvita",
  "timing": "The explicit date range agreed with the customer",
  "contactName": "Customer-provided name",
  "contactPhoneCountryCode": "+506",
  "contactPhoneNumber": "Customer-provided phone number",
  "idempotencyKey": "A unique identifier for this request"
}

Substitua os placeholders descritivos por valores reais fornecidos pelo usuário. Respostas de sucesso de RFQ contêm success, message, rfqUuid, reference e created no nível superior. created: false significa que o envio foi repetido.

Reserva com verificação por e-mail

1. Escolha uma oferta e um horário específico. Obtenha aprovação para a solicitação e preço/moeda conhecidos.
2. POST /booking-intents com serviceId, startIso (ISO 8601 com offset de fuso horário), partySize opcional e as coordenadas exatas origin do cliente para visitas domiciliares. Uma intenção é uma solicitação com expiração, não uma reserva ou um slot retido. A preparação repetida cria intenções separadas: reutilize o link de confirmação retornado em vez de preparar repetidamente.
3. Retorne confirmUrl ao cliente. Na WellFred, um cliente verificado existente pode confirmar diretamente. Caso contrário, o cliente fornece nome/e-mail e recebe o link de login seguro por e-mail existente. Uma conta gratuita é criada se necessário, com divulgação no formulário.
4. O link de e-mail retorna à solicitação salva. Somente o cliente verificado pode enviá-la. A WellFred reverifica horário e preço e usa o serviço de reserva normal. A confirmação repetida da mesma intenção retorna o mesmo resultado de reserva.
5. A página de confirmação relata o resultado. Uma solicitação pendente ainda precisa da aceitação do prestador. Nenhum pagamento é coletado por esta API.

Não peça senhas nem afirme que fornecer um e-mail prova propriedade. A API pública nunca retorna um token de login nem expõe o histórico de reservas do cliente. O e-mail e as etapas finais de confirmação ocorrem na WellFred; nenhuma conexão de conta ChatGPT é necessária para este handoff.

As regras de reserva existentes ainda se aplicam, incluindo requisitos de telefone verificado após a primeira reserva. Se uma intenção expirar, os preços mudarem ou a oferta precisar de seleção de opções, volte à oferta ou prepare uma nova solicitação e obtenha aprovação para os novos detalhes. Não substitua silenciosamente serviços ou preços.

Erros e novas tentativas

Cada operação responde no mesmo envelope: success mais message, com os campos próprios da operação ao lado deles no nível superior. Uma falha define success: false e nomeia o motivo em error_code — leia isso, não a prosa em message, ao ramificar.

Leia erros de validação JSON em 422 e corrija apenas as entradas inválidas. Respeite respostas 429 e Retry-After. As solicitações têm tamanhos limitados e limites de taxa. Um 503 com error_code: CONCIERGE_DAILY_CAP_REACHED significa que as operações de descoberta e perguntas de cotação estão pausadas pelo dia; o restante da API ainda responde, e o cliente pode continuar no site. Inspecione success e os campos de resultado específicos da operação, bem como o status HTTP, antes de relatar sucesso. Nunca tente uma escrita novamente com uma chave de RFQ diferente ou uma nova intenção de reserva apenas porque a resposta original foi perdida.