O que é a API do Loja?

A API do Loja (ModernizaApi) é uma interface de integração que permite executar as operações de cadastro (incluir, alterar, consultar e excluir) sobre as informações do ModerLoja, como produtos, entidades, tabelas de preço, pedidos de venda, documentos financeiros, estoque e notas fiscais.

Ela é usada para integrar o ModerLoja com outros sistemas. Internamente, a Moderniza utiliza a própria API para a integração com o sistema Food.

• API REST sobre HTTP, hospedada no IIS do Windows como um aplicativo chamado ModernizaApi.
• Formato de dados em JSON (também aceita XML e x-www-form-urlencoded).
• Autenticação por token (Bearer Token), com validade de 24 horas.

A API acessa diretamente o banco de dados do ModerLoja, usando as mesmas regras de negócio do Administrativo.

Requisitos

• Servidor Windows com o Administrativo do ModerLoja já instalado e funcionando.
• Acesso ao banco de dados do ModerLoja a partir do servidor.
• Licença do produto Api ModerLoja ativa no Portal do Parceiro para o CNPJ da filial.

Como instalar?

A API só pode ser instalada no servidor. Execute o instalador original do sistema (LojamixWebInstaller.exe):

1. Selecione a opção Nova Instalação.
2. Tipo Servidor.
3. Módulo web Api Loja.
4. Prossiga com a instalação, acompanhando o progresso até o término.

Ao concluir, o instalador informa o endereço para acessar a API. O instalador habilita o IIS, baixa o pacote da API, cria a pasta da aplicação e registra o aplicativo /ModernizaApi dentro do site Default Web Site do IIS, que por padrão responde na porta 80.

Endereço padrão após a instalação, acessando da própria máquina:

http://localhost/ModernizaApi

A API também publica uma interface interativa (Swagger) para consultar e testar os endpoints no próprio servidor:

http://localhost/ModernizaApi/swagger

Licenciamento

Após a instalação, libere a licença do produto Api ModerLoja no Portal do Parceiro para o CNPJ da filial de trabalho do usuário que fará a autenticação.

A licença é verificada no momento em que o token é solicitado. Sem a licença ativa, a API responde com erro e não gera o token:

O aplicativo 'Api Loja' não está ativo para este CNPJ e o token de acesso não poderá ser fornecido.

Autenticação

Todos os endpoints exigem autenticação por Bearer Token. O fluxo é:

1. Solicitar o token informando um usuário e senha do ModerLoja.
2. Enviar o token no cabeçalho Authorization em todas as demais requisições.
3. Solicitar um novo token quando o atual expirar (validade de 24 horas).

Uma ferramenta útil para entender e testar a API é o Postman, que permite montar as requisições como na imagem abaixo.

5.1 Obter o token

Faça uma requisição HTTP POST para o endpoint:

POST http://localhost/ModernizaApi/token

Com o corpo da requisição no formato x-www-form-urlencoded contendo:

Exemplo com curl:

curl -X POST http://localhost/ModernizaApi/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=SEU_USUARIO&password=SUA_SENHA"

A resposta será:

{
  "access_token": "token-gerado",
  "token_type": "bearer",
  "expires_in": 86399
}

O campo expires_in informa a validade do token em segundos (24 horas).

5.2 Usar o token nas demais requisições

Envie o token recebido no cabeçalho Authorization, com o prefixo Bearer:

Authorization: Bearer token-gerado

Exemplo de consulta de entidades:

curl -X POST http://localhost/ModernizaApi/Entidade/Listar \
  -H "Authorization: Bearer token-gerado" \
  -H "Content-Type: application/json" \
  -d "{ \"nome\": \"MARIA\" }"

5.3 Erros de autenticação

Ao receber 401, solicite um novo token e repita a requisição.

Configuração de acesso externo

Após a instalação, a API responde apenas na própria máquina (localhost) e, dependendo do firewall, na rede local. Para que um sistema fora da rede da loja acesse a API, é preciso configurar o servidor, o firewall do Windows e o roteador da internet. Siga as etapas abaixo na ordem.

6.1 Definir a porta no IIS

A API é instalada dentro do Default Web Site, que por padrão usa a porta 80. Se essa porta já é usada por outro sistema, ou se preferir uma porta exclusiva, adicione uma associação (binding) ao site:

1. Abra o Gerenciador do IIS (inetmgr).
2. Selecione o site Default Web Site e clique em Associações... (Bindings) no painel da direita.
3. Clique em Adicionar, tipo http, endereço IP Todos não atribuídos, e informe a porta desejada (exemplo: 8080).
4. Confirme e reinicie o site.

Depois, teste na própria máquina com a nova porta:

http://localhost:8080/ModernizaApi/swagger

6.2 Liberar a porta no Firewall do Windows

Crie uma regra de entrada liberando a porta escolhida (exemplo com a porta 8080).

Pela interface gráfica, abra o Windows Defender Firewall com Segurança Avançada (wf.msc), selecione Regras de Entrada e clique em Nova Regra... no painel da direita:

1. Tipo de regra: Porta.
2. Protocolo TCP, portas locais específicas: 8080 (a porta configurada no IIS).
3. Ação: Permitir a conexão.
4. Perfis: marque Domínio, Particular e Público.
5. Nome: ModernizaApi HTTP.

Se a loja usa um antivírus com firewall próprio, a mesma liberação precisa ser feita nele.

Teste de outro computador da rede local, trocando pelo IP do servidor:

http://192.168.0.10:8080/ModernizaApi

6.3 Fixar o endereço IP do servidor na rede local

O roteador vai encaminhar as conexões para o IP interno do servidor. Esse IP não pode mudar. Configure um IP fixo na placa de rede do servidor ou uma reserva de DHCP no roteador para o endereço físico (MAC) do servidor.

6.4 Redirecionar a porta no roteador (NAT)

No roteador da internet da loja, crie um redirecionamento de porta (port forwarding, servidor virtual ou NAT, conforme o nome usado pelo fabricante):

6.5 Endereço público: IP fixo ou DNS dinâmico

O sistema externo precisa de um endereço estável para acessar a API. Duas opções:

• IP público fixo contratado com o provedor de internet.
• DNS dinâmico (No-IP, DuckDNS, DynDNS ou o serviço do próprio roteador), que mantém um nome como loja.exemplo.ddns.net apontando para o IP atual da loja.

O endereço externo da API fica no formato:

http://loja.exemplo.ddns.net:8080/ModernizaApi

6.6 Recomendações de segurança

• Nunca exponha a API externamente usando a senha padrão do usuário administrador. Troque a senha e crie um usuário exclusivo para a integração.
• Se o sistema externo tem IP fixo conhecido, restrinja a regra do firewall e do roteador a esse IP de origem.
• Use uma porta externa diferente da padrão (80/443) quando possível, para reduzir varreduras automáticas.
• Não exponha a porta do SQL Server (1433) na internet. Somente a porta da API deve ser redirecionada.
• Mantenha o Windows e o servidor atualizados.

6.7 Checklist de validação

• http://localhost:PORTA/ModernizaApi/swagger abre no servidor.
• O mesmo endereço abre de outro computador da rede local usando o IP do servidor.
• O endereço externo abre de uma rede diferente (por exemplo, pelo 4G do celular).
• A requisição de token pelo endereço externo retorna o access_token.

Convenções da API

• Os endpoints seguem o padrão /{Recurso}/{Operação}. As operações mais comuns são Listar (consulta com filtros), Retornar (um registro) e Salvar (inclui quando o ID é zero, altera quando o ID é informado).
• Consultas e gravações usam POST com o corpo em JSON. Alguns recursos também oferecem GET por ID, no formato /{Recurso}/{id}.
• Nos endpoints de listagem, todos os campos do filtro são opcionais. Envie apenas os filtros que deseja aplicar. Campos omitidos não são usados como filtro.
• Campos com valor nulo são omitidos nas respostas JSON.
• Datas no formato ISO 8601 (2026-10-08T00:00:00). Valores numéricos com ponto como separador decimal.
• Os IDs são os IDs internos do banco do ModerLoja. Para localizar um registro por código, CPF ou CNPJ, use os filtros do endpoint Listar ou Retornar do recurso.

A lista completa de recursos, campos e exemplos de requisição e resposta está na documentação técnica: moderniza-dev.github.io/varejo-docs

Cuidados ao utilizar

Aconselhamos utilizar a API com muito cuidado. As operações de gravação incluem e alteram informações diretamente no banco de dados do ModerLoja. Para manter a consistência dos dados:

• Teste a integração primeiro em um banco de homologação.
• Consulte o registro antes de alterar, enviando o objeto completo no Salvar, para não apagar campos que não fazem parte da integração.
• Trate as respostas de erro e registre em log as requisições enviadas.
• Respeite as regras de negócio do sistema (por exemplo, não altere documentos fiscais autorizados).