¿Por qué Timbre?

Hay una pregunta más honesta que «¿usamos una API o lo hacemos nosotros?»: ¿qué parte de esto es tuya para decidir?

Lo que Hacienda provee

El catálogo CAByS, los XSD de la versión 4.4, el algoritmo de la clave de 50 dígitos, las reglas de numeración consecutiva. Lo define Hacienda, es idéntico para cualquier empresa que facture en Costa Rica, y no admite una versión propia —si no coincide exactamente, Hacienda rechaza el documento.

Construir esa pieza adentro de tu producto no la hace mejor que la de nadie más —una clave bien armada es una clave bien armada—, así que el tiempo que tu equipo le mete no compra diferenciación. Compra estar al día con una especificación que no escribiste y que no vas a poder cambiar.

Eso es lo estático: la parte del problema que ya está resuelta en el momento en que la vas a resolver, porque la resolvió Hacienda al publicar la especificación. Construirla de nuevo por proyecto no es empezar de cero, es repetir la misma tarea que ya hizo —o va a tener que hacer— cualquier otra empresa que factura en el país.

Lo que hay que resolver bien, y con Timbre lo resolvés una sola vez

Algunos de los errores que la especificación deja abiertos a quien la implementa —y que Timbre ya resolvió:

• Precisión decimal. Un monto en JSON como número (double) no representa exactamente los decimales que la ley obliga a declarar; la diferencia aparece como un colón de más en un total que Hacienda rechaza. Por eso Timbre trata los montos como texto, no como número.
• Numeración que no perdona. El consecutivo fiscal no tiene huecos ni marcha atrás: un documento emitido por error no se borra, se corrige con una nota de crédito. Un bug de concurrencia acá no es un bug, es un consecutivo fiscal quemado.
• Emitir dos veces por accidente. Un timeout de red no te dice si el documento se creó o no. Timbre resuelve eso con Idempotency-Key: repetir la petición devuelve el documento que ya existe, nunca uno nuevo.
• Verificar que el webhook es de Hacienda, vía Timbre. Un webhook sin firma es una entrada más para que cualquiera diga «Hacienda aceptó tu factura». El de Timbre viene firmado, y verificarlo es parte de la API, no algo que tenés que diseñar vos.
• Ambientes que no se pueden confundir. Sandbox y producción son proyectos distintos, con llaves distintas, y no hay un parámetro que cambie uno por otro —porque ese parámetro es el que alguien manda mal una vez y presenta una prueba como si fuera real.

Ninguno de estos es un problema de facturación en el sentido de tu negocio. Son problemas de ingeniería que ya vienen resueltos.

Lo estático es nuestro, lo tuyo es tuyo

La parte de esto que es igual para cualquier empresa —el catálogo, el XSD, la clave, la numeración, el seguimiento del veredicto— la mantiene Timbre, y la mantiene para todos los que la consumen a la vez, así que un cambio de Hacienda se resuelve una sola vez en un solo lugar.

Lo que queda para vos es lo que sí es tuyo: qué vendés, a quién, a qué precio, con qué flujo. Eso es lo que un cliente compra de tu producto. Vos te dedicás a construirlo mientras Timbre se encarga de presentar y firmar cada transacción contra Hacienda.

Ver cómo se usa en la práctica: Primeros pasos.