FiscalAPI SDK para Java Spring

Ejemplos del SDK de FiscalAPI para Java Spring, 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 de la autoridad tributaria (SAT) y facilitando la generación de facturas, notas de crédito y complementos de pago, nómina, carta porte, etc.

El proyecto consiste en una aplicación Spring Boot que contiene diversos ejemplos para demostrar las diferentes funcionalidades de la API, organizados en controladores REST.

🚀 Características

El SDK de FiscalAPI para Java Spring ofrece una amplia gama de funcionalidades para la facturación electrónica en México:

📋 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.
• 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
• Ejemplos en Python

📥 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)

🛍️ 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

Requisitos previos:

• Java 8 o superior para el SDK
• Maven 3.6+ o utilizar el Maven Wrapper incluido
• Opcional: VSCode, Eclipse o altamente recomendado IntelliJ IDEA

Configuración del entorno

1. Instalar Java JDK 17

Es necesario instalar Java JDK 17 o superior para este proyecto.

Opción A: Descargar JDK

Puedes descargar OpenJDK 17 desde: Microsoft

Opción B: Instalación mediante winget (Windows)

winget install Microsoft.OpenJDK.17

2. Clonar el repositorio

git clone https://github.com/FiscalAPI/fiscalapi-samples-spring.git
cd fiscalapi-samples-spring

3. Configurar propiedades de la aplicación

Crea un archivo application.properties en la carpeta src/main/resources basado en el archivo de ejemplo:

cp src/main/resources/application.properties.example src/main/resources/application.properties

Edita el archivo application.properties y configura tus credenciales:

fiscalapi.api-url=https://test.fiscalapi.com
fiscalapi.api-key=tu_api_key
fiscalapi.tenant=tu_tenant_key

Reemplaza tu_api_key y tu_tenant_key con tus credenciales obtenidas del portal de FiscalAPI.

4. VSCode settings (IntelliJ IDEA resuelve esto automaticamente)

Si utilizas Visual Studio Code, crea o actualiza el archivo .vscode/settings.json con el siguiente contenido:

{
    "java.configuration.updateBuildConfiguration": "automatic",
    "java.home": "C:\\jdk-17.0.14",
    "maven.executable.path": "mvnw.cmd",
    "java.project.referencedLibraries": [ "lib/**/*.jar"],
    "java.compile.nullAnalysis.mode": "automatic"
}

Importante: Ajusta la ruta java.home a la ubicación donde instalaste el JDK 17 en tu sistema.

Compilar y ejecutar el proyecto

5. VSCode variables entorno (IntelliJ IDEA resuelve esto automaticamente)

Configurar el JDK temporalmente para la terminal actual de vscode:

$env:JAVA_HOME = "C:\jdk-17.0.14"
$env:Path += ";$env:JAVA_HOME\bin"

Asegúrate de ajustar la ruta a la ubicación donde instalaste el JDK 17 en tu sistema.

Ejecuta Usando Maven Wrapper

En Windows:

.\mvnw.cmd clean install
.\mvnw.cmd spring-boot:run

En macOS/Linux:

./mvnw clean install
./mvnw spring-boot:run

Ejecuta Usando Maven instalado en el sistema

En Windows:

mvn clean install
mvn spring-boot:run

En macOS/Linux:

mvn clean install
mvn spring-boot:run

Ejecuta: Desde un IDE

1. Importa el proyecto en tu IDE favorito (IntelliJ IDEA, Eclipse, etc.)
2. Asegúrate de que el IDE esté configurado para utilizar JDK 17
3. Ejecuta la clase FiscalapiSamplesSpringApplication como una aplicación Java

Acceso a los ejemplos

Una vez que la aplicación esté en ejecución, puedes acceder a:

• Documentación Swagger UI: Disponible en http://localhost:8080/swagger-ui/index.html

Ejemplos disponibles

La aplicación contiene varios controladores que muestran diferentes funcionalidades:

• InvoicesController: Ejemplos de timbrado de facturas, consultas y cancelaciones
• ProductController: Ejemplos de gestión de productos y servicios

Consulta la documentación Swagger para ver todos los endpoints disponibles y probarlos interactivamente.

Estructura del proyecto

├── src
│   ├── main
│   │   ├── java
│   │   │   └── com/fiscalapi/samples/spring
│   │   │       ├── FiscalapiSamplesSpringApplication.java
│   │   │       ├── config
│   │   │       │   ├── FiscalApiConfig.java
│   │   │       │   └── SwaggerConfig.java
│   │   │       ├── controller
│   │   │       │   ├── InvoicesController.java
│   │   │       │   └── ProductController.java
│   │   │       └── service
│   │   │           └── ProductService.java
│   │   └── resources
│   │       └── application.properties
└── pom.xml

Solución de problemas

Si encuentras errores relacionados con la compilación o ejecución del proyecto:

1. Verifica que estás utilizando Java JDK 17 o superior
   • Puedes comprobar la versión con java -version
2. Asegúrate de que Maven esté correctamente instalado o utiliza el Maven Wrapper incluido
   • Puedes comprobar la versión de Maven con mvn -version o .\mvnw.cmd -version
3. Verifica que el archivo application.properties exista y contenga las credenciales correctas
4. Si utilizas una versión anterior del SDK, actualiza a la última versión en el archivo pom.xml
5. Si estás en Windows y usas PowerShell, asegúrate de ejecutar los comandos con .\mvnw.cmd en lugar de solo mvnw
6. Revisa la documentación oficial de FiscalAPI para más información

🤝 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
• Como obtener mis credenciales
• Portal de FiscalAPI
• Sdk Java
• Soporte técnico
• Certificados prueba
• Más ejemplos Java

---

Desarrollado con ❤️ por Fiscalapi