Desarrollo en Apex sobre REDA

El Apex personalizado alrededor de REDA Financials sigue una regla de oro: construir contra la superficie global y los objetos, nunca contra los internos. Aquí está el conjunto de herramientas estable y los patrones que lo aprovechan bien.

La superficie global — trece clases e interfaces

En un paquete gestionado, solo el código Apex global es visible para tu código; todo lo public vive detrás del muro del espacio de nombres (namespace). REDA Financials mantiene esa superficie admitida deliberadamente pequeña — trece tipos globales para el código de clientes y socios. Cinco son los puntos de entrada del día a día; el resto son los contratos de extensión de facturación electrónica y los tipos de datos que intercambian:

Los contratos de proveedor abstractos se explican en Paquetes de extensión; este artículo se enfoca en las dos clases que tú llamas. Todas las clases de la API se distribuyen en la versión de API 65.0, y aplica la promesa estándar de los paquetes gestionados: una vez publicadas, las firmas globales no pueden eliminarse ni cambiarse por debajo de ti — son el contrato estable.

Lo que no puedes llamar

La capa de servicio interna que hace el trabajo real — contabilización, importación de estados de cuenta bancarios, renderizado de PDF, llamadas de IA y de tipo de cambio, actualizaciones masivas de estado, carga inicial de impuestos — es public, no global. El código Apex del suscriptor no puede llamar estas clases en absoluto: el compilador simplemente no las ve del otro lado del límite de espacio de nombres, y su forma interna puede cambiar en cualquier versión. Si una capacidad que necesitas vive solo detrás de una clase pública, la vía admitida es el comportamiento que esa clase habilita — la contabilización mediante el campo de estado, la generación de PDF mediante refin.PDFGeneratorAPI, la carga inicial de impuestos mediante el Asistente de carga inicial de impuestos empaquetado — no la clase en sí.

refin.GlobalTaxService — el cálculo de impuestos como servicio

Dos métodos estáticos le dan a tu código los mismos motores que usan los documentos, sin efectos secundarios:

• calculateTax(TaxRequest) — impuesto indirecto (IVA/GST/impuesto sobre ventas). Aliméntalo con entidad, cuenta, fecha, lado ('Sales'/'Purchase') y líneas (importe + producto o perfil fiscal explícito, con tu propio lineKey para correlación); obtén de vuelta filas de impuesto por línea totalmente resueltas — tasa, importe, indicador de recuperabilidad, y la cuenta contable a la que se contabilizaría cada impuesto.
• calculateWithholdingTax(WHTRequest) — el motor de retención de impuestos, misma forma: líneas de entrada, retención por línea de salida (tasa, base, importe, motivos de exención, cuenta contable).
• El contrato: sin DML, sin registros creados, nunca lanza una excepción — los errores se devuelven como success=false con un mensaje. La persistencia es enteramente tuya: perfecto para cotizaciones, calculadoras, estimaciones previas a la contabilización o verificaciones de paridad con sistemas externos.

La referencia completa

Ambos puntos de entrada son estáticos:

global static TaxResponse calculateTax(TaxRequest request)
global static WHTResponse calculateWithholdingTax(WHTRequest request)

La documentación de la clase declara el contrato con claridad: "No se realiza DML. No se crean registros de Source_Line_Tax ni WHT_Transaction. El llamador es dueño de la persistencia y de la contabilización." Una respuesta "siempre se devuelve, nunca lanza una excepción al llamador" — los problemas de validación (entidad, cuenta, fecha, lado o líneas faltantes, o un valor de lado inválido) vuelven como success=false con la razón en errorMessage, en el mismo lenguaje de validación que usan los propios documentos. Existe una clase GlobalTaxServiceException en la superficie global, pero bajo el contrato normal lees la respuesta en lugar de capturarla.

Los DTO de solicitud y respuesta son clases globales con miembros globales — todo lo siguiente es tuyo para establecer o leer:

El conjunto de retención de impuestos lo refleja:

Cómo se resuelven las cuentas contables. Las cuentas contables de impuesto indirecto provienen de los registros de mapeo contable por tipo de impuesto (refin__Tax_Type_GL_Mapping__c): un mapeo específico de la entidad tiene prioridad sobre uno de toda la organización, indexado por tipo de impuesto y recuperabilidad para el lado de la solicitud; los impuestos incluidos además reciben una cuenta contable de deducción del lado 'Sales Deduction' / 'Purchase Deduction' del mapeo. Las cuentas contables de retención provienen de la cuenta contable en la Tasa de retención de impuestos coincidente, y por defecto usan la cuenta por pagar de retención predeterminada de la entidad. En otras palabras, la respuesta te indica no solo cuánto sino dónde aterrizaría — la misma resolución que realiza la contabilización.

Una llamada mínima, al estilo Meridian — la entidad de EE. UU. cotizando la línea de renta de un inquilino antes de que exista alguna factura:

refin.GlobalTaxService.TaxRequest req = new refin.GlobalTaxService.TaxRequest();
req.entityId = meridianUsEntityId;
req.accountId = brightlineAccountId;
req.transactionDate = Date.today();
req.side = 'Sales';

refin.GlobalTaxService.TaxLineRequest line = new refin.GlobalTaxService.TaxLineRequest();
line.lineKey = 'unit-4b-rent';
line.amount = 9000;
line.productId = officeRentProductId;
req.lines = new List<refin.GlobalTaxService.TaxLineRequest>{ line };

refin.GlobalTaxService.TaxResponse res = refin.GlobalTaxService.calculateTax(req);
if (res.success) {
    for (refin.GlobalTaxService.TaxResultLine t : res.lines) {
        System.debug(t.lineKey + ' -> rate ' + t.taxRate + ', tax ' + t.taxAmount
            + ', GL ' + t.glAccountId);
    }
} else {
    System.debug(res.errorMessage);
}

El gemelo de retención sigue el mismo ritmo. La entidad de India de Meridian, estimando el TDS sobre la factura de un contratista antes de registrarla: arma un WHTRequest con side = 'Purchase', un WHTLineRequest por línea de factura que lleva lineSubtotal, llama a calculateWithholdingTax, y lee cada WHTResultLine — rate, base, amount, y isExempt con su exemptReason cuando un certificado o umbral exime la línea. Como nada se persiste, el equipo de cuentas por pagar puede cotizar el neto a pagar al proveedor y las cifras coincidirán con el documento contabilizado hasta el último centavo.

refin.PDFGeneratorAPI — documentos desde código

generateOne(sourceRecordId, sourceObjectApiName) renderiza y adjunta el PDF de una Factura de venta, Nota de crédito, Recibo de caja, Comprobante de egreso u Orden de compra contabilizados — devolviendo los IDs de contenido y, donde el territorio habilita enlaces públicos, la URL. El gemelo en Flow se explica en Flows Integration.

La firma:

global static PDFResult generateOne(Id sourceRecordId, String sourceObjectApiName)

En las propias palabras de la clase, "Los paquetes de extensión llaman a esto desde Apex cuando necesitan generación programática de PDF fuera del contexto de Flow." El sourceObjectApiName debe ser uno de los objetos de origen admitidos:

El PDF resultante se adjunta al registro de origen como un ContentVersion con un ContentDocumentLink — un Archivo estándar de Salesforce que puedes consultar, compartir o enviar por correo. El publicUrl del resultado solo se completa "si la Entidad tiene habilitado Auto Public URL; nulo en caso contrario" — así que el código que envía enlaces por correo a clientes debe verificar si es nulo en lugar de asumir que existe una URL. Y es posible que ni siquiera necesites código: cada entidad lleva interruptores de generación automática por tipo de documento (refin__Auto_Gen_PDF_Sales_Invoice__c, refin__Auto_Gen_PDF_Cash_Receipt__c, refin__Auto_Gen_PDF_Cash_Disbursement__c, refin__Auto_Gen_PDF_Purchase_Order__c, refin__Auto_Gen_PDF_Credit_Memo__c) — generateOne es para los momentos fuera de esos, como regenerar bajo demanda o adjuntar a un envío personalizado.

Contabilizar desde Apex — el campo de estado es la API

No existe un método post() para llamar, por diseño: el motor de contabilización se ejecuta en la fase de trigger de la propia actualización del objeto de origen. Tu código Apex contabiliza un documento de la misma forma que lo hace un usuario — cambia refin__Status__c de 'Draft' a 'Posted' con una actualización de DML, y se ejecuta toda la maquinaria: los motores de impuestos y de retención, el marcado del tipo de cambio en la transición a Contabilizado, y todos los guardianes (control de aprobación, validación de período, bloqueos de entidad/cuenta contable inactiva). Una contabilización rechazada se manifiesta como una excepción de DML que lleva el mensaje exacto del guardián — trátala como el contrato de la API, no como ruido.

El patrón de creación confiable son dos pasos: insertar como Borrador (encabezado y líneas), y luego actualizar el estado a 'Posted' en una segunda llamada. Al insertar, un estado nulo toma por defecto 'Draft', los números de documento se asignan automáticamente desde la secuencia de documentos de la entidad (predefinir el Name implica numeración manual, y se valida la unicidad), y los valores predeterminados de la entidad se completan automáticamente — libro mayor, período contable y fecha de vencimiento a partir de la condición de pago del proveedor. Ten en cuenta que cambiar la entidad o el tipo de factura en un Borrador reasigna su número, así que haz tus ediciones antes de contabilizar.

Reaccionar a eventos contables

Tus triggers y Flows disparados por registro sobre objetos refin__ coexisten sin problema con los del propio paquete (el orden entre paquetes y la automatización de la organización sigue las reglas estándar de la plataforma — mantén los tuyos idempotentes). El patrón de mayor valor: reaccionar a las transiciones de estado — un trigger en Factura de venta que detecta Draft→Posted puede alimentar tu sistema descendente con el documento ya completamente validado y numerado. Reacciona después del trabajo del paquete: lee el estado final del registro en lugar de intentar interponerte.

Las reglas que te mantienen a salvo en las actualizaciones

Errores comunes que evitar

Qué sigue

1. Paquetes de extensión — los contratos de proveedor para ISV.
2. Lightning Web Components — la contraparte de interfaz.
3. Descripción general de la API — el mapa general.

Preguntas frecuentes