FiscalAPI SDK para .NET

SDK oficial de https://fiscalapi.com para .NET, la API de facturación CFDI y otros servicios fiscales en México. Simplifica la integración con los servicios de facturación electrónica, eliminando las complejidades del SAT y facilitando la generación de facturas, notas de crédito, complementos de pago, nómina, carta porte, y más. ¡Factura sin dolor!

📋 Facturación CFDI 4.0

• Soporte completo para CFDI 4.0 con todas las especificaciones oficiales
• Timbrado de facturas de ingreso con validación automática
• Timbrado de notas de crédito (facturas de egreso)
• Timbrado de complementos de pago en MXN, USD y EUR
• Timbrado de facturas de nómina
• Timbrado de facturas de carta porte
• Timbrado de facturas de comercio exterior
• Consulta del estatus de facturas en el SAT en tiempo real
• Cancelación de facturas
• Generación de archivos PDF de las facturas con formato profesional
• Personalización de logos y colores en los PDF generados
• Envío de facturas por correo electrónico automatizado
• Descarga de archivos XML con estructura completa
• Almacenamiento y recuperación de facturas por 5 años.
• Dos modos de operación: Por valores o Por referencias

📥 Descarga Masiva

• Acceso a catálogos de descarga masiva del SAT
• Descarga de CFDI y Metadatos en lotes grandes
• Descarga masiva XML con filtros personalizados
• Reglas de descarga automática por RFC
• Solicitudes de descarga via API y Dashboard.
• Automatización de solicitudes de descarga

👥 Gestión de Personas

• Administración de personas (emisores, receptores, clientes, usuarios, etc.)
• Gestión de certificados CSD y FIEL (subir archivos .cer y .key a FiscalAPI)
• Configuración de datos fiscales (RFC, domicilio fiscal, régimen fiscal)
• Datos de empleado (agrega/actualiza/elimina datos de empleado a una persona. CFDI Nómina)
• Datos de empleador (agrega/actualiza/elimina datos de empleador a una persona. CFDI Nómina)

🎖️ Gestión de Timbres

• Gestión de folios fiscales Compra timbres a FiscalAPI y transfiere/retira a las personas de tu organización según tus reglas de negocio.

🛍️ Gestión de Productos/Servicios

• Gestión de productos y servicios con catálogo personalizable
• Administración de impuestos aplicables (IVA, ISR, IEPS)

📚 Consulta de Catálogos SAT

• Consulta en catálogos oficiales del SAT actualizados
• Consulta en catálogos oficiales de Descarga masiva del SAT actualizados
• Búsqueda de información en catálogos del SAT con filtros avanzados
• Acceso y búsqueda en catálogos completos

📖 Recursos Adicionales

• Cientos de ejemplos de código disponibles en múltiples lenguajes de programación
• Documentación completa con guías paso a paso
• Ejemplos prácticos para casos de uso comunes
• Soporte técnico especializado
• Actualizaciones regulares conforme a cambios del SAT

📦 Instalación

Compatible con múltiples versiones de .NET (desde .NET Framework 4.6.1 hasta .NET 8)

NuGet Package Manager:

NuGet\Install-Package Fiscalapi

.NET CLI:

dotnet add package Fiscalapi

⚙️ Configuración

Puedes usar el SDK tanto en aplicaciones sin inyección de dependencias (WinForms, Consolas, WPF, etc.) como en proyectos que usan DI (ASP.NET Core, Blazor, etc.). A continuación se describen ambas formas:

A) Aplicaciones sin Inyección de Dependencias

1. Crea tu objeto de configuración con tus credenciales:

   varsettings=newFiscalApiOptions{ApiUrl="https://test.fiscalapi.com",// https://live.fiscalapi.com (producción)ApiKey="<tu_api_key>",Tenant="<tenant>"};

2. Crea la instancia del cliente:

   varfiscalApi=FiscalApiClient.Create(settings);

Para ejemplos completos, consulta winforms-console.

---

B) Aplicaciones con Inyección de Dependencias (ASP.NET, Blazor, etc.)

1. Agrega la sección de configuración en tu appsettings.json:

   {
   "FiscalapiSettings": {
   "ApiUrl": "https://test.fiscalapi.com", // https://live.fiscalapi.com (producción)"ApiKey": "<YourApiKeyHere>",
   "Tenant": "<YourTenantHere>"
   }
   }

2. Registra los servicios en el contenedor (por ejemplo, en Program.cs):

   builder.Services.AddFiscalApi();

Posteriormente, podrás inyectarIFiscalApiClient donde lo requieras:

publicclassInvoicesController:Controller{privatereadonlyIFiscalApiClient_fiscalApi;publicInvoicesController(IFiscalApiClientfiscalApi){_fiscalApi=fiscalApi;}// Usa _fiscalApi en tus métodos de controlador...}

Para más ejemplos, revisa samples-asp-net.

🔄 Modos de Operación

FiscalAPI admite dos modos de operación:

• Por Referencias: Envía solo IDs de objetos previamente creados en el dashboard de FiscalAPI.
  Ideal para integraciones ligeras.

• Por Valores: Envía todos los campos requeridos en cada petición, con mayor control sobre los datos.
  No se requiere configuración previa en el dashboard.

📝 Ejemplos de Uso

A continuación se muestran algunos ejemplos básicos para ilustrar cómo utilizar el SDK. Puedes encontrar más ejemplos en la documentación oficial.

1. Crear una Persona (Emisor o Receptor)

varfiscalApi=FiscalApiClient.Create(Settings);varrequest=newPerson{LegalName="Persona de Prueba",Email="someone@somewhere.com",Password="YourStrongPassword123!",};varapiResponse=awaitfiscalApi.Persons.CreateAsync(request);

2. Subir Certificados CSD

Descarga certificados de prueba

varfiscalApi=FiscalApiClient.Create(Settings);varcertificadoCsd=newTaxFile{PersonId="984708c4-fcc0-43bd-9d30-ec017815c20e",Base64File="MIIFsDCCA5igAwIBAgI...==",// Certificado .cer codificado en Base64FileType=FileType.CertificateCsd,Password="12345678a",Tin="EKU9003173C9"};varclavePrivadaCsd=newTaxFile{PersonId="984708c4-fcc0-43bd-9d30-ec017815c20e",Base64File="MIIFDjBABgkqhkiG9w0BBQ0...==",// Llave privada .key codificada en Base64FileType=FileType.PrivateKeyCsd,Password="12345678a",Tin="EKU9003173C9"};varapiResponseCer=awaitfiscalApi.TaxFiles.CreateAsync(certificadoCsd);varapiResponseKey=awaitfiscalApi.TaxFiles.CreateAsync(clavePrivadaCsd);

3. Crear un Producto o Servicio

varfiscalApi=FiscalApiClient.Create(Settings);varrequest=newProduct{Description="Servicios contables",UnitPrice=100,SatUnitMeasurementId="E48",SatTaxObjectId="02",SatProductCodeId="84111500"};varapiResponse=awaitfiscalApi.Products.CreateAsync(request);

4. Actualizar Impuestos de un Producto

varfiscalApi=FiscalApiClient.Create(Settings);varrequest=newProduct{Id="310301b3-1ae9-441b-b463-51a8f9ca8ba2",Description="Servicios contables",UnitPrice=100,SatUnitMeasurementId="E48",SatTaxObjectId="02",SatProductCodeId="84111500",ProductTaxes=newList<ProductTax>{newProductTax{Rate=0.16m,TaxId="002",TaxFlagId="T",TaxTypeId="Tasa"},// IVA 16%newProductTax{Rate=0.10m,TaxId="001",TaxFlagId="R",TaxTypeId="Tasa"},// ISR 10%newProductTax{Rate=0.10666666666m,TaxId="002",TaxFlagId="R",TaxTypeId="Tasa"}// IVA 2/3 partes}};varapiResponse=awaitfiscalApi.Products.UpdateAsync(request.Id,request);

5. Crear una Factura de Ingreso (Por Referencias)

varfiscalApi=FiscalApiClient.Create(Settings);varinvoice=newInvoice{VersionCode="4.0",Series="SDK-F",Date=DateTime.Now,PaymentFormCode="01",CurrencyCode="MXN",TypeCode="I",ExpeditionZipCode="42501",Issuer=newInvoiceIssuer{Id="<id-emisor-en-fiscalapi>"},Recipient=newInvoiceRecipient{Id="<id-receptor-en-fiscalapi>"},Items=newList<InvoiceItem>{newInvoiceItem{Id="<id-producto-en-fiscalapi>",Quantity=1,Discount=10.85m}},PaymentMethodCode="PUE",};varapiResponse=awaitfiscalApi.Invoices.CreateAsync(invoice);

6. Crear la Misma Factura de Ingreso (Por Valores)

varfiscalApi=FiscalApiClient.Create(settings);// Agregar sellos CSD, Emisor, Receptor, Items, etc.varinvoice=newInvoice{VersionCode="4.0",Series="SDK-F",Date=DateTime.Now,PaymentFormCode="01",CurrencyCode="MXN",TypeCode="I",ExpeditionZipCode="42501",Issuer=newInvoiceIssuer{Tin="EKU9003173C9",LegalName="ESCUELA KEMPER URGATE",TaxRegimeCode="601",TaxCredentials=newList<TaxCredential>(){newTaxCredential{Base64File="certificate_base64...",FileType=FileType.CertificateCsd,Password="12345678a"},newTaxCredential{Base64File="private_key_base64...",FileType=FileType.PrivateKeyCsd,Password="12345678a"}}},Recipient=newInvoiceRecipient{Tin="EKU9003173C9",LegalName="ESCUELA KEMPER URGATE",ZipCode="42501",TaxRegimeCode="601",CfdiUseCode="G01",Email="someone@somewhere.com"},Items=newList<InvoiceItem>{newInvoiceItem{ItemCode="01010101",Quantity=9.5m,UnitOfMeasurementCode="E48",Description="Invoicing software as a service",UnitPrice=3587.75m,TaxObjectCode="02",Discount=255.85m,ItemTaxes=newList<InvoiceItemTax>{newInvoiceItemTax{TaxCode="002",// IVATaxTypeCode="Tasa",TaxRate=0.16m,TaxFlagCode="T"}}}},PaymentMethodCode="PUE",};varapiResponse=awaitfiscalApi.Invoices.CreateAsync(invoice);

7. Crear Factura con Complemento de Comercio Exterior (Por Valores)

varfiscalApi=FiscalApiClient.Create(settings);varinvoice=newInvoice{VersionCode="4.0",PaymentFormCode="99",PaymentMethodCode="PPD",CurrencyCode="MXN",TypeCode="I",ExpeditionZipCode="42501",Series="CCE",Date=DateTime.Parse("2025-05-02T15:56:40"),PaymentConditions="CondicionesDePago",ExportCode="02",Issuer=newInvoiceIssuer{Tin="EKU9003173C9",LegalName="ESCUELA KEMPER URGATE",TaxRegimeCode="601",TaxCredentials=newList<TaxCredential>{newTaxCredential{Base64File="certificate_base64...",FileType=FileType.CertificateCsd,Password="12345678a"},newTaxCredential{Base64File="private_key_base64...",FileType=FileType.PrivateKeyCsd,Password="12345678a"}}},Recipient=newInvoiceRecipient{Tin="XEXX010101000",LegalName="Persona Fisica Extranjera",ZipCode="42501",TaxRegimeCode="616",CfdiUseCode="S01",CountryId="USA",ForeignTin="123456789"},Items=newList<InvoiceItem>{newInvoiceItem{ItemCode="50211503",ItemSku="131494-1055",Quantity=2,UnitOfMeasurementCode="H87",Description="Cigarros",UnitPrice=200.00m,TaxObjectCode="02",ItemTaxes=newList<InvoiceItemTax>{newInvoiceItemTax{TaxCode="002",TaxTypeCode="Tasa",TaxRate=0.160000m,TaxFlagCode="T"},newInvoiceItemTax{TaxCode="001",TaxTypeCode="Tasa",TaxRate=0.100000m,TaxFlagCode="R"},newInvoiceItemTax{TaxCode="002",TaxTypeCode="Tasa",TaxRate=0.106666m,TaxFlagCode="R"}}}},Complement=newComplement{ComercioExterior=newFiscalapi.Models.ForeignTrade.ComercioExterior{ClaveDePedimentoId="A1",CertificadoOrigen=0,IncotermId="FOB",TipoCambioUSD=17.4948m,Emisor=newFiscalapi.Models.ForeignTrade.Emisor{Domicilio=newFiscalapi.Models.ForeignTrade.EmisorDomicilio{Calle="CALLE DEL PAPEL",ColoniaId="0214",LocalidadId="01",MunicipioId="014",EstadoId="QUE",PaisId="MEX",CodigoPostalId="76199"}},Receptor=newFiscalapi.Models.ForeignTrade.Receptor{NumRegIdTrib="123456789",Domicilio=newFiscalapi.Models.ForeignTrade.ReceptorDomicilio{Calle="ST. A",Estado="TX",PaisId="USA",CodigoPostal="00000"}},Mercancias=newList<Fiscalapi.Models.ForeignTrade.Mercancia>{newFiscalapi.Models.ForeignTrade.Mercancia{NoIdentificacion="131494-1055",FraccionArancelariaId="2402200100",CantidadAduana=2.00m,UnidadAduanaId="01",ValorUnitarioAduana=11.74m,ValorDolares=23.47m}}}}};varapiResponse=awaitfiscalApi.Invoices.CreateAsync(invoice);

Para la versión Por Referencias, sustituye los objetos Issuer y Recipient por new InvoiceIssuer { Id = "..." } y new InvoiceRecipient { Id = "..." } manteniendo el resto idéntico.

8. Firmar Manifiesto

varfiscalApi=FiscalApiClient.Create(settings);varrequest=newSignManifestRequest{Base64Cer="MIIFsDCCA5igAwIBAgI...==",// .cer en Base64Base64Key="MIIFDjBABgkqhkiG9w0BBQ0...==",// .key en Base64Password="12345678a"};varapiResponse=awaitfiscalApi.Manifests.SignAsync(request);if(apiResponse.Succeeded){varbytes=Convert.FromBase64String(apiResponse.Data.Base64File);File.WriteAllBytes($"{apiResponse.Data.FileName}.{apiResponse.Data.FileExtension}",bytes);}

9. Búsqueda en Catálogos del SAT

// Busca los registros que contengan 'inter' en el catalogo 'SatUnitMeasurements' (pagina 1, tamaño pagina 10)varapiResponse=awaitfiscalApi.Catalogs.SearchCatalogAsync("SatUnitMeasurements","inter",1,10);if(apiResponse.Succeeded){foreach(variteminapiResponse.Data.Items){Console.WriteLine($"Unidad: {item.Description}");}}else{Console.WriteLine(apiResponse.Message);}

---

⏳ Operaciones Asíncronas y Sincrónicas

• Asíncrono:

  varapiResponse=awaitfiscalApi.Invoices.GetByIdAsync(<id>);

• Sincrónico (use esto solo en .NET Framework 4.X.X)

  varapiResponse=Task.Run(async()=>awaitfiscalApi.Invoices.GetByIdAsync(<id>)).Result;

📋 Operaciones Principales

• Facturas (CFDI)
  Crear facturas de ingreso, notas de crédito, complementos de pago, cancelaciones, generación de PDF/XML.
• Personas (Clientes/Emisores)
  Alta y administración de personas, gestión de certificados (CSD).
• Productos y Servicios
  Administración de catálogos de productos, búsqueda en catálogos SAT.

🤝 Contribuir

1. Haz un fork del repositorio.
2. Crea una rama para tu feature: git checkout -b feature/AmazingFeature.
3. Realiza commits de tus cambios: git commit -m 'Add some AmazingFeature'.
4. Sube tu rama: git push origin feature/AmazingFeature.
5. Abre un Pull Request en GitHub.

🐛 Reportar Problemas

1. Asegúrate de usar la última versión del SDK.
2. Verifica si el problema ya fue reportado.
3. Proporciona un ejemplo mínimo reproducible.
4. Incluye los mensajes de error completos.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MPL. Consulta el archivo LICENSE para más detalles.

🔗 Enlaces Útiles

• Documentación Oficial
• Portal de FiscalAPI
• Ejemplos WinForms/WPF/Console
• Ejemplos ASP.NET
• Postman Collection
• SDKs

---

Desarrollado con ❤️ por Fiscalapi