SWMS API — Documentação de Integração

Introdução

A SWMS API é uma API REST que troca mensagens em JSON (UTF-8). Todos os endpoints ficam sob o prefixo versionado /v1/ e exigem autenticação por token.

URL base

A URL base depende da instalação do SWMS no seu ambiente. Exemplo:

http://SEU_SERVIDOR/api

Todas as rotas desta documentação são relativas à URL base — por exemplo, POST {URL base}/v1/produtos/importar.

Autenticação

Toda requisição deve enviar o token de acesso no cabeçalho HTTP Authorization, no esquema Bearer:

Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

O token é gerado dentro do SWMS, em Administração → Api Tokens, pelo administrador da empresa. Cada token identifica a empresa: todos os dados gravados pela API pertencem à empresa dona do token.

Requisições sem token, com token inválido ou revogado recebem 401 Unauthorized.

Convenções da API

Upsert — criar e atualizar na mesma chamada

Os endpoints de importação funcionam por upsert: se o registro não existe, é criado; se existe, é atualizado. A chave de casamento de cada cadastro é:

• Produto → campo codigo;
• Unidade do produto → par codigoProduto + unidade;
• Cliente / Fornecedor → cnpj ou cpf (comparados só pelos dígitos). Um dos dois é obrigatório e o dígito verificador é validado.

Reenviar a mesma carga é seguro: o que já foi gravado vira atualização. Isso torna a integração tolerante a reprocessamentos.

Apoios criados automaticamente

Nos produtos, os campos categoria, marca e fabricante são resolvidos pelo título: títulos que não existem no cadastro são criados automaticamente na importação. Atenção: campo vazio ou ausente limpa a associação do produto ("a carga manda").

Produtos

POST  /v1/produtos/importar

Cria e/ou atualiza produtos e suas unidades (embalagens). As duas listas podem ser enviadas juntas ou separadamente; as unidades podem referenciar produtos da própria carga ou já cadastrados.

Exemplo de requisição

{
  "produtos": [
    {
      "codigo": "ERP-00001",
      "titulo": "Arroz Branco Tipo 1 5kg",
      "descricao": "Fardo com 6 pacotes de 5kg",
      "categoria": "Alimentos",
      "marca": "Boa Safra",
      "fabricante": "Boa Safra Alimentos SA",
      "codigoBarras": "7891234567895",
      "ncm": "10063021",
      "pesoLiquido": 5.0,
      "pesoBruto": 5.1,
      "altura": 12,
      "largura": 25,
      "comprimento": 35,
      "controleLote": true,
      "controleValidade": true,
      "diasMinimosValidade": 90,
      "rotacao": "FEFO",
      "permiteFracionamento": true,
      "ativo": true
    }
  ],
  "unidades": [
    {
      "codigoProduto": "ERP-00001",
      "unidade": "UN",
      "unidadeBase": true,
      "fator": 1,
      "codigoBarras": "7891234567895",
      "picking": true,
      "recebimento": true,
      "expedicao": true,
      "ativo": true
    },
    {
      "codigoProduto": "ERP-00001",
      "unidade": "CX",
      "fator": 6,
      "codigoBarras": "17891234567892",
      "recebimento": true,
      "expedicao": true,
      "ativo": true
    }
  ]
}

Campos de produtos[]

Campos de unidades[]

Resposta de sucesso — 200 OK

{
  "produtosNovos": 1,
  "produtosAtualizados": 0,
  "unidadesNovas": 2,
  "unidadesAtualizadas": 0,
  "categoriasCriadas": ["Alimentos"],
  "marcasCriadas": ["Boa Safra"],
  "fabricantesCriados": ["Boa Safra Alimentos SA"]
}

Clientes

POST  /v1/clientes/importar

Cria e/ou atualiza clientes. O corpo é um array de clientes. O casamento é feito pelo CNPJ/CPF (só os dígitos importam — pode enviar com ou sem máscara). Um dos dois é obrigatório em cada registro e o dígito verificador é validado — registro sem documento ou com documento inválido é recusado (resposta 400 com o erro da linha).

Exemplo de requisição

[
  {
    "titulo": "Supermercado Central Ltda",
    "tipo": "PJ",
    "cnpj": "12345678000195",
    "razaoSocial": "Supermercado Central Ltda",
    "nomeFantasia": "Central Supermercados",
    "telefoneComercial": "4133334444",
    "email": "compras@central.com.br",
    "cep": "80010000",
    "endereco": "Rua das Flores",
    "numero": "1500",
    "bairro": "Centro",
    "cidade": "Curitiba",
    "estado": "PR",
    "ativo": true
  }
]

Campos do cliente / fornecedor

Resposta de sucesso — 200 OK

{ "novos": 1, "atualizados": 0 }

Fornecedores

POST  /v1/fornecedores/importar

Cria e/ou atualiza fornecedores. O corpo, os campos e as respostas são idênticos aos de Clientes (veja a tabela acima): array de registros, casamento por CNPJ/CPF (obrigatório e validado), e resposta 200 com novos / atualizados.

Códigos de resposta

Exemplo de erro de validação — 400

{
  "erros": [
    "Clientes linha 1: CNPJ deve ter 14 dígitos",
    "Clientes linha 3: Título repetido na planilha"
  ]
}

Boas práticas

• Envie em lotes (a carga inteira numa chamada) em vez de um registro por requisição
• Em caso de 400, corrija os itens apontados e reenvie a carga completa — o upsert garante que nada duplica;
• Trate 401 como token expirado/revogado: gere um novo no SWMS e atualize a configuração do ERP;
• Nunca exponha o token em front-ends, logs ou repositórios de código.