Integração Z API
v2.12.0-r
Orienta a integração do Teorema ERP com a API do WhatsApp via Z-API para automatizar o envio de mensagens, anexos e personalizações diretamente no sistema.
- Título
- Integração Z API
- Slug
- integracao-z-api
- Sistema(s)
- Gestão Administrativa [04]
- Categoria
- user_manual
- Tipo
- how-to
- Autor
- Marcelo Schemmer
- Setor
- Qualidade
- Modulo
- ""
- Publico
- ""
- Keywords
- Z-API WhatsApp integração instância apiWhatsApp pedido de venda nota fiscal ordem de serviço Client-Token
- Aprovado em
- Julho de 2025
- Release
- ""
- Versão Doc
- "02"
- Revisão
- Paulo Bley
- Versão Pipeline
- 2.5.2
- Chamado
- ""
- Ultima Revisao
- "2026-06-11"
--- title: Integração Z API slug: integracao-z-api sistema: - Gestão Administrativa [04] categoria: user_manual tipo: how-to autor: Marcelo Schemmer setor: Qualidade modulo: "" publico: "" keywords: - Z-API - WhatsApp - integração - instância - apiWhatsApp - pedido de venda - nota fiscal - ordem de serviço - Client-Token aprovado_em: Julho de 2025 release: "" versao_doc: "02" revisao: Paulo Bley versao_pipeline: 2.5.2 chamado: "" ultima_revisao: "2026-06-11" --- ## Visão Geral Permite enviar mensagens e arquivos diretamente do Teorema ERP para clientes via WhatsApp, usando a Z-API (Interface de Programação de Aplicações — Application Programming Interface — do WhatsApp). A integração cobre o módulo Gestão Administrativa (pedidos de venda, emissão de Nota Fiscal — NF-e) e o módulo Balcão (Ordem de Serviço — O.S.). ## Acessar o Site Oficial da Z-API Para iniciar o processo de integração, acesse o site oficial da plataforma.  - Abra o navegador de internet. - Na barra de busca do Google, digite `zapi` e pressione Enter. - Clique no link **Whatsapp API: Integre sua empresa | Z-API**, conforme exibido na imagem. - Você também pode acessar diretamente: https://www.z-api.io ## Fazer Login na Z-API Após acessar o site oficial da Z-API, realize o login para acessar o painel de administração.  - Clique no botão **Login**, localizado no canto superior direito da tela. - Se ainda não possui conta, clique em **Registrar** na tela de login para criar uma conta de demonstração ou produção. - Após o cadastro, retorne ao site e realize o login com os dados cadastrados. > 💡 **Dica:** Use um e-mail válido e de fácil acesso; a confirmação do cadastro será enviada para ele. Após o login, você será redirecionado para o Painel do Cliente Z-API. ## Acessar as Instâncias Web  No menu lateral esquerdo, clique em **Instâncias Web**. Esta seção exibe todas as instâncias cadastradas na conta. - Se for o primeiro acesso, clique em **+ Adicionar** no canto superior direito para criar uma nova instância. - Guarde as informações da coluna **Token**, pois serão utilizadas na integração com o Teorema. > 💡 **Dica:** Ative a autenticação de dois fatores clicando em **Habilitar** no aviso exibido no topo da tela para maior segurança. ## Criar uma Nova Instância Web Caso seja o primeiro acesso ou seja necessário criar uma nova instância:   - Na tela de Instâncias Web, clique no botão verde **+ Adicionar**. - Na tela de **Nova Instância Web**, preencha: - **Nome da instância:** defina um apelido para facilitar a identificação (exemplo: "Meu WhatsApp Vendas"). - **ID da instância:** gerado automaticamente. - **Token de integração:** gerado automaticamente; será utilizado no Teorema. Clique em **Gerar novo token** para regenerar, se necessário. - (Opcional) Configure webhooks para receber eventos automáticos: ao enviar ou receber mensagens, ao conectar ou desconectar, presença no chat e status da mensagem. - Clique em **Salvar** para concluir o cadastro. > ⚠️ **Atenção:** Guarde o Token de Integração; ele é necessário para conectar a Z-API ao Teorema. ## Verificar e Editar a Instância Criada Após a criação, a instância é exibida na lista da tela Instâncias Web com os seguintes dados: nome, ID, token de integração, status, data de vencimento e tipo de pagamento.  Para editar ou visualizar as configurações salvas, realize **duplo clique** sobre a linha da instância. > ⚠️ **Atenção:** Certifique-se de que o status esteja como **Conectada**. Isso indica que a instância foi vinculada corretamente ao número de WhatsApp e está pronta para integração. ## Conectar o WhatsApp via QR Code Após o duplo clique na instância, é exibida a tela com os dados detalhados: nome, API da instância (URL), ID e token de integração. No primeiro acesso, um QR Code será exibido à direita. Para ativar a conexão:  - Abra o WhatsApp no aparelho que será vinculado. - Acesse o menu de configurações e selecione **Aparelhos conectados**. - Leia o QR Code exibido na tela da Z-API. Após a leitura, o status mudará para **Conectado**.  > ⚠️ **Atenção:** Guarde as três informações principais — ID da instância, Token de integração e URL da API — pois serão usadas na configuração do Teorema. ## Acessar os Parâmetros Gerais no Teorema Com os dados da instância Z-API em mãos, configure o Teorema para permitir a integração.  - No sistema **Administrador**, clique na aba **Utilitários** na barra superior. - Selecione a opção **F - Parâmetros Gerais**. ## Configurar os Parâmetros da API no Teorema Na tela de Parâmetros Gerais, configure a integração com a Z-API:  - Clique na aba **API Config**. - Clique no botão de adição (**+**) na lateral para criar uma nova configuração. - Na janela **Config API**, preencha: - **Descrição:** nome para identificar a integração (exemplo: "API WhatsApp"). - **WebService:** cole a URL da API copiada da Z-API. - **Token:** cole o Token de Integração da instância Z-API. - Clique em **Confirmar** para salvar. > ⚠️ **Atenção:** Copie os dados diretamente da tela da instância na Z-API, sem espaços extras, para evitar falhas na autenticação. ## Selecionar o Tipo de Integração com WhatsApp Ainda na janela **Config API**, selecione o tipo de API:  - No campo suspenso **API**, selecione **apiWhatsApp**. - Clique em **Confirmar**. > ⚠️ **Atenção:** Selecione corretamente **apiWhatsApp**; as demais opções destinam-se a outras integrações (NF-e — Nota Fiscal Eletrônica, CT-e — Conhecimento de Transporte Eletrônico, etc.). ## Confirmar os Dados de Integração: API, ID e Token Na tela de detalhes da instância Z-API, copie os três campos necessários:  - **API da instância:** URL completa usada para envio de mensagens. - **ID da instância:** identificador único. - **Token da instância:** código de autenticação necessário para validar a comunicação. Clique no ícone de copiar ao lado de cada campo para garantir precisão ao preencher no Teorema. ## Localizar o Token de Segurança da Conta (Client-Token) Além do token de instância, a Z-API utiliza um Token de Segurança da Conta (**Client-Token**), que deve ser informado no cabeçalho (Header) das requisições.  - No menu lateral da Z-API, clique em **Segurança**. - Na seção **3. Token de segurança da conta**, verifique se o token já foi habilitado. - Se não estiver habilitado, clique em **Configurar agora** para gerar um novo token. > ⚠️ **Atenção:** O token é exibido integralmente apenas na geração. Copie-o imediatamente e salve em local seguro. Em acessos futuros, ele será parcialmente ocultado. Se perdido, será necessário gerar um novo. ## Inserir o Client-Token no Teorema Após obter o Client-Token na aba Segurança da Z-API, inclua-o na configuração da API dentro do Teorema.  - Na janela **Config API**, localize o campo **ClientToken**. - Cole o token de segurança copiado da conta Z-API. - Com os três campos preenchidos — **Instance**, **Token** e **ClientToken** — clique em **Confirmar**. Se os dados estiverem corretos, o Teorema estará integrado à instância Z-API e apto a enviar mensagens automaticamente via WhatsApp. ## Confirmar a Integração na Lista de Parâmetros Após clicar em Confirmar, a nova configuração será listada na tela de Parâmetros Gerais.  A listagem confirmará: - A descrição cadastrada (ex.: apiWhatsApp) - O tipo de API (WhatsApp) - O código da empresa associada (ex.: 0002) ## Acessar o Módulo Gestão Administrativa Com a integração configurada, acesse o módulo Gestão Administrativa para utilizar o envio via WhatsApp.  - Abra o sistema **Gestão Administrativa**. - Insira usuário, senha e data de operação. - Clique em **Login**. ## Abrir Pedidos de Venda  No menu superior, clique em **Vendas** e selecione **Pedido de Venda**. ## Consultar e Localizar um Pedido  Na tela de **Movimento de Vendas**, utilize os filtros superiores para localizar o pedido: - Data de emissão - Número do documento - Empresa relacionada Após localizar o pedido desejado, clique duas vezes para abri-lo ou selecione-o e clique em **Editar**. ## Enviar Mensagem via WhatsApp a partir do Pedido de Venda Dentro do pedido aberto, acesse o menu **Processos > Enviar e-Mail > Mensagem** (ou **Processos > WhatsApp**).  As opções disponíveis são: - **Relatório Pedido de Venda** — envia o documento formatado. - **Mensagem** — envia texto simples e direto. Selecione a opção desejada para abrir a janela de envio via WhatsApp. ## Preencher e Enviar a Mensagem   Na janela de envio: - **Número do WhatsApp:** confirme ou insira o número do cliente (preenchido automaticamente se cadastrado). - **Mensagem:** digite o conteúdo. Use o atalho **Windows + ponto (.)** para abrir o menu de emojis. - **Anexo:** clique no ícone de lupa para anexar arquivos (PDF, imagens, documentos). - Clique em **Enviar**. ## Confirmar o Envio pelo Sistema Após clicar em **Enviar**, o sistema exibirá a mensagem de confirmação:  > **"A Mensagem foi enviada com sucesso!"** Essa notificação confirma que o conteúdo, com ou sem anexo, foi transmitido ao WhatsApp do destinatário. ## Verificar a Mensagem no WhatsApp do Cliente No celular do destinatário, a mensagem enviada estará visível na conversa do WhatsApp:  O conteúdo incluirá o texto digitado no sistema e qualquer anexo adicionado. Em contas gratuitas da Z-API, uma tag de aviso de conta de teste será exibida — esse aviso desaparece após a ativação da conta oficial. ## Enviar Relatório da O.S. via WhatsApp (Módulo Balcão) A partir do módulo Balcão, é possível enviar o relatório da Ordem de Serviço (O.S.) via WhatsApp diretamente pela tela da O.S.  - Na tela da O.S., clique na aba **Imprimir**. - No menu suspenso, selecione **WhatsApp > Relatório O.S.**. Na tela de envio que se abre:  - O número do cliente será preenchido automaticamente (se cadastrado). - Digite a mensagem desejada. - O relatório da O.S. será anexado em PDF automaticamente. - Clique em **Enviar**. ## Enviar Nota Fiscal via WhatsApp (Módulo Gestão Administrativa) Na tela de **Notas Fiscais** do módulo Gestão Administrativa, é possível enviar o PDF da NF-e diretamente ao WhatsApp do cliente.  - Clique na aba **Processos** no menu superior. - Selecione **WhatsApp > Enviar PDF da Nota Fiscal**. Na tela de envio que se abre:  - O número do cliente já aparecerá preenchido (se cadastrado). - Edite a mensagem padrão se necessário. - O PDF da nota fiscal será anexado automaticamente. > **Pré-requisito:** O número de WhatsApp do cliente deve estar informado corretamente no cadastro. ## Enviar PDF e XML da Nota Fiscal via WhatsApp no Pedido de Vendas No Pedido de Vendas, quando houver NF-e vinculada ao pedido, acesse **Processos > WhatsApp** para ver as opções:  - **Enviar PDF da Nota Fiscal** - **Enviar XML da Nota Fiscal** (XML — Extensible Markup Language — arquivo estruturado da nota fiscal eletrônica) ### Enviar o PDF da Nota Fiscal Ao selecionar **Enviar PDF da Nota Fiscal**, o sistema gera automaticamente o arquivo PDF da nota, salva-o temporariamente no computador e abre a tela de envio via WhatsApp. Ao confirmar, somente o PDF correspondente ao pedido é enviado.  ### Enviar o XML da Nota Fiscal Ao selecionar **Enviar XML da Nota Fiscal**, o mesmo processo ocorre para o arquivo XML. Ao confirmar, somente o XML correspondente ao pedido é enviado.  ## Confirmar o Recebimento dos Arquivos no WhatsApp Se o telefone do cliente estiver cadastrado corretamente, o PDF e o XML da NF-e serão enviados um arquivo por vez e estarão visíveis na conversa do WhatsApp.  ## Enviar PDF e XML da Nota Fiscal via WhatsApp pela Emissão de Nota Fiscal No menu **Vendas > Emissão de Nota Fiscal**, as mesmas opções de envio via WhatsApp estão disponíveis.  O funcionamento segue o mesmo processo descrito para o Pedido de Vendas: o sistema gera automaticamente o arquivo correspondente (PDF ou XML), salva-o temporariamente no computador e abre a tela de envio via WhatsApp para encaminhamento ao cliente. > **Pré-requisito:** O telefone do cliente deve estar corretamente cadastrado no sistema. ## Informações do documento > Autor: Marcelo Schemmer > Setor: Qualidade > Módulo: > Chamado: > Versão do Sistema: > Versão do documento: 02 > Revisão: Paulo Bley > Aprovado em: Julho de 2025 --- > 📎 **Arquivos originais:** [Manual de integração Z API.docx](https://drive.google.com/uc?export=download&id=1FPbLfm7LYak_Y6sMeuykIjMYgayrjvIA) · [Manual de integração Z API.pdf](https://drive.google.com/uc?export=download&id=1q-EuSoXvG1RtHP_ulr1qjZWOqtxGP7Jf)
Tags IA:
api
integracao
integracao-z-api
julho
Prioridade: 7