> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/firebase-cloud-firestore.md). # Firebase Cloud Firestore O módulo **Firebase Cloud Firestore** permite criar, buscar, atualizar, consultar e apagar documentos em um banco de dados do Firebase Firestore, sem sair do fluxo. Ele é útil quando sua empresa já usa o Firestore para guardar informações (como pedidos, cadastros ou preferências) e você quer que o chatbot leia ou grave dados nesse banco durante o atendimento. {% hint style="info" %} Se o que você precisa é enviar, buscar ou excluir **arquivos** (como imagens, PDFs ou comprovantes) em vez de dados estruturados, use o módulo irmão **Firebase Cloud Storage**. {% endhint %}

Imagem 1 - Módulo Firebase Cloud Firestone aberto.

### 🧭 Como acessar 1. No menu lateral, clique em **Gerenciamento de aplicativos**. 2. Em seguida, clique em **Fluxos**. 3. Abra ou crie um fluxo e acesse a área de trabalho do fluxo. 4. No painel de módulos, localize a categoria **Integração** (identificada pela cor azul). 5. Arraste o módulo **Firebase Cloud Firestore** para a área de trabalho do fluxo.

Imagem 2 - Painel de módulos com a categoria Integração expandida e o módulo Firebase Cloud Firestore visível no Hyperflow Integrações.

{% hint style="warning" %} **Antes de usar este módulo:** é necessário ter uma integração do tipo **Firebase** já cadastrada, com as credenciais de acesso ao projeto. Caso ainda não exista, cadastre a integração na tela de integrações da plataforma e depois volte para selecioná-la no módulo. {% endhint %} *** ### 🔍 Conhecendo o módulo Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela.

Imagem 3 - Painel de configuração do módulo Firebase Cloud Firestore aberto.

*** #### 🔌 Integração Selecione a integração Firebase já cadastrada que o módulo deve usar para se conectar ao banco de dados.

Imagem 4 - Campo Integração com a credencial Firebase selecionada.

*** #### 🗂️ Parâmetros principais Depois de escolher a integração, preencha os dados abaixo para que o módulo saiba onde e o quê buscar, gravar ou apagar: | Campo | O que preencher | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Banco de dados** | Nome do banco de dados do Firestore que você quer acessar. Na maioria dos projetos, é `(default)`. | | **Operação** | A ação que o módulo deve executar: criar, criar com identificador automático, buscar, atualizar, apagar ou consultar vários documentos. Veja o detalhe de cada uma logo abaixo. | | **Caminho** | O endereço da coleção ou do documento dentro do banco (ex.: `pedidos` para uma coleção inteira, ou `pedidos/pedido-001` para um documento específico). | | **Dados** | Um objeto com as informações que serão gravadas no documento, no formato JSON. Obrigatório para as operações de criar, criar com identificador automático e atualizar. | {% hint style="warning" %} O Firestore **não cria documentos intermediários automaticamente**. Para gravar dados em uma subcoleção (por exemplo, `clientes/joao-silva/pedidos`), o documento pai (`joao-silva`) já precisa existir no banco antes. {% endhint %}

Imagem 5 - Campos Banco de dados, Operação e Caminho preenchidos no painel de configuração.

*** #### 🔀 Saídas do módulo O módulo tem duas saídas: * **Sucesso** — a operação foi concluída, com o resultado disponível para os próximos módulos do fluxo. * **Erro** — não foi possível concluir a operação (por exemplo, caminho inválido, documento pai inexistente ou permissão negada no Firebase).

Imagem 6 - Módulo na área de trabalho do fluxo mostrando as saídas Sucesso e Erro.

*** ### ⚙️ Recursos do módulo #### 1️⃣ Criar ou substituir um documento com identificador definido **🎯 Propósito** Gravar um documento em um caminho específico, com um identificador escolhido por você. Se já existir um documento nesse caminho, ele será substituído. **✅ Como fazer na tela** 1. No campo **Operação**, selecione **Criar**. 2. No campo **Caminho**, informe a coleção seguida do identificador do documento (ex.: `clientes/joao-silva`). 3. No campo **Dados**, informe as informações a serem gravadas em formato JSON (ex.: `{"nome": "João Silva", "status": "ativo"}`).

Imagem 7 - Operação Criar selecionada, com Caminho e Dados preenchidos.

**📌 Resultado esperado** O documento é criado (ou sobrescrito, caso já exista) no caminho informado, e o resultado fica disponível na saída **Sucesso** para uso nos próximos módulos do fluxo. *** #### 2️⃣ Criar um documento com identificador automático **🎯 Propósito** Gravar um novo documento em uma coleção sem precisar escolher um identificador — o Firestore gera um automaticamente. **✅ Como fazer na tela** 1. No campo **Operação**, selecione **Criar com identificador automático**. 2. No campo **Caminho**, informe apenas o nome da coleção (ex.: `pedidos`, sem indicar um documento específico). 3. No campo **Dados**, informe as informações do novo documento em formato JSON (ex.: `{"item": "notebook", "quantidade": 1, "status": "pendente"}`).

Imagem 8 - Operação Criar com identificador automático selecionada, com Caminho apontando só para a coleção.

**📌 Resultado esperado** Um novo documento é criado dentro da coleção informada, com um identificador único gerado automaticamente pelo Firestore. O identificador criado fica disponível no resultado da saída **Sucesso**. *** #### 3️⃣ Buscar um documento **🎯 Propósito** Ler o conteúdo de um documento já existente no banco de dados. **✅ Como fazer na tela** 1. No campo **Operação**, selecione **Buscar**. 2. No campo **Caminho**, informe a coleção e o identificador do documento que deseja consultar (ex.: `clientes/joao-silva`).

Imagem 9 - Operação Buscar selecionada, com o Caminho de um documento específico.

**📌 Resultado esperado** O conteúdo do documento é retornado na saída **Sucesso**, pronto para ser usado na conversa com o cliente (por exemplo, para informar um status ou dado cadastrado). *** #### 4️⃣ Atualizar um documento existente **🎯 Propósito** Alterar apenas alguns campos de um documento já existente, sem substituir o documento inteiro. **✅ Como fazer na tela** 1. No campo **Operação**, selecione **Atualizar**. 2. No campo **Caminho**, informe a coleção e o identificador do documento (ex.: `pedidos/pedido-001`). 3. No campo **Dados**, informe somente os campos que devem ser alterados, em formato JSON (ex.: `{"status": "concluído"}`).

Imagem 10 - Operação Atualizar selecionada, com Dados contendo apenas os campos alterados.

**📌 Resultado esperado** Os campos informados são atualizados no documento existente. Os demais campos do documento não são alterados. *** #### 5️⃣ Apagar um documento **🎯 Propósito** Remover definitivamente um documento do banco de dados. **✅ Como fazer na tela** 1. No campo **Operação**, selecione **Apagar**. 2. No campo **Caminho**, informe a coleção e o identificador do documento a ser removido (ex.: `pedidos/pedido-001`).

Imagem 11 - Operação Apagar selecionada, com o Caminho do documento a ser removido.

**📌 Resultado esperado** O documento é removido permanentemente do banco de dados. Essa ação não pode ser desfeita pelo fluxo. {% hint style="danger" %} Não existe confirmação adicional antes de apagar o documento — assim que o módulo é executado com a operação **Apagar**, a exclusão acontece de imediato. Use uma condição antes deste módulo para confirmar que é realmente o documento certo. {% endhint %} *** #### 6️⃣ Consultar vários documentos de uma coleção **🎯 Propósito** Buscar uma lista de documentos de uma coleção que atendam a uma ou mais condições, em vez de buscar um documento único pelo identificador. **✅ Como fazer na tela** 1. No campo **Operação**, selecione **Consultar**. 2. No campo **Caminho**, informe o nome da coleção que deseja consultar (ex.: `pedidos`). 3. Informe as condições de filtro que os documentos precisam atender (por exemplo, um campo igual, maior ou menor que determinado valor). 4. Se necessário, defina também a ordenação dos resultados e a quantidade máxima de documentos retornados.

Imagem 12 - Operação Consultar selecionada, com uma condição de filtro preenchida.

**📌 Resultado esperado** A lista de documentos que atende às condições informadas é retornada na saída **Sucesso**, na ordem e na quantidade configuradas. *** ### 📌 Dicas úteis * Use identificadores simples e diretos (por exemplo, `pedido-001`) para facilitar a organização e o teste do fluxo. * Depois de usar a operação **Criar com identificador automático**, confira no resultado qual foi o identificador gerado — ele será necessário para buscar, atualizar ou apagar esse documento depois. * Se aparecer um erro relacionado ao caminho informado, verifique se ele está correto para a operação escolhida: para **Criar com identificador automático**, informe apenas a coleção; para as demais operações, informe coleção e documento juntos. * Se aparecer um erro de permissão negada, verifique as regras de segurança do Firestore no projeto Firebase ou confirme se a integração cadastrada tem acesso ao banco. * Sempre garanta que o campo **Dados** contenha um JSON válido antes de publicar o fluxo. *** ### 💡 Caso de uso **Cenário:** uma loja quer registrar automaticamente cada novo pedido feito pelo cliente durante a conversa em um banco de dados Firestore já usado pela empresa. **Configuração principal:** 1. Adicione o módulo **Firebase Cloud Firestore** ao fluxo, no ponto em que o pedido é confirmado pelo cliente. 2. Selecione a integração Firebase já cadastrada. 3. No campo **Operação**, selecione **Criar com identificador automático**. 4. No campo **Caminho**, informe `pedidos`. 5. No campo **Dados**, informe as informações do pedido em JSON, usando variáveis do fluxo (ex.: `{"item": "{{input.produto}}", "quantidade": "{{input.quantidade}}", "status": "pendente"}`). 6. Conecte a saída **Sucesso** ao módulo que confirma o pedido para o cliente na conversa. **Resultado esperado no fluxo:** a cada novo pedido informado pelo cliente, o módulo cria automaticamente um documento na coleção `pedidos`, com um identificador único, e o fluxo segue confirmando o registro para o cliente. *** ### ✅ Resumo * O módulo **Firebase Cloud Firestore** cria, busca, atualiza, consulta e apaga documentos em um banco de dados Firestore diretamente do fluxo. * É necessário ter uma integração do tipo **Firebase** cadastrada previamente para usar o módulo. * O Firestore não cria documentos intermediários automaticamente — para gravar em uma subcoleção, o documento pai precisa existir antes. * A operação **Apagar** remove o documento imediatamente, sem confirmação adicional — use uma condição antes deste módulo para evitar exclusões indevidas. * O módulo tem uma saída de **Sucesso**, com o resultado disponível para o fluxo, e uma saída de **Erro**.