Integração com o Mercos

O Mercos é um aplicativo que permite registrar pedidos sem estar conectado à internet. A integração com o Fácil123 sincroniza clientes, produtos e pedidos automaticamente entre os dois sistemas.

Configurando a integração

Pré-requisito: Entre em contato com o Mercos para solicitar um token de integração antes de iniciar a configuração.

Passos no Mercos:

1. Acesse sua conta no Mercos
2. Navegue até Minha conta → Sistema
3. Selecione Integração e copie o Token

Passos no Fácil123:

1. Clique na Engrenagem no menu superior → clique em Loja de Apps
2. localize o app Mercos e clique em Instalar
3. Cole o token no campo Token
4. Selecione o Quadro e a Etapa para os pedidos importados
5. Opcionalmente selecione um Canal de vendas
6. Defina o Preço importado
7. Clique em Salvar

Após a configuração, a sincronização automática ocorre a cada hora.

Configurando webhook

Você pode habilitar a funcionalidade de webhook para receber alertas em tempo real quando pedidos forem modificados no Mercos.

Atenção: Apenas administradores do sistema podem configurar webhooks.

Passos no Fácil123:

1. Clique na Engrenagem → localize o app Mercos → clique no ícone de lápis
2. Clique no ícone de copiar ao lado de URL do Webhook

Passos no Mercos:

1. Navegue até Minha conta → Sistema → Webhook
2. Clique em Configurar webhook
3. Cole a URL do Fácil123 no campo de endpoint
4. Habilite os eventos desejados e clique em Salvar

Como o preço dos itens é importado

O campo Preço importado define como o preço dos itens de pedidos vindos do Mercos é registrado no Fácil123. Há duas opções:

• Preço cheio com desconto registrado: mantém o preço de tabela como preço de venda e lança a negociação feita pelo vendedor como desconto no item. É o comportamento tradicional da integração.
• Preço praticado, sem desconto: usa o preço negociado pelo vendedor diretamente como preço de venda, sem registrar desconto.

Use Preço praticado, sem desconto quando o preço acertado com o cliente no Mercos já é o preço de venda real (comum no modelo atacarejo, com preços negociados por quantidade), evitando que a diferença em relação à tabela apareça como desconto no pedido importado.

Sobre a sincronização entre os sistemas

Antes de iniciar a integração, é importante entender as regras de sincronização:

Clientes: Sincronização bilateral (Mercos <-> Fácil123). CPF/CNPJ é obrigatório; registros sem essa informação não serão sincronizados.

Produtos: Sincronização bilateral. Todos os produtos devem ter um código; duplicatas bloqueiam a sincronização. O Fácil123 envia apenas "produtos acabados" e "mercadorias para revenda" ao Mercos.

Vendas: Sincronização unidirecional (Mercos -> Fácil123 apenas). As vendas devem ser inseridas no Mercos; registros do Fácil123 não serão enviados ao Mercos.

Estoque: Não há sincronização.

Preparando a sincronização

Antes de habilitar a sincronização, realize auditorias completas nos catálogos de ambos os sistemas para evitar erros de faturamento e discrepâncias nos pedidos.

Conferindo os cadastros no Mercos

Clientes:

• CPF/CNPJ obrigatório (registros inválidos criam duplicatas)
• Telefone: 10-11 caracteres, sem espaços/traços/parênteses, DDD obrigatório, apenas um número
• Cidade/Estado: se a cidade estiver preenchida, o estado se torna obrigatório
• Validação de CEP ocorre no Fácil123
• IE: se preenchida, cidade/estado são obrigatórios; evite "Isento"

Produtos:

• Todos os produtos precisam de códigos; verifique duplicatas
• NCM preenchido no Fácil123 sobrescreve os dados do Mercos
• Limite as unidades de medida às registradas no Fácil123

Conferindo os cadastros no Fácil123

Clientes:

• CPF/CNPJ obrigatório
• Complete todos os campos exigidos pelo Mercos
• Bairro: máximo de 30 caracteres, se preenchido
• Telefone: 10-11 caracteres com DDD
• IE: sem designação "Isento"

Produtos:

• Todos precisam de grupo de tributos ou padrão do sistema
• NCM obrigatório

Vendedores:

• Nomes devem corresponder exatamente aos do Mercos
• Marcar como "Atua como vendedor" no Fácil123

Configurando o Mercos

Clientes

• Marque CPF/CNPJ como campo obrigatório
• Não marque "segmento" como obrigatório (bloqueia a sincronização)
• Não exija "Nome Fantasia" ou "Inscrição Estadual"
• Ative "Bloquear cadastro de mais de um cliente com o mesmo CPF/CNPJ"

Vendedores

• Deixe "Permitir alterar o pedido depois de gerado" desmarcado

Pedidos

A condição de pagamento do pedido no Mercos é o que o Fácil123 usa para encontrar o meio de pagamento correspondente. A busca não exige nome idêntico: o Fácil123 despreza números, datas e palavras como "dias" e "à vista", e procura um meio de pagamento cadastrado cujo nome contenha as palavras que sobraram.

O cuidado, então, não é repetir o nome ao pé da letra (é garantir que a condição do Mercos aponte para um único meio de pagamento do Fácil123). Quando as palavras casam com mais de um cadastro, o Fácil123 não tem como escolher entre eles e o pedido inteiro deixa de entrar, com o erro genérico Erro ao gerar as parcelas no Fácil123, que não aponta a ambiguidade como causa.

Se você tem vários meios de pagamento com nomes parecidos (um "Boleto" para cada estado, por exemplo), dê a cada um pelo menos uma palavra que o diferencie dos demais e use essa palavra na condição de pagamento do Mercos. Depois de nomear o primeiro, teste com um pedido real antes de replicar o padrão para os outros.

• Mercos: Central de ajuda do Mercos
• Fácil123: Gerando parcelas e boletos na venda

Exceção Fiscal

A nomenclatura exata é obrigatória:

• Revenda – Simples
• Revenda – Normal
• Consumo – Não contr
• Consumo – Contribuin
• Mat prima / Simples
• Mat prima / Normal

ST: Configure a tributação por estado em Produtos > Configurações > Tributações.

Plano de Pagamento

Para B2C: Acesse Minha Conta → Políticas comerciais → edite as condições de pagamento conforme os padrões do Fácil123.

O plano de pagamento do Mercos não tem equivalente no Fácil123: quem é procurado na hora de importar o pedido é o meio de pagamento, a partir da condição de pagamento do pedido. Veja Pedidos.

Sobre a sincronização

Para sincronizar

Em Vendas, clique nos três pontinhos → "Sincronizar com o Mercos"

A sincronização automática ocorre a cada hora. Vendas canceladas no Mercos precisam ser canceladas manualmente no Fácil123. A configuração opcional de webhook notifica o Fácil123 sobre alterações nos pedidos. Veja a configuração do webhook.

Produtos não têm um botão para forçar a sincronização manual como o de vendas: depois de ajustar o cadastro, aguarde o próximo ciclo automático e confira nos Logs das Integrações se o produto foi enviado com sucesso.

A última alteração é a que vale

Edições bilaterais são sincronizadas automaticamente. A última fonte de modificação determina qual sistema atualiza o outro. Os dados modificados por último sempre prevalecem entre os sistemas.

Exclusão de dados

Exclusões não são sincronizadas. O Fácil123 impede a exclusão de registros vinculados a vendas. Para dados incorretos: corrija os erros antes da exclusão, depois exclua em ambos os sistemas. A inativação é recomendada.

Quando o pedido é sincronizado com o Fácil123

Os pedidos do Mercos iniciam como orçamentos. A sincronização ocorre após clicar em "Gerar pedido" com status "Concluído".

Após a sincronização, ele aparece como um orçamento no Fácil123.

Alteração no pedido

Edições são sincronizadas apenas do Mercos → Fácil123. Alterações no Fácil123 não chegam ao Mercos. Uma vez convertido em venda/NF-e, edições no orçamento param de sincronizar. Cancelamentos sempre exigem ação manual no Fácil123.

Exceção Fiscal e Natureza da Operação

Três métodos de definição da natureza da operação:

1. Exceção definida no registro do cliente no Mercos → sincroniza com a natureza correspondente no Fácil123
2. Natureza padrão do cliente aplicada se nenhuma exceção for especificada
3. Grupo de tributos padrão das configurações do usuário licenciado se não houver definição prévia

A natureza do Fácil123 é vinculada ao cliente após a confirmação da venda.

Cálculo da ST

Podem ocorrer discrepâncias de centavos entre o pedido do Mercos e a nota do Fácil123 devido a diferenças de arredondamento na ST. O cálculo do Fácil123 é o correto.

Garantindo um bom uso da sincronização

Cadastrando um produto

O Código é o ID que vincula o produto entre o Fácil123 e o Mercos: os dois cadastros precisam ter exatamente o mesmo valor. Para verificar a qual produto do Mercos um cadastro está vinculado, confira o Código do produto em Compras → Produtos no Fácil123.

No Mercos:

• Todos os produtos precisam de códigos
• Informações de NCM sempre fluem apenas do Fácil123 → Mercos

No Fácil123:

• Código obrigatório
• Grupo de tributos válido obrigatório
• NCM obrigatório

Cadastrando um cliente

No Mercos:

• CPF/CNPJ obrigatório
• Telefone: 10-11 caracteres sem caracteres especiais, DDD incluso
• Cidade exige preenchimento do estado
• IE precisa de cidade/UF; evite "Isento"
• Indicador de IE: deixe em branco ou classifique no Fácil123 (sem "Isento")
• Endereço: ex., "Rua Nome da rua"
• Número: ex., "01"

No Fácil123:

• CPF/CNPJ obrigatório
• Preencha todos os campos exigidos pelo Mercos (e-mail/telefone são comuns)
• Telefone: mínimo/máximo de 10-11 caracteres, apenas números, sem caracteres especiais

Gerando pedidos no Mercos

Checklist:

• Pagamento: a condição de pagamento do Mercos precisa identificar um único meio de pagamento do Fácil123 (veja Pedidos)
• Valor do produto: mínimo R$ 0,01; sem totais zerados
• Vendedor: deve existir no Fácil123 com nome correspondente, marcado como "atua como vendedor"

Erros comuns

Caso você esbarre em um erro que não esteja listado aqui, nos avise: estamos em constante evolução!

Logs das Integrações Mercos

Para conferir o tipo de erro gerado na sincronização, ou verificar se ela foi bem-sucedida, utilize os Logs das Integrações.

O acesso aos logs está disponível para o usuário que possui acesso a vendas. Caso contrário, a tela aparecerá sem registros.

Todas as sincronizações são listadas nos Logs das Integrações, tanto as acionadas manualmente quanto as automáticas que ocorrem a cada hora.

O log de erros fica disponível por 7 dias. Após esse prazo ele é deletado e não é mais possível verificar erros anteriores.

Caso as correções não sejam feitas, existe o risco de emitir notas para um cadastro desatualizado ou de um ajuste de produto não estar coerente.

Campo NCM não aparece no cadastro do produto no Mercos

Isso acontece quando a conta do Mercos está configurada para informar a porcentagem de ICMS-ST diretamente no cadastro do produto. Nesse modo, o Mercos substitui o campo NCM pelo campo ST na tela e na API, e isso ocorre independentemente do perfil de acesso.

Para voltar a calcular a ST pelo NCM, acesse o Mercos com um perfil administrador e vá em MINHA CONTA → SISTEMA → CONFIGURAÇÕES DA CONTA → IMPOSTOS e marque "Calcular o ICMS-ST de acordo com o NCM do produto e a Unidade Federativa do cliente". Essa troca é irreversível, então confira antes se algum produto está com a porcentagem de ST preenchida e confirme a mudança com quem administra a conta do Mercos.

Para acionar o suporte do Mercos nesse tipo de investigação, tenha em mãos o ID Empresa e o link Liberar acesso Mercos, disponíveis no rodapé das páginas do sistema (o link só aparece para o perfil administrador). Sem essa liberação, o suporte deles não consegue abrir a conta para diagnóstico.

Dados inválidos, 'emails': No mínimo 1 e-mail é requerido

O campo e-mail está marcado como obrigatório no Mercos. O ajuste do e-mail deve ser feito onde o cliente foi cadastrado.

Dados inválidos, 'telefones': No mínimo 1 telefone é requerido

O campo telefone está marcado como obrigatório no Mercos. Basta preencher no cadastro do Fácil123.

Destinatário precisa ter uma cidade válida

O cliente que está no pedido está com alguma irregularidade na cidade. Pode ser que a UF não esteja preenchida.

Erro ao gerar as parcelas no Fácil123

Esta mensagem cobre duas causas diferentes:

• A parcela digitada no Mercos não é suportada pelo Fácil123.
• A condição de pagamento casou com mais de um meio de pagamento do Fácil123, e o sistema não tem como decidir qual deles usar. Veja Pedidos para saber como nomear os meios de pagamento e evitar essa disputa.

IE:não é válido

A inscrição estadual do cliente não está válida. Caso o cliente não possua Inscrição, deixe em branco. Não preencha com ISENTO, por exemplo.

invoiceproducts:[prorateddiscount:deve ser maior ou igual a 0

O valor dos produtos está como zero reais. Isso não é possível. Todo produto deve ter pelo menos R$ 0,01 (um centavo).

Itens com total zero

O valor dos produtos está como zero reais. Isso não é possível. Todo produto deve ter pelo menos R$ 0,01 (um centavo).

O pedido não pode ser atualizado no Fácil123

A venda já foi transformada em NF-e ou já contém parcelas realizadas no financeiro.

O pedido não pode ser atualizado no Fácil123., A venda não foi sincronizada porque ela já foi movida de etapa no Fácil123. Por favor, faça as modificações necessárias manualmente nos dois sistemas.

A venda já foi transformada em NF-e ou já contém parcelas realizadas no financeiro. Ou simplesmente já saiu da etapa que permite edições de pedido.

Pedido não processado: Cliente não registrado

O cliente que participa deste pedido deve estar sem CPF ou CNPJ.

Pessoa não processada: pessoa sem CPF e CNPJ

Adicione o CPF ou CNPJ ao cadastro. O ajuste deve ser feito onde a pessoa foi cadastrada.

phoneareacode: não é válido (Área não é válido)

O telefone deve conter 10 ou 11 caracteres, sem espaços, traços, parênteses.

phone_number: é muito curto (mínimo: 8 caracteres)

O telefone deve conter 10 ou 11 caracteres, sem espaços, traços, parênteses.

Produto não processado: produto sem código

Adicione código ao cadastro do produto no Mercos.

Produto precisa ter um grupo de tributos válido

Adicione o grupo de tributos no cadastro do Fácil123. Lembre-se: O Fácil123 usa o campo NCM no Mercos para o grupo de tributos, para poder calcular a ST, quando necessário. Então, não deve ser preenchido nada no Mercos com relação à NCM.

Produto precisa ter um NCM para o cálculo da carga tributária

Adicione a NCM no cadastro do Fácil123. Essa informação não é sincronizada com o Mercos.

prorated_discount:deve ser maior ou igual a 0

O valor dos produtos está como zero reais. Isso não é possível. Todo produto deve ter pelo menos R$ 0,01 (um centavo).

Quando informado a Inscrição Estadual a Cidade e a UF não devem ficar em branco

Adicione cidade e UF no cadastro do cliente no Mercos.

Total de parcelas difere do total da venda

A edição do pedido alterou o valor das parcelas, mas elas não foram editadas no Mercos. Verifique as duas informações: Mercos + Fácil123.

Vendedor não encontrado

O vendedor do pedido não está cadastrado no Fácil123. Confira o nome dos usuários (no Mercos e no Fácil123) e verifique se estão iguais. Verifique o cadastro do usuário no Fácil123 e verifique se este usuário está marcado como "atua como vendedor".

Você não pode alterar as parcelas de uma venda com transações realizadas

A alteração vinda do Mercos tentou modificar uma parcela que já foi paga ou recebida no financeiro. As parcelas em aberto da mesma venda continuam podendo ser ajustadas, apenas a parcela já realizada fica travada. Para alterá-la, faça o ajuste diretamente no Financeiro.

Dados inválidos, 'cep': Este campo requer 8 dígitos

O CEP está com problemas.

CNPJ já está em uso ou Dados inválidos, 'cnpj': Este CNPJ já está cadastrado no sistema

Peça ajuda ao suporte. Ocorreu alguma alteração no cadastro que tinha vínculo com o CNPJ.

{"mensagem": "Cliente 19332626 não encontrado."}

Peça ajuda ao suporte. É provável que o vínculo com o cliente tenha sido quebrado. O cadastro foi excluído. E deve haver outro cadastro com o mesmo CNPJ. Informe o ID no Mercos no nome daquele cliente. (este ID não irá existir mais lá) O desenvolvimento deverá trocar o vínculo.

Dados inválidos, 'preco_tabela': Certifique-se de que não tenha mais de 8 dígitos no total

O preço do produto está com mais de 8 casas decimais. Ajustar no Fácil123.

["Produto não pode ficar em branco"]

Algum dos produtos (um ou mais de um) está com problema de cadastro. Existem algumas alternativas de erro mais comuns:

a. o vínculo entre o Fácil123 e o Mercos referente a este item foi quebrado. Ou ele foi deletado no Mercos e recadastrado, ou foi deletado no Fácil123 e recadastrado.

b. o cadastro foi feito no Mercos e pode estar incompleto no Fácil123. Para conferir:

• Verifique se todos os produtos do pedido contém unidade de medida no Mercos.
• se sim, verifique se o cadastro existe no Fácil123. Ele terá que ser complementado com a NCM e o grupo de tributos no Fácil123 antes de o pedido sincronizar.

Pedido cancelado no Mercos o Fácil não entende

Quando isso acontecer, peça ajuda ao suporte e passe o ID do pedido para o desenvolvimento corrigir.

Dados inválidos: Um ou mais produtos não estão cadastrados no Fácil123

Esse erro pode ter mais de uma causa. Um dos motivos possíveis é um produto duplicado no Mercos, com um cadastro ativo e outro inativo ainda vinculado à sincronização. Exclua o cadastro inativo no Mercos, mantendo apenas o ativo. De forma geral, ao inativar um produto no Mercos, exclua-o em vez de apenas deixá-lo inativo, para evitar que ele interfira em sincronizações futuras.

Dados inválidos, * Segmento: Este campo é obrigatório

No Mercos existe o campo Segmento e está marcado como obrigatório. Para resolver é preciso desmarcar ele como obrigatório, editar o cadastro, e então sincronizar.

O destinatário [nome do cliente] não foi encontrado no Fácil123. Por favor, verifique o cadastro no Mercos.

O cliente do pedido ainda não sincronizou com o Fácil123 porque o cadastro dele no Mercos tem algum dado inválido (CPF/CNPJ, telefone, cidade/UF ou Inscrição Estadual, por exemplo). Revise o cadastro do cliente no Mercos e sincronize novamente o pedido.

O produto [nome do produto] ainda não foi sincronizado com o Fácil123. Por favor, verifique o cadastro no Mercos.

Esse erro pode ter mais de uma causa. Um dos motivos possíveis é o produto estar cadastrado no Fácil123 como matéria-prima: o Fácil123 só envia ao Mercos produtos do tipo "produto acabado" ou "mercadoria para revenda" (veja Sobre a sincronização entre os sistemas), então um produto matéria-prima nunca existe do lado do Mercos. Se ele for cadastrado manualmente lá com o mesmo código, a sincronização tenta criar um produto novo no Fácil123 e falha, porque o código já está em uso pelo cadastro existente. Para que o produto sincronize dos dois lados, altere o tipo dele no Fácil123 para "produto acabado" ou "mercadoria para revenda".

Pedido barrado por uma validação personalizada

Quando uma validação personalizada de venda barra o pedido, ele não entra no Fácil123 e os Logs das Integrações mostram "Corrija o seguinte erro no Mercos", seguido da mensagem de erro da validação. Essa mensagem muda conforme a validação configurada. Na Validação de Cliente Inadimplente, por exemplo, ela é "O cliente tem pendências financeiras de R$ X".

A sincronização só busca no Mercos os pedidos alterados depois da última execução, então o pedido barrado fica parado até ser modificado lá. Depois de resolver o motivo do bloqueio (a pendência financeira do cliente, por exemplo), faça qualquer alteração no pedido no Mercos para que ele seja importado de novo. Só quitar o boleto no Fácil123 não basta.

Perguntas e respostas

1 - O que causa a criação de clientes duplicados?
R: CPF/CNPJ preenchido no Mercos mas vazio no Fácil123 gera duplicação durante a sincronização.

2 - Por que incluir o e-mail do fornecedor no Mercos?
R: Todas as pessoas são sincronizadas; os registros devem atender todas as regras.

3 - Para pedidos com desconto, usar Reais ou porcentagem no Mercos?
R: Porcentagem. O Fácil123 converte para Reais durante a sincronização.

4 - Produtos inativos do Mercos integram com o Fácil123?
R: Sim, tanto produtos ativos quanto inativos são integrados.

5 - Dados de transportadora sincronizam das vendas do Mercos para o Fácil123?
R: Não. Transportadora/modo de transporte/placa do veículo não sincronizam. Insira no Fácil123 se necessário.

6 - Como funciona a bonificação no Mercos?
R: Insira como Bonificação no Mercos → sincroniza com o Fácil123 como venda normal → altere a natureza da operação no Fácil123.

7 - É possível importar frete na integração com o Mercos?
R: Sim, é possível.

8 - Se eu cadastrar "cartão de crédito" como meio de pagamento no Mercos, o pedido vai importar?
R: Sim, desde que essa condição identifique um único meio de pagamento no Fácil123. O nome não precisa ser idêntico, mas se as palavras servirem para mais de um cadastro ("Cartão de Crédito" e "Cartão de Crédito Parcelado", por exemplo), o pedido não será sincronizado. Veja Pedidos.