Facturación

El módulo de facturación es el núcleo de Certifactu. Permite firmar, registrar y enviar facturas cumpliendo con los requisitos de Veri*Factu en una única petición.

¿Qué hace el endpoint /invoices/sign?

Calcula la huella digital

Genera el hash SHA-256 encadenado con la factura anterior de la misma serie.

Genera el XML

Crea el documento XML de alta de factura según el esquema de la AEAT.

Firma electrónicamente

Aplica firma XAdES cualificada con certificado de persona jurídica.

Genera el código QR

Crea la URL de verificación y el código QR para incluir en la factura.

Encola envío a AEAT

Programa el envío automático del registro a la Agencia Tributaria.

Crear y Firmar Factura

Este endpoint realiza todo el proceso de cumplimiento Veri*Factu en un solo paso. Envía los datos de tu factura y recibe la firma, el hash encadenado y el código QR listos para usar.

POST /invoices/sign

Firma una factura y prepara su envío a la AEAT

Parámetros del Request

Datos de la factura

series string opcional

Serie de la factura. Recomendado para organizar las facturas por tipo o año (ej: F2024, R2024).

number string requerido

Número secuencial de la factura dentro de la serie.

issue_date string requerido

Fecha de emisión en formato ISO 8601 (YYYY-MM-DD).

issuer_nif string requerido

NIF del emisor. Debe coincidir con el NIF asociado a la API Key.

issuer_name string requerido

Nombre o Razón Social del emisor.

recipient_nif string opcional

NIF del receptor. Obligatorio para facturas completas (F1).

recipient_name string requerido

Nombre o Razón Social del receptor.

tipo_factura enum requerido

Tipo de factura: F1 (Completa), F2 (Simplificada), R1-R5 (Rectificativas).

clave_regimen_iva string requerido

Clave del régimen de IVA aplicable (01 = Régimen general).

descripcion string requerido

Descripción general de la operación.

lineas array requerido

Array con las líneas de detalle de la factura.

Campos de cada línea

descripcion string requerido

Descripción del producto o servicio.

cantidad number requerido

Cantidad de unidades.

precio_unitario number requerido

Precio por unidad sin impuestos.

importe_total number requerido

Importe total de la línea (cantidad × precio).

tipo_impositivo number requerido

Tipo de IVA aplicado (21, 10, 4, 0).

cuota_iva number requerido

Cuota de IVA calculada.

Ejemplo Completo

Crear factura completa (F1)

curl -X POST https://api.certifactu.com/api/v1/invoices/sign \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "series": "F2024",
    "number": "001",
    "issue_date": "2024-01-15",
    "issuer_nif": "B12345678",
    "issuer_name": "Mi Empresa S.L.",
    "recipient_nif": "A98765432",
    "recipient_name": "Cliente Ejemplo S.A.",
    "tipo_factura": "F1",
    "clave_regimen_iva": "01",
    "descripcion": "Servicios de consultoría",
    "base_imponible_total": 1000.00,
    "cuota_iva_total": 210.00,
    "total_amount": 1210.00,
    "lineas": [
      {
        "descripcion": "Consultoría IT",
        "cantidad": 1,
        "precio_unitario": 1000.00,
        "importe_total": 1000.00,
        "tipo_impositivo": 21.00,
        "cuota_iva": 210.00
      }
    ]
  }'

Respuesta Exitosa

{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "chain_hash": "ABC123DEF456789...",
  "previous_hash": "DEF456ABC123789...",
  "signature_status": "SIGNED",
  "aeat_status": "QUEUED",
  "aeat_qr_url": "https://sede.agenciatributaria.gob.es/...",
  "qr_image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Verificar Factura

Verifica la integridad de una factura, comprobando su firma electrónica y su correcto encadenamiento con facturas anteriores.

POST /invoices/verify

Verifica la integridad y firma de una factura

Verificar factura

curl -X POST https://api.certifactu.com/api/v1/invoices/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "invoice_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Respuesta

{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "signature_valid": true,
  "chain_valid": true,
  "aeat_status": "ACCEPTED",
  "aeat_csv": "CSV123456789ABCDEF"
}

Cancelar Factura

Realiza la anulación lógica de una factura, generando el registro de anulación correspondiente para enviar a la AEAT.

POST /invoices/{invoice_id}/cancel

Anula una factura y registra la cancelación

Cancelar factura

curl -X POST https://api.certifactu.com/api/v1/invoices/550e8400.../cancel \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "reason": "Error en datos del cliente"
  }'

Tipos de Factura

La normativa Veri*Factu define los siguientes tipos de factura:

F1 Factura Completa

Factura estándar con todos los datos del emisor y receptor.

F2 Factura Simplificada

Equivalente al ticket. No requiere datos del receptor.

R1 Rectificativa (Art. 80.1-2)

Corrige errores en base imponible o cuota.

R2 Rectificativa (Art. 80.3)

Por concurso de acreedores.

R3 Rectificativa (Art. 80.4)

Por créditos incobrables.

R4 Rectificativa (Resto)

Resto de casos de rectificación.