Referencia de la API (beta)
La API de To Bill es la que usa la propia app: clientes, facturas, presupuestos, artículos, gastos, banco, contabilidad, IVA, salarios y tiempo. Una clave API personal la abre a sus scripts y herramientas, con sus permisos. La referencia interactiva de la API describe cada ruta que una clave puede llamar, sus parámetros y respuestas, ofrece ejemplos en curl, JavaScript, Python y PHP, y le permite probar una solicitud con su clave.
La referencia está en inglés
Como la mayoría de las referencias técnicas, está redactada en inglés, el idioma de los desarrolladores. Esta página resume lo esencial.
Una versión beta
La API está en versión beta (0.x). Sus rutas y sus respuestas pueden cambiar sin previo aviso: no hay garantía de compatibilidad ni soporte para su uso directo. Para conectar un asistente de IA, utilice el servidor MCP, que es la interfaz estable: consulte Conectar un asistente de IA.
Autenticarse
Cada solicitud lleva una clave API personal en el encabezado HTTP Authorization:
curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"La clave se crea en Configuración › Conexiones IA y API: consulte La API y las claves API. Actúa en su nombre, en la empresa donde la creó, con sus permisos en esa empresa. Una clave Solo lectura solo envía solicitudes de lectura (GET); una clave Lectura y modificación también puede crear, modificar y eliminar.
Los errores
Una solicitud rechazada recibe una respuesta JSON de esta forma: { "statusMessage": "error", "message": "…", "error_code": "…", "fallback": "…" }. message es un código estable que su programa puede comprobar; fallback es una frase legible, por ejemplo con el campo en cuestión.
| Código HTTP | Significado |
|---|---|
| 400 | Datos no válidos. |
| 401 | Clave ausente, no válida, caducada o revocada. |
| 403 | Rechazada: clave de solo lectura, permiso que falta, suscripción sin acceso a la API, o parte de To Bill cerrada a las claves (not_available_with_api_token). |
| 404 | No encontrado en esta empresa. |
| 429 | Demasiadas solicitudes: espere el número de segundos indicado en el encabezado Retry-After. |
Los límites
- 300 solicitudes por minuto y por clave; una modificación cuenta doble.
- Una clave no abre ni el inicio de sesión en su cuenta, ni la suscripción, ni los pagos, ni la gestión del equipo y de las claves, ni otra empresa, ni el cockpit de una fiduciaria, ni las acciones masivas. Estas rutas no figuran en la referencia.
La especificación OpenAPI
La referencia se genera a partir del documento OpenAPI 3.1 de la API. Puede importarlo en una herramienta como Postman o generar un cliente a partir de él:
| Qué | Dirección |
|---|---|
| Referencia interactiva | https://docs.tobill.ch/api |
| Especificación OpenAPI 3.1 | https://app.tobill.ch/api/openapi.json |
Probar una solicitud
En la referencia, el botón Test Request envía la solicitud desde su navegador directamente a https://app.tobill.ch, sin intermediarios. Su clave solo va a To Bill y no se guarda: desaparece cuando cierra la página. Una solicitud de modificación modifica realmente sus datos: para descubrir la API, pruébela con una clave Solo lectura.