Servidor MCP
Conecta tu asistente de IA (Claude, Cursor, VS Code…) a la API de Ticketbai WS con el Model Context Protocol. Cada método de la API es una herramienta: emite, consulta y anula facturas TicketBAI y Verifactu desde el chat.
Direcciones
| Entorno | URL del servidor MCP |
|---|---|
| Pruebas | https://api-test.ticketbaiws.eus/mcp-api |
| Producción | https://api.ticketbaiws.eus/mcp-api |
Gestión de empresas y licencias: estos métodos se autentican con el token de desarrollador de tu cuenta de cliente (no con el de una empresa), así que tienen su propio servidor: https://api.ticketbaiws.eus/mcp-api/cuenta, con el token de desarrollador y el NIF de la cuenta en las mismas cabeceras. Añádelo como un segundo conector.
Empieza siempre en pruebas. En producción las facturas tienen validez fiscal y se envían a Hacienda: pide al asistente que te confirme cada factura antes de emitirla.
Conectar tu asistente
Solo necesitas la URL. Al añadir el conector, tu asistente te abre una ventana de Ticketbai WS: inicias sesión con tu cuenta, eliges la empresa y das acceso. No tienes que copiar tokens ni configurar cabeceras.
Claude (claude.ai y Claude Desktop)
- En Ajustes → Conectores, añade un conector personalizado con la URL del servidor MCP.
- Pulsa Conectar, inicia sesión con tu cuenta de Ticketbai WS y elige la empresa.
ChatGPT
- Añade un conector personalizado con la URL del servidor MCP (según tu plan, puede que tengas que activar el modo desarrollador de los conectores).
- Elige autenticación OAuth, inicia sesión con tu cuenta de Ticketbai WS y elige la empresa.
Claude Code
claude mcp add --transport http ticketbaiws-test https://api-test.ticketbaiws.eus/mcp-api
Después, dentro de Claude Code, escribe /mcp y elige Authenticate para iniciar sesión.
Cursor, VS Code y otros clientes
Añade la URL del servidor MCP. Si tu cliente admite OAuth, te pedirá iniciar sesión; si no, usa las cabeceras (abajo).
Una conexión por empresa y entorno. El acceso que das vale solo para la empresa que eliges y solo para el entorno de la URL (pruebas o producción). Si gestionas varias empresas, añade un conector por empresa. Para la gestión de empresas y licencias usa https://api.ticketbaiws.eus/mcp-api/cuenta e inicia sesión con tu cuenta de cliente.
Alternativa: cabeceras con tu token
Para clientes sin OAuth o para automatizaciones, el servidor sigue aceptando el token de la empresa en cabeceras HTTP, como la API REST: Token y Nif. Si tu cliente solo deja elegir cabeceras de una lista, usa X-API-Token y X-Client-ID; si solo permite Authorization, envía Authorization: Bearer TU_NIF:TU_TOKEN.
claude mcp add --transport http ticketbaiws-test https://api-test.ticketbaiws.eus/mcp-api \
--header "Token: TU_TOKEN_DE_TEST" \
--header "Nif: TU_NIF"
El servidor no guarda tu token ni accede a nada que no puedas hacer con la API: cada herramienta hace la misma llamada REST que harías tú, con los mismos límites de uso.
Ejemplos de lo que puedes pedir
Mira conversaciones completas, con las herramientas que usa el asistente, en los casos de uso del servidor MCP.
- «Emite un ticket de 12,10 € IVA incluido, serie T, con un café y un bocadillo.»
- «¿Cómo ha terminado en Hacienda la factura A-2026-0042?»
- «Lista las facturas de ayer que tengan errores.»
- «Anula la factura T-118 y dime la huella de la anulación.»
Herramientas
Son los métodos de la documentación del API, con los mismos parámetros. Algunos métodos de gestión solo existen en producción.
Facturas TicketBAI / Verifactu
ticketbai_post: Nueva factura TicketBAI / Verifactu (POST /tbai/)ticketbai_get: Consulta factura TicketBAI (GET /tbai/)ticketbai_del: Anular factura TicketBAI (DELETE /tbai/)tbai_completar_post: TicketBAI - Completar factura simplificada (POST /tbai-completar/)ticketbai_list_get: Listado facturas TicketBAI (GET /tbai-list/)ticketbai_xml_get: Descarga XML TicketBAI (GET /tbai-xml/)facturae_get: Descarga en formato FacturaE (GET /facturae/, solo producción)tbai_pdf_get: Descarga en formato PDF (GET /tbai-pdf/)status_get: Estado del sistema (GET /status/)reset_tbai_put: Reset envío TBAI (PUT /reset-tbai/)validar_nif_post: Validar NIF en la AEAT (POST /validar-nif/, solo producción)validar_nif_vies_post: Validar NIF en el VIES (POST /validar-nif-vies/, solo producción)
Documento de representación (Verifactu, Bizkaia, Gipuzkoa)
doc_representante_modelo_get: Documento de representación - Descargar modelo (GET /doc-representante/modelo/)doc_representante_post: Documento de representación - Enviar documento (POST /doc-representante/)doc_representante_get: Documento de representación - Descargar documento cargado (GET /doc-representante/)doc_representante_delete: Documento de representación - Revocar documento cargado (DELETE /doc-representante/)
Batuz Bizkaia (LROE)
epigrafes_get: Listado epígrafes (GET /epigrafes/, solo producción)lroe_recibidas_post: LROE - Envío de facturas recibidas (POST /lroe-recibidas/)lroe_recibidas_put: LROE - Modificar facturas recibidas (PUT /lroe-recibidas/)lroe_recibidas_get: LROE - Consulta de facturas recibidas (GET /lroe-recibidas/)lroe_recibidas_del: LROE - Anular facturas recibidas (DELETE /lroe-recibidas/)lroe_gastos_sin_factura_post: LROE - Envío de gastos sin factura (POST /lroe-gastos-sinfactura/)lroe_gastos_sin_factura_put: LROE - Modificar gastos sin factura (PUT /lroe-gastos-sinfactura/)lroe_gastos_sin_factura_get: LROE - Consulta de gastos sin factura (GET /lroe-gastos-sinfactura/)lroe_gastos_sin_factura_del: LROE - Anular gastos sin factura (DELETE /lroe-gastos-sinfactura/)lroe_critcaja_cobros_post: LROE - Criterio de caja - COBROS - Envío de cobros (POST /lroe-critcaja-cobros/)lroe_critcaja_cobros_put: LROE - Criterio de caja - COBROS - Modificar cobros (PUT /lroe-critcaja-cobros/)lroe_critcaja_cobros_get: LROE - Criterio de caja - COBROS - Consulta de cobros (GET /lroe-critcaja-cobros/)lroe_critcaja_cobros_del: LROE - Criterio de caja - COBROS - Anulación de cobros (DELETE /lroe-critcaja-cobros/)lroe_critcaja_pagos_post: LROE - Criterio de caja - PAGOS - Envío de pagos (POST /lroe-critcaja-pagos/)lroe_critcaja_pagos_put: LROE - Criterio de caja - PAGOS - Modificar pagos (PUT /lroe-critcaja-pagos/)lroe_critcaja_pagos_get: LROE - Criterio de caja - PAGOS - Consulta de pagos (GET /lroe-critcaja-pagos/)lroe_critcaja_pagos_del: LROE - Criterio de caja - PAGOS - Anulación de pagos (DELETE /lroe-critcaja-pagos/)
Webhooks, empresas y licencias
webhooks_post: Webhooks - Nuevo webhook (POST /webhooks/)webhooks_get: Webhooks - Consultar webhooks (GET /webhooks/)webhooks_put: Webhooks - Modificar webhook (PUT /webhooks/{codigo_webhook}/)empresas_post: Nueva empresa (POST /empresas/, servidor de cuenta)empresas_get: Listado empresas (GET /empresas/, servidor de cuenta)licencias_post: Nueva licencia (POST /licencias/, servidor de cuenta)licencias_get: Consulta licencias (GET /licencias/, servidor de cuenta)empresas_put: Editar datos empresa (PUT /empresas/{nif}/, servidor de cuenta)
Factura electrónica B2B (SPFE)
spfe_estados_post: SPFE - Comunicar pago, cobro, rechazo o impago (POST /spfe-estados/)spfe_estados_get: SPFE - Consulta de pagos, cobros, rechazos e impagos (GET /spfe-estados/)spfe_recibidas_get: SPFE - Facturas recibidas (GET /spfe-recibidas/)
Buenas prácticas
- Si alguna herramienta devuelve
TOKEN error, pide al asistente que usecomprobar_conexion: te dirá el entorno, qué cabeceras han llegado, el NIF recibido y los 4 últimos caracteres del token. - El envío a Hacienda es asíncrono: después de emitir, el asistente debe consultar el estado con
ticketbai_get(o puedes configurar un webhook). - Los importes de las líneas van sin IVA y las fechas en formato dd/mm/yyyy. Los ejemplos sirven también como referencia para el asistente.
- Si recibes HTTP 429, se ha superado el límite de peticiones: espera antes de reintentar.
- La especificación completa está en openapi.json.
