API

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: de cero a tu primera factura en producción.
Ejemplos: 22 casos listos para copiar (simplificadas, intracomunitarias, rectificativas…).
Terminal de pruebas: prueba la API sin crear cuenta.
Estado del servicio: 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 y licencias 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/ o configura un webhook. Si necesitas la respuesta de Hacienda en la misma petición, envía "sincrono": true en POST /tbai/. 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 de todos los métodos.
llms.txt y 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.

TicketBAI Batuz Bizkaia

TicketBAI Gipuzkoa

TicketBAI Araba

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

$ 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'

$ composer require guzzlehttp/guzzle

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-test.ticketbaiws.eus/status/', [
  'body' => '{}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'Token' => 'xxx',
    'Nif' => '00000014Z'
  ],
]);

echo $response->getBody();

$ python -m pip install requests

import requests

url = "https://api-test.ticketbaiws.eus/status/"
headers = {"Accept": "application/json", "Token" : "xxx", "Nif" : "00000014Z"}
response = requests.request("GET", url, headers=headers)
print(response.text)

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-test.ticketbaiws.eus/status/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api-test.ticketbaiws.eus/status/")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Token", "xxx")
  .addHeader("Nif", "00000014Z")
  .build();
  
Response response = client.newCall(request).execute();

{ } Response JSON

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

Documentación de la API REST de TicketBAI y Verifactu

Entornos y URL base

Autenticación

Resultados y respuestas

Envío a Hacienda

Límites de uso

Para agentes de IA y generadores de código

Métodos del API

Métodos TicketBAI / Verifactu

Documento representación

Métodos específicos para BATUZ BIZKAIA

Otros métodos