API de MiFactu
Tu web cobra y MiFactu hace la factura. Con una llamada, la factura queda creada en tu cuenta, numerada, registrada en VERI*FACTU y con su PDF, en tu archivo y en el trimestre de tu gestor. Incluida en todos los planes.
Empezar
- En tu cuenta, Perfil → API, crea una clave de prueba (
mf_test_…). Sus facturas salen marcadas «PRUEBA · SIN VALIDEZ», no se envían a Hacienda y no cuentan en tu balance. - Integra tu web con ella hasta que todo funcione.
- Crea la clave real (
mf_live_…) y cámbiala en la configuración de tu web. Desde ese momento las facturas son de verdad.
Para facturas reales hace falta la suscripción activa, el perfil completo (nombre o razón social, NIF y domicilio fiscal) y haber firmado la autorización de VERI*FACTU.
Autenticación
Cada petición lleva la clave en la cabecera Authorization. Todo va por HTTPS y en JSON. Los importes van en céntimos (9,99 € = 999) y las fechas en formato AAAA-MM-DD.
curl https://mifactu.app/api/v1/ -H "Authorization: Bearer mf_test_…"
Responde con tu cuenta, el tipo de clave y cuántas facturas llevas este mes.
Crear una factura
POST /api/v1/facturas/
curl https://mifactu.app/api/v1/facturas/ \
-H "Authorization: Bearer mf_test_…" \
-H "Content-Type: application/json" \
-d '{
"referencia": "pedido-10045",
"cliente": {"nombre": "Ana Martín", "nif": "12345678Z",
"domicilio": "C/ Larios 1, 29005 Málaga", "email": "ana@ejemplo.es"},
"lineas": [{"concepto": "Suscripción mensual", "cantidad": 1, "precio": 826}],
"iva_pct": "21",
"notas": "Pagada con tarjeta.",
"enviar": true
}'
| Campo | Qué es |
|---|---|
referencia | Recomendado. Tu identificador de la venta (pedido, cobro…), hasta 100 caracteres. Si repites la petición con la misma referencia, no se crea otra factura: te devolvemos la que ya existe (200 en vez de 201). Con la misma referencia y otros datos: error 409. |
cliente | nombre, nif, domicilio, email, telefono. Con NIF, la factura es completa y lleva nombre y domicilio. Sin NIF, es simplificada: solo hasta 400 € con IVA (3.000 € si en tu perfil tienes marcada una actividad de hostelería, comercio al por menor, transporte de personas…) y sin retención. |
lineas | Conceptos (hasta 30): concepto, cantidad (hasta 3 decimales) y precio unitario en céntimos, sin IVA. |
iva_pct | "21" (por defecto), "10" o "4". |
ret_pct | Retención de IRPF: "0" (por defecto), "7", "15"… |
no_sujeta | true para una operación no sujeta al IVA por las reglas de localización (p. ej. servicios electrónicos a un cliente de Canarias, Ceuta o Melilla). Sin IVA y con la mención legal en la factura. Lo decides tú (o tu asesor) según la operación. |
operacion | Sin él (o ""), una venta normal con IVA. "exenta": exenta de IVA, con exencion. "isp": inversión del sujeto pasivo (subcontratas de obra…): sin IVA, lo declara tu cliente; necesita su NIF y opcionalmente isp_supuesto: "construccion" (art. 84.Uno.2º.f), "inmuebles" (e), "chatarra" (c), "electronica" (g), "oro" (b) u "otro". La factura lleva la mención «Inversión del sujeto pasivo». |
exencion | Causa de la exención (lista L10 de VERI*FACTU): "E1" artículo 20 de la Ley del IVA (sanidad, enseñanza…), "E2" exportación (art. 21), "E3" asimiladas a la exportación (art. 22), "E4" arts. 23 y 24, "E5" venta intracomunitaria (art. 25; el nif del cliente es su NIF-IVA europeo), "E6" otras. Con "E1", exencion_supuesto: el número del apartado del art. 20.Uno ("3" médicos y sanitarios, "9" enseñanza, "10" clases particulares, "23" alquiler de vivienda…) u "otro". Con "otro" o "E6", exencion_texto: el precepto («artículo 20.Uno.12º de la Ley 37/1992»). La factura lleva la mención del artículo. |
recargo_equivalencia | true si el cliente es un comercio minorista en recargo de equivalencia: se le añade el recargo según el IVA (5,2 % con el 21 %, 1,4 % con el 10 %, 0,5 % con el 4 %). Necesita su NIF. |
fecha_operacion | Solo si la venta fue antes del día de hoy. La fecha de la factura es siempre la del día en que se crea. |
notas | Forma de pago, vencimiento… (sale en el PDF). |
enviar | true: mandamos el PDF por correo al email del cliente. |
idioma | Idioma del PDF y del correo al cliente: "es" (Español), por defecto; "gl" (Galego). Sus rectificativas salen en el mismo idioma. |
Respuesta (201):
{
"id": 1532, "numero": "P2026-0007", "serie": "P2026", "tipo": "F1", "fecha": "2026-11-10",
"referencia": "pedido-10045", "prueba": true,
"cliente": {"nombre": "Ana Martín", "nif": "12345678Z", ...},
"lineas": [{"concepto": "Suscripción mensual", "cantidad": "1", "precio": 826, "importe": 826}],
"base": 826, "iva": 173, "recargo_pct": "0", "recargo": 0, "retencion": 0, "total": 999, "moneda": "EUR",
"operacion": "", "exencion": "", "clave_regimen": "01", "mencion": "",
"estado": "registrada", "estado_aeat": "Simulado",
"qr_url": "https://…", "pdf_url": "https://mifactu.app/api/v1/facturas/1532/pdf/",
"rectificativas": [], "pendiente_de_rectificar": 999
}
total es lo que cobras: base + IVA + recargo − retención. Si en tu perfil estás en el criterio de caja, la factura lleva la mención «Régimen especial del criterio de caja» y se registra con la clave 07; en el régimen simplificado, con la clave 20.
Con una clave real, estado_aeat empieza en «Pendiente de envío» y en uno o dos minutos pasa a «Registrada en la AEAT» (o «Rechazada por la AEAT»). Te avisamos si configuras la URL de avisos.
Otras operaciones
GET /api/v1/facturas/ | Lista, de la más nueva a la más antigua. Filtros: referencia, desde, hasta, limite (hasta 100) y antes_de (id: la página siguiente). hay_mas indica si quedan más. |
GET /api/v1/facturas/{id}/ | Una factura. |
GET /api/v1/facturas/{id}/pdf/ | El PDF. |
POST /api/v1/facturas/{id}/enviar/ | Manda el PDF por correo: {"email": "…"} (sin él, al del cliente). |
POST /api/v1/facturas/{id}/rectificar/ | Factura rectificativa (ver abajo). |
POST /api/v1/facturas/{id}/anular/ | Anula una factura que no debió hacerse (se registra la anulación en VERI*FACTU). Si la venta fue real y devuelves el dinero, no se anula: se rectifica. |
DELETE /api/v1/facturas/{id}/ | Solo las de prueba. |
Una clave de prueba solo ve sus facturas de prueba; una real ve todas las facturas reales de tu cuenta, también las que haces en la web o la app.
Devoluciones y correcciones: rectificativas
POST /api/v1/facturas/{id}/rectificar/. Admite referencia (p. ej. el id de la devolución), como al crear.
{"referencia": "devolucion-881", "modo": "diferencias", "motivo": "devolucion", "importe": 999}
modo | motivo | Cuándo |
|---|---|---|
diferencias | devolucion, concurso, incobrable | Devuelves todo o parte (importe en céntimos, IVA incluido; sin él, todo lo que queda), el cliente entra en concurso o la deuda es incobrable. |
sustitucion | error, error_iva | La factura tenía un error: mandas la factura correcta completa (cliente, lineas, iva_pct…, como al crear). |
completa | — | El cliente de una factura simplificada pide la completa: mandas su cliente con NIF, nombre y domicilio. |
Opcional: explicacion (sale en la factura) y enviar. La rectificativa lleva la misma operación que la original (exenta, inversión del sujeto pasivo, recargo de equivalencia, mención): en sustitución se ignoran operacion, exencion y recargo_equivalencia.
Avisos a tu web
Si la clave tiene una URL de avisos, te mandamos un POST cuando Hacienda responde sobre cada factura (con una clave de prueba, al momento y simulado):
{"id": "av_812", "evento": "factura.estado_aeat", "creado": 1794312000,
"datos": {"factura_id": 1532, "numero": "2026-0007", "referencia": "pedido-10045",
"estado": "registrada", "estado_aeat": "Registrada en la AEAT", "prueba": false}}
Responde con un 2xx. Si no, lo reintentamos durante un día. Comprueba la firma de la cabecera MiFactu-Firma: t=…,v1=… con el secreto de los avisos de tu clave: v1 es el HMAC-SHA256 en hexadecimal de t, un punto y el cuerpo tal cual llega. Rechaza los avisos con un t de hace más de 5 minutos.
# Python
import hashlib, hmac, time
def aviso_valido(cabecera, cuerpo: bytes, secreto: str) -> bool:
partes = dict(p.split("=", 1) for p in cabecera.split(","))
esperada = hmac.new(secreto.encode(), partes["t"].encode() + b"." + cuerpo, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, partes["v1"]) and abs(time.time() - int(partes["t"])) < 300
// PHP
function aviso_valido(string $cabecera, string $cuerpo, string $secreto): bool {
parse_str(str_replace(',', '&', $cabecera), $p);
$esperada = hash_hmac('sha256', $p['t'] . '.' . $cuerpo, $secreto);
return hash_equals($esperada, $p['v1']) && abs(time() - (int) $p['t']) < 300;
}
Errores
Con un código HTTP 4xx o 5xx y este formato:
{"error": {"tipo": "datos_no_validos", "mensaje": "NIF no válido", "campos": {"cliente.nif": "NIF no válido"}}}
400 datos_no_validos | Revisa campos. |
401 | Clave no válida o revocada. |
402 sin_suscripcion | La suscripción de la cuenta no está activa. |
403 facturacion_no_disponible | Falta la autorización de VERI*FACTU u otro requisito (lo dice mensaje). |
404 no_encontrada | No hay ninguna factura con ese id para esta clave. |
409 referencia_repetida | Esa referencia ya se facturó con otros datos. |
429 limite_mensual | Límite de facturas del mes de tu plan, o demasiadas peticiones por minuto (120): espera y reintenta. |
502 error_verifactu | No se pudo registrar: no se ha creado nada, puedes reintentar con la misma referencia. |
Límites
Incluida en tu plan, hasta 500 facturas reales al mes (las de prueba van aparte) y 120 peticiones por minuto por clave. Si necesitas más, escríbenos.
Las facturas las expide tu cuenta de MiFactu, con tus datos fiscales, como si las hicieras en la web: tú respondes de los datos que manda tu web. Guarda la clave como una contraseña: quien la tenga puede facturar en tu nombre. Si se ha podido ver, revócala en Perfil → API.