API > SPFE - Comunicar pago, cobro, rechazo o impago

SPFE - Comunicar pago, cobro, rechazo o impago

POST https://{entorno}.ticketbaiws.eus/spfe-estados/

La Ley 18/2022 «Crea y Crece» (desarrollada por el RD 238/2026 y la Orden HAC/1028/2026) obliga a expedir las facturas entre empresas y profesionales en formato electrónico y a informar de su estado: pago, cobro, rechazo o impago. Ticketbai WS envía automáticamente a la Solución Pública de Facturación Electrónica (SPFE) de la AEAT las facturas completas a clientes españoles con NIF que emites con el API, en formato UBL, y descarga las facturas que recibes de tus proveedores.

Estos métodos solo están disponibles para las empresas que tienen activado el envío a la SPFE. Se activa en los datos de la empresa del área privada (Factura electrónica B2B) o con el parámetro spfe de los métodos Nueva empresa y Editar datos empresa. Al activarlo se envían las facturas desde ese día.

Este método comunica a la SPFE el estado de una factura:

cobro o impago de una factura que has emitido con Ticketbai WS. Se identifica con serie y numero.
pago o rechazo de una factura que has recibido. Se identifica con factura, fecha_factura, nif_emisor y nombre_emisor: son los mismos campos que devuelve GET spfe-recibidas, así que puedes reenviarlos tal cual.

Por defecto el estado queda en cola y se envía a la AEAT en los próximos minutos (result: PENDING). Consulta después el resultado con GET spfe-estados, o envía sincrono: true para comunicarlo en el momento y recibir ya la respuesta de la AEAT (OK o ERROR, con el detalle en msg). Si la factura emitida aún no ha llegado a la SPFE, el estado espera a que llegue.

Para anular un estado comunicado por error, envía la misma petición con baja: true.

PARÁMETROS

estado string obligatorio Estado a comunicar: cobro → factura emitida cobrada impago → factura emitida impagada al vencimiento pago → factura recibida pagada rechazo → factura recibida rechazada	pago
baja boolean opcional true para anular un estado comunicado anteriormente	false
serie string obligatorio en cobro e impago Serie de la factura emitida con Ticketbai WS	A
numero string obligatorio en cobro e impago Número de la factura emitida con Ticketbai WS	2026000245
factura string obligatorio en pago y rechazo Serie y número de la factura recibida, tal como los informó el emisor	F2026-0153
fecha_factura string obligatorio en pago y rechazo Fecha de expedición de la factura en formato dd/mm/yyyy. En cobro e impago es opcional y solo sirve para distinguir facturas con la misma serie y número	03/11/2026
nif_emisor string obligatorio en pago y rechazo NIF del emisor de la factura recibida	B01000012
nombre_emisor string obligatorio en pago y rechazo Nombre o razón social del emisor de la factura recibida	Empresa de ejemplo S.L.
fecha string opcional Fecha del pago, cobro o rechazo en formato dd/mm/yyyy. No puede ser futura. Por defecto, hoy	10/11/2026
vencimiento string obligatorio en pago e impago Fecha de vencimiento de la factura en formato dd/mm/yyyy (en impago es la fecha en la que debía pagarse). Opcional en cobro	03/12/2026
motivo_rechazo string opcional (rechazo) Motivo del rechazo: 01 → Rechazo comercial (por defecto) 02 → Consumo particular o no afecto a la actividad	01
fecha_recepcion_mercancia string opcional Fecha de recepción de las mercancías o de los servicios prestados (dd/mm/yyyy), si es relevante para el cómputo del plazo de pago (Ley 3/2004 de morosidad)	05/11/2026
fecha_recepcion_factura string opcional Fecha de recepción de la factura (dd/mm/yyyy). Si no se informa, el plazo de pago cuenta desde la fecha de expedición	04/11/2026
financiacion boolean opcional (cobro) El cobro se ha realizado mediante un instrumento de financiación concertado por el emisor	false
rectificada boolean opcional (pago) La factura pagada ha sido rectificada (el pago no tiene por qué coincidir con el importe original)	false
rectificativa_negativa boolean opcional (pago) Factura rectificativa negativa, sin pago asociado	false
sincrono boolean opcional true para enviar el estado a la AEAT en el momento y devolver su respuesta. Por defecto se envía en cola	true

RESPUESTA (return)

id integer Identificador del estado en Ticketbai WS	128
estado / baja Estado comunicado y si es una anulación	pago
factura, fecha_factura, nif_emisor Factura a la que se refiere	F2026-0153
fecha / vencimiento Fechas comunicadas (dd/mm/yyyy)	10/11/2026
result string PENDING en cola, OK aceptado por la AEAT, ERROR rechazado (ver errores)	OK
errores array Lista de errores de la AEAT: codigo y descripcion

POST https://{entorno}.ticketbaiws.eus/spfe-estados/

$ curl --request POST \
     --url https://api-test.ticketbaiws.eus/spfe-estados/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Token: xxx' \
     --header 'Nif: 00000014Z' \
     --data '
{
    "estado": "pago",
    "factura": "F2026-0153",
    "fecha_factura": "03/11/2026",
    "nif_emisor": "B01000012",
    "nombre_emisor": "Empresa de ejemplo S.L.",
    "fecha": "10/11/2026",
    "vencimiento": "03/12/2026",
    "sincrono": true
}'

$ composer require guzzlehttp/guzzle

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api-test.ticketbaiws.eus/spfe-estados/', [
  'body' => '{"estado": "pago", "factura": "F2026-0153", "fecha_factura": "03/11/2026", "nif_emisor": "B01000012", "nombre_emisor": "Empresa de ejemplo S.L.", "fecha": "10/11/2026", "vencimiento": "03/12/2026", "sincrono": true}',
  '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/spfe-estados/"
payload = {
    "estado": "pago",
    "factura": "F2026-0153",
    "fecha_factura": "03/11/2026",
    "nif_emisor": "B01000012",
    "nombre_emisor": "Empresa de ejemplo S.L.",
    "fecha": "10/11/2026",
    "vencimiento": "03/12/2026",
    "sincrono": True
}
headers = {"Accept": "application/json", "Content-Type": "application/json", "Token": "xxx", "Nif": "00000014Z"}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-test.ticketbaiws.eus/spfe-estados/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Accept: application/json");
headers = curl_slist_append(headers, "Content-Type: application/json");
headers = curl_slist_append(headers, "Token: xxx");
headers = curl_slist_append(headers, "Nif: 00000014Z");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"estado\": \"pago\", \"factura\": \"F2026-0153\", \"fecha_factura\": \"03/11/2026\", \"nif_emisor\": \"B01000012\", \"nombre_emisor\": \"Empresa de ejemplo S.L.\", \"fecha\": \"10/11/2026\", \"vencimiento\": \"03/12/2026\", \"sincrono\": true}");

CURLcode ret = curl_easy_perform(hnd);

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"estado\": \"pago\", \"factura\": \"F2026-0153\", \"fecha_factura\": \"03/11/2026\", \"nif_emisor\": \"B01000012\", \"nombre_emisor\": \"Empresa de ejemplo S.L.\", \"fecha\": \"10/11/2026\", \"vencimiento\": \"03/12/2026\", \"sincrono\": true}");
Request request = new Request.Builder()
  .url("https://api-test.ticketbaiws.eus/spfe-estados/")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "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": {
        "id": 128,
        "estado": "pago",
        "baja": false,
        "factura": "F2026-0153",
        "fecha_factura": "03\/11\/2026",
        "nif_emisor": "B01000012",
        "fecha": "10\/11\/2026",
        "vencimiento": "03\/12\/2026",
        "result": "OK",
        "errores": []
    },
    "msg": null
}

{ } Response en cola (sin sincrono) JSON

HTTP/1.1 200 OK
{
    "result": "PENDING",
    "return": {
        "id": 129,
        "estado": "pago",
        "baja": false,
        "factura": "F2026-0153",
        "fecha_factura": "03\/11\/2026",
        "nif_emisor": "B01000012",
        "fecha": "10\/11\/2026",
        "vencimiento": "03\/12\/2026",
        "result": "PENDING",
        "errores": []
    },
    "msg": null
}

{ } Response con error de la AEAT JSON

HTTP/1.1 200 OK
{
    "result": "ERROR",
    "return": {
        "id": 130,
        "estado": "pago",
        "baja": false,
        "factura": "F2026-0153",
        "fecha_factura": "03\/11\/2026",
        "nif_emisor": "B01000012",
        "fecha": "10\/11\/2026",
        "vencimiento": "03\/12\/2026",
        "result": "ERROR",
        "errores": [
            {
                "codigo": "SPFE-ACTION-01",
                "descripcion": "No existe factura sobre la que actuar"
            }
        ]
    },
    "msg": "SPFE-ACTION-01: No existe factura sobre la que actuar"
}

SPFE - Comunicar pago, cobro, rechazo o impago

Métodos TicketBAI / Verifactu

Documento representación

Métodos específicos para BATUZ BIZKAIA

Factura electrónica B2B - SPFE (Ley Crea y Crece)

Otros métodos