Verifactu en Java: cómo enviar facturas con la API Verifactu

Con la API Verifactu envías una factura desde Java con java.net.http.HttpClient: una petición POST en JSON a https://api.verifacti.com/verifactu/create y recibes al instante el QR en Base64, la huella y un uuid para consultar el estado. No necesitas generar el XML, calcular la huella ni usar certificado digital: Verifacti envía el registro de facturación a la AEAT como colaborador social.

Este tutorial usa Java 11 o superior con java.net.http.HttpClient y Jackson para el JSON. También funciona con OkHttp.

Antes de empezar

  • Una cuenta gratuita de Verifacti: incluye entorno de test y NIF de prueba.
  • La API key de test del NIF de prueba (empieza por vf_test_) en la variable de entorno VERIFACTI_API_KEY. Nunca la escribas en el código.
  • Java 11 o superior y Jackson (com.fasterxml.jackson.core:jackson-databind) en el classpath.

Para dar de alta tus propios NIFs más adelante, sigue la guía rápida de la API Verifactu.

1. Autenticación

Todas las llamadas llevan el header Authorization: Bearer con tu API key. La API key fija el NIF emisor y el entorno (test o producción): no los indicas en la petición. La URL base es https://api.verifacti.com, la misma en test y en producción.

Este tutorial usa el HttpClient del JDK. Guarda esta clase como Verifacti.java: los demás ejemplos la usan. hoy() da la fecha en hora de España, que es la que comprueba la API.

Verifacti.java
// Verifacti.java: una sola función para todas las llamadas a la API de Verifacti.
// Lee la API key de la variable de entorno VERIFACTI_API_KEY.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;

public final class Verifacti {
    static final String BASE_URL = "https://api.verifacti.com";
    static final HttpClient HTTP = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    static final ObjectMapper JSON = new ObjectMapper();

    public static final class Respuesta {
        private final int status;
        private final JsonNode body;

        Respuesta(int status, JsonNode body) {
            this.status = status;
            this.body = body;
        }

        public int status() { return status; }

        public JsonNode body() { return body; }
    }

    public static String hoy() {
        return ZonedDateTime.now(ZoneId.of("Europe/Madrid")).format(DateTimeFormatter.ofPattern("dd-MM-yyyy"));
    }

    public static Respuesta send(String method, String path, Object body, String idempotencyKey) throws Exception {
        HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(BASE_URL + path))
                .timeout(Duration.ofSeconds(30))
                .header("Authorization", "Bearer " + System.getenv("VERIFACTI_API_KEY"));
        if (body != null) {
            request.header("Content-Type", "application/json")
                    .method(method, HttpRequest.BodyPublishers.ofString(JSON.writeValueAsString(body)));
        } else {
            request.method(method, HttpRequest.BodyPublishers.noBody());
        }
        if (idempotencyKey != null) {
            request.header("Idempotency-Key", idempotencyKey);
        }
        HttpResponse<String> response = HTTP.send(request.build(), HttpResponse.BodyHandlers.ofString());
        return new Respuesta(response.statusCode(), JSON.readTree(response.body()));
    }

    public static Respuesta send(String method, String path, Object body) throws Exception {
        return send(method, path, body, null);
    }
}

Con otro cliente HTTP

Con OkHttp la llamada es la misma: URL, header Authorization y el cuerpo en JSON.

OkHttpCliente.java
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.List;
import java.util.Map;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class OkHttpCliente {
    public static void main(String[] args) throws Exception {
        OkHttpClient http = new OkHttpClient();
        String json = new ObjectMapper().writeValueAsString(Map.of(
                "serie", "A",
                "numero", "3",
                "fecha_expedicion", Verifacti.hoy(),
                "tipo_factura", "F1",
                "descripcion", "Servicios de consultoría",
                "nif", "A15022510",
                "nombre", "Empresa Cliente SL",
                "lineas", List.of(Map.of("base_imponible", "200.00", "tipo_impositivo", "21", "cuota_repercutida", "42.00")),
                "importe_total", "242.00"));

        Request request = new Request.Builder()
                .url("https://api.verifacti.com/verifactu/create")
                .header("Authorization", "Bearer " + System.getenv("VERIFACTI_API_KEY"))
                .post(RequestBody.create(json, MediaType.get("application/json")))
                .build();
        try (Response response = http.newCall(request).execute()) {
            System.out.println(response.code() + " " + response.body().string());
        }
    }
}

2. Crear la factura

Crea la factura con POST /verifactu/create. Esta es una factura completa (F1) con una línea al 21 %. fecha_expedicion es la fecha de hoy en formato DD-MM-AAAA: el entorno de test solo acepta la de hoy (o la de ayer).

Los importes van como texto, con punto decimal y dos decimales como máximo. importe_total tiene que cuadrar con la suma de base_imponible y cuota_repercutida de las líneas. nif y nombre son los del destinatario: el NIF emisor lo pone la API key.

Crear.java
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;

public class Crear {
    public static void main(String[] args) throws Exception {
        Map<String, Object> factura = Map.of(
                "serie", "A",
                "numero", "1",
                "fecha_expedicion", Verifacti.hoy(),
                "tipo_factura", "F1",
                "descripcion", "Servicios de consultoría",
                "nif", "A15022510",
                "nombre", "Empresa Cliente SL",
                "lineas", List.of(Map.of("base_imponible", "200.00", "tipo_impositivo", "21", "cuota_repercutida", "42.00")),
                "importe_total", "242.00");

        Verifacti.Respuesta r = Verifacti.send("POST", "/verifactu/create", factura);

        if (r.status() != 200) {
            System.out.println("Error " + r.status() + ": " + r.body().path("codigo").asText() + " " + r.body().path("error").asText());
            System.exit(1);
        }
        System.out.println("uuid: " + r.body().get("uuid").asText());
        System.out.println("estado: " + r.body().get("estado").asText());
        Files.writeString(Path.of("respuesta.json"), r.body().toString());
    }
}

Para otros tipos de factura (simplificada F2, rectificativas R1–R5, exentas…), mira los ejemplos de facturas de Verifactu.

3. Leer la respuesta y el QR

La respuesta llega al momento, sin esperar a la AEAT:

  • uuid: identificador del registro de facturación. Guárdalo para consultar el estado.
  • estado: siempre Pendiente al crear. Verifacti encola el registro y lo envía a la Agencia Tributaria (AEAT), normalmente en uno o dos minutos.
  • url: URL de cotejo de la AEAT que contiene el QR.
  • qr: imagen PNG del QR (290 × 290 px) en Base64.
  • huella: huella (hash) del registro, ya encadenada con el anterior.
Respuesta · 200
{
  "estado": "Pendiente",
  "uuid": "b018ced3-b362-4494-8776-9eefff1c160c",
  "url": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A1&fecha=19-11-2026&importe=242.00",
  "qr": "iVBORw0KGgoAAAANSUhEUgAAASIAAAEi...",
  "huella": "B11F3A015173AD99075E2720F61E2DE1FF08CBFEDD85C6F73C77AD835301B2A3"
}
Qr.java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

public class Qr {
    public static void main(String[] args) throws Exception {
        JsonNode respuesta = new ObjectMapper().readTree(Files.readString(Path.of("respuesta.json")));

        Files.write(Path.of("qr.png"), Base64.getDecoder().decode(respuesta.get("qr").asText()));
        System.out.println("QR guardado en qr.png. URL de verificación: " + respuesta.get("url").asText());
    }
}

Tamaño, posición y leyenda del QR en la factura, en QR de Verifactu.

4. Pegar el QR en la factura en PDF

Para pegar el QR en un PDF desde Java puedes usar Apache PDFBox u OpenPDF. Este ejemplo con PDFBox 3 inserta a 35 × 35 mm el PNG que has guardado en el paso anterior.

Pdf.java · PDFBox
import java.io.File;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDPage;
import org.apache.pdfbox.pdmodel.PDPageContentStream;
import org.apache.pdfbox.pdmodel.common.PDRectangle;
import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;

public class Pdf {
    public static void main(String[] args) throws Exception {
        float mm = 72 / 25.4f;
        try (PDDocument documento = new PDDocument()) {
            PDPage pagina = new PDPage(PDRectangle.A4);
            documento.addPage(pagina);
            PDImageXObject qr = PDImageXObject.createFromFile("qr.png", documento);
            try (PDPageContentStream contenido = new PDPageContentStream(documento, pagina)) {
                float alto = pagina.getMediaBox().getHeight();
                contenido.drawImage(qr, 10 * mm, alto - 49 * mm, 35 * mm, 35 * mm);
            }
            documento.save(new File("factura.pdf"));
        }
    }
}

Con la API no hace falta generar el QR: viene en la respuesta. Si aun así quieres generarlo tú a partir de la url, puedes usar ZXing.

5. Consultar el estado

Consulta el estado del registro con GET /verifactu/status?uuid=…. Hazlo pasado un minuto o, mejor, recibe el resultado por webhook (paso 8). Nunca en un bucle sin espera.

Los estados posibles son Pendiente, Correcto, Aceptado con errores, Incorrecto, Duplicado, Anulado, Factura inexistente, No registrado y Error servidor AEAT. Con Aceptado con errores o Incorrecto, la respuesta trae codigo_error y mensaje_error de la AEAT: qué hacer en cada caso, en errores de Verifactu.

Estado.java
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class Estado {
    public static void main(String[] args) throws Exception {
        String uuid = new ObjectMapper().readTree(Files.readString(Path.of("respuesta.json"))).get("uuid").asText();

        Verifacti.Respuesta r = Verifacti.send("GET", "/verifactu/status?uuid=" + URLEncoder.encode(uuid, StandardCharsets.UTF_8), null);

        String estado = r.body().get("estado").asText();
        System.out.println("estado: " + estado);
        if (estado.equals("Incorrecto") || estado.equals("Aceptado con errores")) {
            System.out.println("AEAT " + r.body().get("codigo_error").asText() + ": " + r.body().get("mensaje_error").asText());
        }
    }
}
Respuesta · 200
{
  "nif": "B12345674",
  "serie": "A",
  "numero": "1",
  "fecha_expedicion": "19-11-2026",
  "operacion": "Alta",
  "estado": "Correcto",
  "url": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A1&fecha=19-11-2026&importe=242.00",
  "qr": "iVBORw0KGgoAAAANSUhEUgAAASIAAAEi...",
  "codigo_error": null,
  "mensaje_error": null,
  "estado_registro_duplicado": null
}

6. Rectificativas y anulaciones

  • Rectificativa: es una factura nueva con tipo_factura de R1 a R5, creada con el mismo POST /verifactu/create. Ver factura rectificativa.
  • Anulación: POST /verifactu/cancel, solo para facturas que no debieron emitirse. Ver anulación.
  • Subsanación: PUT /verifactu/modify, para corregir datos de un registro ya enviado. Ver subsanación.
Anular.java
import java.util.Map;

public class Anular {
    public static void main(String[] args) throws Exception {
        Verifacti.Respuesta r = Verifacti.send("POST", "/verifactu/cancel", Map.of(
                "serie", "A",
                "numero", "1",
                "fecha_expedicion", Verifacti.hoy()));

        System.out.println(r.status() + " " + r.body());
    }
}

La anulación responde con su propio uuid, estado Pendiente y huella.

7. Reintentos sin duplicar

Envía el header opcional Idempotency-Key en /create, /create_bulk, /modify y /cancel. Genera un UUID por factura y reutilízalo en los reintentos de esa misma factura:

  • Mismo cuerpo y misma clave: la API devuelve la primera respuesta, con el header Idempotent-Replayed: true, sin crear otro registro.
  • 409: la primera petición sigue en curso. Espera unos segundos y repite.
  • 422: has usado la clave con un cuerpo distinto. Usa una clave nueva.
  • Un 400 también se guarda: si corriges los datos, usa una clave nueva. Las 5xx no se guardan y el reintento se procesa de nuevo.
  • La clave se recuerda 24 horas y va ligada al NIF emisor. Si han pasado más de 24 horas sin respuesta, comprueba con POST /verifactu/status (serie, numero y fecha_expedicion) si la factura llegó a registrarse antes de reenviarla.
Reintentos.java
import java.io.IOException;
import java.util.List;
import java.util.Map;
import java.util.UUID;

public class Reintentos {
    static Verifacti.Respuesta crearFactura(Map<String, Object> factura, String clave) throws Exception {
        for (int intento = 1; intento <= 5; intento++) {
            try {
                Verifacti.Respuesta r = Verifacti.send("POST", "/verifactu/create", factura, clave);
                if (r.status() != 409 && r.status() < 500) {
                    return r;
                }
            } catch (IOException e) {
                // Sin respuesta: se reintenta con la misma clave
            }
            if (intento < 5) {
                Thread.sleep(1000L << intento);
            }
        }
        throw new IllegalStateException("Sin respuesta tras 5 intentos: reintenta más tarde con la misma clave");
    }

    public static void main(String[] args) throws Exception {
        Map<String, Object> factura = Map.of(
                "serie", "A",
                "numero", "2",
                "fecha_expedicion", Verifacti.hoy(),
                "tipo_factura", "F1",
                "descripcion", "Servicios de consultoría",
                "nif", "A15022510",
                "nombre", "Empresa Cliente SL",
                "lineas", List.of(Map.of("base_imponible", "100.00", "tipo_impositivo", "21", "cuota_repercutida", "21.00")),
                "importe_total", "121.00");

        String clave = UUID.randomUUID().toString();
        Verifacti.Respuesta r = crearFactura(factura, clave);
        System.out.println(r.status() + " " + (r.status() == 200 ? r.body().get("uuid").asText() : r.body().path("error").asText()));
    }
}

8. Webhooks

En lugar de consultar el estado, recibe el resultado por webhook. Los webhooks se crean con la API de gestión de NIFs y se asocian a uno o varios NIFs. Esa API usa la API key de la cuenta (empieza por vfn_, en la variable VERIFACTI_NIFS_API_KEY), que está disponible con una suscripción activa. Con la cuenta gratuita puedes crear un webhook desde el panel.

CrearWebhook.java
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.Map;

public class CrearWebhook {
    public static void main(String[] args) throws Exception {
        String body = new ObjectMapper().writeValueAsString(Map.of(
                "url", "https://tu-dominio.com/webhook",
                "entorno", "test",
                "secret", System.getenv("VERIFACTI_WEBHOOK_SECRET"),
                "nifs", List.of("B12345674"))); // el NIF de prueba de tu cuenta

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.verifacti.com/webhooks"))
                .header("Authorization", "Bearer " + System.getenv("VERIFACTI_NIFS_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode() + " " + response.body());
    }
}

Recibir el aviso

Cada aviso es un POST con un array JSON de registros, con los mismos campos que GET /verifactu/status más el uuid (y sin el QR). Si defines un secret, el header X-Webhook-Signature lleva el HMAC-SHA256 del cuerpo en hexadecimal: calcúlalo sobre el cuerpo tal como llega, antes de parsearlo. X-Webhook-Id es el mismo en todos los reintentos de un aviso: úsalo para no procesarlo dos veces. Responde 2xx en menos de 10 segundos. Este receptor usa el HttpServer del JDK, sin dependencias, y compara la firma con MessageDigest.isEqual.

Webhook.java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Webhook {
    public static void main(String[] args) throws Exception {
        byte[] secret = System.getenv("VERIFACTI_WEBHOOK_SECRET").getBytes(StandardCharsets.UTF_8);
        HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);

        server.createContext("/webhook", exchange -> {
            byte[] cuerpo = exchange.getRequestBody().readAllBytes();
            String firma = String.valueOf(exchange.getRequestHeaders().getFirst("X-Webhook-Signature"));
            int status = 401;
            try {
                Mac mac = Mac.getInstance("HmacSHA256");
                mac.init(new SecretKeySpec(secret, "HmacSHA256"));
                StringBuilder esperada = new StringBuilder();
                for (byte b : mac.doFinal(cuerpo)) {
                    esperada.append(String.format("%02x", b));
                }
                if (MessageDigest.isEqual(esperada.toString().getBytes(StandardCharsets.US_ASCII), firma.getBytes(StandardCharsets.US_ASCII))) {
                    String avisoId = exchange.getRequestHeaders().getFirst("X-Webhook-Id");
                    for (JsonNode registro : new ObjectMapper().readTree(cuerpo)) {
                        System.out.println(avisoId + " " + registro.get("serie").asText() + registro.get("numero").asText() + ": " + registro.get("estado").asText());
                    }
                    status = 200;
                }
            } catch (Exception e) {
                status = 400;
            }
            exchange.sendResponseHeaders(status, -1);
            exchange.close();
        });
        server.start();
    }
}

Ejemplo completo en un solo archivo

Un archivo que crea la factura con Idempotency-Key, guarda el QR en PNG y consulta el estado. Con Java 11 o superior lo ejecutas sin compilar: VERIFACTI_API_KEY=vf_test_… java -cp "jackson/*" Completo.java. Usa la hora actual como número de factura para que puedas ejecutarlo varias veces.

Completo.java
// Verifactu en Java con la API de Verifacti: crea una factura, guarda el QR y consulta el estado.
// Necesita Jackson (com.fasterxml.jackson.core:jackson-databind).
// Uso: VERIFACTI_API_KEY=vf_test_... java -cp "jackson/*" Completo.java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;
import java.util.List;
import java.util.Map;
import java.util.UUID;

public class Completo {
    static final String BASE_URL = "https://api.verifacti.com";
    static final HttpClient HTTP = HttpClient.newHttpClient();
    static final ObjectMapper JSON = new ObjectMapper();

    static HttpResponse<String> send(String method, String path, Object body, String clave) throws Exception {
        HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(BASE_URL + path))
                .timeout(Duration.ofSeconds(30))
                .header("Authorization", "Bearer " + System.getenv("VERIFACTI_API_KEY"));
        if (body != null) {
            request.header("Content-Type", "application/json")
                    .method(method, HttpRequest.BodyPublishers.ofString(JSON.writeValueAsString(body)));
        } else {
            request.method(method, HttpRequest.BodyPublishers.noBody());
        }
        if (clave != null) {
            request.header("Idempotency-Key", clave);
        }
        return HTTP.send(request.build(), HttpResponse.BodyHandlers.ofString());
    }

    public static void main(String[] args) throws Exception {
        String hoy = ZonedDateTime.now(ZoneId.of("Europe/Madrid")).format(DateTimeFormatter.ofPattern("dd-MM-yyyy"));
        String numero = String.valueOf(System.currentTimeMillis() / 1000);
        Map<String, Object> factura = Map.of(
                "serie", "A",
                "numero", numero,
                "fecha_expedicion", hoy,
                "tipo_factura", "F1",
                "descripcion", "Servicios de consultoría",
                "nif", "A15022510",
                "nombre", "Empresa Cliente SL",
                "lineas", List.of(Map.of("base_imponible", "200.00", "tipo_impositivo", "21", "cuota_repercutida", "42.00")),
                "importe_total", "242.00");

        // 1. Crear la factura. La misma Idempotency-Key en cada reintento: nunca se duplica.
        String clave = UUID.randomUUID().toString();
        HttpResponse<String> alta = null;
        for (int intento = 1; intento <= 5; intento++) {
            try {
                alta = send("POST", "/verifactu/create", factura, clave);
                if (alta.statusCode() != 409 && alta.statusCode() < 500) {
                    break;
                }
            } catch (IOException e) {
                // Sin respuesta: se reintenta con la misma clave
            }
            if (intento < 5) {
                Thread.sleep(1000L << intento);
            }
        }
        if (alta == null || alta.statusCode() != 200) {
            System.err.println("Error: " + (alta == null ? "sin respuesta" : alta.statusCode() + " " + alta.body()));
            System.exit(1);
        }
        JsonNode respuesta = JSON.readTree(alta.body());
        String uuid = respuesta.get("uuid").asText();
        System.out.println("Factura A" + numero + " creada. uuid: " + uuid);

        // 2. Guardar el QR para la factura impresa o en PDF.
        Files.write(Path.of("qr.png"), Base64.getDecoder().decode(respuesta.get("qr").asText()));
        System.out.println("QR guardado en qr.png");

        // 3. Consultar el estado. El envío a la AEAT suele tardar uno o dos minutos.
        JsonNode registro = null;
        int ultimo = 0;
        for (int consulta = 0; consulta < 6; consulta++) {
            Thread.sleep(30_000);
            HttpResponse<String> r = send("GET", "/verifactu/status?uuid=" + uuid, null, null);
            registro = JSON.readTree(r.body());
            ultimo = r.statusCode();
            if (r.statusCode() == 200 && !registro.get("estado").asText().equals("Pendiente")) {
                break;
            }
        }
        if (ultimo != 200) {
            System.err.println("Sin respuesta del estado: " + ultimo);
            System.exit(1);
        }
        System.out.println("Estado: " + registro.get("estado").asText());
        if (!registro.path("codigo_error").isNull() && !registro.path("codigo_error").isMissingNode()) {
            System.out.println("AEAT " + registro.get("codigo_error").asText() + ": " + registro.get("mensaje_error").asText());
        }
    }
}

Errores frecuentes

Errores frecuentes al enviar facturas con la API Verifactu
CódigoCausaSolución
401API key ausente o no válidaRevisa el header Authorization y que la clave sea la del NIF.
403NIF desactivadoActívalo en el panel o con la API de gestión de NIFs.
400 vf-verifactu-fecha_expedicion_hoyfecha_expedicion no es la fecha actual (entorno de test)Envía la fecha de hoy en formato DD-MM-AAAA, hora de España.
400 vf-verifactu-importe_total_cuadreimporte_total no cuadra con la suma de las líneasRecalcula base, cuota y recargo de todas las líneas.
400 vf-verifactu-factura_duplicadaYa existe una factura con la misma serie, numero y fecha_expedicionRevisa la numeración.
409Otra petición con la misma Idempotency-Key sigue en cursoEspera unos segundos y repite con la misma clave.
422Idempotency-Key reutilizada con otro cuerpoUsa una clave nueva para la petición corregida.

Todos los códigos y los estados, en errores de Verifactu.

¿Librería propia o API?

Para cumplir con Verifactu puedes integrarte directamente con la AEAT: generar el XML (estructura del XML de Verifactu), calcular la huella y el encadenamiento, enviar con certificado y respetar el control de flujo. O usar una API REST como la de Verifacti, que recibe JSON y no necesita certificado.

Qué cambia entre generar el XML tú mismo y usar la API Verifactu
Qué tienes que resolverGenerar y enviar tú el XMLCon la API Verifactu
FormatoComponer el XML según los esquemas XSD de la AEATEnvías JSON
Huella y encadenamientoCalcular la huella SHA-256 de cada registro y guardar la del anterior por NIFLo hace Verifacti; la huella vuelve en la respuesta
CertificadoLlamada autenticada con certificado electrónico, propio o del clienteSin certificado: Verifacti envía como colaborador social con el modelo de representación de cada NIF
EnvíoRespetar el control de flujo de la AEAT (por defecto, un envío por minuto salvo que acumules 1.000 registros) y gestionar colas y reintentosRespuesta inmediata; Verifacti encola y envía
QRGenerar la URL de cotejo y el QRViene en la respuesta (PNG en Base64)
ConservaciónGuardar registros y respuestasConsulta, listado y exportación de los XML por API

Siguiente paso

Lee la documentación de la API Verifactu, copia los ejemplos de facturas o sigue la guía rápida para pasar a producción. Consulta los precios.

Entorno de test y NIF de prueba incluidos

Lo que dicen quienes ya lo han integrado

Koibox
«La integración con Verifactu fue muy sencilla y el soporte ha sido excelente. Siempre atentos y rápidos para resolver dudas. Muy contento con el servicio.»
Antonio TapiasCTO & Co-Founder, Koibox
Boxify
«Hemos integrado nuestro software en tiempo récord. La documentación es clara y sencilla, y los ejemplos variados y muy útiles. El equipo de soporte me ha ayudado con todas las dudas.»
Kike IsasiFounder, Boxify
Xolo
“Verifacti’s SaaS platform is intuitive and reliable, and their team’s deep expertise and prompt, crystal-clear answers helped us reach our goals on time. They’re not only highly knowledgeable and professional but also a genuine pleasure to work with.”
Sebastien RequiemCTO, Xolo
Mekavo
“Verifacti made Veri*factu compliance surprisingly straightforward. Their API is clean, well-documented, and their support team responds with real solutions — not generic replies. For any SaaS serving Spanish businesses, Verifacti is the partner you want.”
Mehrdad MadadiFounder & Lead Developer, Mekavo

Preguntas sobre Verifactu en Java

¿Hay una librería oficial de Verifactu para Java?

No. La AEAT publica servicios web y esquemas XSD, no librerías. Existen proyectos de terceros que generan y firman el XML. Con la API Verifactu basta un cliente HTTP: envías JSON y recibes el QR.

¿Necesito certificado digital para enviar facturas a Verifactu desde Java?

No con la API Verifactu. Verifacti envía los registros a la AEAT como colaborador social, con el modelo de representación que firma cada NIF.

¿Cómo obtengo el QR de la factura?

Viene en la respuesta de POST /verifactu/create, en el campo qr: una imagen PNG en Base64. Decodifícala y pégala en la factura; no hace falta generarlo.

¿Puedo probar sin efectos fiscales?

Sí. La cuenta gratuita incluye un NIF de prueba conectado al entorno de test de la AEAT: todo el código de este tutorial funciona con su API key (vf_test_…).

¿Cómo reintento un envío sin duplicar la factura?

Con el header Idempotency-Key: genera un UUID por factura y repítelo en cada reintento. Si la primera petición llegó, la API devuelve la misma respuesta y no crea otro registro.

Prueba el código con la cuenta gratuita

Te da la API key de test con la que funciona todo el tutorial.

Entorno de test y NIF de prueba incluidosLee la documentación