REFERÊNCIA OFICIAL · API REST

Construa com os dados do ERP.

Um único ponto seguro para conectar seus aplicativos ao ERP. Consulte os recursos, entenda a autenticação e copie exemplos para começar.

Começar integração →Explorar endpoints

⌁

REST + JSONIntegração simples por HTTP

◈

MultiempresaUma conexão isolada por empresa

⌑

Segurança em camadasChave, aparelho e sessão

⌘

… operaçõesReferência navegável e pesquisável

ANTES DE FAZER REQUISIÇÕES

Autenticação por camadas

A API seleciona o banco pela empresa da chave. O aplicativo nunca recebe acesso direto ao SQL Server.

⌑

Chave de acesso

Identifica o cliente e a empresa vinculada. Envie em toda chamada protegida.

X-API-Key: SUA_CHAVE

◉

Dispositivo ativado

Vincule a chave uma vez e envie o mesmo identificador do aparelho nas chamadas seguintes.

X-Device-Id: device-único

↗

Sessão do usuário

Faça login pelo provedor configurado no servidor. Use o JWT nas rotas de negócio.

Authorization: Bearer <JWT>

ADM

▣

Administração

Rotas para empresas, chaves, usuários e auditoria usam o token administrativo, separado da chave do app.

X-Admin-Token: <token>

Autenticação configurada neste servidor: mobile, que valida credenciais cadastradas pela administração da API. Para validar diretamente a senha do ERP, configure PROVEDOR_CREDENCIAL=erp e uma procedure de validação em ERP_LOGIN_SP; veja os detalhes nas operações de login e credenciais.

Proteja credenciais e tokens. Não os coloque em aplicativos públicos, repositórios, capturas de tela ou logs. Chaves recuperáveis podem ser consultadas pelo administrador no painel. Restrinja o token administrativo à rede de administração.

COMECE EM QUATRO ETAPAS

Primeira integração

Os endpoints versionados agora usam /api/v1. O caminho antigo /v1 continua ativo temporariamente para os apps já instalados. Em produção, prefira HTTPS e um endereço DNS estável.

BASE URL…

Configure uma empresa e emita a licença

No painel administrativo, cadastre e teste o banco da empresa. Emita uma chave vinculada a ela e marque os módulos necessários, como gestao.

ADMIN

Ative a chave no dispositivo

Envie POST /api/v1/dispositivos/ativar com a chave e um deviceId estável. Guarde esse mesmo ID no dispositivo.

UMA VEZ

Entre com o usuário

Envie login e senha em POST /api/v1/auth/login. O provedor de autenticação é configurado no servidor. A resposta fornece accessToken e refreshToken.

SESSÃO

Chame os recursos liberados

Inclua chave, device ID e token Bearer. A API escolhe o banco da empresa e valida sessão, permissões e módulo.

API

Ativação · cURL

curl -X POST "https://seu-servidor:3010/api/v1/dispositivos/ativar" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"android-uuid-estavel","nomeDispositivo":"Meu aparelho","versaoApp":"1.0.0"}'

Login · cURL

curl -X POST "https://seu-servidor:3010/api/v1/auth/login" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "X-Device-Id: android-uuid-estavel" \
  -H "Content-Type: application/json" \
  -d '{"login":"SEU_USUARIO","senha":"SUA_SENHA"}'

REFERÊNCIA DE ENDPOINTS

Encontre uma operação

Busque por recurso, rota ou método. Selecione uma operação para ver autenticação, uso e exemplos.

↔

Paginação: endpoints paginados aceitam pagina (padrão 1) e tamanho (limites variam por endpoint; cadastros auxiliares aceitam até 100). A maioria retorna dados, total, pagina, tamanho e totalPaginas; algumas listas retornam apenas dados, conforme detalhado na operação.

Carregando catálogo de operações…

⌘

Selecione um endpoint

Os detalhes da operação aparecem aqui.

CLIENTES HTTP

Exemplos em várias linguagens

Exemplo de uma chamada autenticada. Substitua URL, chave, device ID e token pelos valores da sua instalação.

GET · clientes

Em aplicativos móveis, armazene tokens com armazenamento seguro do sistema. Renove a sessão com POST /api/v1/auth/refresh e encerre com POST /api/v1/auth/logout.

CONTRATO DE ERRO

Erros e limites

Erros da API usam o mesmo envelope JSON. O campo codigo é estável e pode orientar a ação do aplicativo.

HTTP	Código	O que fazer
400	`REQUISICAO_INVALIDA`	Revise corpo, parâmetros e campos informados.
401	`CHAVE_AUSENTE / CHAVE_INVALIDA / CHAVE_REVOGADA / CHAVE_EXPIRADA`	Confira a chave e a licença com o administrador.
401	`CHAVE_NAO_ATIVADA / DISPOSITIVO_DIVERGENTE`	Ative a chave ou use o dispositivo já vinculado.
401	`CREDENCIAIS_INVALIDAS / USUARIO_BLOQUEADO`	Confira o login/senha ou aguarde o desbloqueio.
401	`TOKEN_AUSENTE / TOKEN_INVALIDO / TOKEN_EXPIRADO / SESSAO_REVOGADA`	Faça refresh quando aplicável ou realize login novamente.
403	`SEM_PERMISSAO / MODULO_INDISPONIVEL`	Solicite ao administrador as permissões ou módulo corretos.
404	`NAO_ENCONTRADO`	Confira o código do recurso.
404	`ROTA_NAO_ENCONTRADA`	Confira método HTTP e caminho da rota.
409	`CONFLITO / EM_PROCESSAMENTO`	Resolva conflito; para reenvio de pedido, reuse a mesma chave de idempotência.
422	`REGRA_NEGOCIO`	Mostre a mensagem retornada e ajuste os dados segundo o ERP.
429	`MUITAS_REQUISICOES`	Aplique espera progressiva e tente novamente.
500 / 503	`ERRO_INTERNO / BANCO_INDISPONIVEL`	Não exponha detalhes internos; tente novamente e consulte os logs/administrador.

Resposta de erro

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "erro": {
    "codigo": "TOKEN_EXPIRADO",
    "mensagem": "Sessão expirada. Renove o acesso."
  }
}

↻

Idempotência para pedidos. POST /api/v1/pedidos exige Idempotency-Key com UUID. Em timeout, reenvie o mesmo corpo com o mesmo UUID. Não gere um novo UUID antes de saber se a operação anterior foi concluída.

ACESSO POR LICENÇA

Módulos e disponibilidade

As consultas por módulo verificam a licença, a sessão e a empresa vinculada à chave.

↗

Vendas

Resumo, vendas realizadas, itens e pedidos nativos. Os pedidos da Força de Venda continuam em suas rotas próprias.

forca_venda

▤

Orçamentos

Listar, consultar, criar, editar e cancelar conforme regras de negócio.

orcamento

▧

Liberações

Consulta de bloqueios pendentes. Aprovação continua no ERP/Agente7.

liberacao

⚒

Ordem de serviço

Consulta de OS, materiais, serviços, apontamentos e despesas. Gravação permanece no ERP.

ordem_servico

▦

Gestão

Dashboard empresarial, comparativos, vendas diárias e rankings. Requer licença do módulo Gestão.

gestao

Financeiro

Contas a pagar e receber, saldos em aberto, vencimentos e movimentos financeiros. Somente leitura.

financeiro

Caixa

Períodos de caixa, fechamentos e movimentações vinculadas. Somente leitura.

caixa

Fiscal

Notas e documentos fiscais resumidos. A API não transmite documentos nem expõe XML por estas rotas.

fiscal

Compras

Pedidos de compra e seus itens, com recebimentos e situação. Somente leitura.

compras

Estoque

Catálogo, saldo por produto e dados auxiliares existentes na API.

estoque

≡

Relatórios

Catálogo de relatórios cadastrados. Consultas SQL configuradas no ERP não são executadas pela API.

relatorios

Operações de alteração: os novos endpoints financeiro, caixa, fiscal, compras e relatórios são somente leitura. Pagamentos, recebimentos, fechamento de caixa, emissão/cancelamento fiscal e gravação de compras não são expostos até integrarem as validações nativas correspondentes do ERP.