Como automatizar a faturação Stripe em Portugal

Para automatizar a faturação Stripe em Portugal, é necessário tratar cada pagamento liquidado como um sinal, recolher os dados fiscais no Stripe, preservar a informação de IVA recebida e criar a FT ou FR no TOConline ou InvoiceXpress. As exceções devem ficar em revisão manual, com uma ligação verificável entre pagamento e fatura.

Que sistema faz cada parte da faturação Stripe?

O Stripe cobra e regista o pagamento. O sistema de faturação cria o documento fiscal português. Entre ambos, a integração valida o evento, organiza os dados e pede a emissão no fornecedor escolhido. Confundir estes papéis leva a arquivar um recibo de pagamento como se fosse a fatura ou a duplicar documentos quando chegam vários eventos para a mesma cobrança.

Uma confirmação do Stripe não se torna automaticamente numa fatura portuguesa. O guia sobre faturas e recibos do Stripe em Portugal explica a diferença jurídica. Neste guia, o objetivo é manter a passagem entre os três sistemas previsível e auditável.

Que evento do Stripe deve iniciar a emissão?

O ponto de partida deve ser um evento de pagamento concluído, mas o evento concreto depende do fluxo. Um pagamento avulso pode chegar porpayment_intent.succeeded. Uma subscrição paga é tratada a partir de invoice.payment_succeeded. Se o PaymentIntent já estiver associado a uma invoice do Stripe, processar ambos sem uma regra de deduplicação pode criar duas tentativas para a mesma venda.

A receção também deve validar a assinatura sobre o corpo original do webhook. A documentação do Stripe avisa que alterar ou voltar a serializar esse corpo impede a verificação. Depois da validação, uma chave idempotente permite reconhecer uma repetição. Por exemplo, se o Stripe reenviar o mesmo evento após uma resposta tardia, a segunda entrega deve terminar sem criar outra fatura.

O instante do webhook não substitui a regra fiscal sobre o prazo de emissão. O artigo 36.º do CIVA prevê, em geral, emissão até ao quinto dia útil seguinte ao momento em que o imposto é devido e emissão na data do recebimento nos casos aí indicados. O fluxo deve conservar a data relevante da operação e não usar apenas a hora em que o servidor recebeu a notificação.

Que dados devem chegar do Stripe à fatura?

A integração precisa de uma fotografia coerente da venda: referência do pagamento, moeda, total, linhas, quantidades, descrições, cliente e informação fiscal fornecida pelo Stripe. Para subscrições, essa fotografia pode vir da invoice associada; num pagamento avulso, pode resultar do PaymentIntent e dos seus metadados. A origem escolhida deve ficar registada para explicar o documento mais tarde.

O NIF e o nome não devem ser inventados quando faltam. O Checkout permite recolher identificadores fiscais empresariais nos países suportados, mas esse mecanismo não resolve todos os casos de consumidor final. O guia sobre NIF na fatura e no Stripe Checkout separa a obrigação fiscal da capacidade técnica do formulário.

Considere-se uma renovação com duas linhas, uma descrição clara, o identificador fiscal da empresa e imposto calculado no Stripe. A fatura deve conservar as duas linhas e os respetivos valores. Fundir tudo numa linha genérica como “serviços” perde informação útil e dificulta a comparação com a cobrança original.

Como deve o IVA passar do Stripe para o fornecedor?

A integração não deve calcular, corrigir ou deduzir taxas de IVA. O Stripe é a origem da taxa, do montante de imposto, do comportamento inclusivo ou exclusivo e dos códigos fiscais que estiverem presentes na venda. O trabalho da integração é transportar esses valores e aplicar o mapeamento configurado pela organização para o código aceite pelo fornecedor.

Não se deve escolher uma taxa a partir do país, do código postal ou do prefixo do NIF. Esses dados podem ajudar a explicar uma venda, mas não substituem a configuração fiscal no Stripe. O tratamento de operações nacionais, intracomunitárias e fora da União Europeia é desenvolvido no guia sobre IVA em serviços digitais vendidos através do Stripe.

Quando o Stripe não fornece imposto, o percurso seguro é explícito. Se a organização configurou o código de isenção predefinido adequado, o documento pode seguir com taxa zero e esse código. Sem essa configuração, o pagamento deve passar para revisão manual. Quando uma venda tem várias taxas, cada linha conserva os dados fiscais recebidos do Stripe e usa o mapeamento correspondente. Um mapeamento ausente ou inválido é uma das condições que encaminham o caso para revisão.

Como configurar a automatização passo a passo?

1. Mapear o processo atual. Deve identificar-se quem configura o Stripe, quem gere as séries no programa de faturação e quem resolve exceções. Um pagamento sem responsável por revisão não está automatizado; está apenas escondido numa fila.

2. Preparar os dados no Stripe. As descrições, linhas, moeda, identificação do cliente e configuração fiscal devem estar presentes antes do pagamento. Corrigir estes dados depois da emissão pode exigir um documento retificativo.

3. Ligar a conta Stripe e o fornecedor de faturação pelos mecanismos de autorização previstos. Os segredos e tokens devem ficar cifrados no servidor, nunca num ficheiro partilhado ou numa mensagem enviada à equipa.

4. Escolher o fornecedor, a série, o tipo FT ou FR e a preferência por rascunho ou documento final. A disponibilidade de rascunhos depende das capacidades declaradas pelo fornecedor e da opção da organização.

5. Configurar o mapa fiscal sem criar regras geográficas paralelas. Os valores do Stripe devem apontar para os códigos do fornecedor; uma ausência ou incompatibilidade deve ter um resultado conhecido, como revisão manual.

6. Testar cenários distintos antes da ativação: pagamento avulso, subscrição, cliente sem NIF, taxa zero, várias taxas, evento repetido, indisponibilidade do fornecedor e reembolso. Cada teste deve indicar o estado esperado e o responsável pela decisão.

7. Ativar e acompanhar as primeiras emissões. A reconciliação deve comparar IDs do Stripe com IDs e números do fornecedor, em vez de depender apenas de mensagens de sucesso.

Como escolher entre FT, FR, rascunho e documento final?

O fluxo suportado trabalha com FT e FR. A escolha pertence à configuração da organização e ao processo contabilístico, não a uma inferência feita a partir do método de pagamento. Um pagamento Stripe bem-sucedido é tratado como liquidado; o estado do documento no fornecedor é uma decisão separada.

TOConline e InvoiceXpress suportam percursos diferentes de autenticação e API, embora ambos possam integrar o mesmo fluxo. A comparação entre TOConline e InvoiceXpress ajuda a escolher com base em preço, rascunhos, acesso do contabilista e gestão multiempresa.

O que deve acontecer quando faltam dados?

Uma falha previsível deve produzir um estado visível, não uma fatura aproximada. Entre os casos típicos estão a falta de série, um código fiscal sem correspondência, país insuficiente para uma operação a zero, NIF rejeitado pelo fornecedor ou credenciais que exigem nova autenticação. O registo deve indicar o motivo e permitir nova tentativa depois da correção.

Por exemplo, se o Stripe não trouxer imposto e também não existir um código de isenção predefinido, a integração não deve adivinhar. O pagamento permanece liquidado, mas a emissão fica em revisão manual. Depois de corrigida a configuração, a nova tentativa reutiliza a mesma transação e evita criar um segundo registo para a cobrança.

As indisponibilidades temporárias do fornecedor podem ser repetidas com limites. Uma repetição técnica não substitui a decisão humana quando o problema é fiscal ou falta informação. Separar estes dois casos impede que uma fila tente indefinidamente resolver algo que exige configuração.

Como devem ser tratados reembolsos e notas de crédito?

Um reembolso altera o estado financeiro da transação, mas não apaga a fatura já emitida. O evento charge.refunded permite registar se o reembolso é parcial ou total. A emissão de uma nota de crédito é um processo contabilístico separado e não deve ser prometida apenas porque o estado do Stripe mudou.

Num reembolso parcial de uma subscrição, devem conservar-se o valor original, o montante reembolsado, a fatura associada e qualquer documento retificativo criado no fornecedor. Alterar a fatura original para fazer coincidir o novo saldo destrói a pista de auditoria. O procedimento deve ser confirmado com a contabilidade antes de automatizar esta etapa.

Como proteger os dados do cliente durante a integração?

O pagamento pode trazer nome, email, NIF e morada suficientes para criar ou localizar o cliente no fornecedor. Esses dados são necessários em memória durante o processamento, mas não precisam de ficar duplicados na base de dados da integração. Para pesquisa e correspondência, podem guardar-se hashes HMAC normalizados por organização e os IDs dos sistemas de origem.

A normalização tem de ser igual na escrita e na leitura. Se o NIF for guardado sem espaços, mas pesquisado com espaços, a correspondência falha e pode criar um cliente duplicado. Por exemplo, o mesmo endereço de email deve ser convertido da mesma forma antes de calcular o HMAC em ambos os percursos.

Que verificação confirma que a automatização funciona?

O teste útil não termina numa resposta HTTP com sucesso. Deve provar que o evento foi aceite uma vez, que a transação ficou ligada a uma única fatura e que o fornecedor devolveu o tipo, estado, número e total esperados. Também deve mostrar que um caso incompleto fica parado para revisão sem criar um documento fiscal incorreto.

Uma amostra pequena pode incluir um pagamento avulso, uma renovação de subscrição e um evento repetido. Depois, compara-se o total e o imposto recebidos do Stripe com as linhas do documento, confirma-se a série e verifica-se que a repetição não criou outra fatura. Os requisitos do documento podem ser revistos no guia de requisitos das faturas portuguesas.

Em produção, a mesma disciplina continua: pagamentos sem documento, revisões manuais abertas e diferenças de total devem aparecer numa fila operacional. Automatizar significa reduzir trabalho repetitivo sem esconder decisões fiscais, exceções ou falhas de reconciliação.