Cómo integrar con éxito la API de sevdesk

sevdesk es uno de los programas de contabilidad más utilizados en Alemania por pequeñas y medianas empresas. Si tu producto apunta al mercado DACH, lo vas a encontrar con frecuencia. Integrarlo te da acceso directo a los datos financieros de cientos de miles de pymes germanófonas.

Al conectar la API de sevdesk a tu producto, puedes:

• Sincronizar automáticamente contactos, facturas y justificantes
• Enviar datos de precontabilidad para eliminar las entradas manuales de tus usuarios
• Recuperar cobros y pagos pendientes para alimentar previsiones de tesorería
• Acceder a datos financieros conformes y compatibles con DATEV, directamente desde la fuente

En esta guía, te explicamos cómo funciona la API de sevdesk, cómo configurar la integración, las buenas prácticas a seguir y cómo Chift simplifica todo el proceso gracias a una única API de Contabilidad Unificada.

¿Qué es la API de sevdesk?

La API de sevdesk es una API REST que permite a las aplicaciones externas acceder de forma programática a los datos contables almacenados en una cuenta sevdesk. Cubre una amplia gama de recursos: contactos, facturas, notas de crédito, justificantes, cuentas bancarias y datos de referencia.

Resumen técnico

• Tipo de API: REST
• URL base: https://my.sevdesk.de/api/v1/
• Formato de datos: JSON
• Métodos HTTP soportados: GET, POST, PUT, DELETE

Una sola API, una sola versión

sevdesk expone una única API REST en /api/v1. No existe un endpoint v2, lo que simplifica las cosas: una sola superficie que integrar, un solo modelo de datos que entender.

sevdesk también es compatible con DATEV, algo esencial para cualquier producto que necesite alimentar el ecosistema contable alemán. Es un requisito clave para los softwares que sirven a contables del espacio DACH o a sus clientes pymes.

Conecta con sevdesk y con todos los grandes programas de contabilidad en una sola integración. Descubre cómo las APIs Unificadas de Chift ayudan a los editores de software a añadir decenas de conectores de una sola vez.

{{CTA-1}}

¿Qué puedes construir con una integración de sevdesk?

Integrar sevdesk abre un amplio abanico de casos de uso para los editores de software financiero y de gestión empresarial. Aquí están los más comunes.

Sincronización de datos de clientes y proveedores

Mantén los datos de contacto alineados automáticamente entre tu producto y sevdesk. Es especialmente valioso para CRMs, ERPs, plataformas de facturación y herramientas de precontabilidad que necesitan una visión coherente de con quién trabaja el cliente, sin reintroducción manual de datos en ninguno de los dos lados.

Automatización de asientos precontables

Permite a tus usuarios enviar datos financieros estructurados directamente a sevdesk, generando asientos contables de forma automática. Las herramientas de gestión de gastos, las plataformas de pago y las soluciones de facturación usan este mecanismo para eliminar el trabajo manual repetitivo, tanto para el usuario como para su contable.

Previsión de tesorería

Los softwares de gestión de tesorería pueden recuperar las facturas de clientes y proveedores abiertas desde sevdesk para construir proyecciones precisas y actualizadas. Con acceso a los datos de AR/AP en tiempo real, tus usuarios anticipan sus flujos de caja en lugar de depender de exportaciones estáticas.

Evaluación de elegibilidad para plataformas de financiación B2B

Las plataformas de crédito digital pueden usar los datos financieros estructurados de sevdesk, incluyendo facturas, historial de pagos y saldos de cuentas, para realizar comprobaciones de elegibilidad y scoring en tiempo casi real. Lo que antes llevaba días puede reducirse a segundos.

Para más ejemplos de integraciones reales, consulta nuestros casos de éxito de Chift.

Cómo empezar con la API de sevdesk

sevdesk usa autenticación por token estático, lo que hace que la configuración sea sencilla. No hay flujo OAuth ni proceso de aprobación. Estos son los pasos:

1. El usuario crea (o accede a) una cuenta sevdesk en sevdesk.de. A tener en cuenta: sevdesk requiere una suscripción de pago. Hay una prueba de 14 días, pero no existe plan gratuito.
2. El usuario genera un token de API desde su cuenta: Configuración → Usuario → Token API.
3. Ese token se introduce en tu integración como api_key.
4. Cada petición a la API envía el token en el header Authorization, en bruto, sin prefijo Bearer:

Authorization: b7794de0085f5cd00560f160f290af38

Un detalle importante que conviene comunicar a tus usuarios: el token tiene una vida útil infinita pero está vinculado a la cuenta de usuario específica. Si ese usuario se elimina, el token se pierde definitivamente y no puede recuperarse. No existe flujo de refresco. Para rotar credenciales, el usuario regenera su token en la interfaz, lo que invalida inmediatamente el anterior.

Chift gestiona la administración de credenciales y la configuración de la conexión, para que tu equipo pueda centrarse en la integración en sí.

¿Cómo funciona la autenticación de la API de sevdesk?

La autenticación en sevdesk difiere de la mayoría de las APIs modernas en un punto clave: no usa OAuth. En su lugar, se basa en un único token estático enviado en cada header de petición.

Lo que esto significa en la práctica:

• Sin expiración de token que gestionar
• Sin flujo de refresco que implementar
• Sin scopes que configurar

El token está vinculado al usuario que lo creó. Si recibes una respuesta HTTP 401, el token ha sido invalidado o revocado. No reintentes la petición. Muestra un error de autenticación claro e invita al usuario a introducir su nuevo token.

Los archivos adjuntos a justificantes siguen un flujo en dos pasos. Primero, POST Voucher/Factory/uploadTempFile (en multipart form data) devuelve un hash interno del nombre de archivo. Ese hash se pasa luego a POST Voucher/Factory/saveVoucher para asociar el PDF al justificante. Ambos pasos deben completarse con éxito para que el adjunto quede registrado.

Buenas prácticas para integrar la API de sevdesk

1. Lee siempre el cuerpo JSON del error, no el código HTTP

Esta es la particularidad más importante de la API de sevdesk: devuelve un HTTP 500 para errores que son semánticamente problemas de nivel 400. El código de estado solo no te dirá qué ha fallado.

Lee siempre el cuerpo de la respuesta JSON y consulta {"error": {"message": "..."}} para entender el problema real. Un ejemplo conocido: "debitor/creditor number already exists" devuelve un 500. Tu integración debe capturar los mensajes de error conocidos y mapearlos a excepciones explícitas, en lugar de tratar cada 500 como un fallo de servidor.

2. Nunca asignes tú mismo los números de cliente o de factura

sevdesk gestiona sus propias secuencias de numeración, y los huecos en esas secuencias generan problemas más adelante. Usa siempre los endpoints dedicados para obtener el próximo número disponible:

• GET /Contact/Factory/getNextCustomerNumber
• GET /SevSequence/Factory/getByType

Deja que sevdesk gestione la enumeración. Asignar números tú mismo arriesga conflictos y peticiones rechazadas.

3. Gestiona la paginación correctamente

sevdesk usa los parámetros limit y offset para la paginación. El valor por defecto recomendado es de 100 registros por página (máximo: 1.000). Para obtener el recuento total de registros, pasa countAll=true. La respuesta incluirá {"total": "157", "objects": [...]}. Detén la paginación cuando len(objects) < limit, o cuando offset + limit >= total.

4. Cachea los recursos correctos, y solo esos

Algunos recursos son estables y se pueden cachear sin riesgo: StaticCountry, SevClient y CheckAccount cambian raramente. Otros nunca deben cachearse. Los contactos, facturas y justificantes mutan con frecuencia, y cachearlos produce lecturas desactualizadas tras actualizaciones, creando inconsistencias difíciles de depurar en tu lógica de sincronización.

5. Recupera las líneas por separado

Las posiciones de facturas, notas de crédito y justificantes no se devuelven en línea por defecto. Están en endpoints separados (InvoicePos, CreditNotePos, VoucherPos) y deben recuperarse por ID padre. Ten en cuenta esas llamadas adicionales al diseñar tu flujo de sincronización.

6. Implementa lógica de reintento con backoff para el rate limiting

sevdesk no publica límites de tasa explícitos, pero las respuestas HTTP 429 pueden producirse bajo carga. Implementa backoff exponencial y reintenta en 429. No reintentes en 401, ya que eso significa que el token ya no es válido.

¿Por qué integrar sevdesk a través de Chift?

Construir una integración directa con sevdesk es factible. Pero una vez que has gestionado las particularidades de autenticación, el parsing de errores, la paginación, las reglas de caché y el flujo de carga en dos pasos, todavía tienes que mantener esa integración a medida que la API evoluciona. Y repetir lo mismo para cada otro programa contable en tu roadmap.

Con la API de Contabilidad Unificada de Chift, integras una sola vez y obtienes acceso a sevdesk, Exact Online, Xero, Sage, Pennylane, MyUnisoft, Visma eAccounting, y muchos más, todo a través del mismo modelo de datos normalizado.

Esto es lo que eso significa para tu equipo:

• Tu equipo técnico construye una sola integración y sigue centrado en tu producto principal
• Los nuevos conectores se activan con un clic, sin trabajo de desarrollo adicional
• La autenticación, la gestión de errores y el mapeo de datos están completamente gestionados por Chift
• Monitorización, logs 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 gana tiempo. Tu equipo comercial puede decir que sí a más solicitudes de integración. Y tu producto se convierte en la elección natural para los clientes que necesitan que sus datos financieros fluyan.

¿Quieres ver cómo Chift conecta tu producto con sevdesk y más de 50 herramientas financieras? Contacta con nuestro equipo para una demo personalizada.

FAQ integración API sevdesk

¿Qué endpoints expone la API de sevdesk?

La API REST de sevdesk en /api/v1 cubre una amplia gama de recursos, entre ellos:

• Contactos /Contact
• Facturas y líneas /Invoice, /InvoicePos
• Notas de crédito y líneas /CreditNote, /CreditNotePos
• Justificantes y líneas /Voucher, /VoucherPos
• Cuentas bancarias /CheckAccount
• Datos de referencia /StaticCountry, /SevClient

Consulta la documentación de la API de sevdesk para la lista completa de endpoints disponibles.

¿Cuáles son los límites de tasa de la API de sevdesk?

sevdesk no publica límites de tasa explícitos. No aparece ninguna cuota numérica por minuto o por hora en su documentación oficial. Dicho esto, las respuestas HTTP 429 pueden producirse bajo carga elevada. Implementa siempre lógica de reintento con backoff exponencial para gestionarlas correctamente.

¿La API de sevdesk soporta OAuth?

No. La autenticación se basa enteramente en un token estático enviado en bruto en el header Authorization, sin prefijo Bearer, sin flujo OAuth y sin expiración. El token es válido hasta que el usuario lo regenere o su cuenta sea eliminada.

¿Qué ocurre si el token de sevdesk de un usuario se pierde o se renueva?

Si el usuario elimina su cuenta, el token de API se pierde definitivamente y no puede recuperarse. Si regenera su token en la interfaz de sevdesk, el anterior queda inmediatamente invalidado. Recibirás un HTTP 401 en tu próxima petición. Muestra un error claro e invita al usuario a introducir su nuevo token en la configuración de tu integración.

¿Es la API de sevdesk adecuada para construir integraciones de software?

Sí. La API REST de sevdesk en /api/v1 está diseñada para integraciones de terceros y cubre todos los objetos contables principales: contactos, facturas, justificantes, notas de crédito y más. Es una base sólida para construir conectividad contable en productos dirigidos al mercado DACH.