Do sandbox ao primeiro evento
Quatro passos. No último, a Kernos manda um evento de teste para o seu endereço e você confere a assinatura.
Para agentes e terminalEsta página em Markdown:
/comece-aqui.mdÍndice das páginas: /llms.txt1 · Pegue a chave de teste
A chave ksk_test_… abre uma empresa de teste só sua, no piloto (https://stag.kernos.com.br), com dados de exemplo. Nesta fase, a Kernos entrega a chave junto com o convite. Ela aparece uma vez: guarde.
terminal
export KERNOS_API_KEY="ksk_test_…"A chave escolhe o ambiente
ksk_test_ só vale no piloto e ksk_live_ só na produção (https://api.kernos.com.br). Chave do outro ambiente recusa com api_key_wrong_environment.
2 · Escolha como falar com a API
Com curl não precisa instalar nada. Os SDKs (Node, Python, PHP, Java, C#, Go e Rust) cuidam da chave, da idempotência e das novas tentativas; veja SDKs e CLI.
3 · Crie um pedido
Importe um pedido de venda. O order_ref é o número no seu sistema e é a chave que impede o pedido de entrar duas vezes.
curlNodePythonPHPJavaC#GoRust
Criar um pedido
curl -X POST "https://stag.kernos.com.br/v1/objects/sales-order" \
-H "Authorization: Bearer ksk_test_…" \
-H "Kernos-Version: 2026-10-03" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"order_ref": "PED-1001",
"customer": "Loja Centro",
"lines": [{ "product": "7891234567895", "qty": 2 }]
}'Criar um pedido
import { Kernos } from '@kernosbr/kernos'
const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.salesOrder.import({
order_ref: 'PED-1001',
customer: 'Loja Centro',
lines: [{ product: '7891234567895', qty: 2 }]
})Criar um pedido
import os
from kernos import Kernos
kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.sales_order.import_({
"order_ref": "PED-1001",
"customer": "Loja Centro",
"lines": [{"product": "7891234567895", "qty": 2}]
})Criar um pedido
<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->salesOrder->import([
'order_ref' => 'PED-1001',
'customer' => 'Loja Centro',
'lines' => [['product' => '7891234567895', 'qty' => 2]]
]);Criar um pedido
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.salesOrder().importOrder(Map.of(
"order_ref", "PED-1001",
"customer", "Loja Centro",
"lines", List.of(Map.of("product", "7891234567895", "qty", 2))
));Criar um pedido
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.SalesOrder.ImportAsync(new {
order_ref = "PED-1001",
customer = "Loja Centro",
lines = new[] {new { product = "7891234567895", qty = 2 }}
});Criar um pedido
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.SalesOrder.Import(ctx, map[string]any{
"order_ref": "PED-1001",
"customer": "Loja Centro",
"lines": []any{map[string]any{"product": "7891234567895", "qty": 2}},
})Criar um pedido
let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.sales_order().import(&json!({
"order_ref": "PED-1001",
"customer": "Loja Centro",
"lines": [{ "product": "7891234567895", "qty": 2 }]
}), None)?;A resposta traz o pedido (sales_order) com o id. Repetir a chamada com o mesmo order_ref recusa com order_already_imported: o pedido não entra em dobro.
4 · Receba um evento
Cadastre o endereço HTTPS do seu sistema e mande um evento de teste.
curlNodePythonPHPJavaC#GoRust
Cadastrar o endereço
curl -X PUT "https://stag.kernos.com.br/v1/webhook-endpoint" \
-H "Authorization: Bearer ksk_test_…" \
-H "Kernos-Version: 2026-10-03" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://seu-sistema.com.br/kernos/webhook",
"events": ["sales_order.finish_packing", "shipment.dispatch"]
}'Cadastrar o endereço
import { Kernos } from '@kernosbr/kernos'
const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.integrationWebhook.save({
url: 'https://seu-sistema.com.br/kernos/webhook',
events: ['sales_order.finish_packing', 'shipment.dispatch']
})Cadastrar o endereço
import os
from kernos import Kernos
kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.integration_webhook.save({
"url": "https://seu-sistema.com.br/kernos/webhook",
"events": ["sales_order.finish_packing", "shipment.dispatch"]
})Cadastrar o endereço
<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->integrationWebhook->save([
'url' => 'https://seu-sistema.com.br/kernos/webhook',
'events' => ['sales_order.finish_packing', 'shipment.dispatch']
]);Cadastrar o endereço
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.integrationWebhook().save(Map.of(
"url", "https://seu-sistema.com.br/kernos/webhook",
"events", List.of("sales_order.finish_packing", "shipment.dispatch")
));Cadastrar o endereço
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.IntegrationWebhook.SaveAsync(new {
url = "https://seu-sistema.com.br/kernos/webhook",
events = new[] {"sales_order.finish_packing", "shipment.dispatch"}
});Cadastrar o endereço
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.IntegrationWebhook.Save(ctx, map[string]any{
"url": "https://seu-sistema.com.br/kernos/webhook",
"events": []any{"sales_order.finish_packing", "shipment.dispatch"},
})Cadastrar o endereço
let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.integration_webhook().save(&json!({
"url": "https://seu-sistema.com.br/kernos/webhook",
"events": ["sales_order.finish_packing", "shipment.dispatch"]
}), None)?;A resposta traz o secret (whsec_…) uma única vez. Guarde: é com ele que o seu servidor confere a assinatura.
curlNodePythonPHPJavaC#GoRust
Mandar um evento de teste
curl -X POST "https://stag.kernos.com.br/v1/webhook-endpoint/ping" \
-H "Authorization: Bearer ksk_test_…" \
-H "Kernos-Version: 2026-10-03" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "type": "ping" }'Mandar um evento de teste
import { Kernos } from '@kernosbr/kernos'
const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.integrationWebhook.ping({ type: 'ping' })Mandar um evento de teste
import os
from kernos import Kernos
kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.integration_webhook.ping({"type": "ping"})Mandar um evento de teste
<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->integrationWebhook->ping(['type' => 'ping']);Mandar um evento de teste
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.integrationWebhook().ping(Map.of("type", "ping"));Mandar um evento de teste
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.IntegrationWebhook.PingAsync(new { type = "ping" });Mandar um evento de teste
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.IntegrationWebhook.Ping(ctx, map[string]any{"type": "ping"})Mandar um evento de teste
let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.integration_webhook().ping(&json!({ "type": "ping" }), None)?;Pronto: o seu endereço recebeu um POST assinado. Veja como conferir a assinatura em Receber eventos.
Travou?
Todo pedido que a sua chave faz fica no registro por 30 dias: GET /v1/requests lista e GET /v1/requests/{request_id} mostra o pedido e, na chave de teste, o corpo da resposta. Cada recusa tem o seu código.