Pular para o conteúdo principal
Version: 4.42

Como enviar dados fiscais à AEAT com curl usando certificados Redtrust

Visão geral​

Este guia explica como enviar informações de IVA e registros de faturas à Agência Estatal de Administração Tributária (AEAT) usando curl, tanto em ambientes Windows quanto Linux. Ele se concentra nos dois principais mecanismos de reporte atualmente utilizados na Espanha:

  • Fornecimento Imediato de Informações (SII): para o reporte quase em tempo real dos livros de registro de IVA.
  • Veri*Factu: para a transmissão de registros de faturamento verificáveis gerados pelos sistemas de faturamento.

Os exemplos pressupõem que você possui o certificado digital no Redtrust e que sabe qual sistema (SII, Veri*Factu ou ambos) se aplica ao seu caso. Este guia pressupõe familiaridade com HTTPS, certificados e o uso básico da linha de comando.

Contexto​

A Espanha está implementando mecanismos de fornecimento de informações tributárias em tempo real ou quase em tempo real para melhorar a rastreabilidade das operações econômicas e reduzir a fraude fiscal. Como parte desse esforço, a AEAT disponibiliza serviços web que aceitam dados estruturados por meio de conexões HTTPS seguras.

Nesse contexto, dois mecanismos complementares são relevantes:

  • SII exige que determinados contribuintes enviem os registros de IVA derivados das faturas emitidas e recebidas dentro de prazos reduzidos. Os dados representam informações contábeis e fiscais, não o documento da fatura em si.
  • Veri*Factu regula como as faturas são geradas e registradas nos sistemas de faturamento e permite (ou exige, dependendo da configuração) a transmissão dos registros de faturamento à AEAT no momento da emissão.

Do ponto de vista técnico, ambos os sistemas se baseiam em solicitações HTTP autenticadas, utilizam TLS mútuo (autenticação do cliente com um certificado X.509), cargas úteis XML estruturadas (de acordo com o serviço) e endpoints específicos da AEAT.

Como a AEAT expõe esses serviços por meio de protocolos web padrão, você pode interagir com eles usando uma ferramenta genérica como o curl. Este guia se concentra nas solicitações ao SII; os exemplos de Veri*Factu seguem o mesmo padrão.

Antes de começar​

  • Agente do Redtrust para Windows
  • curl e Schannel

Etapa 1: Verificar os pré-requisitos​

Para que o curl possa usar o repositório de certificados do Windows, o curl deve usar o Schannel.

Execute o comando para verificar se ele está instalado:

curl -V

A resposta deve incluir Schannel.

curl 8.9.1 (Windows) libcurl/8.9.1 Schannel zlib/1.3 WinIDN
Release-Date: 2024-07-31
Protocols: dict file ftp ftps http https imap imaps ipfs ipns mqtt pop3 pop3s smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets

Etapa 2: Identificar o certificado​

Você pode encontrar a impressão digital (ou thumbprint) na seção Certificados do console de administração.

info

Você também pode listar os certificados pela CLI do PowerShell. Para isso, é necessário ter o agente do Windows instalado e que o usuário tenha iniciado sessão.

Get-ChildItem Cert:\CurrentUser\My

Etapa 3 (apenas Linux): Habilitar o acesso do curl ao token PKCS#11​

O instalador do agente registra o módulo PKCS#11 do Redtrust no p11-kit, portanto você não precisa declarar o caminho da biblioteca no openssl.cnf nem em nenhum outro aplicativo. Você só precisa instalar o componente que o OpenSSL usa para chegar ao p11-kit, que depende da versão do curl que você verificou na etapa 1.

  • Versões do curl anteriores à 8.12: instale o engine PKCS#11 do OpenSSL.
  • curl 8.12 ou posterior: instale o provider PKCS#11 do OpenSSL 3.

O Ubuntu 22.04 e o 24.04 distribuem versões do curl anteriores à 8.12, portanto o engine é o método aplicável nessas distribuições.

Para instalar o engine, execute:

sudo apt install -y libengine-pkcs11-openssl

Para instalar o provider, execute:

sudo apt install -y pkcs11-provider

Nos dois casos, o componente descobre o módulo do Redtrust pelo p11-kit por padrão, portanto não há mais nada a configurar.

Os engines do OpenSSL estão obsoletos desde o OpenSSL 3 e o provider é o substituto oficial deles. Mesmo assim, o curl não aceita URI pkcs11: por meio de providers antes da versão 8.12, portanto o engine continua necessário nas versões anteriores.

Etapa 4: Enviar as informações do SII com curl​

Depois de identificar o certificado (D8B6D009411BC734AC9F12858C46EC63C73D959D neste exemplo), você pode usar o comando a seguir para enviar as informações. Substitua CAMINHO pelo caminho até o arquivo XML que você quer enviar.

curl --connect-timeout 60 -m 60 -s -S -L --header "Content-Type: text/xml;charset=UTF-8" --cert "CurrentUser\My\D8B6D009411BC734AC9F12858C46EC63C73D959D" --data-binary "@CAMINHO\invoice.xml" "https://prewww1.aeat.es/wlpl/SSII-FACT/ws/fe/SiiFactFEV1SOAP"
nota

Observe que este exemplo usa a URL de pré-produção da AEAT. Para produção, mantenha o mesmo caminho e utilize o host de produção (https://www1.agenciatributaria.gob.es). Para a lista completa dos endpoints de produção (e os WSDLs correspondentes), consulte a página oficial de WSDL de serviços web da AEAT.

Este comando usa o certificado para autenticação e a operação correspondente é registrada como um evento no Redtrust.

Resumo​

Você enviou dados fiscais à AEAT com o curl, autenticando a conexão com um certificado que permanece no Redtrust. No Windows, o curl obtém o certificado do repositório do sistema por meio do Schannel. No Linux, ele obtém do token PKCS#11 do agente por meio do p11-kit, com o engine ou o provider do OpenSSL conforme a versão do curl. Nos dois casos, a chave privada nunca sai do Redtrust e cada uso fica registrado como um evento.

Próximas etapas​

Esta página foi útil?