- Verifacturacion

Documentación API

Middleware Verifactu API

Versión 1.0.8

API para gestion de facturacion electronica con Verifactu

🔐 Autenticación

Todas las peticiones (excepto /api/health) requieren 3 headers de autenticación.

Obtén tus credencialesAccede a clientes.verifacturacion.com, ve a «Mi cuenta» y copia tu API Key y Secret.

Genera la firma antes de cada peticiónLa firma caduca a los 5 minutos — calcula una nueva en cada llamada.

Incluye los 3 headers en cada peticiónVer tabla de headers más abajo.

// PHP — genera los headers de autenticación
$apiKey    = 'tu_api_key';
$secret    = 'tu_secret';
$timestamp = time();

$message   = $apiKey . ':' . $timestamp;
$signature = hash_hmac('sha256', $message, $secret);

// Headers que debes incluir en cada petición:
// X-Api-Key: $apiKey
// X-Timestamp: $timestamp
// X-Signature: $signature

Header	Requerido	Descripción
X-Api-Key	obligatorio	Clave de API del cliente, obtenida en el panel de cliente.
X-Timestamp	obligatorio	Timestamp Unix de la peticion (segundos desde 1970).
X-Signature	obligatorio	Firma HMAC-SHA256 calculada con la clave secreta del cliente.

📋 Endpoints

POST /api/invoice/create 🔒

Crear una factura

Crea y registra una nueva factura en el sistema Verifactu. Requiere autenticacion HMAC.

Request Body

Campo

Tipo

Descripción

prestashopId

string

Identificador de la factura/pedido en el sistema de origen

Ej: API_WEBHOOK_TEST_001

invoice_data *

object

Datos de la factura. Para notas de credito usar credit_slip_data con la misma estructura

invoice_data. number *

string

Ej: API-WEBHOOK-TEST-001

invoice_data. total_paid_tax_incl *

number (float)

Ej: 121

invoice_data. total_paid_tax_excl

number (float)

Ej: 100

invoice_data. total_products_tax_excl

number (float)

Usado para calcular la base si no se envia total_paid_tax_excl

invoice_data. total_products_tax_incl

number (float)

invoice_data. total_shipping_tax_excl

number (float)

invoice_data. total_shipping_tax_incl

number (float)

invoice_data. total_discount_tax_excl

number (float)

invoice_data. total_discount_tax_incl

number (float)

invoice_data. total_wrapping_tax_excl

number (float)

invoice_data. total_wrapping_tax_incl

number (float)

invoice_data. shipping_tax_rate

number (float)

invoice_data. discount_tax_rate

number (float)

invoice_data. wrapping_tax_rate

number (float)

invoice_data. partial

Presencia de este campo marca la factura como nota de credito parcial

invoice_data. order_slip_type

string

Presencia de este campo marca la factura como nota de credito

invoice_data. note

string

order_data

object

order_data. invoice_date

string (date-time)

Ej: 2025-10-23T21:32:19+02:00

order_data. reference

string

invoice_address *

object

invoice_address. company

string

Ej: API Test Company S.L.

invoice_address. vat_number

string

CIF/VAT del destinatario. Requerido para operaciones intracomunitarias

Ej: B99999999

invoice_address. dni

string

DNI del destinatario, alternativo a vat_number para persona fisica

invoice_address. country_iso *

string

Codigo ISO del pais (ej. ES). Obligatorio

Ej: ES

invoice_address. postcode

string

Usado para detectar Canarias/Ceuta/Melilla

invoice_address. firstname

string

invoice_address. lastname

string

taxes *

array

Lineas de IVA. La suma de base y amount debe ser consistente con los totales de invoice_data

taxes[]. base

number (float)

Ej: 100

taxes[]. rate

number (float)

Ej: 21

taxes[]. amount

number (float)

Ej: 21

invoice_relationships

object

Solo para notas de credito/rectificativas

invoice_relationships. parent_invoice_id

string

invoice_relationships. original_invoice_number

string

invoice_relationships. original_invoice_date

string (date-time)

metadata

object

metadata. exemption_reason

string

metadata. shop_domain_webhook

string

URL a la que se notificara la creacion de la factura

metadata. shop_domain

string

metadata. prestashop_version

string

metadata. module_version

string

Respuestas

201 Factura creada exitosamente

400 Datos invalidos (formato incorrecto, pais no especificado, NIF invalido, campos obligatorios faltantes o datos inconsistentes)

401 Autenticacion HMAC ausente o invalida

422 No se pudo determinar el tipo de factura o la estrategia de operacion de IVA

500 Error inesperado del servidor

POST /api/invoice/getInvoice 🔒

Consultar una factura

Consulta el estado y los datos de una factura previamente registrada, a partir de su UUID. Requiere autenticacion HMAC.

Request Body

Campo

Tipo

Descripción

invoice_id *

string

UUID de la factura a consultar

Ej: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Respuestas

200 Factura encontrada

400 Formato invalido o invoice_id ausente/vacio/no valido

404 No existe ninguna factura con el invoice_id proporcionado

500 Error inesperado del servidor

GET /api/health

Health check del servicio

Verifica que el servicio esta funcionando correctamente. No requiere autenticacion.

Respuestas

200 Servicio funcionando correctamente