Índice
Para quién es este artículo: managers y administración que quieran llevar datos a su ERP Odoo, y sobre todo el equipo de IT o el desarrollador que construye la conexión. La parte de negocio se explica en lenguaje sencillo; la parte técnica está marcada con 🛠️ para IT.
¿Qué es esta integración?
Odoo es un ERP (sistema de gestión empresarial: contabilidad, facturación, CRM, inventario). Golfmanager no tiene un módulo específico de Odoo, pero sí ofrece una API pública con la que Odoo (o cualquier otro sistema) puede leer y escribir datos de tu club de forma segura.
Es decir, la integración con Odoo se construye conectando ambos sistemas a través de la API de Golfmanager, normalmente con la ayuda de tu equipo técnico.
Una API es una "puerta de entrada" controlada para que dos programas se comuniquen. La API de Golfmanager permite a Odoo consultar y crear datos (clientes, ventas, facturas…) sin acceder directamente a la base de datos.
¿Qué problema resuelve?
Lleva los datos del club a Odoo (clientes, ventas, facturas) sin teclearlos a mano.
Centraliza la gestión y la contabilidad en tu ERP.
Evita ficheros intermedios y dobles registros.
Es flexible: tú decides qué datos sincronizar y en qué dirección.
¿Qué sistemas conecta y en qué dirección viajan los datos?
Conecta Odoo con Golfmanager a través de la API. Puede funcionar en los dos sentidos, según lo que programe tu equipo:
De Golfmanager a Odoo: Odoo consulta a la API los clientes, ventas o facturas y los incorpora.
De Odoo a Golfmanager: Odoo crea o actualiza registros en Golfmanager a través de la API.
No es una sincronización automática "de fábrica": es una conexión a medida que se programa una vez y luego funciona sola. Además, Golfmanager admite webhooks para avisar a Odoo cuando ocurre algo (ver "Cómo funciona la conexión").
¿Qué información se puede intercambiar?
A través de la API se puede acceder a la mayoría de datos de Golfmanager. Los más habituales para un ERP son:
Dato | Uso típico en Odoo |
Clientes | Sincronizar la base de clientes/contactos |
Ventas y facturas | Contabilizar ingresos y facturación |
Productos | Mantener el catálogo y los conceptos |
Reservas y pagos | Informes y conciliación |
🛠️ Para IT: por defecto, la API expone todos los modelos y campos en modo lectura, salvo los marcados como no expuestos (api="0") y los de tipo contraseña o cifrado, que nunca se devuelven. Los campos marcados como expuestos (api="1") son el contrato estable y documentado.
Requisitos previos (antes de empezar)
Una clave de API (API Key) de Golfmanager, asociada a un usuario con los permisos adecuados.
El nombre de tu club (tenant), que es la segunda credencial de cada llamada.
Tener Odoo con capacidad de conectarse a servicios externos (módulo a medida o conector).
Un equipo técnico o desarrollador que construya y mantenga la conexión.
Definir qué datos sincronizar y en qué dirección.
Cómo se configura (paso a paso)
Accede a Golfmanager con un usuario administrador.
Entra en Configuración > Usuarios y elige (o crea) el usuario que usará la API. Lo recomendable es un usuario dedicado con solo los permisos necesarios.
Edita ese usuario y pulsa "Regenerar clave de API" para generar su clave de API.
(Opcional) Ajusta los límites de peticiones por minuto y por hora según el volumen que necesite Odoo.
Copia la clave de API y guárdala de forma segura (no se vuelve a mostrar por la API).
Anota el nombre de tu club (tenant): es la segunda credencial.
Si Odoo gestiona varios clubes con una sola clave, usa Configuración > Claves de API para crear una clave global (multi-club) y asociar los clubes y usuarios correspondientes.
Entrega a tu equipo de IT la clave de API, el nombre del club y la URL base; ellos construyen la conexión en Odoo.
Prueba con pocos registros y valida antes de automatizar.
🛠️ Nota técnica (para IT): la API (versión 3) expone los modelos en rutas del tipo /api/model/<nombre-del-modelo> (por ejemplo, /api/model/customer). Cada petición lleva dos cabeceras: key (la clave de API) y tenant (el nombre del club); también se admite Basic Auth (email:clave). Permite listar, filtrar, seleccionar campos, ordenar y paginar, y crear/actualizar/eliminar. Tienes documentación en /api/doc y un entorno de pruebas en /api/playground de tu propio dominio.
Explicación de cada campo
A continuación se describe cada campo relevante de la conexión: dónde está, qué significa, su impacto en el sistema y un ejemplo de uso (qué ocurre cuando se utiliza y cómo se comporta el sistema).
A) La clave de API (en la ficha del usuario)
1. Clave de API (API Key)
Descripción: una cadena secreta asociada a un usuario que identifica y autoriza a Odoo ante la API de Golfmanager.
Impacto en el sistema: es la credencial principal; sin ella no hay acceso. Se genera/regenera desde la ficha del usuario y nunca se devuelve en las respuestas de la API.
Ejemplo de uso: pulsas "Regenerar clave de API", copias el valor y se lo das a tu equipo de IT.
Qué ocurre cuando se utiliza: Odoo la envía en cada petición (cabecera
key) y accede con los permisos de ese usuario.Comportamiento del sistema: si falta o es incorrecta, la API responde "Clave no válida" (Invalid key) o "se requiere la clave de API" y rechaza la llamada. Al regenerarla, la clave anterior deja de funcionar (sirve para revocarla).
2. Peticiones por minuto
Descripción: el número máximo de llamadas por minuto que admite esa clave (por defecto, 30).
Impacto en el sistema: protege el servicio frente a un exceso de llamadas. Lo ajusta un administrador.
Ejemplo de uso: lo subes si Odoo necesita procesar más volumen en poco tiempo.
Qué ocurre cuando se utiliza: cada minuto se cuentan las llamadas de esa clave.
Comportamiento del sistema: al superar el límite, la API responde con error 429 "Rate Limit Exceeded… per minute" y rechaza temporalmente. El valor 0 significa sin límite.
3. Peticiones por hora
Descripción: el número máximo de llamadas por hora de esa clave (por defecto, 1000).
Impacto en el sistema: igual que el límite por minuto, pero en ventana de una hora.
Ejemplo de uso: lo ajustas si la sincronización diaria de Odoo hace muchas llamadas.
Qué ocurre cuando se utiliza: se cuentan las llamadas en cada hora.
Comportamiento del sistema: al superarlo, la API responde "Rate Limit Exceeded… per hour". El valor 0 significa sin límite.
B) Clave de API global / multi-club (Configuración > Claves de API)
4. Clave de API global y clubes (tenants) asociados
Descripción: una clave pensada para acceder a varios clubes con una sola credencial, asociando cada club a un usuario.
Impacto en el sistema: útil cuando un mismo Odoo (o un grupo de clubes) gestiona varios tenants. Se administra en Configuración > Claves de API y la clave se genera automáticamente.
Ejemplo de uso: das de alta la clave y asocias los clubes y el usuario de cada uno.
Qué ocurre cuando se utiliza: con una sola clave, Odoo puede consultar los clubes accesibles (
/api/tenants) y operar en cada uno indicando su nombre.Comportamiento del sistema: si la clave no es de tipo multi-club y se intenta usar como tal, la API responde "Not a multitenant api key".
C) Las dos credenciales de cada llamada (las usa Odoo)
5. Clave (key) y Club (tenant)
Descripción: las dos cabeceras que viajan en cada petición: la clave de API (
key) y el nombre del club (tenant).Impacto en el sistema: ambas son obligatorias: identifican quién llama y a qué club se dirige la operación.
Ejemplo de uso: Odoo añade
key: <tu-clave>ytenant: <nombre-de-tu-club>a cada llamada.Qué ocurre cuando se utiliza: la API valida la clave y dirige la operación al club indicado.
Comportamiento del sistema: si falta el club, responde "Se requiere el club" (Tenant is required); si falta o es errónea la clave, "Clave no válida".
D) Permisos del usuario asociado a la clave
6. Permisos / perfil del usuario de la API
Descripción: la clave de API hereda los permisos del usuario al que pertenece (de su perfil).
Impacto en el sistema: definen qué puede leer, crear o actualizar Odoo. Lo que ese usuario no puede ver, la API tampoco lo devuelve.
Ejemplo de uso: al usuario de la API le das solo lo necesario (por ejemplo, leer clientes y facturas).
Qué ocurre cuando se utiliza: cada llamada respeta esos permisos.
Comportamiento del sistema: si falta permiso, la operación se rechaza; además, ciertos campos (contraseñas, datos cifrados) nunca se exponen, aunque el usuario tenga permiso.
Cómo funciona la conexión
Lectura: Odoo pide a la API la lista de clientes, ventas o facturas. 🛠️ Admite filtros (operadores
=,!=,>,<,like,iny combinaciones AND/OR), selección de campos, orden y paginación (por defecto 20 registros, máximo 100, con cursor para la siguiente página).Escritura: Odoo puede crear, actualizar o eliminar registros en Golfmanager.
Webhooks (avisos en tiempo real): en lugar de preguntar constantemente, Odoo puede recibir un aviso cuando ocurre un evento. 🛠️ Los webhooks van firmados (HMAC-SHA256) y reintentan automáticamente si tu sistema no responde.
Seguridad: cada llamada va firmada con la clave de API y respeta los permisos del usuario asociado.
Límites de uso: la API aplica un máximo de peticiones por minuto/hora (configurable en la clave) para proteger el servicio.
Limitaciones a tener en cuenta
No es un conector "listo para usar": requiere desarrollo en el lado de Odoo.
Necesita mantenimiento por parte de tu equipo técnico.
Respeta permisos y límites de uso: la clave de API solo accede a lo que su usuario puede ver, y dentro de los límites de peticiones.
Algunos campos no se exponen (contraseñas o datos cifrados), aunque el usuario tenga permiso.
🛠️ Los campos de relación devuelven identificadores: para resolver una relación (por ejemplo, el cliente de una factura) puede hacer falta otra llamada.
La responsabilidad de la sincronización (qué, cuándo y cómo) está en la conexión que construyas.
Preguntas frecuentes
¿Existe un conector de Odoo "de fábrica"?
No. Golfmanager no tiene un módulo específico de Odoo. La conexión se construye usando la API pública de Golfmanager, normalmente con tu equipo técnico o un desarrollador.
La conexión da un error de autenticación / "Clave no válida".
La clave de API es incorrecta, está vacía o se regeneró (y la antigua dejó de valer). Comprueba que se envía la clave correcta en la cabecera key y que el nombre del club (tenant) es el adecuado. Si hace falta, regenera la clave en la ficha del usuario y actualízala en Odoo.
Aparece "Se requiere el club" (Tenant is required) o "se requiere la clave de API".
Falta una de las dos credenciales obligatorias. Cada llamada debe enviar la clave y el nombre del club. Revisa que Odoo incluye ambas cabeceras.
Recibo un aviso de exceso de peticiones (error 429 / "Rate Limit Exceeded").
Se han superado los límites de peticiones por minuto o por hora de esa clave. Reduce la frecuencia de las llamadas en Odoo, agrupa operaciones, o pide a un administrador que aumente los límites de la clave (o los ponga sin límite si procede).
Aparece que un modelo "no está expuesto" o "no existe en este tenant".
El modelo que intentas consultar no está disponible vía API o su módulo no está instalado en ese club. Revisa el nombre del modelo y que el módulo correspondiente esté activo en tu Golfmanager.
No veo un campo o un dato que esperaba.
Dos motivos posibles: el usuario de la clave no tiene permiso para ese dato, o el campo no se expone por la API (por ejemplo, contraseñas o datos cifrados). Ajusta los permisos del usuario asociado a la clave; los campos cifrados no se devuelven en ningún caso.
No se crea o no se actualiza un registro.
Suele deberse a que faltan campos obligatorios, a que el usuario no tiene permiso de escritura sobre ese modelo, o a que el cuerpo de la petición va vacío ("Data is empty"). Revisa los datos enviados y los permisos del usuario.
Quiero conectar varios clubes con Odoo. ¿Necesito una clave por club?
Puedes usar una clave de API global (multi-club) desde Configuración > Claves de API, asociando los clubes y un usuario por club. Con una sola clave, Odoo consulta los clubes accesibles e indica en cada llamada a cuál se dirige. Si usas una clave normal como si fuera multi-club, verás "Not a multitenant api key".
¿La API es solo de lectura o también puedo escribir?
Ambas. Odoo puede leer (listar y consultar) y también crear, actualizar o eliminar registros, siempre dentro de los permisos del usuario de la clave.
¿Cómo evito estar preguntando todo el rato por cambios?
Con webhooks: en lugar de consultar la API constantemente, Odoo puede recibir un aviso cuando ocurre un evento. Reduce el número de llamadas y mantiene los datos más al día. Su configuración la hace tu equipo técnico.
¿Dónde puedo probar la API antes de programar la integración?
En tu propio dominio tienes la documentación en /api/doc y un entorno de pruebas ("playground") en /api/playground para lanzar llamadas de ejemplo y ver las respuestas.
¿Cómo revoco una clave si se ha filtrado?
Regenera la clave de API en la ficha del usuario (o en la clave global): la anterior deja de funcionar inmediatamente. Después, actualiza la nueva clave en Odoo.
¿Qué datos puede leer Odoo exactamente?
La mayoría de los modelos del sistema: clientes, ventas, facturas, líneas de factura, productos, reservas, pagos, etc. No se exponen los campos de contraseña ni los cifrados. Los campos documentados como expuestos son el contrato estable.
¿Qué filtros y opciones de consulta hay?
Se puede filtrar con los operadores =, !=, mayor/menor, like e in (y combinaciones AND/OR), elegir qué campos devolver, ordenar y paginar. No se admite SQL libre.
¿Es seguro? ¿Dónde guardo la clave?
La clave es como una contraseña: guárdala en un lugar seguro (no en código compartido ni correos), usa una clave dedicada con permisos mínimos y regénerala si sospechas que se ha filtrado. La clave nunca se devuelve por la API.
Buenas prácticas recomendadas
Usa una clave de API dedicada para la conexión con Odoo, con los permisos justos.
Empieza por una dirección y unos pocos datos (por ejemplo, clientes) y amplía después.
Prueba en el entorno de pruebas (
/api/playground) antes de automatizar.Ajusta los límites de peticiones al volumen real y usa webhooks para reducir llamadas.
Documenta la conexión (qué se sincroniza, cuándo y cómo) para su mantenimiento.