--- title: "Referência da API de agendamentos e catálogo" description: "Gerencie agendamentos, especialistas, produtos e serviços com a Public API: leia a agenda, crie e atualize horários e sincronize o Google Calendar." canonical_url: https://chatfuel.com/pt/docs/public-api/bookings-and-catalog markdown_url: https://chatfuel.com/pt/docs/public-api/bookings-and-catalog.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Referência da API de agendamentos e catálogo Gerencie agendamentos, especialistas, produtos e serviços com a Public API: leia a agenda, crie e atualize horários e sincronize o Google Calendar. A parte de agendamentos e catálogo da Public API do Chatfuel cobre o que o Fuely AI vende e agenda: os produtos e serviços do catálogo, os especialistas com seus horários de trabalho e os agendamentos no calendário. Uma integração pode espelhar os agendamentos em outro sistema, criar horários a partir de um site ou CRM e manter o catálogo sincronizado com uma loja. A leitura funciona para usuários virtuais **Agent**; criar e alterar qualquer coisa exige **Editor**. ## Como ler os agendamentos [#como-ler-os-agendamentos] ```graphql type Bot { # Agent. Bookings in the time range. bookingsV2(startTime: Time!, endTime: Time!): [BookingBase!]! bookingV2(id: BookingID!): BookingBase! # A booking contact without a chat, found by phone number. inlineContact(phoneNumber: String!): BookingInlineContact } ``` ```graphql query Week($botID: BotID!) { bot(id: $botID) { bookingsV2(startTime: "2026-10-12T00:00:00Z", endTime: "2026-10-19T00:00:00Z") { id startTime endTime status # Pending, Reschedule, Confirmed, Canceled, Attended, NoShow service { ... on GoodsService { id title } } specialist { id } } } } ``` Os horários são timestamps RFC 3339. Um agendamento está vinculado a um contato existente (`contactID`) ou a um contato inline com nome e número de telefone, para pessoas que agendaram sem conversar com o bot. ## Como criar e alterar agendamentos [#como-criar-e-alterar-agendamentos] ```graphql type Mutation { # Editor. Errors: BookingStartTimeRequired, BookingEndTimeRequired, BookingInvalidDuration, # BookingEndTimeBeforeStartTime, BookingContactPlatformNotAllowed bookingCreateV2(botID: BotID!, req: BookingInput!): BookingBase! bookingUpdateV2(botID: BotID!, id: BookingID!, req: BookingUpdateInput!): BookingBase! # Editor. Confirm, cancel or mark as attended or no-show. bookingStatusResolveV2(botID: BotID!, bookingID: BookingID!, status: BookingStatus!): BookingBase! bookingDeleteV2(botID: BotID!, id: BookingID!): BookingBase! # Editor. Errors: BookingInlineContactNoteTooLong bookingInlineContactSetNote(id: InlineContactID!, note: String): BookingInlineContact! } input BookingInput { contactID: ContactID # an existing contact, or inlineContact: BookingInlineContactInput # { name, phoneNumber, note, countryCode } serviceID: GoodsItemID specialistID: SpecialistID startTime: Time! endTime: Time! } ``` ```graphql mutation Book($botID: BotID!, $serviceID: GoodsItemID!, $specialistID: SpecialistID!) { bookingCreateV2( botID: $botID req: { inlineContact: { name: "Ana Souza", phoneNumber: "+5511999990000", countryCode: "BR" } serviceID: $serviceID specialistID: $specialistID startTime: "2026-10-14T13:00:00Z" endTime: "2026-10-14T14:00:00Z" } ) { id status } } ``` ## Assinaturas de agendamentos [#assinaturas-de-agendamentos] ```graphql type Subscription { # Agent. bookingAdded(botID: BotID!): Booking! bookingUpdated(botID: BotID!): Booking! bookingDeleted(botID: BotID!): BookingID! } ``` ## Como gerenciar especialistas [#como-gerenciar-especialistas] Especialistas são as pessoas ou os recursos com os quais um agendamento é feito, cada um com um perfil, uma agenda semanal e os serviços que oferece. Leia-os com `bot.specialists` e `bot.specialist(id:)` (**Agent**). ```graphql type Mutation { # Editor. Errors: SpecialistNameNotUnique, SpecialistFirstNameRequired, SpecialistFirstNameTooLong, … specialistCreate(botID: BotID!, info: SpecialistInfoInput!): Bot! specialistUpdate(botID: BotID!, specialistID: SpecialistID!, info: SpecialistInfoInput!): Specialist! specialistDelete(botID: BotID!, specialistID: SpecialistID!): Bot! } input SpecialistInfoInput { profile: SpecialistProfileInput! schedule: SpecialistScheduleInput! goodsServices: [GoodsItemID!]! } ``` ## Como conectar o Google Calendar de um especialista [#como-conectar-o-google-calendar-de-um-especialista] O Google Calendar de um especialista mantém a disponibilidade dele sincronizada com o resto da sua agenda. O dono da agenda a conecta por meio de um link, assim ninguém compartilha credenciais do Google: ```graphql type Mutation { # Editor. Creates a link the calendar owner opens to connect their Google Calendar. specialistCreateGoogleCalendarConnectionLink(botID: BotID!, specialistID: SpecialistID!): SpecialistGoogleCalendarLink! specialistDeleteGoogleCalendarConnectionLink(botID: BotID!, specialistID: SpecialistID!): Bot! # Editor. Starts a sync; follow its progress with taskUpdated. Errors: SpecialistDoesNotExist specialistStartGoogleCalendarSync(botID: BotID!, specialistID: SpecialistID!): Task! specialistDisconnectGoogleCalendar(botID: BotID!, specialistID: SpecialistID!, googleCalendarID: GoogleCalendarID!): Specialist! } ``` `bot.availableGoogleCalendars`, que retorna as agendas da sua própria conta do Google, é **Somente token pessoal**. [Arquivos e tarefas](https://chatfuel.com/pt/docs/public-api/files-and-tasks) descreve `Task` e `taskUpdated`. ## Como gerenciar produtos e serviços [#como-gerenciar-produtos-e-serviços] O catálogo contém os produtos e serviços que o Fuely AI pode recomendar e agendar. Leia-o com `bot.goodsCatalog`, `bot.goodsProduct(id:)` e `bot.goodsService(id:)` (**Agent**). ```graphql type Mutation { # Editor. Errors: GoodsItemsTooMuchForBot, GoodsItemTitleRequired, GoodsItemTitleNotUnique, # GoodsItemTitleTooShort, GoodsItemTitleTooLong, GoodsItemDescriptionTooLong, … goodsProductCreate(botID: BotID!, product: GoodsProductInput!): Bot! goodsProductUpdate(botID: BotID!, itemID: GoodsItemID!, product: GoodsProductInput!): GoodsProduct! goodsProductDelete(botID: BotID!, itemID: GoodsItemID!): Bot! goodsServiceCreate(botID: BotID!, service: GoodsServiceInput!): Bot! goodsServiceUpdate(botID: BotID!, itemID: GoodsItemID!, service: GoodsServiceInput!): GoodsService! goodsServiceDelete(botID: BotID!, itemID: GoodsItemID!): Bot! } input GoodsProductInput { title: String! description: String! price: GoodsItemPriceInput # { amount: "199.90", currency: … } images: [FileID!]! isAvailable: Boolean! } input GoodsServiceInput { title: String! description: String! price: GoodsItemPriceInput images: [FileID!]! durationSeconds: Int! isAvailable: Boolean! } ``` Primeiro faça o upload das imagens dos produtos, como descrito em [como fazer requisições](https://chatfuel.com/pt/docs/public-api/requests), e passe os IDs dos arquivos em `images`. Os títulos devem ser únicos dentro do catálogo. As mutações de atualização substituem o item inteiro, então envie todos os campos. ## Problemas comuns [#problemas-comuns] ### "BookingContactPlatformNotAllowed" [#bookingcontactplatformnotallowed] O contato está em um canal que não suporta agendamentos. Use um contato de um canal compatível ou agende com um `inlineContact` pelo número de telefone. ### "GoodsItemTitleNotUnique" [#goodsitemtitlenotunique] Outro produto ou serviço já tem esse título. Os títulos são comparados em todo o catálogo do bot. ### "NotEnoughPermissions" quando um Agent cria um agendamento [#notenoughpermissions-quando-um-agent-cria-um-agendamento] Um usuário virtual Agent pode ler agendamentos, especialistas e o catálogo, mas não pode alterá-los. Use um usuário virtual Editor.