Chave, ambiente e limite
Como a chave autentica, o que ela abre, em que ambiente fala, quanto aguenta e o que fica registrado.
/guias/chave-ambiente-e-limite.mdÍndice das páginas: /llms.txtA chave decide o ambiente
| Prefixo | Ambiente | Endereço |
|---|---|---|
ksk_test_ | Piloto, numa empresa de teste | https://stag.kernos.com.br |
ksk_live_ | Produção | https://api.kernos.com.br |
Mande a chave em Authorization: Bearer ksk_…. O prefixo escolhe o endereço: com SDK você nunca configura URL. Chave do outro ambiente recusa com api_key_wrong_environment.
O que a chave abre
A chave tem ações (sales_order.import, product.list…, o id que a página de cada rota mostra) e, se quiser, uma lista de CDs. Fora delas, a rota recusa com api_key_action_not_granted. Quem cria e gira a chave é quem gere a empresa; uma chave nunca cria outra. A chave só vale nas rotas desta referência: em qualquer outra, api_key_out_of_scope.
A chave tem validade opcional. Vencida, recusa com api_key_expired. A chave inteira aparece uma vez, na criação; depois só os 4 últimos caracteres.
Cabeçalhos
| Cabeçalho | Para quê |
|---|---|
Authorization | Bearer ksk_…. |
Kernos-Version | A versão do contrato (2026-10-03). Sem ele, a mais nova. A resposta sempre diz qual usou, no mesmo cabeçalho. |
Idempotency-Key | Um UUID por escrita (POST, PUT, PATCH, DELETE). Repetida com o mesmo corpo, devolve a mesma resposta sem escrever de novo; com corpo diferente, idempotency_key_reused. |
A resposta
Toda resposta é o envelope { ok, data, error, error_code, field, trace_id }. Com ok: true, o resultado vem em data. Com ok: false, decida pelo error_code (estável), mostre o error (a frase em português) e, se for falar com a Kernos, mande o trace_id. Veja os erros.
O limite
Cada chave pode fazer 25 pedidos por segundo em ksk_live_ e 10 em ksk_test_. Passou: HTTP 429 rate_limited com Retry-After em segundos. Os SDKs esperam e repetem até 2 vezes, no 429, no 5xx e na falha de rede; nunca num 4xx.
O registro de pedidos
A Kernos guarda cada pedido da chave por 30 dias: rota, status, código de recusa e duração. GET /v1/requests lista os da própria chave e GET /v1/requests/{request_id} mostra um. Na chave de teste, o registro guarda também o corpo da resposta (até 8 KB); na de produção, nunca guarda corpo. O request_id é o X-Request-Id que você mandou ou o que a Kernos gerou.