Saltar para o conteúdo principal
KSeF 2.0 · envio da fatura

Exceções do KSeF ao enviar uma fatura: 21405, 21180, 21184 e as restantes

Estes códigos chegam de imediato, como resposta HTTP 400 ao envio da fatura, antes de o KSeF analisar o seu conteúdo. Nisso diferem de estados como o 450, que chegam depois. No Odoo vê-os juntamente com a resposta completa do KSeF.

FlexigoTech · Responsável: Víctor Gómez · Atualizado em 5 de novembro de 2026

O essencial

Módulo
KSeF 2.0
Versões
Odoo 17, 18, 19 e 20
Verificado
no código do módulo, versão 20.0 · nas fontes indicadas no fim
Leitura
4 min

Como vê-los no Odoo

Quando o KSeF rejeita o pedido, o l10n_pl_edi no Odoo 18, 19 e 20 mostra na fatura «Error when sending invoices to the KSeF» e, por baixo, «KSeF API Error: » com a resposta tal como chegou, incluindo o exceptionCode. Na 18 e na 19 em polaco: «Podczas wysyłania faktur do KSeF wystąpił błąd» e «Błąd API KSeF: …». Se o KSeF recusar já ao abrir a sessão, a mensagem começa por «Failed to open KSeF session: ». A fatura não recebe estado KSeF, por isso, depois de corrigida, envia-a como antes.

Cartão da exceção 21405 do KSeF com os códigos do envio
O código 21405 com a respetiva descrição da API e as restantes exceções que o envio de uma fatura numa sessão interativa devolve.

Códigos, textos e o que fazer

CódigoTexto do KSeFO que fazer
21405«Błąd walidacji danych wejściowych.» (erro de validação dos dados de entrada), details do validadorLeia os details; o exemplo da documentação é «Wskazany kod formularza nie jest wspierany.» (código de formulário não suportado).
21001«Nieczytelna treść.» (conteúdo ilegível), details com uma descriçãoO KSeF não conseguiu ler o pedido; documentado na API 2.9.0 e devolvido também antes.
21155«Przekroczono dozwoloną liczbę faktur w sesji.» (demasiadas faturas na sessão)Uma sessão admite até 10 000 faturas; é preciso uma sessão nova.
21173«Brak sesji o wskazanym numerze referencyjnym.» (não existe sessão com essa referência)O KSeF não conhece a sessão guardada na empresa; o Odoo não a substitui por sua conta (abaixo).
21180«Status sesji nie pozwala na wykonanie operacji.» (o estado da sessão não o permite), p. ex. «Status sesji {code} uniemożliwia wysyłkę faktur.»A sessão foi fechada ou caducou entre a verificação e o envio.
21184«Sesja tymczasowo niedostępna.» (sessão temporariamente indisponível), com details de manutençãoO KSeF aconselha tentar mais tarde ou abrir outra sessão.
21402«Nieprawidłowy rozmiar pliku.» (tamanho de ficheiro incorreto)O tamanho do pedido não corresponde ao conteúdo.
21403«Nieprawidłowy skrót pliku.» (impressão digital do ficheiro incorreta)A impressão digital SHA-256 não corresponde ao conteúdo.
21166«Korekta techniczna niedostępna.» (correção técnica indisponível)Refere-se à correção técnica de uma fatura offline.
21167«Status faktury nie pozwala na korektę techniczną.» (o estado da fatura não permite correção técnica)Igual: não há correção técnica para uma fatura processada corretamente.

A sessão no Odoo

O Odoo guarda o número da sessão interativa na empresa. Antes de enviar, pergunta ao KSeF o estado da sessão: se for 100, sessão aberta, continua a usá-la; caso contrário, abre outra com o formulário FA (3) 1-0E. Por isso o 21180 costuma desaparecer na tentativa seguinte. Com o 21173 é diferente: no envio seguinte, o Odoo pergunta pela mesma sessão, recebe o mesmo erro («Failed to check KSeF session: …») e não abre outra. A sessão guardada só se apaga removendo o certificado KSeF nas definições e guardando, e voltando a adicionar o certificado depois. Isto resulta do código do Odoo; não o testámos contra o KSeF. Perante um 21184, o KSeF sugere uma sessão nova, mas o Odoo só abre uma quando a guardada deixa de ter o estado 100; se o erro se repetir, espere, como aconselha a mensagem.

Os códigos 21402 e 21403 dizem respeito a cálculos feitos pelo próprio programa que envia: o Odoo calcula a impressão digital e o tamanho da fatura antes e depois de a cifrar. Com um Odoo standard não resultam dos dados da fatura. O Odoo não envia correções técnicas de faturas offline, por isso o 21166 e o 21167 vêm de outro programa.

Antes de reportar o problema

  • Copie a mensagem completa do Odoo, com o JSON que segue a «KSeF API Error:».
  • Anote o código e o texto de details.
  • Verifique se o erro afeta uma fatura ou todas as que estão a ser enviadas.
  • Verifique se acontece em produção ou no ambiente de testes.
Esquema: o que o KSeF devolve com a exceção 21405 e o que mostra o Odoo 20
Esquema feito a partir do código do l10n_pl_edi do Odoo 20 e da especificação da API do KSeF 2.9.0; o riscado é o que o Odoo não guarda ou não faz.

Estados da própria sessão: 440 e 445

A sessão interativa também tem estado. O 440 «Sesja anulowana» (sessão anulada) com details «Nie przesłano faktur» significa que na sessão não foi enviada nenhuma fatura, e o 445 «Błąd weryfikacji, brak poprawnych faktur», que nenhuma passou a verificação. O Odoo só verifica se a sessão tem o estado 100, por isso não os mostra; procure a causa nos estados das faturas, como o 450.

O nosso módulo, Poland KSeF 2.0 Validator, não envia faturas nem vê estes códigos; com a subscrição do FlexigoTech Cloud, se carregar em «Validate FA(3) (FlexigoTech Cloud)» antes de enviar a fatura, verifica o ficheiro FA(3) contra o esquema. Esse resultado não trava o envio do l10n_pl_edi: uma fatura «Not valid» sai igualmente se a enviar.

Continue a ler

Código 450 do KSeF: «Błąd weryfikacji semantyki dokumentu faktury»O código 450 do KSeF rejeita uma fatura FA(3) após rever o seu conteúdo. Onde está o motivo real, o que o Odoo 18, 19 e 20 não mostra e como voltar a enviá-la.Estados técnicos da fatura no KSeF: 550, 500, 405, 430 e 435Estados da fatura no KSeF alheios ao seu conteúdo: 550 «Operacja została anulowana przez system», 500, 405, 430 e 435. O que faz o Odoo e porque o 550 fica em Sent.KSeF HTTP 429, 403 e 401: limites de pedidos e acesso negadoKSeF 2.0 responde 429 Too Many Requests ao ultrapassar o limite, 403 com reasonCode sem acesso e 401 com o token expirado. Limites e o que fazem Odoo 18, 19 e 20.
Verificado no código do módulo (versão 20.0) e nas fontes indicadas

Fontes