A ZATCA rejeita faturas com códigos de erro lacónicos, e descodificá-los sob pressão de deadline é brutal. Aqui ficam os sete principais que vemos em produção, ordenados por frequência, com um fix testado para cada.
1. ENT_ICV-001 — Invoice Counter Value fora de sequência
O ICV tem de crescer monotonicamente por dispositivo. A causa é quase sempre emissão paralela a partir de dois processos contra o mesmo EGS. Fix: serializa a atribuição do ICV atrás de uma única fonte de verdade (uma sequência de BD chega).
2. ENT_PIH-002 — Previous Invoice Hash não bate certo
O hash que submeteste como anterior não bate com o que a ZATCA tem registado. Causa: alguém reenviou uma fatura velha ou a cache local ficou para trás. Fix: pergunta à Fatoora o último hash clearado e re-semeia a tua cadeia.
3. KSA-25 — Código de categoria fiscal em falta ou inválido
Cada linha precisa de um código UNCL5305: S, Z, E, O ou AE. Falha comum: deixar em branco em linhas a taxa zero. Fix: emite Z explicitamente, não o omitas.
4. KSA-12 — Número de IVA do vendedor mal formado
Os números de IVA sauditas têm 15 dígitos, começam por 3 e terminam num dígito de checksum. Erro comum: submeter o Commercial Registration Number de 10 dígitos em vez disso. Fix: lê o IVA da tabela tax_registrations com kind='VAT', não do campo da licença comercial.
5. CLOCK_DRIFT — IssueDateTime fora de sincronização em mais de 30 segundos
Drift do relógio do servidor. Fix: sincronização NTP contra pool.ntp.org, todos os minutos, em cada host que emita faturas.
6. KSA-08 — Fatura standard sem IVA do comprador
As faturas B2B na KSA exigem o IVA (TaxID) do comprador. As simplificadas (B2C) não. Fix: ramifica pelo InvoiceTypeCode no teu serializador (388 = standard, 388 com subtype 02 = simplificada).
7. KSA-19 — Montante de imposto inconsistente com totais de linha
Soma dos impostos por linha ≠ TaxTotal. A causa é quase sempre arredondar a meio do cálculo. Fix: arredonda apenas o subtotal final por taxa (banker's rounding), nunca por linha.