Decide dónde nace la factura
Un pedido confirmado, un servicio finalizado y un cobro no siempre significan lo mismo. Define qué hecho convierte una operación en factura y qué persona o regla lo autoriza.
Mantén un identificador estable del sistema de origen. Esa referencia permite detectar repeticiones y relacionar la respuesta con la operación correcta.
Define un contrato de datos
Documenta emisor, destinatario, fecha, serie, conceptos, impuestos y totales. Indica campos obligatorios, formatos y validaciones.
No envíes información innecesaria. La integración debe explicar qué ocurre si falta un dato fiscal o si un importe no coincide.
Diseña respuestas y reintentos
Tu sistema necesita distinguir una solicitud recibida, una factura generada y una remisión aceptada o rechazada. Guardar solo “correcto” o “error” dificulta cualquier soporte.
Los reintentos deben evitar duplicar facturas. Utiliza claves idempotentes o el mecanismo acordado en la documentación técnica.
Mantén el histórico donde ya está
La integración puede centrarse en operaciones nuevas. El programa anterior puede conservar documentos y otras funciones si delimitas su uso.
Devuelve al sistema de origen la referencia de la factura y el estado necesario para que el equipo trabaje sin abrir varias aplicaciones para reconstruir una incidencia.
Alcance técnico mínimo
- Evento de emisión
- Identificador único
- Campos y validaciones
- Estados y errores
- Reintentos sin duplicados
- Responsable de mantenimiento
El contrato técnico mínimo de la API
Define una referencia idempotente para cada operación, campos obligatorios, formatos de fecha e importe, autenticación y respuestas de error. Aclara cuándo una operación se considera recibida, cuándo se genera la factura y cómo recupera tu sistema el identificador y el estado del registro.
Incluye reintentos y conciliación. Una caída de red no debe crear dos facturas ni dejar una venta sin seguimiento. Tu aplicación necesita distinguir entre una petición no recibida, una operación rechazada y un registro pendiente. Prueba esos tres estados antes de conectar producción.
Guía de aplicación paso a paso
Define el evento de facturación. Aclara si la emisión ocurre al confirmar, entregar, cobrar o aprobar administrativamente. La API no debe decidir por accidente un criterio de negocio. Tu sistema envía la operación solo cuando se cumplen las condiciones acordadas y conserva la referencia que originó esa decisión.
Diseña el contrato de datos. Documenta campos, formatos, catálogos, obligatoriedad y validaciones. Incluye ejemplos de varias líneas, descuentos, impuestos y destinatarios. Versiona el contrato para que un cambio no rompa integraciones activas ni produzca interpretaciones distintas entre entornos.
Controla identidad e idempotencia. Cada operación necesita una clave estable que sobreviva a reintentos. Antes de crear otra factura, consulta el resultado asociado a esa clave. Registra solicitud y respuesta sin guardar credenciales ni datos innecesarios en archivos de diagnóstico.
Trata respuestas y tiempos. Distingue aceptación, rechazo, espera y error técnico. Define cuánto espera el sistema, cuándo reintenta y cuándo interviene una persona. El usuario debe ver un estado comprensible sin interpretar códigos internos ni asumir que una pantalla bloqueada significa que nada ocurrió.
Prueba recuperación y conciliación. Interrumpe comunicaciones, repite peticiones y simula datos inválidos en un entorno controlado. Después compara pedidos, facturas y registros. La integración está preparada cuando recupera coherencia tras una incidencia, no solo cuando completa el recorrido ideal.
Ejemplo práctico
Un e-commerce confirma un pedido y su aplicación crea una referencia única. Envía por API los datos necesarios, recibe la identificación de la factura y consulta el estado del registro. Si la red falla, reintenta con la misma referencia para evitar duplicados. El comercio conserva pedidos, catálogo y cobros; VerifacturDocs concentra la generación de la factura y la parte VERI*FACTU acordada.
Antes de cerrar la decisión
Antes de producción, acuerda niveles de registro que permitan investigar sin exponer información innecesaria. Conserva referencias, tiempos y códigos de estado; protege credenciales y datos personales. Define cuánto tiempo estarán disponibles esos registros técnicos y quién puede consultarlos durante una incidencia.
Mide la integración con indicadores sencillos: operaciones enviadas, aceptadas, rechazadas, pendientes y tiempo de recuperación. Una API estable no es la que nunca falla, sino la que detecta el fallo, mantiene la identidad de la operación y permite volver a un estado coherente.
Incluye en la documentación un ejemplo completo de solicitud y respuesta para cada estado relevante. Añade responsables, tiempo máximo de espera y procedimiento manual si el servicio no está disponible. Estos ejemplos aceleran futuras modificaciones del ERP o e-commerce y reducen el riesgo de que otro desarrollador interprete el contrato de forma diferente.
Preguntas frecuentes
¿Tengo que reescribir mi ERP o e-commerce?
No necesariamente. Puede conservar la lógica de pedidos, clientes y cobros, y enviar los datos necesarios a VerifacturDocs mediante una API definida.
¿Cómo se evitan facturas duplicadas?
Con una referencia estable por operación, peticiones idempotentes y una consulta de estado antes de repetir. Ese comportamiento debe probarse ante errores de red y respuestas incompletas.
Fuentes consultadas
Contenido informativo. La aplicación de la norma depende de la situación de cada negocio.