# Documentación de la API REST de TicketBAI y Verifactu

Con la API REST de Ticketbai WS conectas tu aplicación, tienda online, TPV o ERP con las haciendas vascas (TicketBAI en Araba, Bizkaia/Batuz y Gipuzkoa) y con la Agencia Tributaria AEAT (Verifactu), y generas facturas electrónicas FacturaE para las administraciones públicas.

**¿Empiezas ahora?**

- [Guía rápida](https://ticketbaiws.eus/es/desarrolladores/guia-rapida/): de cero a tu primera factura en producción.
- [Ejemplos](https://ticketbaiws.eus/es/desarrolladores/ejemplos/): 22 casos listos para copiar (simplificadas, intracomunitarias, rectificativas…).
- [Terminal de pruebas](https://ticketbaiws.eus/es/desarrolladores/terminal/): prueba la API sin crear cuenta.
- [Estado del servicio](https://ticketbaiws.eus/es/desarrolladores/estado/): tiempos de respuesta de la API y de cada Hacienda.

## Entornos y URL base

Todos los métodos siguen este patrón:

https://{entorno}.ticketbaiws.eus/{recurso}/

- `POST`  Crear (p. ej. una factura nueva)
- `GET`  Consultar
- `PUT`  Modificar
- `DEL`  Anular

El entorno es **api-test**  para pruebas (los envíos van al entorno de pruebas de Hacienda, sin validez fiscal) y **api**  para producción. Algunos métodos de gestión (empresas, licencias, webhooks y validación de NIF) solo existen en producción.

## Autenticación

Cada petición lleva dos cabeceras: **Token** , el token de la empresa para ese entorno (está en el área privada; hay uno para pruebas y otro para producción), y **Nif** , el NIF del emisor. Los parámetros se envían en un objeto `JSON`  con `Content-Type: application/json`. En los métodos GET también puedes enviarlos en la query string.

Excepción: los métodos de [empresas](https://ticketbaiws.eus/es/empresas-post/) y [licencias](https://ticketbaiws.eus/es/licencias-post/) gestionan tu cuenta y se autentican con el **token de desarrollador**  de tu cuenta de cliente y el NIF de la cuenta, no con los de una empresa.

## Resultados y respuestas

La API responde con HTTP 200 y un objeto con tres variables: **result** , **return**  y **msg** .

- **result** : `OK`, `PENDING` (aceptada y pendiente de envío a Hacienda) o `ERROR`.
- **return** : los datos resultantes (huella, URL de verificación, código QR…).
- **msg** : los mensajes de estado o de error.

Comprueba siempre **result** , no solo el código HTTP.

## Envío a Hacienda

La API responde al momento y el envío a Hacienda se hace en segundo plano. Para saber cómo ha terminado, consulta la factura con [GET /tbai/](https://ticketbaiws.eus/es/ticketbai-get/) o configura un [webhook](https://ticketbaiws.eus/es/webhooks-post/). Si necesitas la respuesta de Hacienda en la misma petición, envía `"sincrono": true` en [POST /tbai/](https://ticketbaiws.eus/es/ticketbai-post/). Los importes de las líneas van **sin IVA** .

## Límites de uso

Si se supera el límite de peticiones, la API responde con HTTP 429. Reintenta con una espera creciente y no consultes el estado en bucle: para eso están los webhooks.

## Para agentes de IA y generadores de código

- [Especificación OpenAPI 3.1](https://api.ticketbaiws.eus/openapi.json) de todos los métodos.
- [llms.txt](https://ticketbaiws.eus/llms.txt) y [llms-full.txt](https://ticketbaiws.eus/llms-full.txt) (toda la documentación en un fichero).
- Cada página de esta documentación tiene versión Markdown: añade `.md` a la URL, p. ej. [es/ticketbai-post.md](https://ticketbaiws.eus/es/ticketbai-post.md).

**GET** `https://{entorno}.ticketbaiws.eus/status/`

```bash
$ curl --request GET \
     --url https://api-test.ticketbaiws.eus/status/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Token: xxx' \
     --header 'Nif: 00000014Z'
```

Respuesta:

```json
HTTP/1.1 200 OK
{
	"result": "OK",
	"return": [],
	"msg": "Ready"
}
```

## Métodos del API

### Métodos TicketBAI / Verifactu

- [`POST`  Nueva factura / subsanación (zuzendu) TicketBAI / Verifactu](https://ticketbaiws.eus/es/ticketbai-post/)
- [`POST`  Completar factura simplificada](https://ticketbaiws.eus/es/tbai-completar-post/)
- [`GET`  Consulta factura TicketBAI / Verifactu](https://ticketbaiws.eus/es/ticketbai-get/)
- [`GET`  Listado facturas TicketBAI / Verifactu](https://ticketbaiws.eus/es/ticketbai-list-get/)
- [`GET`  Descarga XML TicketBAI / Verifactu](https://ticketbaiws.eus/es/ticketbai-xml-get/)
- [`GET`  Descarga factura en formato FacturaE](https://ticketbaiws.eus/es/facturae-get/)
- [`GET`  Descarga factura en PDF](https://ticketbaiws.eus/es/tbai-pdf-get/)
- [`GET`  Estado sistema](https://ticketbaiws.eus/es/status-get/)
- [`DEL`  Anular factura TicketBAI / Verifactu](https://ticketbaiws.eus/es/ticketbai-del/)
- [`PUT`  Forzar reenvío TicketBAI / Verifactu](https://ticketbaiws.eus/es/reset-tbai-put/)
- [`POST`  Validar NIF en la AEAT](https://ticketbaiws.eus/es/validar-nif-post/)
- [`POST`  Validar NIF en el VIES](https://ticketbaiws.eus/es/validar-nif-vies-post/)

### Documento representación

- [`GET`  Documento Representación - Descargar modelo](https://ticketbaiws.eus/es/doc-representante-modelo-get/)
- [`POST`  Documento Representación - Enviar documento](https://ticketbaiws.eus/es/doc-representante-post/)
- [`GET`  Documento Representación - Descargar documento cargado](https://ticketbaiws.eus/es/doc-representante-get/)
- [`DELETE`  Documento Representación - Revocar documento cargado](https://ticketbaiws.eus/es/doc-representante-delete/)

### Métodos específicos para BATUZ BIZKAIA

- [`GET`  Listado de epígrafes](https://ticketbaiws.eus/es/epigrafes-get/)
- [`POST`  LROE - **Facturas recibidas**  - Envío (BATUZ)](https://ticketbaiws.eus/es/lroe-recibidas-post/)
- [`PUT`  LROE - **Facturas recibidas**  - Modificar (BATUZ)](https://ticketbaiws.eus/es/lroe-recibidas-put/)
- [`GET`  LROE - **Facturas recibidas**  - Consulta (BATUZ)](https://ticketbaiws.eus/es/lroe-recibidas-get/)
- [`DEL`  LROE - **Facturas recibidas**  - Anular (BATUZ)](https://ticketbaiws.eus/es/lroe-recibidas-del/)
- [`POST`  LROE - **Criterio Caja COBROS**  - Envío (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-cobros-post/)
- [`PUT`  LROE - **Criterio Caja COBROS**  - Modificar (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-cobros-put/)
- [`GET`  LROE - **Criterio Caja COBROS**  - Consulta (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-cobros-get/)
- [`DEL`  LROE - **Criterio Caja COBROS**  - Anular (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-cobros-del/)
- [`POST`  LROE - **Criterio Caja PAGOS**  - Envío (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-pagos-post/)
- [`PUT`  LROE - **Criterio Caja PAGOS**  - Modificar (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-pagos-put/)
- [`GET`  LROE - **Criterio Caja PAGOS**  - Consulta (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-pagos-get/)
- [`DEL`  LROE - **Criterio Caja PAGOS**  - Anular (BATUZ)](https://ticketbaiws.eus/es/lroe-critcaja-pagos-del/)

### Otros métodos

- [`POST`  Webhooks - Nuevo webhook](https://ticketbaiws.eus/es/webhooks-post/)
- [`PUT`  Webhooks - Modificar webhook](https://ticketbaiws.eus/es/webhooks-put/)
- [`GET`  Webhooks - Consultar webhooks](https://ticketbaiws.eus/es/webhooks-get/)
- [`POST`  Nueva empresa](https://ticketbaiws.eus/es/empresas-post/)
- [`PUT`  Editar datos empresa](https://ticketbaiws.eus/es/empresas-put/)
- [`GET`  Listado de empresas](https://ticketbaiws.eus/es/empresas-get/)
- [`POST`  Nueva licencia](https://ticketbaiws.eus/es/licencias-post/)
- [`GET`  Listado de licencias](https://ticketbaiws.eus/es/licencias-get/)

Fuente: https://ticketbaiws.eus/es/documentacion-api/