Skip to content

Latest commit

 

History

History
129 lines (75 loc) · 3.99 KB

README.en.md

File metadata and controls

129 lines (75 loc) · 3.99 KB

Fiscalapi-Spring

Spring Boot microservice that consumes the Fiscalapi API, for issuing compliance CFDI invoices in Mexico.

Versión en español

📋 Prerequisites

  • Docker and Docker Compose
  • Postman (optional, for testing with included collection)

Fiscalapi Account Setup

Before starting the application, you need to configure your Fiscalapi account:

1. Create an account

If you don't have an account yet, you can create one here. Don't forget to confirm your email by clicking the link sent.

2. Activate trial subscription

To stamp invoices you need an active subscription in the test environment and available stamps in your account. More information

3. Get API credentials

With your active subscription and available stamps, get your API keys to authenticate your HTTP requests to the API.

Project Configuration

Copy application.properties.sample to application.properties and configure:

  • fiscalapi.url: Fiscalapi base URL (test/live)
  • fiscalapi.api-key: Fiscalapi API Key
  • fiscalapi.tenant-id: Tenant ID
  • fiscalapi.timezone: Timezone (default: America/Mexico_City)
  • fiscalapi.debug: Debug mode for logging

Import into Postman

  1. Import collection: In Postman, go to Import → File → Select Fiscalapi-Spring.postman_collection.json

  2. Import environment: In Postman, go to Import → File → Select Fiscalapi-Spring-Dev.postman_environment.json

  3. Configure environment: Select the Fiscalapi-Spring-Dev environment and set the baseUrl variable to http://localhost:8080

Start the Application

Start the service

docker compose up --build

Service will be available at http://localhost:8080

Stop and remove everything

docker compose down -v

⚡ Features

Resources

  • Invoices /api/v4/invoices

    Manages the complete lifecycle of CFDI electronic invoices: create, list, cancel, query, download XML/PDF files, and send by email.

  • Products /api/v4/products

    Represents goods or services offered by an organization. Programmatic management of product and service catalog with taxes.

  • People /api/v4/people

    Represents any tax entity (individual or company). Centralized concept for managing organization resources.

  • API Keys /api/v4/apikeys

    Authenticates requests. Each API key has associated roles and permissions that determine allowed actions.

  • Stamps /api/v4/stamps

    Fiscal folios purchased in bundles to validate electronic invoices with the SAT. One stamp is consumed per invoice issued.

  • Tax Files /api/v4/tax-files

    Digital Seal Certificates (.cer and .key files) issued by the SAT that allow digitally signing invoices.

  • Catalogs /api/v4/catalogs

    CFDI 4.0 codes and values provided by the SAT, essential for creating electronic invoices.

Technologies

  • Spring Boot 3.5.7 with OpenJDK 25
  • PostgreSQL with Flyway for migrations
  • OpenAPI/Swagger at /swagger-ui.html
  • JPA/Hibernate with schema validation
  • Custom HTTP client for Fiscalapi

📚 API Documentation

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

🐛 Report Issues

  1. Make sure you're using the latest SDK version.
  2. Check if the issue has already been reported.
  3. Provide a minimal reproducible example.
  4. Include complete error messages.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🔗 Useful Links

Made with ❤️ by Fiscalapi