API do KontNotas

O cliente pode ser informado por customerId ou por customer.document — integrações costumam conhecer o CNPJ, não o id interno. Passe "issue": false para deixar em rascunho. Cada item referencia o serviço por serviceId — é dele que saem código municipal, item da LC 116 e alíquota.

{
  "customer": { "document": "11.222.333/0001-81" },
  "documentType": "NFSE",
  "description": "Consultoria de marketing — agosto/2026",
  "competenceDate": "2026-08-31",
  "items": [
    {
      "description": "Gestão de mídias sociais",
      "quantityMilli": 1000,
      "unitPriceCents": 350000,
      "unit": "UN"
    }
  ],
  "issue": true
}

Valores são inteiros em centavos e quantidades em milésimos (1 unidade = 1000). Não há ponto flutuante em lugar nenhum da API — é o que garante que R$ 0,01 nunca desapareça num arredondamento.

A resposta é 202 com a nota — inclusive com "issue": false. A emissão é assíncrona: a nota volta em queued (ou draft) e o desfecho chega depois, pela consulta ou pelos webhooks.

Serviço de construção civil (subitens 07.02, 07.04, 07.05, 07.06, 07.07, 07.08, 07.17, 07.19 e 14.14 em obra): o fisco recusa a nota sem a identificação da obra. Envie-a em obra, numa das três formas — o número do CNO, o endereço da obra ou o código CIB. O mesmo objeto volta na resposta.

{ "obra": { "tipo": "cno", "codigo": "12.345.67890/12" } }

{ "obra": { "tipo": "endereco", "cep": "89010-000", "logradouro": "Rua XV de Novembro",
            "numero": "100", "bairro": "Centro" } }

{ "obra": { "tipo": "cib", "codigo": "1234567X" } }

Filtros: status e customerId. Paginação por limit (1 a 100, padrão 25) e offset. Não há filtro por período — para um recorte de datas, pagine e filtre pelo competenceDate de cada nota.

{
  "object": "list",
  "data": [ { "object": "invoice", "id": "inv_01J...", "status": "authorized", … } ],
  "total": 128,
  "hasMore": true
}

O status segue a máquina de estados do documento: draft → validating → queued → processing → authorized, com pending quando a conferência barra a nota por cadastro, rejected e error como desfechos da emissão e cancelling → cancelled no cancelamento (recusado, ele volta a authorized). Enquanto estiver em validating, queued ou processing, consulte — não reemita.

Na nota recusada, rejection traz a tradução do KontNotas (code, message e hint) e o que o provedor disse, cru: providerCode, providerMessage, field e details — todas as rejeições, cada uma com a correction que o município manda, quando manda. Oriente pelo code; mostre à pessoa o providerMessage. Os campos crus são null em nota rejeitada antes de 25/09/2026 e em falha técnica.

"rejection": {
  "code": "E0120",
  "message": "IM do prestador não deve ser informado, pois não existem…",
  "hint": "…",
  "providerCode": "E0120",
  "providerMessage": "(o texto do fisco, como veio)",
  "field": "IM",
  "details": [
    { "code": "E0120", "message": "(…)", "field": "IM", "correction": null }
  ]
}

Sem tipo, é o PDF. Nota inexistente, de outra organização ou arquivada responde 404 KONTNOTAS_INVOICE_NOT_FOUND; nota que ainda não tem o arquivo pedido responde 404 KONTNOTAS_NOT_FOUND — o XML fica disponível depois da autorização, e o PDF depende do provedor fiscal. Todo download entra na trilha de auditoria da organização.

O prazo e as regras de cancelamento são do município, não do KontNotas. Quando a nota está fora do prazo, a resposta explica isso em vez de tentar e falhar. A resposta é 202 com a nota em cancelling, até o provedor confirmar.

{
  "object": "list",
  "data": [
    {
      "object": "service",
      "id": "svc_01J...",
      "numero": 3,
      "name": "Toxina botulínica",
      "municipalServiceCode": "0602",
      "lc116Code": "06.02",
      "cnaeCode": "9602502",
      "issRateBps": 300,
      "fiscalConfigured": true
    }
  ],
  "total": 4,
  "hasMore": false
}

Serviços excluídos ficam de fora, como ficam da tela de emissão. fiscalConfigured só é verdadeiro com código de serviço e alíquota de ISS — sem os dois, a nota com esse serviço não passa pela conferência. Paginação por limit e offset.

numero é o número de cadastro — o “nº 3” que a tela mostra ao lado do nome. É por organização, estável e nunca reaproveitado, nem depois de o serviço ser excluído. O item da nota continua referenciando o serviço pelo id.

{ "object": "service", "id": "svc_01J...", "numero": 3, "deleted": true, "archived": true }

Serviço usado por alguma nota (rascunho incluído), recorrência ou automação é arquivado, com archived: true: sai do catálogo e da emissão, e as notas antigas continuam inteiras. Sem uso nenhum, é apagado de vez, com archived: false.

Id de outra organização, inexistente ou já excluído responde 404 KONTNOTAS_SERVICE_NOT_FOUND. Emitir com um serviço excluído responde 422 KONTNOTAS_SERVICE_ARCHIVED, sem criar a nota.

{
  "object": "organization",
  "id": "org_01J...",
  "name": "Clínica Bella Estética Ltda.",
  "document": "11222333000181",
  "documentType": "CNPJ",
  "environment": "production",
  "certificate": { "status": "valid", "notAfter": "2027-03-12T00:00:00.000Z" },
  "fiscalReady": true,
  "pending": []
}

Do certificado saem só a situação e a validade — nada que o identifique. fiscalReady diz se uma NFS-e mandada com esta chave passaria pela configuração da organização, e pending lista, em texto, o que falta. O ambiente que vale é o da chave: uma chave kn_live_ numa organização ainda em testes aparece como pendência.

A conferência é a do pré-voo da emissão, na parte que não depende da nota — CNPJ e endereço da empresa, inscrição municipal, dados do Simples, certificado —, somada às credenciais do provedor e aos escopos da chave: sem invoice.create, invoice.issue e customer.manage, a emissão volta 403, e a chave aparece como pendência.

{
  "object": "usage",
  "period": "2026-09",
  "plan": { "key": "start", "name": "Start" },
  "invoices": { "used": 12, "limit": 30, "remaining": 18, "exceeded": false }
}

limit e remaining são null no plano ilimitado. exceeded é verdadeiro quando a próxima nota seria recusada pelo limite — com 30 de 30, já é. O período é o mês de apuração do contador, com a virada à meia-noite de Brasília.