# Ticketbai WS

> API REST para emitir facturas TicketBAI (Araba, Bizkaia/Batuz y Gipuzkoa) y Verifactu (AEAT) desde cualquier tienda online, TPV o ERP. Ticketbai WS firma el XML, lo encadena, lo envía a Hacienda y devuelve la huella, la URL de cotejo y el QR. Servicio de Berein Internet S.L. (Vitoria-Gasteiz), colaborador social de la AEAT y de la Diputación Foral de Gipuzkoa.

Puntos clave para integrar la API:
- URL base: `https://api-test.ticketbaiws.eus` (pruebas) y `https://api.ticketbaiws.eus` (producción).
- Autenticación: cabeceras `Token` (token de test o real de la empresa) y `Nif` (NIF emisor). Cuerpo en JSON. Los métodos de empresas y licencias usan el token de desarrollador y el NIF de la cuenta de cliente.
- La API responde siempre con HTTP 200; el resultado está en `result`: `OK`, `PENDING` (Verifactu en cola) o `ERROR` (motivos en `msg`).
- Los importes de las líneas van sin IVA. El envío a Hacienda se hace en segundo plano salvo que se pida `"sincrono": true`.
- Para enviar en producción con el certificado de Ticketbai WS, cada empresa autoriza a Ticketbai WS una sola vez: en Verifactu, Bizkaia y Gipuzkoa firmando el documento de representación (área privada o métodos `/doc-representante/`); en Araba registrando el certificado de dispositivo en la sede de la Diputación. También puede cargar su propio certificado.

## Especificación para agentes

- [OpenAPI 3.1](https://api.ticketbaiws.eus/openapi.json): todos los métodos, parámetros, autenticación y ejemplos de respuesta
- [Documentación completa del API](https://ticketbaiws.eus/llms-full.txt): todas las páginas de la documentación en un solo fichero Markdown
- [Servidor MCP](https://ticketbaiws.eus/es/desarrolladores/mcp/): `https://api-test.ticketbaiws.eus/mcp-api` (pruebas) y `https://api.ticketbaiws.eus/mcp-api` (producción); una herramienta por método del API; autenticación OAuth 2.1 (el usuario inicia sesión con su cuenta de Ticketbai WS y elige la empresa) o con las cabeceras `Token` y `Nif` (o `X-API-Token` y `X-Client-ID`); la gestión de empresas y licencias va en `https://api.ticketbaiws.eus/mcp-api/cuenta` con el token de desarrollador de la cuenta ([Markdown](https://ticketbaiws.eus/es/desarrolladores/mcp.md))
- [Casos de uso del servidor MCP](https://ticketbaiws.eus/es/desarrolladores/casos-de-uso-mcp/): conversaciones de ejemplo (emitir una factura, registrar un gasto en el LROE, enviar facturas a la gestoría o al cliente) con las herramientas que se usan en cada caso
- [Índice de la documentación en Markdown](https://ticketbaiws.eus/es/documentacion-api.md): cada página del API tiene versión Markdown añadiendo `.md` a su URL (p. ej. `/es/ticketbai-post.md`)

## Desarrolladores

- [Guía rápida de integración](https://ticketbaiws.eus/es/desarrolladores/guia-rapida/): de cero a producción en siete pasos ([Markdown](https://ticketbaiws.eus/es/desarrolladores/guia-rapida.md))
- [Ejemplos de la API](https://ticketbaiws.eus/es/desarrolladores/ejemplos/): 22 casos con JSON y código (simplificadas, intracomunitarias, OSS, exportaciones, exentas, recargo de equivalencia, rectificativas, subsanación, anulación) ([Markdown](https://ticketbaiws.eus/es/desarrolladores/ejemplos.md))
- [Terminal de pruebas](https://ticketbaiws.eus/es/desarrolladores/terminal/): simulador sin cuenta con las validaciones y mensajes de error reales
- [Estado del servicio](https://ticketbaiws.eus/es/desarrolladores/estado/): tiempos de respuesta de la API y de cada Hacienda

## Documentación de la API

- [Documentación de la API](https://ticketbaiws.eus/es/documentacion-api/): autenticación, formato de respuesta y lista de endpoints
- [Nueva factura o subsanación (POST /tbai/)](https://ticketbaiws.eus/es/ticketbai-post/): campos del alta de factura TicketBAI y Verifactu
- [Consultar una factura](https://ticketbaiws.eus/es/ticketbai-get/): estado en Hacienda, huella, URL de cotejo y QR
- [Listado de facturas](https://ticketbaiws.eus/es/ticketbai-list-get/)
- [Anular una factura](https://ticketbaiws.eus/es/ticketbai-del/)
- [Descargar el XML](https://ticketbaiws.eus/es/ticketbai-xml-get/)
- [Descargar la factura en PDF](https://ticketbaiws.eus/es/tbai-pdf-get/)
- [Completar una factura simplificada](https://ticketbaiws.eus/es/tbai-completar-post/)
- [Webhooks](https://ticketbaiws.eus/es/webhooks-post/): aviso del cambio de estado de una factura en los envíos asíncronos (firma HMAC SHA256)
- [Estado del sistema (GET /status/)](https://ticketbaiws.eus/es/status-get/)
- [Autorizar a Ticketbai WS ante tu Hacienda](https://ticketbaiws.eus/es/registro-de-certificado-de-dispositivo/): qué hay que hacer en Araba, Bizkaia, Gipuzkoa y Verifactu antes de pasar a producción
- [Documento de representación (GET /doc-representante/modelo/)](https://ticketbaiws.eus/es/doc-representante-modelo-get/): descargar, enviar, consultar y revocar el documento de representación (Verifactu, Bizkaia y Gipuzkoa)

## Normativa

- [Qué es Verifactu](https://ticketbaiws.eus/es/que-es-verifactu/): plazos, obligados y diferencias con TicketBAI
- [Qué es TicketBAI](https://ticketbaiws.eus/es/que-es-ticketbai/): funcionamiento y calendario por territorio

## Integraciones

- [App para Shopify](https://ticketbaiws.eus/es/guia-app/): guía de instalación y uso de la app (Shopify y Shopify POS)
- [Integración con WooCommerce](https://ticketbaiws.eus/es/integracion-woocommerce/)

## Opcional

- [Tarifas](https://ticketbaiws.eus/es/tarifas/)
- [Preguntas frecuentes](https://ticketbaiws.eus/es/faqs/)
- [Contacto](https://ticketbaiws.eus/es/contacto/)