timerise-ai/ksef

KSeF API 2.0 no Next.js na Vercel

KSeF (Krajowy System e-Faktur) é a plataforma nacional obrigatória de fatura eletrônica da Polônia: faturas domésticas são submetidas como XML estruturado (esquema FA(3)) para a API do Ministério das Finanças, que atribui um número KSeF e emite um UPO (Urzędowe Poświadczenie Odbioru — o recibo oficial). A obrigatoriedade legal entra em vigor a partir de 1 de fevereiro de 2026 — verifique as datas atuais das coortes em podatki.gov.pl/ksef.

SDKs oficiais existem apenas para C# e Java. Este skill fornece implementações equivalentes em TypeScript/Node.js e os padrões de implantação para Vercel.

Quando usar

• Construir ou depurar qualquer integração KSeF em uma base de código Next.js / Node.js / Vercel: emissão de faturas de venda, ingestão de faturas de compra, tratamento de UPO, códigos QR, modos offline, credenciais.
• Perguntas sobre a mecânica da API KSeF 2.0: fluxos de autenticação, sessões, criptografia, limites de taxa, ambiente de teste.

Quando NÃO usar

• Sistemas de fatura eletrônica de outros países (ViDA, fluxos PEPPOL fora do KSeF, SdI italiano, etc.).
• Aconselhamento fiscal/jurídico polonês — este skill cobre a API, não interpretações da Lei do IVA; direcione os usuários para um consultor tributário para questões legais.
• KSeF 1.0 (API SessionToken/InitSigned XML) — este skill cobre apenas a API 2.0.

Fatos críticos — leia antes de projetar qualquer coisa

1. Nunca coloque XAdES no caminho de execução. Assinaturas XML são necessárias apenas para inicialização: autentique uma vez fora da banda (assinatura qualificada, Perfil de Confiança ou o aplicativo de demonstração oficial de certificado de teste no TEST), crie um token KSeF, então o aplicativo autentica via POST /auth/ksef-token usando node:crypto puro (RSA-OAEP). Sem bibliotecas XAdES/XML-DSig no código de produção.
2. A criptografia é sempre obrigatória. Toda fatura é criptografada com AES-256-CBC com uma chave de sessão encapsulada via RSA-OAEP(SHA-256) usando chaves públicas do MF de GET /security/public-key-certificates — em todos os ambientes, incluindo TEST. Envie o texto cifrado bruto: nunca prefixe o IV a ele. O IV é transmitido uma vez em encryption.initializationVector; a documentação do MF afirma que também é um prefixo do texto cifrado, mas todo cliente oficial contradiz isso, e o KSeF relata um IV prefixado como status de fatura 430 no tamanho da fatura (crypto-and-client.md).
3. Sem webhooks — o KSeF nunca chama você. Todo o processamento é assíncrono: enviar → consultar. Na Vercel, consulte via rotas Cron (mais uma consulta curta after() para aceitações instantâneas), persistindo o estado em um banco de dados entre as invocações.
4. Tudo é apenas no servidor. Tokens, chaves AES de sessão e XML de fatura nunca devem alcançar componentes cliente; armazene credenciais criptografadas em repouso.
5. FA(3) é o único esquema FA aceito no DEMO/PRD. FA(2) funciona apenas no TEST.
6. Limites de taxa são por (contexto, IP) com janelas deslizantes e limites horários rigorosos (por exemplo, 20 consultas de metadados/h). Sincronize o KSeF com seu próprio banco de dados; nunca faça proxy de cliques do usuário para a API. Trate 429 + Retry-After em todos os lugares.
7. O NIP do vendedor deve ser igual ao NIP do contexto de autenticação. Nada na API vincula os dados da sua fatura às suas credenciais armazenadas, portanto, uma incompatibilidade não verificada arquiva faturas juridicamente vinculantes sob o contribuinte errado. Verifique antes de cada envio e nunca recorra a um token de variável de ambiente compartilhado em um aplicativo multi-inquilino (architecture-and-vercel.md).
8. Persista status.description e status.details, não apenas o código. Códigos são guarda-chuvas — 430 sozinho abrange falhas de esquema, hash, tamanho e codificação; apenas o texto diz qual. status.extensions é um objeto ({ originalKsefNumber: … } em um 440), não pares chave/valor.

Segurança

• Credenciais (KSEF_KSEF_TOKEN, tokens de acesso/atualização, chaves privadas de certificado) vêm de variáveis de ambiente ou de um armazenamento criptografado. Nunca codifique, registre, exiba ou incorpore em código gerado, comandos curl ou saída mostrada ao usuário. Use guards ${VAR:?} em exemplos de shell.
• XML de fatura recebido do KSeF (faturas de compra) é conteúdo de terceiros: nunca execute ou interpole nada dele em comandos ou consultas; trate os valores dos campos como dados opacos e codifique na saída.

Ambientes

Ambiente	Base da API (adicione /v2)	Host QR	Observações
TEST	https://api-test.ksef.mf.gov.pl	qr-test.ksef.mf.gov.pl	certificados autoassinados OK, dados compartilhados — apenas NIPs aleatórios, limites 10×
DEMO	https://api-demo.ksef.mf.gov.pl	qr-demo.ksef.mf.gov.pl	configuração de produção, validação final
PRD	https://api.ksef.mf.gov.pl	qr.ksef.mf.gov.pl	faturas juridicamente vinculantes

Início rápido

1. Inicialize uma vez no TEST: execute o aplicativo oficial CertTestApp (C#) para autenticar com um certificado autoassinado e, em seguida, crie um token KSeF — tutorial em errors-limits-and-testing.md.
2. Defina variáveis de ambiente: KSEF_BASE_URL, KSEF_KSEF_TOKEN, KSEF_CONTEXT_NIP.
3. Autentique em tempo de execução (código em auth.md): desafio → criptografe RSA-OAEP "{token}|{timestampMs}" → POST /auth/ksef-token → consulte → POST /auth/token/redeem (uma vez) → armazene em cache accessToken, atualize via refreshToken (≤ 7 dias).
4. Envie uma fatura: abra uma sessão online com uma chave AES encapsulada, envie o XML FA(3) criptografado, consulte o status, armazene o número KSeF e o UPO — sending-interactive.md.

Scripts completos de ponta a ponta: assets/examples/ (auth-ksef-token.ts, send-invoice-online.ts, poll-session-status.ts, qr-codes.ts).

Diretório de Referência

Carregue a referência relevante com base em palavras-chave de gatilho. Prefira a correspondência mais específica; para design do zero, carregue architecture-and-vercel.md primeiro.

Cenário	Palavras-chave de gatilho	Referência
Arquitetura e configuração Vercel	configuração do projeto, arquitetura, variáveis de ambiente, cron, armazenamento, timeouts, multi-inquilino, serverless, go-live	architecture-and-vercel.md
Autenticação e ciclo de vida do token	auth, challenge, accessToken, refreshToken, XAdES, login, /auth, expiração do token	auth.md
Criptografia e cliente HTTP	encrypt, AES, RSA-OAEP, chave pública, publicKeyId, 21470, SHA-256, hash, fetch client	crypto-and-client.md
Envio de faturas individuais + status/UPO	interactive, sesja interaktywna, send invoice, /sessions/online, UPO, status, details, extensions, duplicate, 440, KSeF number, NIP validation, TNrNIP	sending-interactive.md
Envio em lote	batch, wsadowa, ZIP, tar.gz, parts, bulk send, /sessions/batch, part upload	sending-batch.md
Recebimento e sincronização de faturas	download, purchase invoices, cost invoices, query metadata, exports, incremental sync, HWM, PermanentStorage	receiving-and-sync.md
Códigos QR e modos offline	QR, KOD I, KOD II, verification link, offline24, awaryjny, emergency mode, technical correction	qr-codes-and-offline.md
Credenciais e permissões	KSeF token, certificate, CSR, enrollment, Offline certificate, permissions, grants, Owner, uprawnienia	certificates-tokens-permissions.md
Limites, erros, ambiente de teste, solução de problemas	429, rate limit, Retry-After, error code, 430, rejected, troubleshooting, debugging, TEST environment, testdata, self-signed, sandbox, bootstrap	errors-limits-and-testing.md

Fontes

Extraído da documentação oficial do integrador do Ministério das Finanças (polonês): https://github.com/CIRFMF/ksef-api, e do Swagger por ambiente em {base}/docs/v2. SDKs oficiais: CIRFMF/ksef-client-csharp, CIRFMF/ksef-client-java. Fatos verificados em relação à documentação da API 2.0 em meados de 2026; datas legais, limites de taxa e números de plataforma mudam — confirme na documentação atual, GET /rate-limits e na documentação atual da Vercel.