¿Cómo se transfieren los datos de inspección a ERP y contabilidad sin duplicar registros?

Respuesta breve: ¿cómo se evita el registro duplicado?

Dé a cada trabajo de inspección una identidad de origen invariable; ejecute la transferencia a ERP de forma idempotente con esa identidad, fuerce la unicidad en la base de datos y vincule a contabilidad solo el documento de destino verificado.

Que una integración funcione en el flujo normal no basta. También cuando se pierde la respuesta de red, cuando el mensaje de la cola llega repetido o cuando dos workers toman el mismo trabajo, el resultado debe ser un único cliente, un único pedido y un único vínculo de facturación.

¿Por qué se produce el registro duplicado?

Respuesta breve: la mayoría de los duplicados no se debe a que el usuario pulse dos veces el botón, sino a un reintento incontrolado hecho en el momento ambiguo en que la primera petición tuvo éxito pero se perdió su respuesta.

El sistema de inspección envía a ERP la petición de apertura de pedido. ERP crea el registro, pero la conexión se cierra y la integración no recibe respuesta. Si el worker reenvía la misma petición como si fuera nueva, puede abrirse un segundo pedido. Un riesgo similar se da con la entrega al menos una vez en colas, workers en paralelo, la repetición manual tras un tiempo de espera agotado y la sincronización por lotes.

IETF RFC 9110 define la operación idempotente como aquella en que aplicar la misma petición varias veces tiene el efecto pretendido de una sola aplicación. PUT tiene esta propiedad; la creación de recursos con POST debe protegerse además. El diseño técnico no debe suponer que la red entrega exactamente una vez.

¿Qué identidad debe ser la titular del registro?

El trabajo de inspección, el pedido de ERP, el asiento contable y el documento electrónico no son la misma identidad. Al inicio de la cadena debe existir un UUID del trabajo de origen invariable; las identidades generadas por los demás sistemas deben guardarse en campos separados como equivalentes.

OASIS UBL 2.4 Invoice define campos de referencia entre la factura y el pedido y otros documentos. La guía del Portal e-Fatura de la GİB también indica que las facturas con el mismo UUID y número de factura no pueden cargarse de nuevo. La consecuencia práctica es no sustituir la identidad del trabajo de inspección por el número del documento electrónico, sino mantener las identidades separadas en una tabla de correspondencia bidireccional.

¿Cómo debe generarse la idempotency key?

La clave no debe regenerarse aleatoriamente en cada reintento; debe permanecer igual en todos los intentos del mismo efecto comercial. Un alcance ejemplo puede derivarse de la combinación canónica de las piezas siguientes:

tenant + hedef_sistem + işlem_türü + kaynak_iş_uuid + kaynak_sürümü

La versión de origen importa. Reenviar la misma versión del informe debe devolver el resultado existente; si la revisión autorizada va a crear un nuevo efecto comercial, debe ser un evento aparte con una regla de negocio explícita. El registro de idempotencia debe conservar junto a la clave el resumen del payload, la hora de primera aparición, el estado y la identidad de la respuesta de destino.

La referencia vigente de la API de Stripe documenta que tras un fallo de conexión la petición create/update puede repetirse con seguridad con la misma idempotency key, y que si la clave es la misma pero cambian los parámetros, la petición se rechaza. Este comportamiento específico del proveedor también es un ejemplo de contrato útil para el adaptador ERP interno: si llega la misma clave con un cliente, importe o equivalencia tributaria distintos, no la sobrescriba silenciosamente; someta el conflicto a revisión.

¿Por qué no basta el control en la aplicación?

En el enfoque “consulta primero si existe, si no, inserta”, dos workers pueden ver a la vez el resultado de que no existe. La unicidad debe forzarse también en la base de datos.

Establezca en la tabla de correspondencia de la integración una tenant_id + target_system + document_type + source_job_uuid unique constraint compuesto. La documentación vigente de INSERT de PostgreSQL indica que con una unique constraint ON CONFLICT explica que su uso puede producir, bajo carrera, un resultado de insert/update atómico. Si su regla de negocio no permite la actualización, devuelva el ID de destino existente en caso de conflicto; si los datos difieren, abra un registro de revisión fail-closed.

UNIQUE (tenant_id, target_system, document_type, source_job_uuid)

aynı anahtar + aynı payload özeti  -> mevcut sonucu döndür
aynı anahtar + farklı payload       -> çakışma, otomatik belge açma

¿Cómo debe configurarse el flujo de outbox y de colas?

Marcar el informe de inspección como “listo para facturar” y escribir por separado el mensaje del ERP puede generar estados a medias. El estado del trabajo y el evento de integración deben confirmarse en la misma transacción local.

1. El usuario autorizado aprueba la versión del informe y el alcance de facturación.
2. La aplicación, dentro de la misma transacción, actualiza el estado del trabajo e inserta una fila de outbox con el UUID del evento.
3. El worker envía el evento del outbox al adaptador de destino con una idempotency key fija.
4. En una respuesta exitosa, el ID de destino del ERP y un resumen de la respuesta se guardan en la tabla de enlace.
5. Si se pierde el ACK, el mismo evento llega de nuevo; el consumidor ve el enlace del trabajo por el UUID del evento y devuelve el resultado existente.
6. Un error de datos permanente no entra en un bucle de reintentos; se deriva a una cola de revisión o de mensajes muertos.

La guía de Transactional Outbox de Microsoft recomienda almacenar el objeto de negocio y el evento en la misma transacción; la guía de Service Bus recomienda que el consumidor sea idempotente mediante el MessageId o una identidad de negocio, dado que pueden perderse ACK y haber reentregas. La detección de duplicados del lado del emisor no sustituye al control de unicidad del receptor.

¿Cómo se hace de forma segura la asignación de clientes, servicios e impuestos?

Evitar el registro duplicado no es solo un problema técnico de reintentos. Abrir de nuevo al mismo cliente con otra grafía de la razón social o facturar el mismo servicio con un código distinto también genera duplicación operativa.

• Cliente: vincúlelo con el VKN/TCKN verificado en el ámbito del tenant o con la clave maestra de la institución; no use la razón social por sí sola como clave.
• Servicio: conecte el método de inspección a la tabla aprobada de códigos de stock/servicio del ERP; no abra automáticamente códigos sin correspondencia como texto libre.
• Impuestos y moneda: aplique una asignación versionada a la lista de códigos del sistema de destino; ante una asignación ausente o inválida, detenga la generación del documento.
• Importe: fije las líneas calculadas, los descuentos y el impuesto con el resumen de la versión de origen; tras la aprobación, lleve cualquier cambio a un nuevo flujo de revisión.
• Autoridad: gestione por separado, con pistas de auditoría propias, los roles de creación de clientes, modificación de asignaciones y generación de documentos financieros.

Una correspondencia ambigua no debe “elegir el resultado más parecido”. La transferencia debe esperar hasta que se complete la revisión humana; de la decisión tomada deben registrarse quién, cuándo, el valor anterior/nuevo y la justificación.

¿Cómo debe monitorearse el estado de la transferencia?

Un único campo “exitoso/fallido” oculta ambigüedad. La máquina de estados debe indicar qué paso puede repetirse.

Eliminar el registro de transferencia exitosa y reenviar no es un método de corrección. Si ya se emitió el documento financiero, la anulación, devolución o reversión debe ejecutarse con su propia identidad y flujo de aprobación.

¿Qué controles debe realizar la conciliación?

La conciliación diaria debe comparar los registros de origen y de destino a nivel de identidad, no limitarse a contar el registro de errores.

• Trabajos listos para facturar sin enlace de destino.
• Varios documentos de destino enlazados al mismo UUID de trabajo de origen.
• Documentos presentes en el destino sin contrapartida en la tabla de enlaces de origen.
• Registros cuyo resumen del payload enviado no coincide con la versión de origen.
• Intentos que permanecen en estado ambiguo más tiempo del definido.
• Asignaciones manuales, anulaciones y reversiones con falta de aprobación o prueba.

El resultado de la conciliación no debe eliminar automáticamente ni fusionar en lote. Debe mostrar al usuario autorizado los registros sospechosos, sus identidades en ambos sistemas y la operación segura propuesta.

¿Cómo pilotar la integración de VizyonTech?

Vizyon Periyodik En el paso de los flujos de inspección, como los de Vizyon Muayene, hacia el ERP, pruebe los escenarios de error antes del escenario normal. Deben probarse: doble clic sobre el mismo trabajo, el ERP que crea el registro pero no responde, el mismo mensaje de cola entregado a dos workers, la misma clave con distinto payload, una asignación de cliente inválida y la revisión del informe.

El criterio de éxito del piloto no es “la integración funcionó”. En cada escenario debe demostrarse cuántos registros se crearon en el destino, si se estableció el enlace origen-destino, si el reintento devolvió el mismo resultado, si la ambigüedad permaneció visible y si se bloqueó la operación financiera no autorizada. Para proteger la cadena de decisión del informe de inspección, la guía del flujo de trabajo de firma electrónica también puede evaluarse conjuntamente.