Pular para o conteúdo principal
Version: 4.40

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 saída 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: Localizar a impressão digital do 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): Configurar o OpenSSL para usar o engine PKCS#11 do Redtrust​

  1. Localize o arquivo de configuração do OpenSSL em /etc/ssl/openssl.cnf.

  2. Crie uma cópia do arquivo, por exemplo, no seu diretório pessoal.

    cp /etc/ssl/openssl.cnf $HOME/openssl-redtrust.cnf

  3. Edite o arquivo de configuração copiado e adicione as seguintes seções para habilitar o framework de engines do OpenSSL.

    openssl_conf = openssl_init

    [openssl_init]
    engines = engine_section

    [engine_section]
    redtrust = redtrust_engine

    [redtrust_engine]
    engine_id = redtrust

    # Caminho para o engine PKCS#11 do OpenSSL (pkcs11.so).
    # Exemplos:
    # - /usr/lib/x86_64-linux-gnu/engines-3/pkcs11.so
    # - /usr/lib64/engines-3/pkcs11.so
    dynamic_path = OPENSSL_ENGINES_DIR/pkcs11.so

    # Caminho para o módulo PKCS#11 do Redtrust (libkeyfactorpkcs11.so).
    # Exemplos:
    # - /usr/lib/libkeyfactorpkcs11.so
    # - /usr/local/lib/libkeyfactorpkcs11.so
    MODULE_PATH = REDTRUST_PKCS11_MODULE_PATH/libkeyfactorpkcs11.so

    init = 1

    Ao adicionar as seções openssl_conf e engines, você indica ao OpenSSL que carregue engines criptográficos externos durante a inicialização.

    tip

    Você pode localizar o módulo PKCS#11 do Redtrust com sudo find /usr /lib /opt -name "libkeyfactorpkcs11.so" 2>/dev/null e o engine pkcs11 para OpenSSL 3.x com sudo find /usr /lib /opt -path "*engines-3*" -name "pkcs11.so" 2>/dev/null.

    Se não conseguir encontrar este último, talvez seja necessário instalar libp11-3 e libengine-pkcs11-openssl. Para isso, execute sudo apt update e sudo apt install -y libp11-3 libengine-pkcs11-openssl.

  4. Informe ao OpenSSL que ele deve usar o arquivo de configuração personalizado. Como você está usando um arquivo de configuração copiado, é necessário indicá-lo explicitamente ao OpenSSL. Defina a variável de ambiente OPENSSL_CONF:

    export OPENSSL_CONF=$HOME/openssl-redtrust.cnf

  5. Verifique a configuração do engine do Redtrust:

    openssl engine -t -c

Se a configuração estiver correta, a saída incluirá uma entrada semelhante à seguinte:

(rdrand) Intel RDRAND engine
[RAND]
    [ available ]
(dynamic) Dynamic engine loading support
    [ unavailable ]
(redtrust) pkcs11 engine
    [ available ]

Se o engine aparecer como disponível, o OpenSSL pode carregar corretamente o engine PKCS#11 do Redtrust e usá-lo para as operações criptográficas necessárias para autenticar o envio de informações ao SII.

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.

curl --connect-timeout 60 -m 60 -s -S -L --header "Content-Type: text/xml;charset=UTF-8" --cert "CurrentUser\My\D8B6D009411BC734AC9F12858C46EC63C73D959D" --data-binary "@path\file.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.