Integración API Twinfield: cómo conectarte, configurar y seguir las mejores prácticas

Twinfield, el software contable en la nube de Wolters Kluwer, es ampliamente utilizado por pymes y firmas contables en Europa, especialmente en los Países Bajos, Bélgica y el Reino Unido. Integrar Twinfield en tu producto te permite:

• Recuperar datos financieros: asientos contables, facturas, códigos de IVA y dimensiones de cuenta
• Enviar transacciones y asientos directamente al entorno Twinfield de tus clientes
• Automatizar la conciliación, los flujos de precontabilidad y el matching de facturas
• Gestionar entornos multi-empresa y multi-oficina gracias a la arquitectura multi-cluster de Twinfield

Esta guía cubre cómo funciona la API de Twinfield, cómo configurar tu integración, las mejores prácticas a seguir, y cómo la API Contable Unificada de Chift te permite centrarte en lo que realmente importa.

¿Qué es la API de Twinfield?

La API de Twinfield se basa en Web Services SOAP, un protocolo XML. Todos los endpoints están alojados en una URL de cluster específica (https://api.<cluster>.twinfield.com) y exponen definiciones WSDL estándar.

La autenticación se realiza mediante OAuth2. Los clientes proporcionan un Client ID y un Client Secret para obtener tokens de acceso. Un punto clave: Twinfield es una plataforma multi-cluster, por lo que la URL del cluster debe extraerse del token JWT decodificado (campo twf.clusterUrl) y usarse para todas las solicitudes SOAP posteriores.

Los principales web services disponibles son:

• ProcessXml (/webservices/processxml.asmx) , el servicio central para crear, actualizar y leer prácticamente todas las entidades mediante mensajes XML. Es el servicio que Chift utiliza principalmente.
• Finder (/webservices/finder.asmx), búsqueda de dimensiones, oficinas y otras entidades
• Matching (/webservices/matching.asmx), gestión del matching de transacciones
• Bank books / Cash books, servicios dedicados a la gestión de libros de tesorería
• Declarations, gestión de declaraciones de IVA e impuestos
• Documents (/webservices/documentservice.svc), gestión de adjuntos
• Deleted transactions (/webservices/deletedtransactionsservice.svc), recuperación de transacciones eliminadas
• Pay and Collect, Budgets, Hierarchies, XBRL, servicios especializados

ProcessXml acepta elementos XML raíz como transaction, dimension, vat, salesinvoice, match, list, read y browse, entre otros.

🔗 Para la documentación técnica completa, visita el portal para desarrolladores de Twinfield.

{{CTA-1}}

Examples of Twinfield API integration use cases

Gestión y previsión de tesorería

Las plataformas de gestión de tesorería pueden obtener facturas de clientes y proveedores pendientes, asientos contables y saldos de cuentas directamente desde Twinfield para alimentar proyecciones en tiempo real. La integración bidireccional también permite la precontabilidad: enviar datos de transacciones enriquecidos de vuelta a Twinfield para generar asientos de forma automática.

Conectar SaaS vertical a la contabilidad

Las plataformas SaaS verticales, como los ERP para construcción, pueden enviar facturas de proveedores, facturas de clientes y registros de gastos a Twinfield, generando asientos contables en pocos clics. Esto elimina la doble entrada de datos y reduce errores tanto para empresarios como para sus contables.

Automatización de los procesos de cobro de deudas

Las plataformas de recobro pueden extraer las cuentas por cobrar abiertas de Twinfield para activar recordatorios de pago automáticos y flujos de cobro. Una vez recibido el pago, el estado puede devolverse a Twinfield para mantener los registros contables al día, sin reconciliación manual.

Para más ejemplos de integraciones contables exitosas, explora nuestros casos de estudio de Chift.

Cómo configurar tu integración con la API Twinfield

Estos son los pasos para empezar con la API de Twinfield:

1. Registra una aplicación OAuth2 en el portal de desarrolladores de Twinfield para obtener un Client ID y un Client Secret
2. Solicita la certificación de tu ClientId, las integraciones no certificadas están limitadas al 5 % del cupo de créditos estándar, lo que bloquea cualquier uso en producción
3. Completa el flujo OAuth2 para obtener un token de acceso, luego decodifica el JWT para extraer twf.clusterUrl, esta es la URL base para todas las solicitudes SOAP
4. Construye tu capa de solicitudes SOAP usando el servicio ProcessXml. Cada solicitud contiene un payload XML cuyo elemento raíz corresponde al tipo de entidad a manipular (<transaction>, <salesinvoice>, <read>, etc.)
5. Gestiona entornos multi-cluster y multi-oficina: los clientes de Twinfield pueden tener varias oficinas o filiales, cada una requiriendo solicitudes separadas

La conexión inicial está al alcance de la mayoría de equipos de desarrollo. Pero una integración lista para producción exige más: mapeo de datos consistente entre oficinas, lógica de refresco de tokens, gestión de límites de velocidad, paginación de grandes conjuntos de datos y mantenimiento continuo a medida que evoluciona la API.

Mejores prácticas para la integración API Twinfield

• Extrae siempre la URL del cluster desde el JWT. Twinfield es multi-cluster. Enviar solicitudes SOAP al cluster incorrecto provoca fallos de autenticación. Lee twf.clusterUrl del token decodificado antes de cualquier llamada API.
• Certifica tu ClientId. Las integraciones no certificadas reciben solo el 5 % del cupo estándar — 50 créditos/min en lugar de 1.000. No es un límite que se pueda esquivar: es un techo duro que bloquea cualquier carga de trabajo real en producción. La certificación es un requisito previo, no una opción.
• Prioriza las operaciones de lectura. Las solicitudes de tipo Query (<read>, <list>, <columns>, llamadas Finder) cuestan 1 crédito. Las operaciones de escritura cuestan 3 créditos. Diseñar un conector orientado a la lectura amplía considerablemente tu presupuesto de créditos por minuto.
• Agrupa con cuidado, respeta los límites. Twinfield recomienda un máximo de 25 elementos hijo por elemento padre y 500 líneas por transacción o factura. Superar estos valores puede causar fallos en el procesamiento. Divide las operaciones de escritura voluminosas en lotes adecuados.
• Implementa backoff exponencial en errores 429. Cuando se alcanzan los límites de velocidad o concurrencia, la API devuelve 429 Too Many Requests con un encabezado Retry-After. Usa ese valor como base para tu backoff exponencial.
• Respeta los límites de concurrencia. Además de los cupos de créditos por minuto, Twinfield impone un máximo de 20 solicitudes concurrentes por ClientId y 10 por combinación ClientId+OrganisationId. Los procesos batch intensivos deben regularse en consecuencia.

Conéctate a Twinfield, Exact Online, Sage y más con una sola integración

Construir una integración directa con Twinfield implica gestionar solicitudes SOAP, el enrutamiento de tokens multi-cluster, la lógica de refresco OAuth2, la gestión de límites de créditos, la normalización de datos entre oficinas de Twinfield y el mantenimiento continuo a medida que evoluciona la plataforma. Y luego hay que hacer todo eso de nuevo para cada herramienta contable en tu hoja de ruta.

Con la API Contable Unificada de Chift, te integras una sola vez y accedes a Twinfield, Exact Online, Pennylane, Sage, Xero, Odoo, MyUnisoft, y muchas más, todas a través del mismo modelo de datos normalizado.

Lo que esto desbloquea para tu equipo:

• Tu equipo de ingeniería construye una sola integración y se mantiene enfocado en tu producto principal
• Los nuevos conectores se activan con un clic, sin trabajo de desarrollo adicional
• La autenticación, el manejo SOAP, el enrutamiento multi-cluster y el mapeo de datos son gestionados completamente por Chift
• Monitorización, logging y mantenimiento a largo plazo incluidos
• Soporte experto de un equipo que entiende tanto los aspectos técnicos como de negocio de las integraciones financieras

Tu equipo de desarrollo ahorra tiempo. Tu equipo de ventas puede decir sí a más solicitudes de integración. Y tu producto se convierte en la opción predeterminada para los clientes que necesitan que sus datos contables fluyan.

La API Contable Unificada de Chift: una sola integración, todos los conectores contables esenciales.Twinfield es solo una de las muchas plataformas contables disponibles a través de la API Unificada de Chift. Con una sola integración, tu aplicación accede a datos consistentes y normalizados desde: Twinfield, Exact Online, Sage, Xero, Pennylane, MyUnisoft, Odoo y muchas más.

No necesitas construir ni mantener un conector único para cada plataforma, Chift se encarga de eso. Adoptar las APIs Unificadas de Chift simplifica tu desarrollo, elimina el mantenimiento de integraciones y te permite escalar rápidamente en nuevos mercados.

¿Listo para integrar Twinfield y mucho más? Reserva una demo y descubre cómo Chift puede acelerar tus integraciones contables.

Preguntas frecuentes sobre la API Twinfield

¿Qué endpoints incluye la API Twinfield?

El conector Twinfield de Chift expone un amplio conjunto de endpoints estandarizados a través del servicio ProcessXml, incluyendo (sin ser exhaustivos):

• Clientes /clients
• Proveedores /suppliers
• Códigos de IVA /vat-codes
• Asientos contables /journal-entries
• Plan de cuentas /accounts
• Transacciones /transactions
• Facturas de venta /invoices
• Dimensiones (centros de coste, proyectos) /dimensions

Consulta nuestra documentación API de Twinfield para la lista completa de rutas disponibles.

¿Cuáles son los límites de velocidad de la API Twinfield?

Twinfield utiliza un sistema de créditos (en vigor desde diciembre de 2024). Las operaciones de consulta cuestan 1 crédito; todas las demás operaciones cuestan 3 créditos. Aquí están los cupos por minuto para integraciones certificadas:

Las integraciones certificadas reciben 1.000 créditos/min por dirección IP, 1.000 créditos/min por ClientId y 1.000 créditos/min por OrganisationId. El bucket combinado ClientId + OrganisationId está limitado a 500 créditos/min. Las integraciones no certificadas reciben el 5 % de esos límites en todos los buckets: 50 créditos/min por IP, por ClientId y por OrganisationId, y 25 créditos/min para el bucket combinado.

Los límites de concurrencia se aplican por separado: máximo 20 solicitudes simultáneas por ClientId, máximo 10 por combinación ClientId+OrganisationId. Los encabezados X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Credited y Retry-After se incluyen en las respuestas cuando se alcanzan los límites.

¿Twinfield admite REST o solo SOAP?

La API principal de Twinfield es exclusivamente SOAP. No existe una API REST nativa para los datos contables y de transacciones. Todas las operaciones sobre entidades pasan por el servicio ProcessXml mediante payloads XML. Esto añade complejidad de implementación en comparación con las APIs REST modernas: tu integración debe gestionar la descubrimiento WSDL, la serialización XML y el formateo de sobres SOAP.

¿Qué es el multi-cluster en Twinfield y por qué importa?

Twinfield aloja los datos de los clientes en múltiples clusters de servidores. Cada entorno de cliente reside en un cluster específico, y la URL base de la API varía según el cluster. Si envías solicitudes al cluster incorrecto, la autenticación fallará, incluso con un token válido. Debes leer el claim twf.clusterUrl del JWT decodificado y usarlo como URL base para todas las llamadas SOAP. Es uno de los errores de integración más frecuentes.

¿Por qué es importante la certificación del ClientId?

Los ClientIds no certificados están limitados al 5 % del cupo de créditos estándar de Twinfield, 50 créditos por minuto en lugar de 1.000. A 3 créditos por operación de escritura, esto significa unas 16 solicitudes de escritura por minuto antes de alcanzar el límite. Para cualquier conector de producción que maneje volúmenes reales de datos de clientes, este techo hace inviable la integración sin certificación. Se recomienda encarecidamente solicitar la certificación a Twinfield desde el inicio del desarrollo.