API y persistencia documental

WowConta! ofrece contratos públicos para que las extensiones trabajen con documentos y partidas sin depender de su almacenamiento físico.

La integración debe utilizar identidades y operaciones de dominio, en lugar de resolver la persistencia documental mediante nombres de tablas, columnas, prefijos o consultas propias sobre el almacenamiento del núcleo.

Los ejemplos de esta guía son fragmentos para código ejecutado dentro de WordPress, con WowConta! cargado. No constituyen por sí solos un proceso completo de expedición.

Puntos de entrada públicos

• Wowc_IdFactura: identidad documental, con serie, número y condiciones de proforma y rectificativa.
• Wowc_Factura: representación de la factura, carga de cabecera y partidas, datos públicos y cálculos documentales.
• Wowc_Partida: representación de una partida y construcción de copias comerciales o fiscales.
• Wowc_Facturacion: capacidades, diagnósticos, consultas funcionales, fábricas de unidades y contratos fiscales.
• Wowc_Unidad_Trabajo: coordinación de la persistencia de una nueva factura definitiva y de las operaciones participantes.
• Wowc_Unidad_Entrega: coordinación de persistencia propia de extensiones para operaciones posteriores.

Guardar un objeto fuera de una unidad coordinada no hace que otras escrituras participen automáticamente en su transacción.

Consultar capacidades

Las capacidades se consultan mediante:

• Wowc_Facturacion::capacidades().
• Wowc_Facturacion::diagnostico().
• Wowc_Facturacion::capacidades_requeridas().

El diagnóstico devuelve capacidades y errores funcionales. La lista de capacidades requeridas permite comprobar qué garantías necesita la unidad de trabajo documental.

$diagnostico = Wowc_Facturacion::diagnostico();
$faltantes   = array();

foreach ( Wowc_Facturacion::capacidades_requeridas() as $capacidad ) {
    if ( empty( $diagnostico['capacidades'][ $capacidad ] ) ) {
        $faltantes[] = $capacidad;
    }
}

Si $faltantes no está vacío, la integración no debe tratar la operación coordinada como disponible. La fábrica de la unidad realiza sus propias comprobaciones y puede devolver WP_Error aunque exista un diagnóstico previo favorable.

Entre las capacidades requeridas están las transacciones, las identidades documentales únicas, la numeración segura, los bloqueos coordinados, los snapshots completos, las copias fiscales exactas y la persistencia de perfiles SIF.

Para persistencia propia de una extensión existen también diagnostico_tablas_extension() y diagnostico_perfiles_fiscales_sif(). Cuando una extensión incorpora almacenamiento propio a una unidad, debe declararlo en el plan.

Un diagnóstico favorable expresa capacidades comprobadas para ese contexto. No acredita la conformidad fiscal del conjunto ni garantiza que la conexión permanezca inalterada durante una ejecución posterior.

Consultas y edición de proformas

Las consultas funcionales incluyen:

• seleccionar_proformas().
• buscar_partidas_por_referencia().
• referencia_mas_reciente().
• cargar_proforma_versionada().

Debe respetarse el contrato de retorno de cada método:

• Una lista vacía representa una consulta correcta sin coincidencias.
• null representa ausencia cuando el método lo contempla.
• WP_Error representa un fallo y no debe convertirse en ausencia.

referencia_mas_reciente() devuelve una referencia comercial según su ordenación, no la fecha de la última importación.

La edición coordinada utiliza unidad_edicion() y su diagnóstico específico, diagnostico_edicion(). La revisión de una proforma representa su contenido; no es un contador de eventos, una firma ni una prueba de inmutabilidad.

La capacidad de edición coordinada se limita a esa API y a los participantes de su protocolo. No implica que todas las rutas de escritura documental estén protegidas.

Preparar una unidad de trabajo

Wowc_Facturacion::unidad_de_trabajo() recibe un plan que declara:

• La identidad completa de la proforma de origen.
• La serie de destino.
• La condición de rectificativa del documento de destino.
• Los recursos adicionales de las extensiones participantes.
• El almacenamiento propio de las extensiones que debe participar.

En el siguiente ejemplo, $origen es un Wowc_IdFactura validado que identifica una proforma existente. $serie_destino y $rectificativa proceden de la configuración y de la operación validada.

$unidad = Wowc_Facturacion::unidad_de_trabajo(
    array(
        'origen'        => $origen,
        'serie'         => $serie_destino,
        'rectificativa' => $rectificativa,
    )
);

if ( is_wp_error( $unidad ) ) {
    return $unidad;
}

Preparar la unidad no expide una factura. Las operaciones se realizan mediante ejecutar(), cuyo callback recibe la unidad activa.

Dentro de ese callback están disponibles, entre otras:

• cargar_origen(): relee la proforma bajo la protección de la unidad.
• asignar_numeracion(): asigna el número de una factura definitiva nueva.
• guardar_factura(): inserta la factura nueva numerada por la unidad.
• guardar_partida(): inserta partidas nuevas para una factura creada por la unidad.
• confirmar_y_copiar_perfil_fiscal_sif_a_factura(): confirma el perfil fiscal y lo copia al destino dentro de la operación coordinada.

El perfil se construye desde la proforma releída y sus datos fiscales mediante construir_perfil_fiscal_sif_proforma(). La confirmación directa mediante guardar_perfil_fiscal_sif_confirmado() está rechazada y no sustituye la confirmación coordinada.

La integración debe comprobar cada resultado y devolver WP_Error ante un fallo. No debe ignorar errores y continuar con las escrituras siguientes.

Numeración y copias de partidas

El número 0 solo sirve como solicitud temporal de numeración para una factura definitiva nueva. No es un número válido de factura expedida ni debe aceptarse como número definitivo procedente del navegador.

La asignación se realiza mediante la operación coordinada. Una extensión no debe calcular por su cuenta el siguiente número.

Las dos APIs de copia de partidas tienen finalidades distintas:

• crear_copia_para_factura() crea una partida para reutilización comercial y deja sin completar el contrato, los periodos y la referencia de la nueva operación.
• crear_copia_fiscal_para_factura() conserva esos datos junto con el contenido comercial y fiscal para una factura definitiva nueva con identidad completa.

Ambas construyen una partida nueva todavía no persistida. La copia fiscal no reutiliza la operación ni la identidad del origen y no modifica la partida original. Un destino fiscal incompleto o que siga siendo proforma provoca InvalidArgumentException.

Condiciones de las garantías

Las unidades verifican las condiciones de persistencia y coordinación antes y durante las operaciones. Sus garantías requieren:

• Almacenamiento participante apto para transacciones.
• Identidades documentales únicas y numeración coordinada.
• Recursos declarados antes de ejecutar el callback.
• Continuidad verificable de la conexión y de la sesión.
• Conservación de la transacción y de los bloqueos coordinados.
• Uso de las operaciones públicas de la unidad para las escrituras documentales.
• Uso de conexion() para las escrituras propias de las extensiones participantes.

Las escrituras propias relevantes deben pasar por verificar_escritura(), con el número exacto de filas esperado. La acreditación mediante acreditar_extension() vincula al proveedor con la conexión, los requisitos y la ejecución activa; no es un permiso reutilizable fuera del callback.

No deben ejecutarse cambios de esquema, límites transaccionales externos, cambios de sesión ni manipulaciones de los bloqueos coordinados. Tampoco deben abrirse unidades anidadas.

Estas garantías cubren a los participantes que respetan el protocolo. No constituyen una barrera frente a código o escritores externos que actúen al margen de él. Las operaciones de red, la firma y otros efectos externos no se revierten mediante una transacción de base de datos.

Confirmación, rechazo e incertidumbre

La integración debe distinguir:

1. Confirmación conocida: la unidad ha verificado la confirmación de su transacción.
2. Rechazo o fallo con resultado resuelto: la operación no llegó a escribir o su reversión pudo acreditarse.
3. Resultado incierto: no puede establecerse con seguridad el resultado de la confirmación, la reversión o la limpieza, o existe posibilidad de una confirmación externa.

Wowc_Unidad_Trabajo::ejecutar() devuelve el valor del callback cuando termina correctamente o WP_Error ante un fallo. Un error de limpieza puede producirse después de una confirmación conocida: recibir un error no demuestra que no haya datos persistidos.

Deben revisarse el código y los datos del error, incluidas las indicaciones de confirmación conocida, confirmación indeterminada o confirmación externa posible cuando estén presentes.

Wowc_Unidad_Entrega::ejecutar() devuelve un resultado estructurado con exito, confirmada, valor, error e indicadores de incertidumbre. No debe interpretarse como si tuviera el mismo formato de retorno que la unidad de trabajo documental.

Ante incertidumbre:

1. Detener la repetición automática.
2. Aislar la conexión afectada.
3. Conciliar los documentos y efectos persistidos desde otra sesión sana.
4. Resolver el estado anterior antes de decidir una nueva operación.

Una nueva unidad, una consulta satisfactoria o un intento de reversión posterior no demuestran por sí solos que la operación original no se haya confirmado.

Snapshot fiscal

snapshot_fiscal() proporciona una estructura documental versionada con identidad completa, cabecera, partidas ordenadas, desglose de IVA e importes.

Requiere una factura cargada con una carga completa y satisfactoria de sus partidas. Una factura con cero partidas no es lo mismo que un fallo al cargarlas.

Para consumidores SIF, la vía ordinaria es:

$snapshot = Wowc_Facturacion::snapshot_fiscal_sif( $factura );

if ( is_wp_error( $snapshot ) ) {
    return $snapshot;
}

$validacion = Wowc_Facturacion::validar_snapshot_fiscal_sif( $snapshot );

if ( is_wp_error( $validacion ) ) {
    return $validacion;
}

$factura debe estar cargada completamente y disponer del perfil fiscal confirmado. El perfil se obtiene desde la conexión de esa factura y con su identidad completa.

El segundo argumento opcional de snapshot_fiscal_sif() no es una vía de confirmación o expedición y no debe utilizarse para sustituir ese flujo.

Importes del snapshot SIF v3

El snapshot SIF v3 separa la clasificación fiscal confirmada de las sugerencias comerciales. Sus importes monetarios se expresan en céntimos enteros de euro:

• cuota_total: IVA, sin recargo de equivalencia.
• cuota_recargo_equivalencia: recargo separado dentro del desglose.
• importe_total: base, IVA y recargo, antes de retención.
• importe_retencion: retención separada.

Los proveedores deben respetar esta semántica al proyectar los datos a otros formatos. No deben suponer que un campo XML con un nombre parecido tiene exactamente el mismo significado.

Obtener o copiar un perfil confirmado no vuelve a calcularlo como si fuera una clasificación nueva. Un perfil incoherente produce un error de validación; no se repara silenciosamente.

Separación respecto a firma, XML y remisión

El snapshot es un contrato de datos fiscales. Su validación comprueba ese contrato, no una firma, un XML o una respuesta de remisión.

La generación de registros, su proyección XML, la firma cuando proceda y la remisión pertenecen a los componentes adicionales. Deben vincular sus resultados al documento y al snapshot correctos y validar su propia parte de la integración.

La persistencia confirmada y el snapshot válido no acreditan por sí solos la conformidad SIF del conjunto.

Documentación relacionada

• Índice de documentación
• Firmas y extensiones