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[].
Las integraciones v1.0 existentes no necesitan enviar campos v1.1.

Los cambios incompatibles se publicaran en una nueva version publica.

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.

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.

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.

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.

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.

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.

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.