# 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.

### 1 · 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**

```sh
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`](/erros/api_key_wrong_environment.md).

### 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](/sdks.md).

### 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.

#### curl

**Criar um pedido**

```sh
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 }]
  }'
```

#### Node

**Criar um pedido**

```js
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 }]
})
```

#### Python

**Criar um pedido**

```python
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}]
})
```

#### PHP

**Criar um pedido**

```php
<?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]]
]);
```

#### Java

**Criar um pedido**

```java
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))
));
```

#### C#

**Criar um pedido**

```csharp
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 }}
});
```

#### Go

**Criar um pedido**

```go
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}},
})
```

#### Rust

**Criar um pedido**

```rust
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`](/erros/order_already_imported.md): 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.

#### curl

**Cadastrar o endereço**

```sh
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"]
  }'
```

#### Node

**Cadastrar o endereço**

```js
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']
})
```

#### Python

**Cadastrar o endereço**

```python
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"]
})
```

#### PHP

**Cadastrar o endereço**

```php
<?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']
]);
```

#### Java

**Cadastrar o endereço**

```java
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")
));
```

#### C#

**Cadastrar o endereço**

```csharp
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"}
});
```

#### Go

**Cadastrar o endereço**

```go
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"},
})
```

#### Rust

**Cadastrar o endereço**

```rust
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.

#### curl

**Mandar um evento de teste**

```sh
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" }'
```

#### Node

**Mandar um evento de teste**

```js
import { Kernos } from '@kernosbr/kernos'

const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.integrationWebhook.ping({ type: 'ping' })
```

#### Python

**Mandar um evento de teste**

```python
import os
from kernos import Kernos

kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.integration_webhook.ping({"type": "ping"})
```

#### PHP

**Mandar um evento de teste**

```php
<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->integrationWebhook->ping(['type' => 'ping']);
```

#### Java

**Mandar um evento de teste**

```java
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.integrationWebhook().ping(Map.of("type", "ping"));
```

#### C#

**Mandar um evento de teste**

```csharp
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.IntegrationWebhook.PingAsync(new { type = "ping" });
```

#### Go

**Mandar um evento de teste**

```go
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.IntegrationWebhook.Ping(ctx, map[string]any{"type": "ping"})
```

#### Rust

**Mandar um evento de teste**

```rust
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](/guias/receber-eventos.md).

> **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](/erros.md).