Entendiendo el ecosistema: DTE, Hacienda y el flujo general

Antes de escribir una sola línea de código, tuve que entender un mundo completamente nuevo. Este post es sobre ese proceso — con todo y los malentendidos.

---

Lo primero: descargar el mundo del Ministerio de Hacienda

El Ministerio de Hacienda de El Salvador pone a disposición de los desarrolladores todo lo que necesitas para implementar el sistema de Documentos Tributarios Electrónicos. Todo, en teoría. Porque cuando abres esos documentos por primera vez, la cantidad de información puede ser abrumadora.

Lo que descargué al inicio fue:

• La documentación técnica oficial
• Los catálogos de códigos
• Los esquemas JSON de cada tipo de documento
• Los endpoints para el ambiente de pruebas y producción
• El firmador oficial

Con eso sobre la mesa, empecé a leer. Y entre más leía, más preguntas surgían.

---

El flujo general: de JSON a sello

Antes de entrar en los detalles de los problemas que tuve, vale la pena entender cómo funciona el proceso completo de emisión de un DTE, porque sin tener esto claro, nada de lo demás tiene sentido.

El flujo es básicamente este:

1. Generás el JSON del documento tributario según el esquema que define el MH
2. Firmás el documento con el firmador para obtener el documento codificado
3. Enviás el documento firmado al endpoint correspondiente del MH
4. El MH procesa el documento y retorna una respuesta con el sello de recepción
5. Almacenás la respuesta y el documento queda oficialmente registrado

Simple en papel. En la práctica, cada uno de esos pasos tiene sus propias complejidades, y yo fui descubriendo cada una por el camino.

---

El primer tropiezo: los catálogos y el conocimiento asumido

Los catálogos son documentos que definen los códigos que debés usar en cada campo. Por ejemplo, el tipo de documento, la forma de pago, el tipo de ítem, y muchos más. Todo tiene un código específico que el MH espera recibir.

El problema es que esa documentación está escrita asumiendo que quien la lee ya tiene cierto conocimiento del mundo tributario. Términos, conceptos y relaciones que para alguien con experiencia en contabilidad o en implementaciones anteriores son obvios, para mí no lo eran.

Fue una mezcla de inexperiencia y desconocimiento de detalles que el documento simplemente daba por sabidos. No había una sección que dijera «si nunca has trabajado con facturación electrónica, empezá por aquí.» Simplemente asumía que ya sabías.

Así que gran parte del tiempo inicial no fue programando, sino entendiendo el contexto detrás de cada campo y cada catálogo.

---

El malentendido más grande: ¿qué es un esquema JSON?

Aquí viene la confesión más honesta de este post.

Cuando abrí los esquemas JSON que provee el MH, vi algo como esto:

{
  "tipoDte": {
    "type": "string",
    "description": "Tipo de Documento Tributario Electrónico"
  },
  "numeroControl": {
    "type": "string",
    "maxLength": 31
  }
}

Y mi primer pensamiento fue: «bien, aquí relleno mis datos y listo.»

No entendí al inicio que ese esquema no era una plantilla para rellenar. Era una definición de tipos de datos y estructura — básicamente un contrato que me decía qué campos existían, qué tipo de dato esperaban, cuáles eran obligatorios y cuáles opcionales. Era documentación de la forma del JSON, no el JSON en sí.

Ese malentendido me hizo perder tiempo valioso hasta que lo entendí. Y una vez que lo entendí, todo empezó a tener más sentido.

---

El recurso que no esperaba: mis propias facturas

Estaba atorado tratando de entender la estructura real que debía tener el JSON de salida, cuando se me ocurrió algo: yo había recibido facturas electrónicas en mi correo de compras que había hecho.

Abrí esos correos, descargué los archivos adjuntos y ahí estaba — un JSON real, con una estructura real, con datos reales. No era un esquema abstracto de tipos y definiciones. Era el documento como el MH lo recibe y lo procesa.

Eso fue un antes y un después. Comparar el esquema del MH con una factura real me permitió entender exactamente cómo se traducía cada definición a un valor concreto. Cuáles campos eran siempre requeridos, cuáles venían vacíos en ciertos casos, cómo se anidaban los objetos.

A veces el mejor recurso de aprendizaje no está en la documentación oficial, sino en el mundo real que ya existe alrededor de lo que estás construyendo.

---

El primer esquema funcional

Con todo ese proceso encima — los catálogos, el malentendido de los esquemas, el apoyo de las facturas reales — fui construyendo mi primer esquema funcional campo por campo, sacando parte por parte en un documento separado para entender cada sección antes de pasar a la siguiente.

El tipo de documento que elegí para empezar fue la Factura de Consumidor Final, la más común y la que mejor podía validar con los ejemplos que tenía.

Fue lento. No había IA a la que preguntarle «¿qué significa este campo?» como existe hoy. Cada duda era buscar en el documento, buscar en los catálogos, buscar en foros, o simplemente probar. La IA estaba en sus inicios y usarla para este tipo de consultas técnicas tan específicas era algo que todavía no era una opción real.

Todo fue a puro documento, pura lectura y pura prueba y error.

---

Lo que viene

Con el ecosistema entendido y el primer esquema en mano, el siguiente paso fue pensar en cómo organizar todo esto como un proyecto. Cómo estructurar el código, qué decisiones de arquitectura tomar antes de empezar a construir.

De eso hablo en el siguiente post: Cómo estructuré el proyecto desde el inicio.

---

¿Te pasó algo similar cuando te enfrentaste a documentación técnica que asumía que ya sabías cosas que estabas aprendiendo? Contame en los comentarios.