Fiscalapi-Spring

Microservicio Spring Boot que consume el API de Fiscalapi, para la emision de Facturas CFDI en México.

English version

📋 Prerrequisitos

• Docker y Docker Compose
• Postman (opcional, para pruebas con la colección incluida)

Configuración de cuenta Fiscalapi

Antes de levantar la aplicación, necesitas configurar tu cuenta de Fiscalapi:

1. Crear una cuenta

Si aún no tiene una cuenta, puede crear una aquí. No olvide confirmar su correo electrónico haciendo clic en el enlace enviado.

2. Activar suscripción de prueba

Para timbrar facturas necesita una suscripción activa en el ambiente de pruebas y timbres disponibles en su cuenta. Más información

3. Obtener credenciales API

Con su suscripción activa y timbres disponibles, obtenga sus claves API para autenticar sus solicitudes HTTP a la API.

Configuración del proyecto

Copia application.properties.sample a application.properties y configura:

• fiscalapi.url: URL base de Fiscalapi (test/live)
• fiscalapi.api-key: API Key de Fiscalapi
• fiscalapi.tenant-id: Tenant ID
• fiscalapi.timezone: Zona horaria (default: America/Mexico_City)
• fiscalapi.debug: Modo debug para logs

Importar en Postman

1. Importar la colección: En Postman, ve a Import → File → Selecciona Fiscalapi-Spring.postman_collection.json

2. Importar el environment: En Postman, ve a Import → File → Selecciona Fiscalapi-Spring-Dev.postman_environment.json

3. Configurar el environment: Selecciona el environment Fiscalapi-Spring-Dev y configura la variable baseUrl con http://localhost:8080

Levantar la aplicación

Iniciar el servicio

docker compose up --build

El servicio estará disponible en http://localhost:8080

Detener y eliminar todo

docker compose down -v

⚡ Características

Recursos

• Facturas /api/v4/invoices

  Gestiona el ciclo de vida completo de facturas electrónicas CFDI: crear, listar, cancelar, consultar, descargar XML/PDF y enviar por correo.

• Productos /api/v4/products

  Representa bienes o servicios ofrecidos por una organización. Gestión programática del catálogo de productos y servicios con impuestos.

• Personas /api/v4/people

  Representa cualquier entidad fiscal (persona física o moral). Concepto centralizado para gestionar recursos de la organización.

• API Keys /api/v4/apikeys

  Autenticación de solicitudes. Cada API key tiene roles y permisos asociados que determinan las acciones permitidas.

• Sellos /api/v4/stamps

  Folios fiscales comprados en paquetes para validar facturas electrónicas ante el SAT. Se consume un timbre por cada factura emitida.

• Archivos Fiscales /api/v4/tax-files

  Certificados de Sello Digital (.cer y .key) emitidos por el SAT que permiten firmar digitalmente las facturas.

• Catálogos /api/v4/catalogs

  Códigos y valores CFDI 4.0 proporcionados por el SAT, esenciales para la creación de facturas electrónicas.

Tecnologías

• Spring Boot 3.5.7 con OpenJDK 25
• PostgreSQL con Flyway para migraciones
• OpenAPI/Swagger en /swagger-ui.html
• JPA/Hibernate con validación de esquema
• Cliente HTTP personalizado para Fiscalapi

📚 Documentación API

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/api-docs
• Postman Collection: Fiscalapi-Spring.postman_collection.json

🐛 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
• Fiscalapi
• Test Dashboard
• Live Dashboard

---

Desarrollado con ❤️ por Fiscalapi