PrimuxDocs

Referência da API

API de integração do Primux Nexus

Conecte o seu ERP a lojas virtuais, balanças, aplicativos e planilhas. Com uma chave de acesso, o outro sistema consulta, cadastra, altera e exclui os produtos da empresa, sem passar pela tela.

Basehttps://dev-api.primux.cloud AuthBearer nxs_… FormatoJSON · UTF-8
URL base
https://dev-api.primux.cloud/v1/nexus

Visão geral

A API segue o padrão REST: cada rota tem um endereço, um método HTTP e responde em JSON (UTF-8). Hoje ela cobre os produtos da empresa; novas áreas do ERP serão acrescentadas no mesmo endereço.

  • Uma chave identifica a empresa: não é preciso informar o código da empresa nas rotas.
  • O Nexus precisa estar com a assinatura em dia. Empresa suspensa, cancelada ou com cobrança em atraso recebe o erro 403 empresa_inativa.
  • Tudo o que a API grava passa pelas mesmas regras da tela de produtos (campos obrigatórios, código de barras repetido, categoria e unidade existentes) e fica na auditoria da empresa.
  • Os valores numéricos voltam como texto com casas fixas (por exemplo, "8.9000"). Ao enviar, use número ou texto.
A API não altera o saldo de estoque: ele continua sendo movimentado por compras, vendas e ajustes dentro do ERP.
Resposta 200
{
  "empresa": { "codigo": "mercado-bom-preco" },
  "chave": { "nome": "Loja virtual", "acesso": "escrita" }
}

Início rápido

  1. No console, abra Nexus e, em API de integração, crie uma chave: dê um nome (por exemplo, Loja virtual) e escolha o acesso.
  2. Copie a chave que aparece (começa com nxs_). Por segurança ela não é mostrada de novo.
  3. Guarde a chave numa variável de ambiente do seu sistema, nunca no código nem em arquivos versionados.
  4. Teste com GET /v1/nexus/eu: se voltar o código da empresa, a chave está valendo. Depois use as rotas de produtos.

O exemplo ao lado sincroniza um preço: procura o produto pelo código de barras e atualiza o preço; se ele não existir, cadastra. É o fluxo mais comum de uma loja virtual ou de uma balança.

Atualizar o preço (ou cadastrar) pelo código de barras
# 1) procura pelo código de barras
curl "https://dev-api.primux.cloud/v1/nexus/produtos?busca=7891000100134" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"

# 2a) se achou, atualiza o preço (só o campo enviado muda)
curl -X PATCH "https://dev-api.primux.cloud/v1/nexus/produtos/7" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"preco_venda":9.49}'

# 2b) se não achou, cadastra
curl -X POST "https://dev-api.primux.cloud/v1/nexus/produtos" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"descricao":"Feijão Carioca 1kg","codigo_barras":"7891000100134","preco_venda":9.49}'

Chaves de acesso

Cada sistema que se conecta deve ter a sua própria chave. Assim dá para revogar uma sem parar as outras.

  • Somente leitura: só consulta produtos (GET). Ideal para vitrines, painéis e relatórios.
  • Leitura e escrita: também cadastra, altera e exclui (POST, PUT, PATCH e DELETE).
  • Cada empresa pode ter até 10 chaves ativas ao mesmo tempo.
  • Revogue a chave no console assim que ela vazar ou o sistema deixar de ser usado: o acesso para na hora.

Abrir o Nexus no console

A chave vale como senha da empresa. Quem a tem faz tudo o que o acesso dela permite.
Variável de ambiente
export PRIMUX_NEXUS_CHAVE="nxs_COLE_AQUI_A_SUA_CHAVE"

Autenticação

Envie a chave em todas as requisições, no cabeçalho Authorization, no formato Bearer. Não envie a chave na URL.

Muitas tentativas com chave inválida bloqueiam o endereço por um minuto (erro 429).
Cabeçalho HTTP
Authorization: Bearer nxs_0123456789abcdefghijklmnopqrstuvwxyz0123456

Referência da API

Empresa e chave em uso

GET/v1/nexus/eu

Devolve o código da empresa e o nome e o acesso da chave. Use para testar a conexão.

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/nexus/eu" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"
Resposta
{
  "empresa": { "codigo": "mercado-bom-preco" },
  "chave": { "nome": "Loja virtual", "acesso": "escrita" }
}

Referência da API

Listar produtos

GET/v1/nexus/produtos?busca=leite&status=ativo&limite=50

Lista os produtos. Parâmetros opcionais: busca (parte da descrição, do código de barras ou do código interno), status (ativo ou inativo) e limite (padrão 50, máximo 200).

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/nexus/produtos?busca=leite&status=ativo&limite=50" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"
Resposta
{
  "produtos": [
    {
      "id": "5",
      "descricao": "Leite Integral 1L",
      "codigo_barras": "7891000100110",
      "preco_venda": "5.4900",
      "preco_custo": "0.0000",
      "unidade_medida_id": "1",
      "status": "ativo",
      "...": "demais campos do produto"
    }
  ],
  "total": 1,
  "limite": 50
}

Referência da API

Ver um produto

GET/v1/nexus/produtos/5

Devolve todos os campos de um produto, pelo id. Produto que não existe responde 404 nao_encontrado.

Requisição
curl -X GET "https://dev-api.primux.cloud/v1/nexus/produtos/5" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"
Resposta
{
  "id": "5",
  "descricao": "Leite Integral 1L",
  "codigo_barras": "7891000100110",
  "marca": "",
  "preco_venda": "5.4900",
  "preco_custo": "0.0000",
  "estoque_minimo": "0.000",
  "unidade_medida_id": "1",
  "categoria_id": "",
  "categoria_nome": "",
  "status": "ativo",
  "...": "demais campos do produto"
}

Referência da API

Cadastrar produto

POST/v1/nexus/produtos

Cadastra um produto (chave com escrita). Só descricao e preco_venda são obrigatórios. Responde 201 com o produto criado e o endereço dele no cabeçalho Location.

Parâmetros do corpo

descricao texto obrigatório
Nome do produto, como aparece no PDV e no cupom.
preco_venda número obrigatório
Preço de venda, em reais. Use ponto nos decimais (8.9).

A lista completa de campos, com os fiscais, está em Campos do produto.

Requisição
curl -X POST "https://dev-api.primux.cloud/v1/nexus/produtos" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"codigo_barras":"7891000100134","descricao":"Feijão Carioca 1kg","marca":"Tio João","preco_custo":6.1,"preco_venda":8.9,"unidade_medida_id":1}'
Resposta
{
  "id": "7",
  "descricao": "Feijão Carioca 1kg",
  "codigo_barras": "7891000100134",
  "marca": "Tio João",
  "preco_custo": "6.1000",
  "preco_venda": "8.9000",
  "status": "ativo",
  "...": "demais campos do produto"
}

Referência da API

Alterar produto

PATCH/v1/nexus/produtos/7

Altera um produto (chave com escrita). Só os campos enviados mudam; o resto continua como está. PUT e PATCH fazem a mesma coisa.

Requisição
curl -X PATCH "https://dev-api.primux.cloud/v1/nexus/produtos/7" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"preco_venda":9.49}'
Resposta
{
  "id": "7",
  "descricao": "Feijão Carioca 1kg",
  "preco_venda": "9.4900",
  "...": "demais campos do produto"
}

Referência da API

Excluir produto

DELETE/v1/nexus/produtos/7

Exclui um produto (chave com escrita). Responde 204, sem corpo.

Requisição
curl -X DELETE "https://dev-api.primux.cloud/v1/nexus/produtos/7" \
  -H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"
Resposta
(sem corpo — resposta 204)

Campos do produto

Estes são os campos que a API aceita ao cadastrar ou alterar. Os campos fiscais não listados aqui (CST, CSOSN, alíquotas e outros) seguem o cadastro do ERP e também são aceitos.

descricao texto (até 200) obrigatório
Nome do produto, como aparece no PDV e no cupom.
preco_venda número obrigatório
Preço de venda, em reais. Use ponto nos decimais (8.9).
codigo_barras texto (até 20)
Código de barras (EAN). Não pode repetir em outro produto da empresa.
codigo_interno texto (até 40)
Código próprio da empresa para o produto.
marca texto (até 100)
Marca do produto.
preco_custo número
Preço de custo, em reais.
categoria_id inteiro
Id de uma categoria já cadastrada no ERP.
unidade_medida_id inteiro
Id da unidade de medida (por exemplo, UN ou KG) já cadastrada no ERP.
estoque_minimo número
Estoque mínimo para o alerta de reposição.
peso_kg número
Peso em quilos.
imagem_url texto (https ou /caminho)
Endereço da foto: https://… ou um caminho do próprio sistema.
status ativo | inativo
ativo (aparece no PDV) ou inativo.
ncm texto (até 10)
NCM do produto (nota fiscal).
cest texto (até 10)
CEST do produto (substituição tributária).
cfop texto (até 5)
CFOP padrão do produto.
Campo com nome desconhecido não é ignorado: a API responde 422 e aponta o campo, para você não gravar errado em silêncio.
Corpo de um cadastro
{
  "descricao": "Feijão Carioca 1kg",
  "codigo_barras": "7891000100134",
  "marca": "Tio João",
  "preco_custo": 6.1,
  "preco_venda": 8.9,
  "unidade_medida_id": 1
}

Erros

Quando algo dá errado, a resposta traz o status HTTP e um JSON com erro (código fixo, bom para o seu programa) e mensagem (texto para a pessoa). No 422, campos mostra o que corrigir em cada campo.

StatusCódigoQuando acontece
400corpo_invalidoO corpo não é um objeto JSON válido.
401nao_autenticadoFaltou o cabeçalho Authorization: Bearer <chave>.
401chave_invalidaA chave não existe ou foi revogada.
403empresa_inativaA empresa está suspensa, cancelada ou com a cobrança em atraso.
403sem_permissaoA chave é só de leitura e a rota grava (POST, PUT, PATCH ou DELETE).
404nao_encontradoO produto não existe nesta empresa.
404rota_inexistenteA rota não existe. Confira o endereço e o método.
405metodo_nao_permitidoO método HTTP não é aceito.
413corpo_grandeO corpo passa de 64 KB.
422dados_invalidosAlgum campo está inválido ou é desconhecido. Veja campos na resposta.
429limite_excedidoPassou de 120 requisições por minuto na mesma chave.
502servico_indisponivelO Nexus não respondeu agora. É seguro tentar de novo.
Resposta de validação (422)
{
  "erro": "dados_invalidos",
  "mensagem": "Corrija os campos indicados.",
  "campos": {
    "descricao": "Informe a descrição.",
    "preco_venda": "O preço de venda: não pode ser menor que 0."
  }
}

Limites e boas práticas

  • 120 requisições por minuto por chave (erro 429 limite_excedido, com o cabeçalho Retry-After).
  • 1.200 requisições por minuto por endereço de origem.
  • 30 tentativas com chave inválida por minuto por endereço de origem.
  • Corpo de até 64 KB por requisição.
  • Listas com até 200 produtos por chamada; use busca e limite para filtrar.

Boas práticas

  • Use uma chave por sistema e dê a ela o menor acesso possível (leitura, se só consulta).
  • Para atualizar só o preço, envie só preco_venda com PATCH: o resto do produto não muda.
  • Para achar um produto, busque pelo código de barras e use o id que voltar nas próximas chamadas.
  • Guarde o id do Nexus junto do produto no seu sistema e evite listar tudo a cada sincronização.

Tentar de novo com segurança

Os erros 429 (limite) e 502 (Nexus indisponível) são passageiros: espere e tente de novo, dobrando a espera a cada tentativa. Não repita sozinho os erros 4xx: eles pedem correção na chamada.

Tentar de novo com segurança
import os, time, requests

def chamar(metodo, url, corpo=None, tentativas=4):
    espera = 1
    for _ in range(tentativas):
        r = requests.request(metodo, url, json=corpo, timeout=15,
                             headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"})
        if r.status_code not in (429, 502):
            return r
        time.sleep(float(r.headers.get("Retry-After", espera)))
        espera *= 2
    return r

Perguntas frequentes

Posso usar a API de uma página web, direto do navegador?

Não. A chave não pode ficar exposta no navegador. Chame a API pelo servidor do seu sistema e entregue o resultado à página.

A API altera o saldo de estoque?

Não. Ela cuida do cadastro do produto. O saldo muda por compras, vendas e ajustes dentro do ERP.

Os preços voltam como texto. Por quê?

Para não perder casas decimais. Converta para número no seu sistema; ao enviar, pode mandar número ou texto.

O que acontece se o plano do Nexus vencer?

Depois da carência a empresa é suspensa e a API responde 403 empresa_inativa. Ao pagar a fatura, no financeiro do console, as mesmas chaves voltam a funcionar.

Como sei quem alterou um produto pela API?

Cada gravação fica na auditoria da empresa, em nome do dono, com o endereço de origem marcado como API.