API REST vs web service SOAP del RNDC

SOAP es un protocolo más antiguo: define un único mensaje de entrada y salida, con una estructura XML fija que hay que respetar al milímetro. El RNDC usa ese modelo: un solo endpoint, una sola operación, y un campo (procesoid) que decide qué documento estás enviando dentro del mismo mensaje.

REST, en cambio, organiza la integración por recursos: una ruta para remesas, otra para manifiestos, y el cuerpo va en JSON, un formato más fácil de leer y de generar desde cualquier lenguaje moderno. Fassiltrans ofrece esa capa REST encima del SOAP del Ministerio: tu sistema habla JSON con nosotros, y nosotros hablamos SOAP con el RNDC.

En la práctica, eso cambia quién arma el mensaje y quién lo valida. Con SOAP, tu equipo tiene que construir el XML a mano: respetar el orden de las etiquetas, enviar el procesoid correcto para cada tipo de documento y revisar que ningún campo quede fuera, aunque vaya vacío. Con una API REST, esas reglas ya están escritas una sola vez, en un lugar, y tu equipo solo manda los datos que ya tiene en su sistema.

Si quieres el detalle completo del web service del Ministerio —la URL, los procesoid de cada documento y las reglas que más rompen una integración— ya lo cubrimos en la guía del web service del RNDC. Aquí nos concentramos en la comparación con REST.

Del lado del RNDC, cada campo tiene un nombre fijo en mayúsculas, como FECHACITAPACTADACARGUE o MERCANCIAREMESA, y van dentro de la etiqueta variables, hermana de solicitud dentro del mismo sobre SOAP. Del lado de Fassiltrans, ese mismo dato se llama fecha_cargue o mercancia_codigo, en minúsculas y con una fecha en formato ISO (2026-10-01) en lugar de 01/10/2026.

Mira los dos fragmentos en las dos pestañas. Son el mismo dato, la misma remesa, escrita de dos maneras distintas:

Tu equipo nunca escribe el XML de la pestaña SOAP. Envía el JSON de la pestaña REST, con nombres legibles y fechas en el formato que ya usa tu sistema, y la API se encarga de armar el sobre SOAP, poner el procesoid correcto y convertir cada fecha a dd/MM/yyyy antes de que llegue al Ministerio.

Cuando integras directo contra el web service, los errores llegan como códigos cortos del RNDC. No siempre dicen qué campo falló ni por qué; tu equipo tiene que mantener una tabla propia para traducirlos y decidir si el error se puede corregir y reenviar, o si hay que avisarle a alguien.

Con la API de Fassiltrans, la mayoría de los errores se detectan antes de llegar al Ministerio: validamos los campos obligatorios, el formato de fecha y el código de mercancía, y si algo no cumple, la respuesta trae el nombre del campo y un mensaje en español que tu equipo entiende sin buscar una tabla de códigos.

Para ayudar a evitar que un reenvío duplique un documento, puedes enviar tu referencia_externa para identificar cada documento. Así tu sistema puede reintentar cuando no está seguro de si el primer envío llegó, con menos riesgo de reportar la misma remesa dos veces.

El web service del Ministerio no avisa solo: si tu equipo quiere saber si una remesa cambió de estado, tiene que volver a consultar el RNDC con el tipo=3, una y otra vez, para no perderse un cambio.

Con webhooks, el flujo se invierte: Fassiltrans le envía un aviso a una URL de tu sistema cada vez que el RNDC acepta un documento, lo rechaza o registra el cumplido. Tu equipo deja de preguntar «¿ya cambió?» y simplemente reacciona cuando le llega la notificación, con menos llamadas y menos código de consulta que mantener.

Una skill es un paquete de instrucciones y ejemplos que un asistente de código carga antes de trabajar con una herramienta concreta. En lugar de que tu desarrollador le explique a mano cómo es cada endpoint, cada campo y cada mensaje de error de la API, el asistente ya lo tiene: la skill trae los esquemas de remesas y manifiestos, los errores más comunes y ejemplos de código.

Eso sí: la skill no reemplaza la revisión humana. El asistente propone código, prueba contra el sandbox y ajusta según los errores que recibe, pero tu desarrollador sigue siendo quien revisa y aprueba lo que se conecta a producción. Tampoco tiene tus credenciales: esas siguen guardadas y cifradas en Fassiltrans, nunca en manos del asistente.

Con esa combinación, escribir el cliente REST para tu ERP o TMS deja de ser un proyecto de semanas y se convierte en una sesión guiada entre tu equipo y su asistente de código. Puedes leer más sobre el alcance completo de la API RNDC para empresas de Fassiltrans.

Construir la integración SOAP propia no es imposible. Si tu empresa tiene un equipo de desarrollo permanente, reporta pocos tipos de documento (por ejemplo, solo remesa y manifiesto) y está dispuesta a dedicar tiempo cada vez que el RNDC cambia una regla, un cliente propio puede funcionar bien y sin costos adicionales por fuera de ese equipo.

El punto en contra aparece con el tiempo: cada ajuste del Ministerio —un campo nuevo, un cambio de validación, o la próxima vez que el Ministerio cambie algo, como ya pasó con la migración al RNDC2— se convierte en trabajo de tu equipo de TI, además de mantener el resto de tus sistemas. Si tu volumen crece, si manejas varios tipos de documento, o si tu equipo prefiere dedicarse a tu producto y no al SOAP del Ministerio, una API intermedia como la de Fassiltrans absorbe ese mantenimiento y te deja solo la parte JSON.

Hay señales concretas que ayudan a decidir. Si solo reportas remesa intermunicipal y manifiesto, sin remesa urbana ni anulaciones, el alcance del SOAP propio es más pequeño y más fácil de sostener. Si además reportas varios tipos de documento, manejas un volumen creciente de despachos o tu equipo de TI ya está ocupado con otros proyectos, cada procesoid nuevo que agregues es una pieza más de XML que mantener, probar y actualizar cuando el Ministerio cambie algo.

No hay una respuesta única: depende de tu equipo, tu volumen y cuánto quieres invertir en mantener algo que no es el producto de tu empresa.