ZATCA Fase 2 (Arábia Saudita): faturação eletrónica no Odoo

A Arábia Saudita implementou a faturação eletrónica obrigatória em duas fases através da ZATCA (Zakat, Tax and Customs Authority), sob o nome Fatoorah. A Fase 1 (desde dezembro de 2021) já exigia gerar e conservar faturas eletrónicas estruturadas. A Fase 2 vai muito mais longe: integração técnica direta com a plataforma da autoridade.

O que é exatamente a Fase 2 (Integration Phase)

A Fase 2 é conhecida como Integration Phase. Já não basta gerar a fatura: o seu sistema de faturação tem de ligar-se por API à plataforma da ZATCA (Fatoora) e seguir um formato e um ciclo de validação concretos.

A ZATCA distingue dois tipos de documento com fluxos diferentes:

• Standard Tax Invoice (B2B/B2G): requer clearance. A fatura é enviada à ZATCA antes de ser entregue ao cliente; a ZATCA valida-a, sela-a criptograficamente e devolve-a autorizada.
• Simplified Tax Invoice (B2C): requer reporting. É entregue ao cliente de imediato com o seu QR e comunicada à ZATCA nas 24 horas seguintes.

Requisitos técnicos que não pode ignorar

• Fatura em formato XML UBL 2.1 (ou PDF/A-3 com XML incorporado) segundo o esquema da ZATCA.
• Assinatura criptográfica com um certificado emitido pela ZATCA após o onboarding do dispositivo (CSID).
• Hash encadeado (PIH, Previous Invoice Hash) que liga cada fatura à anterior e garante a integridade da série.
• Código QR com campos TLV (nome do vendedor, NIF/VAT, data, total, IVA e o selo criptográfico) legível pela app da ZATCA.
• UUID único por fatura e um contador sequencial (ICV) que a ZATCA verifica para detetar lacunas.

Como funciona no Odoo 19

O nosso módulo integra todo este ciclo no fluxo de faturação nativo do Odoo, sem back-offices externos. Quando confirma uma fatura, o Odoo gera o XML UBL, calcula o hash encadeado, envia-o para assinatura com o certificado digital emitido pela ZATCA, constrói o QR e faz a chamada de clearance ou reporting consoante o tipo de documento.

Cada fatura guarda o seu estado perante a ZATCA (aceite, aceite com avisos ou rejeitada), a mensagem da autoridade e o selo devolvido. Se a ZATCA rejeitar um documento, o motivo fica registado na própria fatura para poder corrigi-lo e reenviá-lo, sem perder a rastreabilidade.

O que vigiar antes da sua data limite

• Confirme a sua wave e a data exata na carta de notificação da ZATCA: a janela de integração abre com meses de antecedência, mas tem um prazo firme.
• Dados mestres limpos: o NIF/VAT, a morada, o código postal e o regime de IVA têm de estar corretos no Odoo, ou o clearance falhará.
• Teste primeiro na sandbox da ZATCA: o onboarding do certificado e as primeiras faturas têm de ser validados no ambiente de testes antes de passar a produção.
• Não misture séries: o hash encadeado (PIH) exige numeração contínua; um salto ou uma fatura duplicada quebra a cadeia.

A ZATCA Fase 2 não é um acrescento cosmético: é uma mudança na forma como se emite cada fatura. Bem feita dentro do Odoo, é transparente para a equipa de faturação; feita a meio, transforma-se em faturas rejeitadas e trabalho manual todos os dias.

O que fazemos sobre isto