Facturapi Java SDK

Official Java SDK for Facturapi.

Español: README.es.md

Facturapi helps developers generate valid electronic invoices (CFDI) in Mexico.

If you've used Stripe or a similar API-first payments or billing SDK, the surface here should feel familiar: typed models on the way out, flexible JSON objects on the way in.

Make sure you have a Facturapi account and your API key.

Compatibility

• Java 11+
• Kotlin/JVM
• Android 8.0 (API level 26) o superior
• Spring Boot, Jakarta EE, Quarkus, Micronaut, and other JVM server apps

Installation

Maven:

<dependency>
  <groupId>io.facturapi</groupId>
  <artifactId>facturapi-java</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle:

implementation("io.facturapi:facturapi-java:1.0.0")

Quickstart

import io.facturapi.Facturapi;
import java.util.Map;

Facturapi facturapi = new Facturapi("sk_test_...");

var customer = facturapi.customers().create(Map.of(
  "legal_name", "Mi Empresa SA de CV",
  "tax_id", "XAXX010101000",
  "tax_system", "601",
  "email", "cliente@example.com"
), null);

var invoice = facturapi.invoices().create(Map.of(
  "customer", customer.getId(),
  "items", java.util.List.of(Map.of("quantity", 1, "product", "prod_123"))
), null);

System.out.println(invoice.getId());

Uploads

import java.io.File;

var organization = facturapi.organizations().uploadLogo(
  "org_123",
  new File("logo.png")
);

var updated = facturapi.organizations().uploadCertificate(
  "org_123",
  new File("certificate.cer"),
  new File("certificate.key"),
  "secret"
);

Errors

import io.facturapi.FacturapiException;

try {
  facturapi.customers().retrieve("cus_123");
} catch (FacturapiException e) {
  System.out.println(e.getMessage());
  System.out.println(e.getStatusCode());
  System.out.println(e.getErrorCode());
  System.out.println(e.getErrorPath());
}

Design

• Inputs use flexible JSON dictionaries (Map<String, Object>).
• Outputs are typed Java models (Invoice, Customer, SearchResult<T>, etc.).
• Errors expose the useful API error fields directly on FacturapiException.
• Auth uses Authorization: Bearer <apiKey>.

Configuration

Facturapi facturapi = Facturapi.builder("sk_test_...")
  .apiVersion("v2")
  .timeout(java.time.Duration.ofSeconds(20))
  .build();

Custom HTTP Client

For tests or advanced setups, you can inject your own OkHttpClient:

import okhttp3.OkHttpClient;

Facturapi facturapi = Facturapi.builder("sk_test_...")
  .httpClient(new OkHttpClient())
  .build();

Documentation

Full docs: https://docs.facturapi.io

Support

• Issues: open a GitHub issue
• Email: contacto@facturapi.io