Como Criar uma Série de Faturação no InvoiceXpress

O InvoiceXpress é o software certificado mais usado por lojas online portuguesas, em parte porque a sua API é a mais simples de automatizar. Mas antes de qualquer automação emitir a primeira fatura, tem de existir uma série comunicada à AT e com ATCUD atribuído.

Este guia mostra como criar a série no InvoiceXpress, comunicá-la à Autoridade Tributária e confirmar que está pronta a emitir. No fim explico a armadilha que mais faturas parte em automações: no InvoiceXpress uma série não é uma sequência, é uma família de sequências.

Antes de começar

Precisas de duas coisas:

• Acesso de administrador à conta InvoiceXpress (só o administrador vê o separador das séries).
• Um subutilizador AT com a operação WSE — Comunicação e Gestão de Séries por webservice. Se ainda não o criaste, começa por ATCUD: Como criar utilizador na Autoridade Tributária.

Se o conceito de série ainda não está assente, lê primeiro Séries de faturação: o que são e como comunicar à AT.

Passo 1 — Abrir a gestão de séries

1. Inicia sessão na tua conta, em https://<a-tua-conta>.app.invoicexpress.com.
2. Menu de topo direito (nome da conta) → Definições.
3. Separador Séries de Faturação.

A lista mostra as séries existentes, o estado de comunicação à AT e qual está marcada como predefinida. Uma conta nova traz normalmente uma série automática com o ano corrente.

O endereço da conta é <conta>.app.invoicexpress.com. O subdomínio antigo sem .app continua a responder em alguns ecrãs mas não em todos — se um link te der erro, acrescenta o .app.

Passo 2 — Criar a série

Clica em Nova Série e preenche:

| Campo | O que colocar | Exemplo | |---|---|---| | Nome da série | Letras maiúsculas e dígitos, sem espaços nem acentos | 2026A | | Numeração inicial | 1 em série nova. Se migras de outro software, o número seguinte ao último emitido | 1 | | Predefinida | Marca se vai ser a série usada por defeito nos documentos novos | ✓ |

Ao contrário do Moloni, não escolhes aqui o tipo de documento. No InvoiceXpress a série serve todos os tipos (fatura, fatura-recibo, fatura simplificada, nota de crédito, nota de débito, recibo) e o sistema mantém, internamente, uma numeração separada por tipo dentro da mesma série. É por isso que verás o mesmo nome 2026A em documentos com sequências diferentes.

O nome tem de coincidir exatamente com o identificador que vais comunicar à AT. Uma letra diferente e o SAF-T é rejeitado meses depois, quando já é caro corrigir.

Passo 3 — Comunicar a série à AT

Via A — Webservice, a partir do InvoiceXpress (recomendado)

1. Em Definições → Comunicação AT (nalgumas contas surge como Configurações AT ou Webservice AT), introduz as credenciais do subutilizador AT no formato NIF/N e a respetiva senha. São as mesmas credenciais do subutilizador que criaste no Portal das Finanças — o webservice é autorizado na criação desse utilizador, não há chave separada a pedir.
2. Volta a Definições → Séries de Faturação, abre a série e clica em Comunicar à AT.
3. Em segundos a AT devolve o código de validação de 8 caracteres, que fica gravado na série. O estado passa a Comunicada.

Via B — Manualmente no Portal das Finanças

1. Portal das Finanças → Todos os Serviços → Faturas e Outros Documentos Fiscais → Comunicar Séries Documentais → Registar Série.
2. Preenche, uma vez por cada tipo de documento que vais emitir nessa série (FT, FR, FS, NC, ND...):
   • Identificador da série: o nome exato (2026A).
   • Numeração sequencial inicial: 1.
   • Meio de processamento: Programa informático de faturação.
   • Número de certificação do software: 192 (o número do InvoiceXpress junto da AT). Confirmas sempre no rodapé de um documento já emitido, que imprime Processado por programa certificado n.º 192/AT.
3. Submete e guarda cada código de validação devolvido.
4. No InvoiceXpress, edita a série e cola o código no campo ATCUD.

A Via A evita este trabalho todo: o InvoiceXpress comunica cada tipo de documento por ti à medida que são precisos.

Passo 4 — Confirmar que a série emite certificada

Emite um documento de teste — de preferência uma fatura-recibo, que é o tipo que as automações mais usam — e confirma que:

• O identificador sai como FR 2026A/1.
• O PDF traz QR Code.
• Traz a linha ATCUD: <código>-<número>, por exemplo CSDF7T5H-00001.
• O rodapé menciona o programa certificado.

Onde a série e o ATCUD aparecem num documento certificado.

Se o documento sair sem ATCUD, a série não está comunicada para aquele tipo de documento, ainda que esteja comunicada para outros.

A armadilha: uma série são várias sequências

Esta é a parte que a documentação não diz com todas as letras e que parte automações em silêncio.

No InvoiceXpress, uma série guarda um id por tipo de documento. O id de topo é o da fatura.

Quando pedes as séries pela API (GET /sequences.json), cada série responde com um id no topo e um id distinto por tipo de documento:

{
  "id": 47734,
  "serie": "2026A",
  "current_invoice_sequence_id": 47734,
  "current_invoice_receipt_sequence_id": 47736,
  "current_credit_note_sequence_id": 47739
}

O id de topo é o da fatura. Se o usares para criar uma fatura-recibo, o InvoiceXpress responde:

HTTP 400 — A série não corresponde ao tipo de documento

O documento não é criado e a venda fica por faturar, sem erro visível do lado da loja. A regra é: usa sempre o id específico do tipo que estás a emitir, e só cai no id de topo quando o específico não existe.

Há ainda um segundo detalhe: enquanto só existirem rascunhos numa série, o id específico desse tipo pode ainda não vir preenchido. Aparece depois de o primeiro documento desse tipo ser finalizado.

Erros frequentes no InvoiceXpress

• Série não predefinida: documentos criados sem série explícita caem na série marcada como predefinida. Se a predefinida ainda é a do ano anterior, começas janeiro a numerar no sítio errado.
• Estado "Por comunicar" num só tipo de documento: comunicaste FT mas não NC, e a primeira devolução do ano falha.
• Nome com espaço ou acento: aceite no InvoiceXpress, rejeitado no SAF-T.
• Mudar a numeração inicial depois do primeiro documento: não é possível. Cria uma série nova e desativa a antiga.
• Viragem de ano: uma série anual nova tem de ser criada e comunicada antes da primeira venda de janeiro, não depois.

Como o Rioko ajuda

O Rioko lê as séries da tua conta InvoiceXpress pela API e mostra-as por nome no painel — escolhes a série e o Rioko trata do resto, incluindo escolher o id certo para o tipo de documento que vai emitir em cada venda (fatura, fatura-recibo ou nota de crédito). Se configurares uma série que a conta não tem, ou que ainda não foi comunicada, a ligação recusa emitir em vez de deixar a fatura sair sem ATCUD.

Na viragem de ano, o painel avisa-te para apontar a ligação à série nova, para que nenhuma venda de janeiro saia ainda numerada no exercício anterior.

Configurar a ligação ao InvoiceXpress →