El recurso invoices te permite gestionar las facturas de venta de tu empresa. Puedes crear facturas, consultarlas, actualizarlas, eliminarlas, registrar pagos y enviarlas por email.

Este artículo incluye ejemplos prácticos para los casos de uso más comunes: facturas con distintos tipos de IVA, con retención IRPF, con suplidos, con precios IVA incluido y con pagos.

💡 Recomendación: Antes de empezar a desarrollar, te recomendamos crear un entorno de pruebas (sandbox) para hacer tus primeras llamadas sin afectar tus datos reales.

Endpoints disponibles

Método	Endpoint	Descripción
GET	/{companyId}/invoices	Lista de facturas (con filtros y paginación)
POST	/{companyId}/invoices	Crear una factura
GET	/{companyId}/invoices/{id}	Obtener una factura por ID
PUT	/{companyId}/invoices/{id}	Actualizar una factura
DELETE	/{companyId}/invoices/{id}	Eliminar una factura
POST	/{companyId}/invoices/{id}/payments	Registrar pagos en una factura
PUT	/{companyId}/invoices/{id}/pdf	Generar PDF de la factura
PUT	/{companyId}/invoices/{id}/send	Enviar factura por email
PUT	/{companyId}/invoices/{id}/tags	Actualizar etiquetas de la factura
PUT	/{companyId}/invoices/{id}/facturae	Generar factura en formato Facturae

Ejemplos de código

Los siguientes ejemplos muestran cómo crear facturas para diferentes casos de uso. Todos los ejemplos usan el método POST a /{companyId}/invoices.

Factura básica (minimal)

El caso más simple: una factura con una sola línea y un tipo de IVA.

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "invoice",
      "main": {
        "docNumber": {
          "series": "F"
        },
        "contact": "con_10000000-0000-4000-8000-000000000000",
        "currency": "EUR",
        "lines": [
          {
            "quantity": 1,
            "unitPrice": 100,
            "tax": ["S_IVA_21"],
            "text": "Descripción del servicio"
          }
        ]
      }
    }
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/invoices

Resultado: Una factura de 100€ + 21% IVA = 121€ total.

Factura con varios tipos de IVA

Cuando vendes productos con distintos tipos impositivos (21%, 10%, 4%).

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 100,
          "tax": ["S_IVA_21"],
          "text": "Producto IVA 21%"
        },
        {
          "quantity": 1,
          "unitPrice": 50,
          "tax": ["S_IVA_10"],
          "text": "Producto IVA 10%"
        },
        {
          "quantity": 1,
          "unitPrice": 20,
          "tax": ["S_IVA_4"],
          "text": "Producto IVA 4%"
        }
      ]
    }
  }
}

Resultado:

Línea 1: 100€ + 21€ IVA
Línea 2: 50€ + 5€ IVA
Línea 3: 20€ + 0,80€ IVA
Total: 196,80€

Factura con retención IRPF

Para profesionales que aplican retención en sus facturas.

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 100,
          "tax": ["S_IVA_21", "S_IRPF_15"],
          "text": "Servicios profesionales"
        }
      ]
    }
  }
}

Resultado:

Base: 100€
IVA 21%: +21€
IRPF 15%: -15€
Total a pagar: 106€

Factura con cuentas contables personalizadas

Cuando necesitas contabilizar líneas en cuentas específicas del plan contable.

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 100,
          "tax": ["S_IVA_21"],
          "text": "Producto estándar",
          "account": "700000"
        },
        {
          "quantity": 1,
          "unitPrice": 250,
          "tax": ["S_IVA_21"],
          "text": "Producto especial contabilizado en la cuenta 700001",
          "account": "700001"
        }
      ]
    }
  }
}

Nota: El campo account indica la cuenta contable donde se registrará el ingreso de esa línea.

Factura con suplidos

Los suplidos son gastos que has pagado en nombre de tu cliente y que debes repercutir sin IVA.

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 100,
          "tax": ["S_IVA_21"],
          "text": "Servicios profesionales"
        },
        {
          "quantity": 1,
          "unitPrice": 50,
          "tax": ["S_SUPLIDOS"],
          "text": "Suplidos Registro Mercantil",
          "document": "pro_suplido",
          "account": "566000"
        }
      ]
    }
  }
}

Resultado:

Servicios: 100€ + 21€ IVA = 121€
Suplidos: 50€ (sin IVA)
Total: 171€

Factura con precios IVA incluido

Útil cuando trabajas con precios finales (PVP) y necesitas que FacturaDirecta calcule la base imponible.

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "taxIncludedPrices": true,
      "currency": "EUR",
      "lines": [
        {
          "quantity": 2,
          "unitPrice": 100,
          "tax": ["S_IVA_21"],
          "text": "Producto PVP 100€"
        }
      ]
    }
  }
}

Resultado:

Total línea: 2 x 100€ = 200€ (IVA incluido)
Base calculada: 165,29€
IVA 21%: 34,71€
Total: 200€

Factura pagada automáticamente

Crea una factura y registra el pago completo en un solo paso.

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 100,
          "tax": ["S_IVA_21"],
          "text": "Descripción del servicio"
        }
      ]
    }
  },
  "payments": [
    {
      "bank": "ban_10000000-0000-4000-8000-000000000000"
    }
  ]
}

Nota: Al indicar solo el bank sin amount, FacturaDirecta entiende que el pago es por el importe total de la factura.

Factura con múltiples pagos

Cuando el cliente ha pagado en varios plazos antes de emitir la factura.

{
  "content": {
    "type": "invoice",
    "main": {
      "docNumber": {
        "series": "F"
      },
      "date": "2026-05-01",
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 100,
          "tax": ["S_IVA_21"],
          "text": "Descripción del servicio"
        }
      ]
    }
  },
  "payments": [
    {
      "date": "2026-04-15",
      "bank": "ban_10000000-0000-4000-8000-000000000000",
      "amount": 50
    },
    {
      "date": "2026-04-25",
      "bank": "ban_10000000-0000-4000-8000-000000000000",
      "amount": 50
    },
    {
      "bank": "ban_10000000-0000-4000-8000-000000000000"
    }
  ]
}

Resultado: Factura de 121€ con tres pagos:

15/04: 50€
25/04: 50€
01/05: 21€ (resto pendiente)

Campos importantes

Estos son los campos más relevantes al crear o actualizar facturas:

Campos del objeto main

Campo	Tipo	Descripción
contact	string	ID del cliente (obligatorio)
currency	string	Código de moneda ISO 4217 (ej: EUR, USD)
date	string	Fecha de emisión (formato YYYY-MM-DD). Si no se indica, se usa la fecha actual
dueDate	string	Fecha de vencimiento (formato YYYY-MM-DD)
docNumber	object	Número de documento: `series` (obligatorio), `number` (opcional, se asigna automáticamente)
lines	array	Líneas de la factura (obligatorio, mínimo 1)
taxIncludedPrices	boolean	Si es `true`, los precios unitarios incluyen impuestos
exchangeRate	number	Tipo de cambio (solo para monedas distintas a EUR)
emails	string	Emails destinatarios separados por comas

Campos de cada línea

Campo	Tipo	Descripción
text	string	Descripción del producto o servicio (obligatorio)
quantity	number	Cantidad (obligatorio)
unitPrice	number	Precio unitario (obligatorio)
tax	array	Array de IDs de impuestos (obligatorio). Ej: `["S_IVA_21"]`
discount	number	Descuento en importe absoluto
discountRate	number	Descuento en porcentaje (0-100)
account	string	Cuenta contable para esta línea
document	string	ID del producto de referencia

Campos de cada pago

Campo	Tipo	Descripción
bank	string	ID de la cuenta bancaria (obligatorio)
amount	number	Importe del pago. Si no se indica, se asume el total pendiente
date	string	Fecha del pago (formato YYYY-MM-DD). Si no se indica, se usa la fecha de la factura

Códigos de impuestos

Estos son los códigos de impuestos más comunes para facturas de venta en España:

Código	Descripción
S_IVA_21	IVA general 21%
S_IVA_10	IVA reducido 10%
S_IVA_4	IVA superreducido 4%
S_IRPF_15	Retención IRPF 15%
S_SUPLIDOS	Suplidos (sin IVA)

Nota: Para consultar todos los impuestos disponibles en tu empresa, usa el endpoint GET /{companyId}/taxes.

Estados de una factura

Las facturas pueden tener los siguientes estados:

Estado	Descripción
draft	Borrador: factura en edición, sin numerar
pending	Pendiente de pago: tiene saldo pendiente pero no ha vencido
overdue	Vencida: el saldo pendiente ha superado la fecha de vencimiento
paid	Pagada: saldo pendiente es cero
overpaid	Sobrepagada: los pagos superan el importe de la factura
voided	Anulada: factura cancelada

Errores comunes

Error: "contact is required"

El campo contact es obligatorio. Asegúrate de incluir el ID de un cliente existente.

Error: "lines must have at least 1 item"

Una factura necesita al menos una línea. Verifica que el array lines no está vacío.

Error: "tax is required for each line"

Cada línea debe incluir el campo tax con al menos un código de impuesto. Si la línea está exenta, usa el código de exención correspondiente.

Error: "series not found"

La serie indicada en docNumber.series no existe en la configuración de tu empresa. Verifica las series disponibles en Ajustes > Series de documentos.

Error: "bank not found"

El ID de banco indicado en los pagos no existe. Consulta las cuentas bancarias disponibles con GET /{companyId}/banks.

API: Facturas de venta (invoices)

Endpoints disponibles

Ejemplos de código

Factura básica (minimal)

Factura con varios tipos de IVA

Factura con retención IRPF

Factura con cuentas contables personalizadas

Factura con suplidos

Factura con precios IVA incluido

Factura pagada automáticamente

Factura con múltiples pagos

Campos importantes

Campos del objeto main

Campos de cada línea

Campos de cada pago

Códigos de impuestos

Estados de una factura

Errores comunes

Error: "contact is required"

Error: "lines must have at least 1 item"

Error: "tax is required for each line"

Error: "series not found"

Error: "bank not found"