Verifactu en Dolibarr: cómo conectar Dolibarr con la API Verifactu
Verifacti no tiene módulo oficial para Dolibarr: Dolibarr se conecta con la API Verifactu con un módulo propio cuyo trigger, al validar una factura, la envía en JSON y guarda el QR. Sin generar el XML, sin calcular la huella y sin certificado digital: Verifacti envía el registro de facturación a la AEAT como colaborador social. El mismo patrón sirve para TicketBAI con la API TicketBAI.
Qué APIs necesitas para Dolibarr
Tu conector usa dos piezas: la API de envío que corresponde al NIF (API Verifactu en territorio común; API TicketBAI en Álava, Bizkaia y Gipuzkoa) y la API de gestión de NIFs, que integras una vez para dar de alta el NIF, gestionar el modelo de representación y recibir los webhooks. Cada NIF usa una u otra API según dónde tribute.
Cómo conectar Dolibarr con la API
Flujo: factura validada en Dolibarr (trigger BILL_VALIDATE) → tu módulo → API Verifactu o API TicketBAI → AEAT o hacienda foral.
- Da de alta el NIF con la API de gestión de NIFs y firma el modelo de representación. Cada NIF tiene su API key.
- Crea un módulo con un trigger y los atributos complementarios
verifactu_uuidyverifactu_qren facturas. - En
BILL_VALIDATE, construye la factura y llama aPOST /verifactu/create. - Guarda
uuidyqren los atributos y añade el QR al modelo de PDF.
¿Fabricas software y quieres ofrecer Verifactu a tus clientes? Lo tienes en fabricantes de ERP.
Ejemplo: de la factura validada al registro
El trigger usa el número definitivo de la factura (newref: durante BILL_VALIDATE, ref aún es la provisional), solo actúa sobre facturas estándar (los anticipos y los abonos necesitan su propio mapeo) y no reenvía una factura ya registrada. El total es base + IVA, sin recargo ni retención. Si la API responde con un error, devuelve -1 y Dolibarr deshace la validación y muestra el mensaje.
<?php
// htdocs/custom/verifacti/core/triggers/interface_99_modVerifacti_VerifactiTriggers.class.php · Dolibarr 16+.
// Envía cada factura de cliente validada a la API Verifactu.
// Crea antes los atributos complementarios verifactu_uuid y verifactu_qr en las facturas.
require_once DOL_DOCUMENT_ROOT . '/core/triggers/dolibarrtriggers.class.php';
class InterfaceVerifactiTriggers extends DolibarrTriggers
{
public function __construct($db)
{
parent::__construct($db);
$this->family = 'financial';
$this->description = 'Envía las facturas validadas a la API Verifactu';
}
public function runTrigger($action, $object, User $user, Translate $langs, Conf $conf)
{
// Solo facturas estándar; los anticipos (TYPE_DEPOSIT) y los abonos necesitan su propio mapeo
if ($action !== 'BILL_VALIDATE' || $object->type != Facture::TYPE_STANDARD) {
return 0;
}
// Ya registrada (se volvió a borrador y se valida otra vez): no se reenvía
$object->fetch_optionals();
if (!empty($object->array_options['options_verifactu_uuid'])) {
return 0;
}
// Durante BILL_VALIDATE, ref aún es la provisional (PROV…); el número definitivo está en newref
$ref = $object->newref ?: $object->ref;
$porTipo = [];
foreach ($object->lines as $linea) {
$tipo = (string) (float) $linea->tva_tx;
$porTipo[$tipo]['base'] = ($porTipo[$tipo]['base'] ?? 0) + $linea->total_ht;
$porTipo[$tipo]['cuota'] = ($porTipo[$tipo]['cuota'] ?? 0) + $linea->total_tva;
}
$object->fetch_thirdparty();
$nif = $object->thirdparty->idprof1 ?: preg_replace('/^ES/', '', (string) $object->thirdparty->tva_intra);
preg_match('/^(.*?)(\d+)$/', $ref, $partes);
$factura = [
'serie' => $partes[1],
'numero' => $partes[2],
'fecha_expedicion' => dol_print_date($object->date, '%d-%m-%Y'),
'tipo_factura' => $nif ? 'F1' : 'F2',
'descripcion' => $object->ref_client ?: 'Factura ' . $ref,
'lineas' => [],
// total_ttc incluye el recargo de equivalencia y resta la retención de IRPF: el registro lleva base + IVA
'importe_total' => price2num($object->total_ht + $object->total_tva, 'MT'),
];
if ($nif) {
$factura['nif'] = $nif;
$factura['nombre'] = $object->thirdparty->name;
}
foreach ($porTipo as $tipo => $l) {
$factura['lineas'][] = [
'base_imponible' => price2num($l['base'], 'MT'),
'tipo_impositivo' => $tipo,
'cuota_repercutida' => price2num($l['cuota'], 'MT'),
];
}
$cuerpo = json_encode($factura);
$ch = curl_init('https://api.verifacti.com/verifactu/create');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getDolGlobalString('VERIFACTI_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: dolibarr-' . $object->id . '-' . substr(hash('sha256', $cuerpo), 0, 12),
],
CURLOPT_POSTFIELDS => $cuerpo,
]);
$registro = json_decode((string) curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
$this->errors[] = 'Verifactu: ' . ($registro['error'] ?? 'sin respuesta');
return -1; // la validación de la factura se deshace
}
$object->array_options['options_verifactu_uuid'] = $registro['uuid'];
$object->array_options['options_verifactu_qr'] = $registro['qr'];
$object->insertExtraFields();
return 1;
}
}El código agrupa las líneas por tipo de IVA y usa F1 si el cliente tiene NIF y F2 si no. Envía la cabecera Idempotency-Key con el identificador de la factura y un resumen del cuerpo: un reintento igual no duplica la factura y, si corriges los datos tras un error, la clave cambia. La respuesta trae el uuid, el estado (Pendiente: el envío a la AEAT queda en cola), la URL de verificación, el QR en Base64 y la huella: guárdalos con la factura.
Más código en el tutorial de Verifactu en PHP. Para TicketBAI, la llamada es a POST /ticketbai/create con la API key del NIF foral: los campos, en la documentación de la API TicketBAI.
Casos particulares en Dolibarr
| Caso | Qué hacer | Dónde ampliar |
|---|---|---|
| Numeración | Cada factura necesita una serie con numeración correlativa. Si los números de factura pueden tener huecos, asigna a la factura un número propio | Requisitos de Verifactu |
| Cliente sin NIF | Factura simplificada (F2), sin nif ni nombre. La API rechaza una F2 de más de 3.000 € (vf-verifactu-f2_limite_3000) | Factura simplificada |
| Devolución o abono | Factura rectificativa: R5 si la original era simplificada; R1–R4 si era completa | Rectificativas |
| Cliente que pide factura completa después | Factura de canje (F3) que sustituye a la simplificada | Factura de canje |
| Canarias, Ceuta y Melilla | IGIC o IPSI en las líneas (campo impuesto), no IVA | IGIC · IPSI |
| Productos sin IVA | Revisa si son exentos (operacion_exenta) o no sujetos (calificacion_operacion): no se envían como tipo 0 | Factura exenta |
| Anulación | Solo para facturas que no debieron emitirse: POST /verifactu/cancel | Anulación |
| Venta a otro país de la UE | Depende de si el cliente es empresa y del umbral de ventas a distancia | Ejemplos intracomunitarios |
| Recargo de equivalencia | tipo_recargo_equivalencia y cuota_recargo_equivalencia en la línea de IVA, no como otra línea | Recargo de equivalencia |
| Retención de IRPF | No se envía: importe_total es base + cuota (+ recargo), sin restar la retención | Suplidos y retención |
| Varias sociedades o tiendas | Un NIF por sociedad, cada uno con su API key | API de gestión de NIFs |
Fechas
La primera fila solo aplica si construyes el conector para venderlo a otros: entonces vendes software de facturación. Para quien factura, las fechas de Verifactu están publicadas en el BOE y el aplazamiento a octubre de 2028 está anunciado sin norma publicada. En Álava, Bizkaia y Gipuzkoa, TicketBAI está en vigor.
| Quién | Fecha | Estado | Norma |
|---|---|---|---|
| Productores y comercializadores de software de facturación El RDL 15/2025 no modificó esta fecha. | Desde 29 jul 2025 | En vigor | RD 1007/2023 · Orden HAC/1177/2024 |
| Contribuyentes del Impuesto sobre Sociedades | 1 ene 2027 | Publicada en el BOE con fecha futura | RDL 15/2025 |
| Resto de obligados, autónomos incluidos | 1 jul 2027 | Publicada en el BOE con fecha futura | RDL 15/2025 |
| Aplazamiento de las obligaciones pendientes La nota no precisa el alcance para quien factura más de 8 M€. | oct 2028 | Anunciada sin norma publicada | Nota de Hacienda, 5 oct 2026 |
| TicketBAI en Álava: obligados forales Escalonado desde el 1 de abril de 2022; el resto de contribuyentes, desde el 1 de diciembre de 2022. | Desde 1 dic 2022 | En vigor | NF 13/2021 y DF 48/2021 · FAQ 1.9 · calendario |
| Batuz en Bizkaia (TicketBAI y LROE): todos los obligados Sociedades que no son pymes, desde el 1 de enero de 2024; el resto, en ventanas el 1 de julio de 2024, el 1 de enero de 2025, el 1 de julio de 2025 y el 1 de enero de 2026. | Desde 1 ene 2026 | En vigor | NF 8/2023 · Batuz |
| TicketBAI en Gipuzkoa: obligados forales Escalonado por actividad desde el 1 de julio de 2022. | Desde 1 jun 2023 | En vigor | NF 3/2020 · DF 32/2020 |
Esta información no es asesoramiento: cada contribuyente determina lo que le aplica con su asesor.
Más detalle en plazos de Verifactu y TicketBAI.
Precio
Tarifa pública de la API Verifactu y la API TicketBAI: pagas por cada NIF activo en producción, sin IVA. Para volumen hay precio a medida por NIF.
Desde
14,99 €
al mes el primer NIF activo en producción, sin IVA
Ver todos los precios- El precio por NIF baja con cada tramo de NIFs.
- Entorno de test y NIF de prueba gratuitos.
- Plan anual con un 10 % de descuento, sin costes de instalación.
- Hasta 3.000 registros de facturación al mes por NIF.
- Plan Startup para empresas de menos de 12 meses, con menos de 100.000 € de facturación y menos de 200.000 € de financiación.
- Mismo precio con la API Verifactu y la API TicketBAI: cada NIF usa una u otra según dónde tribute.
- Firma online del modelo de representación: 2,90 € + IVA por firma.
Recursos para desarrolladores
Para tu IA: llms.txt y la especificación OpenAPI.
Preguntas sobre Verifactu y Dolibarr
Más preguntas sobre Verifactu¿Hay un módulo o app de Verifacti para Dolibarr?
¿Basta con Dolibarr para cumplir Verifactu?
¿Sirve también para TicketBAI?
/ticketbai/create), los campos de la factura y la API key.¿Necesito certificado digital?
¿Cuánto cuesta?
Otras integraciones
Conecta Dolibarr en el entorno de test
Crea tu cuenta gratuita y prueba la API con un NIF de prueba antes de pasar a producción.