Saltar al contenido

Versionado ​

La version publica actual es v1.

text
https://api.factulit.es/api/v1
https://api.sandbox-factulit.es/api/v1

El 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_version no se envia, se interpreta como 1.0.
  • 1.1 anade campos fiscales y de conciliacion opcionales.
  • 1.3 anade correction_events[] explicitos.
  • 1.4 anade tags[] opcional como hechos del origen para reglas configuradas por la cuenta.
  • 1.5 anade metadatos temporales opcionales y la fecha de cobro paid_at.
  • 1.6 anade buyer_role opcional como hecho declarado del comprador.
  • 1.7 anade id_external_variation opcional para identificar la variacion exacta de una linea.
  • 1.8 anade kind opcional en discounts[] y unmapped_totals[].
  • 1.9 fija como se leen las fechas sin zona horaria y anade source_timezone opcional.
  • 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 tags en 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_timezone y por ultimo en UTC. Los payloads anteriores a 1.9 la siguen leyendo en UTC.
  • source_timezone es 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[] y unmapped_totals[] aceptan kind con los valores promotional, customer_credit, gift_card, loyalty o unknown. Un valor fuera de esa lista se descarta.
  • kind es una comodidad, no el unico camino: una regla configurada por el titular sobre el code de la fila prevalece sobre la etiqueta del conector.
  • unmapped_totals[] exige code estable en minusculas; sin el, la fila se descarta.

v1.7 (aditivo, retrocompatible) ​

  • Las lineas de breakdown[] y de correction_events[].lines[] aceptan id_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, business o unknown) declara el rol del destinatario en esa compra. Es un hecho neutral, no una orden fiscal: su ausencia equivale a unknown y 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_at declara la fecha de cobro.

Registro de cambios ​

v1 facturas directas programadas (1.10, aditivo, retrocompatible) (2026-11-05) ​

  • POST /invoice acepta los opcionales scheduled_issue_date, scheduled_issue_time y send_to_customer. Con fecha programada responde 202 y 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} informa scheduled, issued, failed o cancelled, y scheduled_error_code si 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_version de los pedidos. Ver Facturas.

v1 description de la factura directa: 120 caracteres (2026-10-19) ​

  • POST /invoice admite hasta 120 caracteres en description, 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 ahora 422.
  • 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. La description de 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 /invoice para emitir atomicamente una factura numerada y su registro ALTA.
  • external_id aporta idempotencia por conexion; GET /invoice/{external_id} recupera el resultado y PUT se rechaza porque una factura emitida es inmutable.
  • Las operaciones existentes de clientes, estados, pedidos y claves no cambian.

v1.1 (aditivo, retrocompatible) ​

  • invoice_action incorpora el valor exchange_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[].regime queda documentado con la lista completa de claves de regimen VeriFactu (ClaveRegimen). El nucleo respeta siempre un regime explicito; solo lo deriva automaticamente cuando la linea no lo trae o envia el generico 01.

Estos campos son opcionales y no cambian el comportamiento de las integraciones v1.0 o v1.1 existentes que los omitan.

Documentacion publica de la API de Factulit.