Mercos — Integração com Força de Vendas¶

Aplicativo externo IntegraMercos.exe | Sincronização automática em intervalo configurável

O que é¶

A Integração Mercos é um aplicativo standalone (separado do Master Key) que sincroniza dados entre o Master Key e a plataforma de força de vendas Mercos. A sincronização ocorre em ciclos automáticos com execução em fila sequencial de etapas interdependentes.

O fluxo é bidirecional: - Mercos → Master Key: pedidos - Master Key → Mercos: clientes, categorias, produtos, imagens, estoque, tabelas de preço, notas fiscais e contas a receber

A integração também retroalimenta o Mercos com atualizações de status dos pedidos (cancelamentos e mudanças de situação), mantendo o estado sincronizado nos dois sentidos.

Pré-requisitos¶

Company Token fornecido pela Mercos para a empresa (obtido no painel da Mercos)
Banco de dados do Master Key acessível pelo computador onde o aplicativo roda

O Application Token é fixo e embutido no aplicativo — não requer configuração.

Configuração¶

Acesse o menu Opções → Configurações no aplicativo. As configurações são salvas em arquivo INI na mesma pasta do executável.

Token¶

Campo	O que é
Company Token	Token da empresa fornecido pela Mercos. Enviado como cabeçalho `CompanyToken` em todas as requisições

O ApplicationToken (cabeçalho ApplicationToken) é fixo, definido internamente no aplicativo.

Estoque¶

Campo	O que é
Filiais de Estoque	Filiais cujos saldos somam para calcular o estoque enviado

Pedidos¶

Campo	O que é
Transportador	Transportador padrão atribuído aos pedidos importados

Produtos¶

Campo	O que é
Usar Preço de Venda 2	Quando marcado, envia `PR_PRECOVEND2` em vez de `PR_PRECOVEND` como preço de venda
Enviar Unidades de Caixa Master	Quando marcado, envia a unidade de caixa master do produto

Fluxo de Sincronização¶

A cada ciclo, o aplicativo executa as etapas na seguinte ordem sequencial:

Categorias
  └──► Usuarios
         └──► Segmentos
                └──► Status
                       └──► CondicoesPagamento
                              └──► Clientes ──► CondicoesPagamentoCliente
                                                       └──► Pedidos
                                                              └──► Produtos
                                                                     ├──► Imagens
                                                                     ├──► TabelasPreco
                                                                     │      └──► PrecosTabelasPreco
                                                                     │             └──► TabelasPrecoCliente
                                                                     └──► Estoque
                                                                            └──► Notas
                                                                                   └──► ContasReceber

A maior parte das etapas é sequencial — cada uma aguarda a conclusão da anterior. Todas as chamadas à API tratam throttling HTTP 429 pausando o tempo indicado pelo campo tempo_ate_permitir_novamente antes de retentar.

1. Categorias (Master Key → Mercos)¶

Sincroniza a árvore de categorias de produtos. O ID externo da categoria no Mercos é salvo na tabela CAMPOS.

2. Usuarios (Master Key → Mercos)¶

Sincroniza os usuários/vendedores do Master Key para o Mercos.

3. Segmentos (Master Key → Mercos)¶

Sincroniza segmentos de clientes.

4. Status (Master Key → Mercos)¶

Sincroniza as situações/status de pedidos. Os IDs externos dos status no Mercos são armazenados na tabela CAMPOS (tipo Status) e usados na retroalimentação dos pedidos.

5. Condições de Pagamento (Master Key → Mercos)¶

Sincroniza as condições de pagamento disponíveis.

6. Clientes (Master Key → Mercos)¶

Exporta clientes modificados desde a última sincronização para o Mercos.

Para cada cliente: - Envia dados cadastrais: razao_social, nome_fantasia, cnpj (ou CPF), inscricao_estadual, suframa, endereço completo, observação - Tipo definido pelo tamanho do documento: CPF (11 dígitos) → F; CNPJ → J - Envia limite_credito_disponivel e limite_credito_total se o cliente tiver limite de crédito ativo e dentro da validade; caso contrário, envia zero - Após enviar o cliente, sincroniza a vinculação cliente ↔ vendedor (v1/usuarios_clientes): - Bloqueia vendedores anteriores que não são mais o responsável - Libera o vendedor atual do cliente - Clientes de usuários administradores ou inativos são ignorados nessa etapa

Campos enviados:

Campo Master Key	Campo Mercos	Descrição
`CL_NOME`	`razao_social`	Razão social
`CL_NOMFAN`	`nome_fantasia`	Nome fantasia
`CL_CGC` / `CL_CPF`	`cnpj`	CNPJ ou CPF
`CL_INSCRICAO`	`inscricao_estadual`	Inscrição estadual
`CL_SUFRAMA`	`suframa`	SUFRAMA
`CL_ENDERECO`	`rua`	Logradouro
`CL_NRO`	`numero`	Número
`CL_COMPL` (até 50)	`complemento`	Complemento
`CL_BAIRRO` (até 30)	`bairro`	Bairro
`CL_CEP`	`cep`	CEP
`CL_CIDADE`	`cidade`	Cidade
`CL_UF`	`estado`	Estado
`CL_OBSGERAL`	`observacao`	Observação geral
`CL_LIMITECRED`	`limite_credito_*`	Limite de crédito

7. Condições de Pagamento por Cliente (Master Key → Mercos)¶

Sincroniza as condições de pagamento específicas habilitadas para cada cliente.

8. Pedidos (Mercos → Master Key)¶

Importa pedidos modificados desde a última sincronização.

GET v2/pedidos?alterado_apos={datetime}
Cria ou atualiza pedidos no Master Key
Pedidos já faturados ou cancelados (status 1 ou 3) não são atualizados

A etapa também é bidirecional para status: pedidos cancelados ou com status atualizado no Master Key têm o status correspondente enviado de volta ao Mercos: - Cancelamento: POST v1/pedidos/cancelar/{id} - Mudança de situação: atualiza usando o ID externo do status (armazenado em CAMPOS com tipo Status)

9. Produtos (Master Key → Mercos)¶

Sincroniza produtos modificados desde a última sincronização. Executa após Pedidos.

Envia apenas produtos com EC_DISP <> 'N' e PR_INATIVO <> 'S'; produtos já enviados anteriormente são atualizados mesmo que não atendam mais ao critério (para refletir inativação)
Produtos sem grade → produto simples
Produtos com grade → produto com variações
Envia preço conforme configuração (Preço de Venda ou Preço de Venda 2)
Envia unidades de caixa master se a opção estiver marcada

10. Imagens (Master Key → Mercos)¶

Envia imagens dos produtos. Executa após Produtos.

11. Tabelas de Preço (Master Key → Mercos)¶

Sincroniza as tabelas de preço cadastradas no Master Key.

12. Preços por Tabela (Master Key → Mercos)¶

Sincroniza os preços de cada produto em cada tabela de preço. Executa após Tabelas de Preço.

13. Tabelas de Preço por Cliente (Master Key → Mercos)¶

Vincula tabelas de preço específicas a clientes. Executa após Preços por Tabela.

14. Estoque (Master Key → Mercos)¶

Atualiza o estoque de cada produto. Executa após Produtos.

Consulta saldo por produto (e por grade, quando aplicável) nas filiais configuradas
Desconta a margem de segurança (EC_MARGEMEST)
Envia somente produtos que já possuem ID externo no Mercos (precisam ter sido enviados pela etapa de Produtos)
Trata throttling HTTP 429

15. Notas Fiscais (Master Key → Mercos)¶

Envia notas fiscais emitidas e cancela notas canceladas no Mercos. Executa após Estoque.

Busca notas a enviar desde a última sincronização
Exclui no Mercos as notas canceladas no Master Key

16. Contas a Receber (Master Key → Mercos)¶

Sincroniza títulos de contas a receber. Executa após Notas.

Remove contas excluídas no Master Key
Envia contas a receber modificadas desde a última sincronização

Tabelas e campos relevantes¶

Tabela	Campo	Função
`CAMPOS`	`CAMPO` / `VALOR`	Armazena IDs externos (cliente, produto, categoria, status, tabela de preço) vinculados aos códigos internos
`ECOMMERCE`	`EC_DISP`	Produto disponível (`S`/`N`) — produtos `N` são ignorados na exportação
`ECOMMERCE`	`EC_MARGEMEST`	Margem de segurança de estoque descontada do saldo
`PRODUTOS`	`PR_INATIVO`	Produto inativo — ignorado na exportação (mas atualizado se já existir no Mercos)
`PRODUTOS`	`PR_PRECOVEND` / `PR_PRECOVEND2`	Preço de venda enviado conforme configuração
`CLIENTES`	`CL_LIMITECRED` / `CL_CONTROLLIMITE` / `CL_VALLIMCRED`	Limite de crédito enviado ao Mercos

Perguntas frequentes do suporte¶

"O ciclo aborta sem sincronizar nada" → Verifique se o Company Token está configurado e é válido. Confirme também se as Filiais de Estoque estão preenchidas.

"Produto não está sendo enviado para o Mercos" → Verifique se EC_DISP <> 'N' e PR_INATIVO <> 'S' no cadastro do produto.

"Estoque está desatualizado no Mercos" → Confirme quais filiais estão em Filiais de Estoque. Verifique também a margem de segurança (EC_MARGEMEST) e se o produto já foi sincronizado pela etapa de Produtos (o estoque só é enviado para produtos com ID externo registrado).

"Pedido não entrou no Master Key" → Verifique a situação do pedido no Mercos e o log da etapa de Pedidos. Pedidos já faturados (status 1) no Master Key não são reprocessados.

"Status do pedido não foi atualizado no Mercos após cancelamento" → A retroalimentação de status usa o ID externo do status armazenado na tabela CAMPOS (tipo Status). Verifique se a etapa de Status foi concluída com sucesso e se o status correspondente possui ID externo registrado.

"Vendedor do cliente está errado no Mercos" → A etapa de Clientes sincroniza automaticamente a vinculação cliente-vendedor via v1/usuarios_clientes, bloqueando vendedores antigos e liberando o atual. Se o vendedor do cliente for um administrador no Master Key, a vinculação é ignorada.

"O ciclo está muito lento" → A API do Mercos aplica throttling (HTTP 429). Quando atingido, o ciclo aguarda o tempo indicado pelo Mercos antes de continuar. Isso é normal em sincronizações com grande volume de dados.