NetArcaWs 0.7.0

NetArcaWs para .NET 10

NetArcaWs es una biblioteca y herramienta .NET 10 para integrar servicios web de ARCA, basada en PyAfipWs de Mariano Reingart y distribuida bajo licencia LGPL-3.0-or-later.

Ofrece clientes SOAP tipados, autenticación WSAA, selección explícita de identidad por operación, health checks opt-in y una CLI para preparar certificados y solicitudes CSR. La cobertura implementada y sus límites se describen en la wiki publicada; el alcance del código no implica paridad completa con PyAfipWs ni homologación de todas las operaciones.

Instalación

Agregá el paquete principal a un proyecto .NET 10:

dotnet add package NetArcaWs

La aplicación debe contar con un certificado emitido por ARCA y autorizado para el servicio y ambiente elegidos. La herramienta NetArcaWs.Tool ayuda a generar claves y CSR; ARCA emite el certificado.

Inicio rápido

Registrá los servicios una vez al iniciar la aplicación y obtené el cliente tipado por inyección de dependencias. El ejemplo siguiente consulta un catálogo de WSCPE; la aplicación debe construir el contexto a partir de un tenant autenticado y autorizado.

using Microsoft.Extensions.DependencyInjection;
using NetArcaWs.Cryptography;
using NetArcaWs.HealthChecks;
using NetArcaWs.Multitenancy;
using NetArcaWs.Services;
using NetArcaWs.Wsaa;

var certificate = WsaaCertificateContent.FromPem(certificatePem, privateKeyPem);
var services = new ServiceCollection();
services.AddNetArcaWs(options =>
{
    options.Endpoint = WsaaOptions.HomologationEndpoint;
    options.Certificate = certificate;
});
using var provider = services.BuildServiceProvider();

var tenant = new ArcaTenantContext(
    tenantId: authorizedTenantId,
    cuit: representedCuit,
    environment: ArcaEnvironment.Homologation,
    certificate: certificate);
var wscpe = provider.GetRequiredService<IWscpeService>();
var provinces = await wscpe.consultarProvinciasAsync(
    tenant,
    new NetArcaWs.Contracts.Wscpe.ConsultarProvinciasRequest(),
    cancellationToken);

El host resuelve y autoriza tenant, CUIT, ambiente y certificado antes de crear ArcaTenantContext; no uses valores libres del request para elegir credenciales. Podés proporcionar el contenido PEM, PFX/P12 o Base64 desde la configuración o un almacén de secretos administrado por tu aplicación.

Consultá la guía de inicio rápido, WSAA y certificados y contexto multitenant para configurar autenticación y ambientes.

Servicios disponibles

Las fachadas tipadas exponen las operaciones implementadas para estos contratos. La wiki contiene el detalle de métodos, autenticación, ejemplos y límites por servicio.

WSMTXCA corresponde a facturación con detalle; WSFECred cubre el ciclo de Factura de Crédito Electrónica MiPyME. La autorización fiscal depende de los permisos ARCA de cada certificado y CUIT.

Funcionalidades adicionales

Los clientes usan SOAP 1.1 sobre HttpClient, contratos XML tipados y APIs asíncronas con cancelación. WSAA conserva los tickets en caché local hasta su vencimiento efectivo; esta caché no se comparte entre procesos o réplicas.

Los health checks se agregan optativamente por servicio y ambiente. Verifican disponibilidad técnica y no prueban autenticación, autorización de una CUIT ni una operación fiscal. La guía de funcionalidades adicionales reúne health checks, cálculos decimales y diferencias respecto de PyAfipWs.

La herramienta de certificados genera claves y CSR y permite inspeccionar certificados locales; ARCA debe emitir el certificado. Protegé las claves y no registres certificados, claves privadas, tickets o datos fiscales en logs.

Persistencia opcional

El paquete principal no depende de EF Core; los paquetes opcionales agregan persistencia para SQLite, MySQL/MariaDB, PostgreSQL y SQL Server, con migraciones oficiales por motor y módulo cuando se seleccionan. El store versionado de certificados y la cola/worker de recuperación fiscal son opt-in; la aplicación autoriza los contextos, fija la referencia de credencial y aplica sus migraciones expresamente. SQLite admite procesos del mismo host sobre archivo local; para varios hosts se requiere una base transaccional compartida.

La guía Diario fiscal explica configuración y recuperación, y Modelo relacional documenta las tablas y las migraciones oficiales opcionales. El diario durable cubre autorizaciones unitarias WSFEv1, WSFEXv1 y WSMTXCA; una respuesta incierta requiere reconciliación y no se reenvía automáticamente.

Documentación

La wiki del proyecto contiene guías de uso, catálogo de servicios, operaciones, arquitectura, seguridad, homologación y contribución. El inventario de fuentes upstream se mantiene en referencias del repositorio.

Para conocer la arquitectura y las decisiones de seguridad, consultá ARCHITECTURE.md, SECURITY.md y los ADR.

Desarrollo y contribuciones

Se requiere el SDK fijado en global.json. Para compilar la solución desde la raíz del repositorio:

dotnet restore NetArcaWs.slnx --locked-mode
dotnet build NetArcaWs.slnx --configuration Release --no-restore
dotnet test --solution NetArcaWs.slnx --configuration Release --no-build --no-restore

Las pruebas locales usan datos sintéticos y no acreditan homologación con ARCA. Las pruebas fiscales son opt-in y requieren certificados y permisos adecuados. Leé CONTRIBUTING.md antes de enviar cambios.

Licencia

NetArcaWs se distribuye bajo LGPL-3.0-or-later, con atribución al proyecto upstream PyAfipWs y a su autor, Mariano Reingart. Consultá THIRD-PARTY-NOTICES.md para los avisos de terceros.