Produtos › Criar

Cadastra um item

POST/v1/objects/product

Pede a descrição e ao menos um código: EAN ou SKU (missing_identity sem nenhum). EAN e SKU são únicos na empresa.

Ação da chave: product.create

Quem cria a chave escolhe as ações que ela abre; sem esta, a rota recusa com api_key_action_not_granted.

Toda escrita pede Idempotency-Key

Um UUID por escrita. Repetida com o mesmo corpo, devolve a mesma resposta sem escrever de novo. Os SDKs mandam sozinhos.

Corpo

description string OBRIGATÓRIO

ean string

sku string

source string

A origem da leitura, para o livro de recusas.

tracks_lot boolean ou string

true ou false.

uom string

O código da unidade na NF-e; H87 (peça) por padrão.

Devolve

O data do envelope { ok, data, error, error_code, field, trace_id }:

product objeto OBRIGATÓRIO

11 campos

active boolean

complete boolean

O cadastro tem o que o galpão precisa para operar o item.

created_at data e hora

description string

ean string, ou nulo

id uuid

short_code string, ou nulo

sku string, ou nulo

tracks_lot boolean

traits objeto

Os atributos do item, pelo catálogo da empresa, na unidade base (peso em g, medidas em mm).

uom string

A unidade de medida, pelo código da NF-e (H87 é peça).

Recusas

HTTP 400 · Pedido mal formado

invalid_idempotency_key HTTP 400Toda escrita pede o cabeçalho Idempotency-Key com um UUID.

version_unknown HTTP 400A Kernos-Version pedida não existe. Use uma das versões declaradas no cabeçalho, ou não o mande.

HTTP 401 · Sem credencial válida

api_key_expired HTTP 401A chave venceu. Gire a chave no painel e use a nova.

api_key_wrong_environment HTTP 401A chave é do outro ambiente: ksk_test_ vai em https://stag.kernos.com.br, ksk_live_ em https://api.kernos.com.br.

unauthenticated HTTP 401Credencial ausente, inválida ou expirada.

HTTP 403 · Sem permissão

agent_token_out_of_scope HTTP 403O token de agente (kat_) só vale na porta MCP. Para a API, use o token de sessão ou uma chave de integração.

api_key_action_not_granted HTTP 403A chave não tem esta ação. Edite as ações da chave no painel.

api_key_out_of_scope HTTP 403A chave só vale nas rotas do contrato público.

depot_out_of_reach HTTP 403Quem chama não alcança o CD deste objeto. Peça alcance ao CD ou use outra credencial.

forbidden_role HTTP 403O papel de quem chama nesta empresa não permite esta ação.

module_not_subscribed HTTP 403A empresa não assina o módulo desta rota.

tenant_mismatch HTTP 403A credencial não pertence à empresa do endereço chamado.

tenant_unavailable HTTP 403A empresa está indisponível no momento.

HTTP 409 · Conflito

duplicate_ean HTTP 409Já existe produto com este EAN nesta empresa.

duplicate_sku HTTP 409Já existe produto com este SKU nesta empresa.

idempotency_key_reused HTTP 409Esta Idempotency-Key já foi usada com outro corpo. Gere uma chave nova para uma escrita nova.

HTTP 422 · Não processável

invalid_ean HTTP 422O EAN tem de ter só dígitos, de 8 a 14 (EAN-8, UPC, EAN-13 ou GTIN-14).

missing_description HTTP 422O nome do produto (description) é obrigatório.

missing_identity HTTP 422Informe pelo menos um identificador: sku ou ean.

unknown_uom HTTP 422A unidade de medida não existe nesta empresa.

HTTP 429 · Muitos pedidos

rate_limited HTTP 429Muitos pedidos por segundo com esta chave. Espere o Retry-After, em segundos, e tente de novo.

curlNodePythonPHPJavaC#GoRust

Cadastra um item

curl -X POST "https://stag.kernos.com.br/v1/objects/product" \
  -H "Authorization: Bearer ksk_test_…" \
  -H "Kernos-Version: 2026-10-03" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Camiseta verde M",
    "ean": "7891000315507",
    "sku": "CAM-VD-M",
    "source": "import"
  }'

Cadastra um item

import { Kernos } from '@kernosbr/kernos'

const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.product.create({
  description: 'Camiseta verde M',
  ean: '7891000315507',
  sku: 'CAM-VD-M',
  source: 'import'
})

Cadastra um item

import os
from kernos import Kernos

kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.product.create({
  "description": "Camiseta verde M",
  "ean": "7891000315507",
  "sku": "CAM-VD-M",
  "source": "import"
})

Cadastra um item

<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->product->create([
  'description' => 'Camiseta verde M',
  'ean' => '7891000315507',
  'sku' => 'CAM-VD-M',
  'source' => 'import'
]);

Cadastra um item

Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.product().create(Map.of(
    "description", "Camiseta verde M",
    "ean", "7891000315507",
    "sku", "CAM-VD-M",
    "source", "import"
));

Cadastra um item

var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.Product.CreateAsync(new {
  description = "Camiseta verde M",
  ean = "7891000315507",
  sku = "CAM-VD-M",
  source = "import"
});

Cadastra um item

client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.Product.Create(ctx, map[string]any{
  "description": "Camiseta verde M",
  "ean": "7891000315507",
  "sku": "CAM-VD-M",
  "source": "import",
})

Cadastra um item

let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.product().create(&json!({
  "description": "Camiseta verde M",
  "ean": "7891000315507",
  "sku": "CAM-VD-M",
  "source": "import"
}), None)?;

Resposta · 200 (a forma, sem dado real)

{
  "ok": true,
  "data": {
    "product": {
      "active": true,
      "complete": true,
      "created_at": "2026-10-03T12:00:00Z",
      "description": "…",
      "ean": "…",
      "id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
      "short_code": "…",
      "sku": "…",
      "tracks_lot": true,
      "traits": {},
      "uom": "…"
    }
  },
  "error": null,
  "error_code": null,
  "field": null,
  "trace_id": null
}

Ambiente

ksk_test_ fala com https://stag.kernos.com.br; ksk_live_, com https://api.kernos.com.br. O prefixo da chave escolhe o endereço.