Esta página apresenta o processo de instalação e configuração do **Plugin Emissor de NF-e para WooCommerce do Base ERP**. Após instalado e configurado, o plugin conecta sua loja WooCommerce ao Base ERP por meio de uma chave de API, permitindo iniciar o fluxo de emissão de NF-e para pedidos de produtos vendidos na loja, desde que os produtos estejam cadastrados e vinculados corretamente entre os sistemas. *** ## Quando utilizar Utilize esta página quando precisar: - instalar o Plugin Emissor de NF-e para WooCommerce; - configurar a conexão entre WooCommerce e Base ERP; - definir se a integração utilizará Sandbox ou Produção; - gerar e informar a chave de API do Base ERP; - validar se a conexão foi salva corretamente; - preparar a loja para o vínculo de produtos e emissão de NF-e. ### Importante A instalação e configuração do plugin são apenas a primeira etapa do processo. Para que o fluxo de emissão de NF-e funcione corretamente, também será necessário cadastrar os produtos no Base ERP e vinculá-los aos produtos correspondentes no WooCommerce. *** ## Antes de começar Antes de instalar e configurar o plugin, verifique se: - sua loja utiliza WooCommerce; - você possui acesso administrativo ao WordPress; - sua conta Asaas é de pessoa jurídica; - o Base ERP está ativado para a conta; - você possui acesso ao Base ERP; - você definiu se fará testes em Sandbox ou emissão real em Produção; - você possui ou irá gerar uma chave de API do Base ERP no ambiente correto. ### Atenção Cada ambiente possui sua própria chave de API. A chave gerada em Sandbox deve ser utilizada apenas no ambiente Sandbox. A chave gerada em Produção deve ser utilizada apenas no ambiente de Produção. *** ## Instalação do Plugin Você pode instalar o Plugin Emissor de NF-e para WooCommerce pela loja oficial do WordPress ou por instalação manual. *** ### Loja oficial do WordPress Faça o download e a instalação do plugin pela loja oficial do WordPress: [Plugin Emissor de NF-e para WooCommerce](https://br.wordpress.org/plugins/base-erp-invoices-for-woocommerce/) Essa é a forma recomendada para instalação, pois permite utilizar o fluxo padrão de instalação de plugins do WordPress. *** ### Download e instalação manual Caso prefira instalar manualmente, siga os passos abaixo: 1. Faça o download do arquivo `.zip` clicando [aqui](https://github.com/asaasdev/woocommerce-nf-plugin/releases/download/1.0.0/base-erp-invoices-for-woocommerce.zip). 2. Acesse o painel administrativo da sua loja WordPress. 3. Vá até o menu **Plugins > Adicionar Plugin**. 4. Na parte superior da tela, clique em **Enviar Plugin**. 5. No modal exibido, clique em **Escolher arquivo**. 6. Selecione o arquivo `.zip` baixado no passo 1. 7. Clique em **Instalar Agora**. 8. Com a instalação concluída, clique em **Ativar Plugin**. Após a ativação, o Plugin Emissor de NF-e estará instalado em sua loja. A próxima etapa é configurar a conexão com o Base ERP.
*** ## Configuração do Plugin Com o plugin instalado e ativado, siga para a configuração da conexão com o Base ERP. Para isso, é necessário que você já tenha acessado o Base ERP previamente e [gerado sua chave de API](https://docs.baseerp.com.br/docs/autenticacao), que será responsável por conectar sua loja WooCommerce ao emissor de NF-e. Também será necessário definir o ambiente de conexão: | Ambiente | Quando utilizar | | ------------ | -------------------------------------------------------------------------------- | | **Sandbox** | Para testes, simulações e validação do fluxo antes da emissão real de NF-e. | | **Produção** | Para emissão real de notas fiscais. Utilize somente após validar a configuração. | As informações sobre acesso ao Base ERP e seus respectivos ambientes podem ser consultadas na [documentação oficial do Base ERP](https://docs.baseerp.com.br/docs). *** ## Gerando a chave de API no Base ERP Após definir o ambiente de conexão, gere a chave de API no Base ERP correspondente ao ambiente que será utilizado. Siga os passos abaixo: 1. Acesse sua conta Asaas no ambiente escolhido: **Sandbox** ou **Produção**. 2. Após o login, clique no ícone de aplicativos, localizado no canto superior direito da conta Asaas, próximo ao sino de notificações. 3. Acesse o **Base ERP**. Para mais detalhes sobre ativação e acesso, consulte a documentação sobre [conta Asaas no Base ERP](https://docs.baseerp.com.br/docs/conta-asaas). 4. Dentro do Base ERP, vá até **Configurações > Chaves de API**. 5. Crie uma nova chave. 6. Para facilitar a identificação, você pode nomeá-la como **Emissor NF WooCommerce** ou outro nome relacionado à sua operação. 7. Após a geração, copie a chave e armazene-a em local seguro. ### Responsabilidades com a sua chave de API - A chave de API do Base ERP segue o modelo de chave irrecuperável, ou seja, ela será exibida apenas uma vez quando criada. - Copie e salve a chave em local seguro antes de sair da área de integrações. - Nunca armazene chaves de API em texto claro dentro do código-fonte ou em arquivos de configuração acessíveis ao público. - Caso você perca sua chave, não será possível recuperá-la. Será necessário gerar uma nova chave e substituir a anterior. - Cada ambiente, Produção e Sandbox, possui uma chave de API única e exclusiva. - Gere a chave no mesmo ambiente que será selecionado nas configurações do plugin. *** ## Informando a chave no WooCommerce Com a chave gerada e salva em segurança, informe-a no plugin dentro do WordPress. Siga os passos abaixo: 1. Acesse o painel administrativo da sua loja WordPress. 2. Vá até **WooCommerce > Configurações**. 3. Nas abas superiores, clique em **Base ERP**. 4. Selecione o ambiente de conexão: **Sandbox** ou **Produção**. 5. Cole a chave de API no campo **API Key**. 6. Salve as configurações. Se tudo ocorrer dentro do esperado, será exibida uma mensagem informando que as configurações foram salvas com sucesso. *** ## Configurações importantes Durante a configuração, tenha atenção aos seguintes campos: | Configuração | Descrição | | --------------------------- | ------------------------------------------------------------------------ | | Ambiente | Define se o plugin irá se conectar ao Sandbox ou à Produção do Base ERP. | | API Key | Chave responsável por autenticar a conexão entre WooCommerce e Base ERP. | | Aba Base ERP no WooCommerce | Local onde a conexão do plugin é configurada. | | Produtos vinculados | Etapa necessária após a configuração para permitir a emissão de NF-e. | ### Boa prática Antes de utilizar Produção, configure o plugin em Sandbox e valide o fluxo completo de instalação, conexão, cadastro e vínculo de produtos. *** ## Como o plugin atua após a configuração Depois que o plugin estiver instalado e conectado ao Base ERP, sua loja estará preparada para iniciar o processo de emissão de NF-e para pedidos de produtos vendidos no WooCommerce. Entretanto, a emissão depende de etapas complementares, como: - cadastro dos produtos no Base ERP; - preenchimento das informações fiscais necessárias; - vínculo entre o produto do WooCommerce e o produto correspondente no Base ERP; - validação do ambiente configurado; - conferência dos pedidos que serão utilizados no fluxo de emissão. ### Atenção A configuração da API Key não substitui o cadastro e vínculo dos produtos. Produtos sem vínculo correto entre WooCommerce e Base ERP podem não ser identificados no processo de emissão de NF-e. *** ## Impactos de trocar o ambiente A troca entre Sandbox e Produção deve ser feita com cautela. | Alteração | Impacto | | ------------------------------ | --------------------------------------------------------------------------- | | Sandbox para Produção | Passa a utilizar a conexão destinada à emissão real de NF-e. | | Produção para Sandbox | Passa a utilizar o ambiente de testes e simulação. | | API Key de ambiente incorreto | Pode impedir a conexão entre WooCommerce e Base ERP. | | Ambiente incorreto selecionado | Pode gerar falhas de autenticação ou envio de dados para o ambiente errado. | Antes de trocar o ambiente, confirme se a chave de API informada pertence ao ambiente selecionado. *** ## Impactos operacionais Uma configuração incorreta pode impactar diretamente o fluxo fiscal e operacional da loja. Alguns impactos possíveis incluem: - falha na conexão entre WooCommerce e Base ERP; - impossibilidade de iniciar o fluxo de emissão de NF-e; - envio de dados para o ambiente incorreto; - uso de chave de API inválida ou incompatível; - produtos vendidos sem vínculo com o Base ERP; - necessidade de gerar uma nova chave de API em caso de perda; - atraso na emissão de notas fiscais; - divergências entre pedidos do WooCommerce e registros no Base ERP. Por isso, valide a conexão e o vínculo de produtos antes de iniciar a emissão real em Produção. *** ## Erros e dúvidas comuns | Situação | Possível causa | Como agir | | ------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- | | Aba Base ERP não aparece no WooCommerce | Plugin não instalado ou não ativado | Verifique se o plugin foi instalado e ativado corretamente | | Configuração não é salva | Campo obrigatório não preenchido ou erro temporário no WordPress | Revise os campos e tente salvar novamente | | Plugin não conecta ao Base ERP | API Key inválida, ausente ou de ambiente incorreto | Gere uma nova chave no ambiente correto e atualize o plugin | | API Key perdida | A chave é exibida apenas uma vez | Gere uma nova chave no Base ERP e substitua a anterior | | Ambiente incorreto | Produção selecionada com chave de Sandbox, ou o contrário | Confirme o ambiente selecionado e a origem da chave | | NF-e não é emitida após configurar o plugin | Produtos ainda não cadastrados ou não vinculados ao Base ERP | Siga a etapa de cadastro e vínculo de produtos | *** ## Boas práticas Para uma configuração mais segura, recomenda-se: - instalar o plugin pela loja oficial do WordPress sempre que possível; - testar o fluxo em Sandbox antes de utilizar Produção; - gerar a chave de API no ambiente correto; - salvar a chave de API em local seguro; - não armazenar a chave em arquivos públicos ou código-fonte; - revisar o ambiente selecionado antes de salvar a configuração; - validar se a mensagem de sucesso foi exibida após salvar; - cadastrar e vincular os produtos antes de iniciar o fluxo de emissão; - revisar periodicamente a configuração do plugin; - manter controle interno das chaves geradas e substituídas. *** ## Próximo passo Após instalar e configurar o plugin, o próximo passo é realizar o **cadastro e vínculo de produtos**. Essa etapa é necessária para que o Base ERP consiga identificar corretamente os produtos vendidos no WooCommerce e utilizar as informações no processo de emissão de NF-e. ```text Instalar o plugin ↓ Configurar ambiente e API Key ↓ Cadastrar produtos no Base ERP ↓ Vincular produtos no WooCommerce ↓ Validar fluxo de emissão de NF-e ```