Da consulta à integração.

1. Autentique no backend

O contrato usa X-API-Key: <API_KEY>. A organização é resolvida pela chave, nunca por um tenant_id enviado no corpo. Scopes limitam as operações permitidas. Chaves serão emitidas no console quando o piloto estiver disponível.

curl 'https://api.example.invalid/v1/questions?quality=available&limit=10' \
  -H 'X-API-Key: SUA_CHAVE_NO_SERVIDOR' \
  -H 'Idempotency-Key: kubdata-lista-demo-0001'

const response = await fetch('https://api.example.invalid/v1/questions?quality=available&limit=10', {
  headers: { 'X-API-Key': process.env.KUBDATA_API_KEY,
    'Idempotency-Key': 'kubdata-lista-demo-0001' }
});
if (!response.ok) throw new Error('Kuberdata: ' + response.status);
const page = await response.json();

import os, json, urllib.request
url = 'https://api.example.invalid/v1/questions?quality=available&limit=10'
req = urllib.request.Request(url, headers={
    'X-API-Key': os.environ['KUBDATA_API_KEY'],
    'Idempotency-Key': 'kubdata-lista-demo-0001'
})
with urllib.request.urlopen(req, timeout=30) as response:
    page = json.load(response)

2. Preserve snapshot e revisão

Continue a leitura com o cursor retornado, preservando os mesmos filtros. Não junte páginas de snapshots diferentes. Guarde o ID e a revisão usados no material do aluno. ETag e If-None-Match permitem resposta 304 sem nova cobrança de objeto.

3. Para processar, faça uma cotação

1. Envie os arquivos pelo fluxo de upload e classificação.
2. Solicite POST /quotes com SKU e input.
3. Confira os componentes e o teto em créditos.
4. Crie o job com quote_id, max_credits e Idempotency-Key.
5. Consulte o job ou receba um evento assinado.

4. Trate os limites

Não repita 402 ou 403 automaticamente. Para 429, respeite Retry-After. Para falha transitória, use backoff com jitter e a mesma chave de idempotência. Nunca repita um débito com uma chave nova sem reconciliar o primeiro.