Fact.pt¶
Serviço Fact.pt — identificador factpt. Verificado com uma conta sandbox real do
Fact.pt.
Configurar o Fact.pt¶
No Fact.pt¶
- Crie uma chave da API no Backoffice do Fact.pt. A chave fica associada a uma série de documentos.
- Confirme que essa série tem 8 casas decimais de precisão. O plugin envia preços unitários sem
IVA com várias casas decimais para as faturas baterem certo ao cêntimo; uma série de 2 casas
decimais recusa-os (
price: Trying to use an item having more than 2 decimal digits, in an incompatible series.). - Para testar, faça o mesmo na sandbox. Os tokens de sandbox e de produção são diferentes.
No pretix¶
Abra Configurações → Faturação PT do evento, clique no cartão Fact.pt e preencha a sua secção. Para usar um só token em todos os eventos de um organizador, preencha-o antes em Configurações → Faturação PT do organizador; veja Definições ao nível do organizador.

- Cole o Token da API (x-auth-token).
- Marque Usar ambiente de testes (sandbox) enquanto testa. Desmarque, e cole o token de produção, quando passar a produção.
- ID da taxa de IVA (Fact.pt) passa a uma lista das taxas ativas da sua conta assim que o token é válido. Escolha a taxa que o pretix cobra nos bilhetes do evento; veja A taxa de IVA tem de coincidir com a do pretix.
- Escolha uma Unidade e um Tipo de item. Para bilhetes, Unidades e Serviço é a escolha habitual.
- Carregue em Guardar. O aviso Ainda não está em uso desaparece, e as encomendas pagas passam a ser faturadas.
Definições¶
| Definição | Descrição |
|---|---|
| Token da API (x-auth-token) | O seu token da API do Fact.pt. A série dele tem de ter 8 casas decimais. |
| Usar ambiente de testes (sandbox) | Emite em api.sandbox.fact.pt. Os tokens de sandbox e de produção são diferentes. |
| ID da taxa de IVA (Fact.pt) | Lista das taxas ativas da sua conta, carregada em direto quando o token é válido. Aplicada a todas as linhas. |
| Unidade (Fact.pt) | Unidades / Metros / Caixas / Kilos / Litros. |
| Tipo de item | Serviço ou Produto. |
A taxa de IVA tem de coincidir com a do pretix¶
O Fact.pt recebe o preço sem IVA de cada linha e acrescenta-lhe a taxa configurada. Se essa taxa for diferente da que o pretix cobrou, o documento ficaria com um valor que o comprador nunca pagou (por exemplo, um bilhete de 15,00 € sem regra de IVA no pretix, faturado a 23%, passa a 18,45 €).
Por isso, antes de cada emissão, o plugin compara a taxa configurada com a taxa do pretix em cada linha e recusa com um erro explícito se não coincidirem:
Divergência de IVA: o pretix cobrou 0% nesta encomenda mas a taxa configurada no Fact.pt é 23%
(Taxa normal (23%)). A fatura seria emitida com o valor errado. Corrija a regra de IVA do evento
ou a definição da taxa de IVA do Fact.pt.
Corrija a regra de IVA ou a definição e carregue em Tentar novamente.
Nota
Uma taxa de IVA por evento: um evento que venda artigos a taxas diferentes ainda não pode ser faturado. Veja as Limitações conhecidas.
Clientes¶
- Com NIF — é reutilizado um cliente do Fact.pt com exatamente esse NIF. Caso contrário, é criado um (ou atualizado, se o Fact.pt já tiver esse NIF) a partir da morada de faturação da encomenda.
- Sem NIF — é reutilizado um cliente consumidor final com o mesmo nome; caso contrário, o
Fact.pt cria um com o NIF
999999990. Um comprador sem nome nem empresa fica registado como "Consumidor Final".
Uma morada portuguesa sem código postal é enviada com 0000-000, que o Fact.pt aceita onde um
código vazio é recusado. Os campos da morada são reduzidos a uma linha e cortados aos limites do
Fact.pt.
Clientes duplicados
Se vários clientes do Fact.pt tiverem o NIF do comprador, a emissão pára com
Multiple clients with same tin. Specify an ID. O plugin não adivinha a qual deles faturar:
junte os duplicados no Backoffice do Fact.pt e tente novamente.
Um cliente criado ou atualizado a partir do pretix substitui a ficha desse NIF no Fact.pt com os dados da morada da encomenda.
Proteção contra duplicados e novas tentativas¶
Cada documento leva um identifierId (pretix-<evento>-<código da encomenda>), e o Fact.pt recusa
um segundo documento com o mesmo. É isso que torna as novas tentativas seguras: uma falha de rede
(timeout, Fact.pt inacessível) é repetida automaticamente, até três vezes com uns minutos de
intervalo, e se o primeiro pedido tiver afinal chegado, a repetição é recusada em vez de emitir em
duplicado. Entretanto a linha diz nova tentativa automática dentro de alguns minutos, e desistiu
ao fim de várias tentativas se todas falharem; carregue então em Tentar novamente.
Se o primeiro pedido tiver afinal chegado, o documento existe no Fact.pt mas o pretix nunca recebeu
o número. Por isso, em qualquer nova tentativa, automática ou à mão, o plugin começa por procurar
nos documentos emitidos desde essa tentativa um com o identifierId da encomenda e associa-o à
encomenda. Veja nas Limitações conhecidas até onde vai essa procura.
Uma recusa (token errado, divergência de IVA, dados inválidos) nunca é repetida automaticamente: corrija a causa e carregue em Tentar novamente.
Uma encomenda paga de novo depois de um reembolso
recebe um novo identificador por cada nova fatura (…-r1, …-r2), e cada nota de crédito usa o da
sua fatura seguido de -credit.
Notas de crédito¶
Emitidas com o endpoint de crédito do Fact.pt, creditando o documento original na totalidade. O Fact.pt só permite uma nota de crédito por documento, pelo valor total.
Documentos e números¶
O número mostrado no pretix (por exemplo 2025QG/9) é o que o Fact.pt devolve para o documento. As
linhas emitidas pelo Fact.pt oferecem também Abrir no Fact.pt, uma ligação para a página
permanente do documento.