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.
https://dev-api.primux.cloud AuthBearer nxs_… FormatoJSON · UTF-8https://dev-api.primux.cloud/v1/nexusVisã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.
{
"empresa": { "codigo": "mercado-bom-preco" },
"chave": { "nome": "Loja virtual", "acesso": "escrita" }
}Início rápido
- No console, abra Nexus e, em API de integração, crie uma chave: dê um nome (por exemplo, Loja virtual) e escolha o acesso.
- Copie a chave que aparece (começa com nxs_). Por segurança ela não é mostrada de novo.
- Guarde a chave numa variável de ambiente do seu sistema, nunca no código nem em arquivos versionados.
- 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.
# 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}'<?php
$chave = getenv('PRIMUX_NEXUS_CHAVE');
$base = 'https://dev-api.primux.cloud/v1/nexus';
function chamar(string $metodo, string $url, ?array $corpo = null): array {
global $chave;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $metodo,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $chave, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => $corpo ? json_encode($corpo) : null,
]);
$dados = json_decode(curl_exec($ch), true) ?? [];
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
return [$status, $dados];
}
$codigo = '7891000100134';
[$status, $r] = chamar('GET', $base . '/produtos?busca=' . urlencode($codigo));
if ($status !== 200) { exit("Erro {$status}: {$r['erro']} - {$r['mensagem']}\n"); }
if (count($r['produtos']) > 0) {
$id = $r['produtos'][0]['id'];
[$status, $p] = chamar('PATCH', "{$base}/produtos/{$id}", ['preco_venda' => 9.49]);
} else {
[$status, $p] = chamar('POST', $base . '/produtos', [
'descricao' => 'Feijão Carioca 1kg', 'codigo_barras' => $codigo, 'preco_venda' => 9.49,
]);
}
if ($status === 422) { print_r($p['campos']); } // campo a campo, o que precisa corrigir
elseif ($status >= 400) { echo "Erro {$status}: {$p['erro']}\n"; }
else { echo "Produto {$p['id']} com preço {$p['preco_venda']}\n"; }const chave = process.env.PRIMUX_NEXUS_CHAVE;
const base = 'https://dev-api.primux.cloud/v1/nexus';
async function chamar(metodo, url, corpo) {
const r = await fetch(url, {
method: metodo,
headers: { Authorization: `Bearer ${chave}`, 'Content-Type': 'application/json' },
body: corpo ? JSON.stringify(corpo) : undefined,
});
return { status: r.status, dados: r.status === 204 ? null : await r.json() };
}
const codigo = '7891000100134';
const busca = await chamar('GET', `${base}/produtos?busca=${codigo}`);
if (busca.status !== 200) throw new Error(`${busca.status} ${busca.dados.erro}: ${busca.dados.mensagem}`);
const existente = busca.dados.produtos[0];
const { status, dados } = existente
? await chamar('PATCH', `${base}/produtos/${existente.id}`, { preco_venda: 9.49 })
: await chamar('POST', `${base}/produtos`, { descricao: 'Feijão Carioca 1kg', codigo_barras: codigo, preco_venda: 9.49 });
if (status === 422) console.error(dados.campos); // campo a campo, o que precisa corrigir
else if (status >= 400) console.error(`${status} ${dados.erro}`);
else console.log(`Produto ${dados.id} com preço ${dados.preco_venda}`);import os, requests
BASE = "https://dev-api.primux.cloud/v1/nexus"
sessao = requests.Session()
sessao.headers["Authorization"] = f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"
codigo = "7891000100134"
busca = sessao.get(f"{BASE}/produtos", params={"busca": codigo}, timeout=15)
busca.raise_for_status()
produtos = busca.json()["produtos"]
if produtos:
r = sessao.patch(f"{BASE}/produtos/{produtos[0]['id']}", json={"preco_venda": 9.49}, timeout=15)
else:
r = sessao.post(f"{BASE}/produtos", json={
"descricao": "Feijão Carioca 1kg", "codigo_barras": codigo, "preco_venda": 9.49,
}, timeout=15)
dados = r.json()
if r.status_code == 422:
print(dados["campos"]) # campo a campo, o que precisa corrigir
elif r.status_code >= 400:
print(r.status_code, dados["erro"], dados["mensagem"])
else:
print("Produto", dados["id"], "com preço", dados["preco_venda"])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.
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.
Authorization: Bearer nxs_0123456789abcdefghijklmnopqrstuvwxyz0123456Referê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.
curl -X GET "https://dev-api.primux.cloud/v1/nexus/eu" \
-H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/nexus/eu');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_NEXUS_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/nexus/eu', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_NEXUS_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/nexus/eu",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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).
curl -X GET "https://dev-api.primux.cloud/v1/nexus/produtos?busca=leite&status=ativo&limite=50" \
-H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/nexus/produtos?busca=leite&status=ativo&limite=50');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_NEXUS_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/nexus/produtos?busca=leite&status=ativo&limite=50', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_NEXUS_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/nexus/produtos?busca=leite&status=ativo&limite=50",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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.
curl -X GET "https://dev-api.primux.cloud/v1/nexus/produtos/5" \
-H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/nexus/produtos/5');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_NEXUS_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/nexus/produtos/5', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_NEXUS_CHAVE}`,
},
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/nexus/produtos/5",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"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
descricaotexto obrigatório- Nome do produto, como aparece no PDV e no cupom.
preco_vendanú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.
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}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/nexus/produtos');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{"codigo_barras":"7891000100134","descricao":"Feijão Carioca 1kg","marca":"Tio João","preco_custo":6.1,"preco_venda":8.9,"unidade_medida_id":1}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_NEXUS_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/nexus/produtos', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_NEXUS_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"descricao": "Feijão Carioca 1kg",
"codigo_barras": "7891000100134",
"marca": "Tio João",
"preco_custo": 6.1,
"preco_venda": 8.9,
"unidade_medida_id": 1
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.post(
"https://dev-api.primux.cloud/v1/nexus/produtos",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"},
json={
"descricao": "Feijão Carioca 1kg",
"codigo_barras": "7891000100134",
"marca": "Tio João",
"preco_custo": 6.1,
"preco_venda": 8.9,
"unidade_medida_id": 1
},
timeout=15,
)
dados = resposta.json(){
"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.
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}'<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/nexus/produtos/7');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_POSTFIELDS => '{"preco_venda":9.49}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_NEXUS_CHAVE'),
'Content-Type: application/json',
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/nexus/produtos/7', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_NEXUS_CHAVE}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"preco_venda": 9.49
}),
});
const dados = await resposta.json();import os, requests
resposta = requests.patch(
"https://dev-api.primux.cloud/v1/nexus/produtos/7",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"},
json={
"preco_venda": 9.49
},
timeout=15,
)
dados = resposta.json(){
"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.
curl -X DELETE "https://dev-api.primux.cloud/v1/nexus/produtos/7" \
-H "Authorization: Bearer $PRIMUX_NEXUS_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/nexus/produtos/7');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIMUX_NEXUS_CHAVE'),
],
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/nexus/produtos/7', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.PRIMUX_NEXUS_CHAVE}`,
},
});
console.log(resposta.status); // 204 = excluídoimport os, requests
resposta = requests.delete(
"https://dev-api.primux.cloud/v1/nexus/produtos/7",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_NEXUS_CHAVE']}"},
timeout=15,
)
print(resposta.status_code) # 204 = excluído(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.
descricaotexto (até 200) obrigatório- Nome do produto, como aparece no PDV e no cupom.
preco_vendanúmero obrigatório- Preço de venda, em reais. Use ponto nos decimais (8.9).
codigo_barrastexto (até 20)- Código de barras (EAN). Não pode repetir em outro produto da empresa.
codigo_internotexto (até 40)- Código próprio da empresa para o produto.
marcatexto (até 100)- Marca do produto.
preco_custonúmero- Preço de custo, em reais.
categoria_idinteiro- Id de uma categoria já cadastrada no ERP.
unidade_medida_idinteiro- Id da unidade de medida (por exemplo, UN ou KG) já cadastrada no ERP.
estoque_minimonúmero- Estoque mínimo para o alerta de reposição.
peso_kgnúmero- Peso em quilos.
imagem_urltexto (https ou /caminho)- Endereço da foto: https://… ou um caminho do próprio sistema.
statusativo | inativo- ativo (aparece no PDV) ou inativo.
ncmtexto (até 10)- NCM do produto (nota fiscal).
cesttexto (até 10)- CEST do produto (substituição tributária).
cfoptexto (até 5)- CFOP padrão do produto.
{
"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.
| Status | Código | Quando acontece |
|---|---|---|
| 400 | corpo_invalido | O corpo não é um objeto JSON válido. |
| 401 | nao_autenticado | Faltou o cabeçalho Authorization: Bearer <chave>. |
| 401 | chave_invalida | A chave não existe ou foi revogada. |
| 403 | empresa_inativa | A empresa está suspensa, cancelada ou com a cobrança em atraso. |
| 403 | sem_permissao | A chave é só de leitura e a rota grava (POST, PUT, PATCH ou DELETE). |
| 404 | nao_encontrado | O produto não existe nesta empresa. |
| 404 | rota_inexistente | A rota não existe. Confira o endereço e o método. |
| 405 | metodo_nao_permitido | O método HTTP não é aceito. |
| 413 | corpo_grande | O corpo passa de 64 KB. |
| 422 | dados_invalidos | Algum campo está inválido ou é desconhecido. Veja campos na resposta. |
| 429 | limite_excedido | Passou de 120 requisições por minuto na mesma chave. |
| 502 | servico_indisponivel | O Nexus não respondeu agora. É seguro tentar de novo. |
{
"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.
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 rPerguntas 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.