Cuatro errores que aparecen siempre al integrar el SII de la AEAT
Resumen:
- El sistema debe distinguir entre no enviado, enviado tarde y rechazado: son tres estados distintos.
- Los rechazos se clasifican en dos familias y cada una requiere una respuesta diferente.
- Sin idempotencia, un fallo de red produce envíos duplicados.
- El entorno de pruebas es más permisivo que el real: valida menos de lo que valida producción.
Integrar el suministro inmediato de información parece sencillo visto desde fuera: se genera un mensaje, se envía y se recibe respuesta. En la práctica, todas las integraciones que hemos hecho se atascaron en los mismos cuatro sitios.
Uno: tratar el plazo como si no existiera
La obligación no es solo enviar: es enviar dentro de plazo. Un sistema que envía cuando puede, sin control de vencimientos, funciona bien hasta el primer día que algo se cae.
Lo que hace falta es un estado explícito por factura y una alerta cuando alguna se acerca al límite sin haberse enviado. No basta con una cola que reintenta: alguien tiene que enterarse si la cola lleva dos días atascada.
El error concreto que hemos visto varias veces es una cola silenciosa. Los envíos fallaban, se reintentaban, volvían a fallar, y nadie miraba el registro. Se descubrió tres semanas después.
Dos: meter todos los rechazos en el mismo saco
Un rechazo puede venir de dos sitios muy distintos y confundirlos genera trabajo inútil.
| Tipo de rechazo | Qué hay que hacer |
|---|---|
| Dato de la factura incorrecto | Importe que no cuadra, tipo impositivo inválido, fecha imposible. Hay que corregir la factura y volver a emitir, no solo reenviar. |
| Dato del receptor | Identificación fiscal que no consta o no corresponde. La factura puede estar bien; lo que falla es el padrón de clientes. Se corrige el dato y se reenvía. |
| Formato o estructura | El mensaje no cumple el esquema. Es un defecto del software, no de los datos, y afecta a todas las facturas por igual. |
| Duplicado | Ya constaba un registro con esa referencia. Casi siempre es consecuencia de un reintento sin control de idempotencia. |
Sin esta clasificación, administración recibe una lista de errores homogénea y no sabe cuáles puede resolver y cuáles tiene que escalar.
Tres: reintentar sin idempotencia
Este es el error más caro y el más fácil de evitar.
El escenario es siempre el mismo: se envía una factura, la conexión se corta antes de recibir respuesta, y el sistema no sabe si llegó. La reacción natural, tanto de un programa como de una persona, es reintentar. Si el envío original sí había llegado, ahora hay dos registros.
La solución es que cada envío lleve un identificador estable y que, antes de reintentar, el sistema consulte el estado en lugar de asumirlo. Es un patrón conocido y aun así aparece sin implementar en la mayoría de integraciones que revisamos.
Cuatro: no conciliar nunca
Se asume que si los envíos se aceptaron, todo está bien. No siempre. Puede haber facturas emitidas que nunca entraron en la cola por un fallo en el punto de origen, o registros aceptados con datos distintos a los que la empresa cree tener.
La conciliación periódica —descargar lo registrado, comparar con lo propio, revisar diferencias— es aburrida y es lo que evita descubrir un desfase de meses cuando ya es difícil de arreglar.
Preguntas frecuentes
¿Qué pasa si se envía una factura fuera de plazo?
El envío se acepta pero queda marcado como extemporáneo, y eso puede acarrear consecuencias. Lo importante desde el punto de vista técnico es que el sistema distinga entre no haber enviado y haber enviado tarde: son situaciones distintas que requieren respuestas distintas.
¿Un rechazo significa que la factura está mal?
No siempre. Hay rechazos por datos incorrectos de la factura y rechazos por problemas del envío, como un identificador de receptor que no consta. El sistema debe clasificarlos porque los primeros exigen corregir la factura y los segundos solo reenviar tras arreglar el dato.
¿Cómo se evita enviar dos veces la misma factura?
Con idempotencia: cada envío lleva un identificador propio y el sistema comprueba el estado antes de reintentar. Sin eso, un fallo de red durante el envío deja la duda de si llegó, y la reacción natural de reintentar genera duplicados.
¿Hay que conciliar contra lo que la AEAT tiene registrado?
Sí, y conviene hacerlo periódicamente, no solo cuando aparece un problema. Descargar lo registrado y compararlo con lo propio detecta discrepancias mientras aún se pueden corregir con facilidad.
¿Se puede probar la integración sin enviar datos reales?
Sí, existe un entorno de pruebas. La advertencia es que se comporta de forma más permisiva que el real: hemos visto integraciones que funcionaban en pruebas y fallaban en producción por validaciones que el entorno de test no aplicaba.
Lo que sí funciona
Las integraciones que se comportan bien comparten cuatro rasgos: estado explícito por factura, clasificación de errores por tipo, idempotencia en los reintentos y un proceso de conciliación programado. Nada de eso es sofisticado. Es disciplina en el diseño del flujo, que es exactamente lo que se salta quien tiene prisa.
Cómo se ve una integración sana desde administración
El criterio que usamos para dar por buena una integración no es técnico: es si la persona de administración puede responder tres preguntas sin llamar a nadie.
| Pregunta | Dónde debe verla |
|---|---|
| ¿Hay facturas pendientes de enviar? | Un contador visible en la pantalla principal, no un informe que hay que ejecutar. |
| ¿Alguna se acerca al plazo? | Un aviso que aparece solo, sin depender de que alguien lo consulte. |
| ¿Qué rechazos puedo resolver yo? | Los errores clasificados por tipo, con el dato concreto que falla señalado. |
Si esas tres cosas están resueltas, la integración funciona aunque por dentro sea mejorable. Si no lo están, no importa lo elegante que sea el código: el problema va a llegar tarde y va a llegar en forma de sorpresa.
El coste de descubrirlo tarde
Una cola atascada durante días no se arregla enviando lo pendiente: hay que revisar factura por factura cuáles llegaron, cuáles no y cuáles llegaron duplicadas. Ese trabajo de reconciliación cuesta más horas que haber construido bien las alertas desde el principio.