Buscador de notas

1. Acesso

Endereço: https://buscador-e.khontra.com. Só HTTPS.

Peça à Khontra uma chave para o seu produto. Toda rota de /v1 leva o cabeçalho X-API-Key. A chave aparece uma vez, fica só no seu backend e nunca vai para o navegador. Cada produto só enxerga as empresas cujo certificado ele mesmo enviou: o resto responde 404.

curl https://buscador-e.khontra.com/v1/certificates -H "X-API-Key: $BUSCADOR_API_KEY"

2. O fluxo

1. Seu backend busca a chave pública: GET /v1/certificates/public-key.
2. O navegador do usuário cifra PFX e senha com essa chave (código abaixo). O PFX nunca anda aberto.
3. Seu backend repassa o envelope em POST /v1/certificates e guarda o serial_number.
4. De hora em hora, POST /v1/documents/search com os seriais e o next_cursor de cada um.

3. Enviar o certificado

RSA-OAEP (SHA-256) protege uma chave AES-256-GCM, que cifra {"pfx_base64", "password"}, com o kid como dado associado. A API recusa PFX aberto.

async function encryptCertificate(pfxBase64, password, state, sources, { kid, public_key_pem }) {
  const b64 = (b) => btoa(String.fromCharCode(...new Uint8Array(b)));
  const der = Uint8Array.from(
    atob(public_key_pem.replace(/-----[^-]+-----|\s/g, "")), (c) => c.charCodeAt(0));
  const rsa = await crypto.subtle.importKey(
    "spki", der, { name: "RSA-OAEP", hash: "SHA-256" }, false, ["encrypt"]);
  const aes = await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt"]);
  const nonce = crypto.getRandomValues(new Uint8Array(12));
  const ciphertext = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv: nonce, additionalData: new TextEncoder().encode(kid) }, aes,
    new TextEncoder().encode(JSON.stringify({ pfx_base64: pfxBase64, password })));
  const raw = await crypto.subtle.exportKey("raw", aes);
  const encryptedKey = await crypto.subtle.encrypt({ name: "RSA-OAEP" }, rsa, raw);
  return { kid, state, sources,
    encrypted_key: b64(encryptedKey), nonce: b64(nonce), ciphertext: b64(ciphertext) };
}

O corpo do POST /v1/certificates é o objeto devolvido. state é a UF (GO). Resposta 201: {"serial_number", "cnpj", "valid_until", "active"}. Reenviar o mesmo certificado não duplica nada.

Quais fontes ligar (sources, obrigatório)

• nfse: pode ligar sempre.
• nfe e cte: a SEFAZ tem uma fila só por CNPJ.

4. Buscar notas

curl -X POST https://buscador-e.khontra.com/v1/documents/search \
  -H "X-API-Key: $BUSCADOR_API_KEY" -H "Content-Type: application/json" \
  -d '{"serial_numbers": ["3a7f91c2d04e5b6a8c1d"], "cursors": {"3a7f91c2d04e5b6a8c1d": "..."}}'

{
  "results": {
    "3a7f91c2d04e5b6a8c1d": {
      "serial_number": "3a7f91c2d04e5b6a8c1d",
      "cnpj": "11222333000181",
      "company_name": "...",
      "certificate_active": true,
      "last_success": {"cte": null, "nfe": null, "nfse": "2026-11-04T11:55:10Z"},
      "documents": [{"doc_type": "nfse", "access_key": "...", "status": "complete", "...": "..."}],
      "next_cursor": "...",
      "has_more": false
    }
  },
  "not_found": []
}

• A busca lê o banco do buscador e nunca chama a SEFAZ. Uma nota nova leva até cerca de 1 hora para aparecer.
• next_cursor é a sua posição: enviado de volta, só vêm documentos novos ou alterados, inclusive cancelamentos. Um documento pode voltar; grave por doc_type + access_key.
• has_more: true: chame de novo na hora com o novo cursor.
• Até 100 seriais por chamada (hexadecimal, com : ou decimal). Serial desconhecido ou de outro produto vem em not_found.
• Filtros: doc_type (nfe, nfse, cte), status (summary, complete, cancelled, denied), issued_from, issued_to, limit_per_certificate (até 500) e include_xml.
• NF-e em summary é só o resumo: o XML completo depende da ciência, que só é ligada com autorização do cliente.

5. Rotas

Esquemas completos e "Try it out": Swagger.

6. Erros e limites

Erros vêm em application/problem+json com code e request_id. Mande o request_id (ou o cabeçalho X-Request-ID da resposta) quando pedir ajuda.