Magazord — Integração com E-commerce¶

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

O que é¶

A Integração Magazord é um aplicativo standalone (separado do Master Key) que sincroniza dados entre o Master Key e uma loja na plataforma de e-commerce Magazord. A sincronização ocorre em ciclos automáticos com execução paralela das etapas independentes.

O fluxo é bidirecional: - Magazord → Master Key: clientes e pedidos - Master Key → Magazord: preços, estoque e notas fiscais

A integração com a Magazord é focada em operação: não envia cadastro de produtos (gerenciado diretamente na plataforma) — apenas mantém preços, estoque e notas sincronizados.

Pré-requisitos¶

URL base da API Magazord (ex.: https://api.magazord.com.br)
Chave de API (API Key) e Senha fornecidos pela Magazord
Banco de dados do Master Key acessível pelo computador onde o aplicativo roda

Importante: a Magazord utiliza PR_CODALFA (código de referência alfanumérico) como identificador do produto — não o PR_CODIGO numérico. Todos os produtos que devem ser sincronizados precisam ter o campo PR_CODALFA preenchido.

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.

API¶

Campo	O que é
URL	URL base da API Magazord (ex.: `https://api.magazord.com.br`)
API Key	Chave de autenticação fornecida pela Magazord
Senha	Senha de autenticação. Combinada com a API Key forma o cabeçalho `Authorization: Basic base64(Key:Senha)`

Estoque¶

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

Pedidos¶

Campo	O que é
Vendedor	Código do vendedor padrão atribuído a cada pedido importado
Transportador	Código do transportador padrão atribuído aos pedidos

Clientes¶

Campo	O que é
Vendedor	Vendedor padrão atribuído ao cliente cadastrado
Praça	Praça padrão do cliente
Atividade	Atividade padrão do cliente

Vendedor, Praça e Atividade são obrigatórios para clientes. O ciclo aborta se algum não estiver configurado.

Produtos¶

Campo	O que é
Tabela de Preço	Tabela principal de preços enviada à Magazord. Tabelas adicionais podem ser configuradas na seção `[TabelasPreco]` do INI

NF-e (opcional)¶

Campo	O que é
Database NF-e	Caminho do banco de dados auxiliar de NF-e (opcional — só necessário se a emissão de notas usa banco separado)

Fluxo de Sincronização¶

A cada ciclo, o aplicativo executa as etapas com a seguinte ordem de dependências:

Clientes ──► Pedidos ──► Estoque
                    └──► Notas

Preços (independente)

Clientes inicia primeiro. Pedidos aguarda Clientes. Estoque e Notas aguardam Pedidos. Preços roda em paralelo, independentemente.

1. Clientes (Magazord → Master Key)¶

Importa clientes modificados desde a última sincronização, paginado.

Para cada cliente: - Busca no Master Key por CPF/CNPJ ou e-mail para evitar duplicatas - Se não encontrado, busca pelo ID externo Magazord vinculado anteriormente - Se ainda não encontrado, cria um novo cliente com tipo C e consumidor S - Importa endereço principal e endereços adicionais - Resolve cidade/UF pelo estado informado; se não encontrar, consulta o serviço de CEP. Se ainda assim não resolver, registra UF=!! e Cidade=Cidade Inexistente!

2. Pedidos (Magazord → Master Key)¶

Importa pedidos com dataHoraUltimaAlteracaoSituacao posterior à última sincronização, paginado. Executa após Clientes.

Comportamentos especiais: - Pedidos com situação 1 (aguardando pagamento) não são importados — só entram após aprovação - Pedidos do tipo "lojista" (marketplace com lojista definido) são ignorados - Pedidos do e-mail de teste teste@comprador.com.br são ignorados - Se o cliente não existir no Master Key, o pedido importa o cliente automaticamente via API Magazord - Pedidos já faturados (status 1) no Master Key não são reabertos; pedidos cancelados só são reprocessados se o valor ou a quantidade de itens mudou

Mapeamento de status (campo pedidoSituacao):

Situação Magazord	`PE_STATUS`	`PE_FINANCEIRO`
`2`, `14`, `24` (cancelado, estornado, chargeback pago)	3 (cancelado)	2
`4`,`5`,`6`,`7`,`8`,`12`,`19`,`23`,`27`,`30` (aprovados e em andamento)	0 (aberto)	1 (pago)
`9`,`10`,`11`,`26`,`29` (fraude, disputa, chargeback)	0 (aberto)	2
Demais	0 (aberto)	0 (pendente)

Campos importados:

Campo Magazord	Campo Master Key	Descrição
`codigo`	`PE_PEDEXTERNO`	Código do pedido na Magazord
`dataHora`	`PE_DATA` / `PE_HORA`	Data e hora de criação
`valorTotal`	`PE_VLRTOTAL`	Valor total
`cep` (endereço de entrega)	`PE_ENTREGA`	Define se há entrega (`S`/`N`)
Endereço de entrega	`PE_OBS`	Dados do endereço gravados na observação

3. Preços (Master Key → Magazord)¶

Envia preços de produtos modificados desde a última sincronização. Executa independentemente, em paralelo com as demais etapas.

Usa PR_CODALFA como referência do produto na Magazord — produtos sem PR_CODALFA são ignorados
Suporta múltiplas tabelas de preço: a tabela principal e tabelas adicionais configuradas em [TabelasPreco] no arquivo INI
Envia lotes de até 100 produtos por requisição via POST /v1/preco
Campos enviados: produto (PR_CODALFA), tabelaPreco (código da tabela na Magazord), precoVenda, precoAntigo

4. Estoque (Master Key → Magazord)¶

Atualiza o estoque dos produtos. Executa após Pedidos.

Usa PR_CODALFA como referência do produto; para produtos com grade, usa o código de grade (CODGRADE)
Soma os saldos das filiais configuradas; desconta a margem de segurança (MARGEM). Valores negativos são enviados como zero
Envia para POST /v1/estoque com: produto, deposito=1, quantidade, tipo=1, tipoOperacao=0, origemMovimento=1

5. Notas Fiscais (Master Key → Magazord)¶

Envia XML das notas fiscais emitidas no Master Key para a Magazord. Executa após Pedidos.

Vincula a nota ao pedido correspondente na Magazord pelo código externo
Envia o XML completo da NF-e
Se o banco de dados de NF-e for separado (campo Database NF-e configurado), conecta ao banco auxiliar para buscar o XML

Tabelas e campos relevantes¶

Tabela	Campo	Função
`CAMPOS`	`CAMPO` / `VALOR`	Armazena IDs externos (pedido, cliente) vinculados aos códigos internos
`PRODUTOS`	`PR_CODALFA`	Código de referência alfanumérico — identificador do produto na Magazord
`PRODF_GRADE`	`FG_CODBARRA` / código de grade	Referência da grade enviada ao estoque
`ECOMMERCE`	`EC_MARGEMEST`	Margem de segurança de estoque (descontada do saldo enviado)
`PEDIDOS`	`PE_PEDEXTERNO`	Código do pedido na Magazord — usado para vincular NF-e

Perguntas frequentes do suporte¶

"O ciclo inicia mas aborta sem sincronizar nada" → Verifique se Vendedor, Praça e Atividade (Clientes) estão configurados. Confirme também as credenciais de API (Key e Senha).

"Preço não está sendo atualizado na Magazord" → Verifique se o produto tem PR_CODALFA preenchido — produtos sem esse campo são ignorados pela etapa de Preços e Estoque. Confirme também se a tabela de preço selecionada nas configurações está correta.

"Estoque desatualizado na Magazord" → Verifique se as filiais corretas estão em Filiais de Estoque e se PR_CODALFA está preenchido. Para produtos com grade, o campo de código de grade (CODGRADE) deve estar configurado.

"Pedido não foi importado do Magazord" → Verifique a situação do pedido. Pedidos com situação 1 (aguardando pagamento) não são importados — aguardar a aprovação. Pedidos de "lojista" (marketplace) também são ignorados intencionalmente.

"Pedido importado sem cliente" → Se o cliente não for encontrado por CPF/CNPJ ou e-mail, a integração tenta importá-lo automaticamente via API Magazord. Se ainda assim falhar, o pedido não é importado. Verifique se o cliente tem CPF/CNPJ ou e-mail cadastrado na Magazord.

"Nota fiscal não foi enviada à Magazord" → Confirme que o pedido correspondente foi importado do Magazord (a nota é vinculada pelo PE_PEDEXTERNO). Se usa banco de NF-e separado, verifique o campo Database NF-e nas configurações.

"Cliente com cidade 'Cidade Inexistente!'" → A cidade informada na Magazord não foi encontrada na tabela de cidades do Master Key e o serviço de CEP não resolveu. Atualize o cadastro manualmente no Master Key.