Versionado
La version publica actual es v1.
text
https://api.factulit.es/api/v1
https://api.sandbox-factulit.es/api/v1El versionado es comun a los dos entornos: ambos sirven la misma version v1 y el mismo contrato de pedidos.
Factulit mantiene v1 compatible para integraciones server-side existentes. Se pueden anadir campos cuando no rompen payloads existentes.
Contrato de pedidos
Los pedidos soportan contract_version.
- Si
contract_versionno se envia, se interpreta como1.0. 1.1anade campos fiscales y de conciliacion opcionales.1.3anadecorrection_events[]explicitos.1.4anadetags[]opcional como hechos del origen para reglas configuradas por la cuenta.1.5anade metadatos temporales opcionales y la fecha de cobropaid_at.1.6anadebuyer_roleopcional como hecho declarado del comprador.1.7anadeid_external_variationopcional para identificar la variacion exacta de una linea.1.8anadekindopcional endiscounts[]yunmapped_totals[].1.9fija como se leen las fechas sin zona horaria y anadesource_timezoneopcional.- Las integraciones v1.0 existentes no necesitan enviar campos v1.1.
Los cambios incompatibles se publicaran en una nueva version publica.
v1.4 (aditivo, retrocompatible)
- Los pedidos pueden enviar hasta 100
tags, con 255 caracteres por valor. - Omitir
tagsen una actualizacion conserva la lista;tags: []la vacia. - Las etiquetas nunca ordenan facturar o cancelar. El propietario configura reglas ordenadas en Factulit y los reembolsos/correcciones explicitos conservan prioridad.
v1.9 (aditivo, retrocompatible)
- Una fecha con zona horaria (
Z,+02:00) es un instante; es la forma recomendada. La zona del negocio no la cambia. - Una fecha sin zona se lee como hora local: primero en la zona del negocio configurada en Factulit, despues en
source_timezoney por ultimo en UTC. Los payloads anteriores a 1.9 la siguen leyendo en UTC. source_timezonees una zona IANA (Europe/Madrid). Cualquier otro valor se ignora sin rechazar el pedido.- Factulit decide el dia de la operacion en la zona del negocio. Un pedido ya facturado conserva sus fechas si una nueva lectura solo difiere en la zona. Ver Pedidos.
v1.8 (aditivo, retrocompatible)
discounts[]yunmapped_totals[]aceptankindcon los valorespromotional,customer_credit,gift_card,loyaltyounknown. Un valor fuera de esa lista se descarta.kindes una comodidad, no el unico camino: una regla configurada por el titular sobre elcodede la fila prevalece sobre la etiqueta del conector.unmapped_totals[]exigecodeestable en minusculas; sin el, la fila se descarta.
v1.7 (aditivo, retrocompatible)
- Las lineas de
breakdown[]y decorrection_events[].lines[]aceptanid_external_variation, la variacion exacta vendida. Se deja vacio en productos simples. - La variacion entra en las huellas de version y de decision fiscal: cambiarla invalida una decision previa aunque el total no varie.
v1.6 (aditivo, retrocompatible)
buyer_role(consumer,businessounknown) declara el rol del destinatario en esa compra. Es un hecho neutral, no una orden fiscal: su ausencia equivale aunknowny nunca amplia por si sola el umbral de la factura simplificada.
v1.5 (aditivo, retrocompatible)
- Metadatos temporales opcionales (
source_updated_at,source_event_id,source_event_occurred_at,mapper_version,sync_scope) para ordenar el historico. Su ausencia nunca impide sincronizar. paid_atdeclara la fecha de cobro.
Registro de cambios
v1 facturas directas programadas (1.10, aditivo, retrocompatible) (2026-11-05)
POST /invoiceacepta los opcionalesscheduled_issue_date,scheduled_issue_timeysend_to_customer. Con fecha programada responde202y un borrador sin numero, que se emite ese dia con las mismas guardas que el panel. Requiere plan Pro o Premium vigente.GET /invoice/{external_id}informascheduled,issued,failedocancelled, yscheduled_error_codesi falla. No hay webhook.PUT /invoice/{external_id}actualiza, reprograma, cancela o adelanta (issue_now) una programada; las emitidas siguen inmutables (409).- No cambia el
contract_versionde los pedidos. Ver Facturas.
v1 description de la factura directa: 120 caracteres (2026-10-19)
POST /invoiceadmite hasta 120 caracteres endescription, la longitud que se declara a la AEAT como descripcion de la operacion. El limite documentado de 500 inducia a error: a la AEAT solo llegaban los 120 primeros. Un valor mas largo devuelve ahora422.- Antes de guardar y declarar la descripcion se quitan saltos de linea, caracteres de control, emojis y otros simbolos que no son texto. Una descripcion sin texto util devuelve
422. Ladescriptionde cada linea conserva su limite de 500 caracteres y la misma limpieza.
v1 emision directa de facturas (aditivo, retrocompatible)
- Las conexiones API con consentimiento explicito para facturar con VeriFactu pueden usar
POST /invoicepara emitir atomicamente una factura numerada y su registroALTA. external_idaporta idempotencia por conexion;GET /invoice/{external_id}recupera el resultado yPUTse rechaza porque una factura emitida es inmutable.- Las operaciones existentes de clientes, estados, pedidos y claves no cambian.
v1.1 (aditivo, retrocompatible)
invoice_actionincorpora el valorexchange_to_full, que solicita el canje de una factura simplificada (F2) ya emitida por una factura completa (F3) cuando el cliente aporta su identificacion fiscal. Ver Ciclo fiscal.- Se anade
original_order_reference(opcional, hasta 64 caracteres) a nivel de pedido para referenciar el pedido original cuando el canje F3 llega como un pedido distinto en lugar de una actualizacion. breakdown[].regimequeda documentado con la lista completa de claves de regimen VeriFactu (ClaveRegimen). El nucleo respeta siempre unregimeexplicito; solo lo deriva automaticamente cuando la linea no lo trae o envia el generico01.
Estos campos son opcionales y no cambian el comportamiento de las integraciones v1.0 o v1.1 existentes que los omitan.