El recurso bills te permite consultar las facturas de compra y gastos (tickets) de tu empresa. Puedes listar todas las facturas, filtrar por diferentes criterios y obtener los detalles de una factura específica.

Este artículo incluye ejemplos prácticos para consultar facturas de compra usando los diferentes filtros disponibles.

Nota: Actualmente la API permite consultar facturas de compra pero no crearlas. Para registrar gastos, usa la interfaz web de FacturaDirecta o el escáner de documentos.

💡 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}/bills	Lista de facturas de compra (con filtros y paginación)
GET	/{companyId}/bills/{id}	Obtener una factura de compra por ID

Ejemplos de código

Listar todas las facturas de compra

Obtiene las facturas de compra más recientes con paginación por defecto.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/bills

Filtrar por rango de fechas

Obtiene las facturas de compra de un periodo específico.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  "https://app.facturadirecta.com/api/TU_COMPANY_ID/bills?minDate=2026-01-01&maxDate=2026-01-31"

Filtrar por proveedor

Obtiene las facturas de compra de un proveedor específico.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  "https://app.facturadirecta.com/api/TU_COMPANY_ID/bills?contact=con_xxxxx"

Filtrar por importe

Obtiene las facturas de compra con importe entre 100€ y 500€.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  "https://app.facturadirecta.com/api/TU_COMPANY_ID/bills?minTotal=100&maxTotal=500"

Buscar tickets sin proveedor

Útil para encontrar gastos menores (tickets) que no tienen proveedor asociado.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  "https://app.facturadirecta.com/api/TU_COMPANY_ID/bills?hasContact=false"

Filtrar por etiquetas

Obtiene las facturas que tienen una etiqueta específica.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  "https://app.facturadirecta.com/api/TU_COMPANY_ID/bills?anyOfTheseTags=tag_xxxxx"

Obtener detalle de una factura

Obtiene todos los datos de una factura de compra específica.

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/bills/bil_xxxxx

Parámetros de filtro

Puedes combinar varios filtros en la misma consulta:

Parámetro	Tipo	Descripción
minDate	string	Fecha mínima (formato YYYY-MM-DD)
maxDate	string	Fecha máxima (formato YYYY-MM-DD)
contact	string	ID del proveedor
hasContact	boolean	true: solo con proveedor, false: solo sin proveedor (tickets)
minTotal	number	Importe total mínimo
maxTotal	number	Importe total máximo
currency	string	Moneda (ISO 4217: EUR, USD, etc.)
draft	string	include: incluir borradores, only: solo borradores, exclude: excluir
country	string	País del proveedor (ISO 3166-1 Alpha-2)
allTheseTags	string	Todas las etiquetas (separadas por coma)
anyOfTheseTags	string	Cualquiera de las etiquetas (separadas por coma)
hasTags	boolean	true: solo con etiquetas
sortBy	string	Campo de ordenación
related	string	Incluir datos relacionados (contact, payments, attachments)

Estructura de respuesta

La respuesta incluye los datos de cada factura de compra:

{
  "data": [
    {
      "id": "bil_xxxxx",
      "content": {
        "type": "bill",
        "main": {
          "title": "Factura FC-2026-001 - Proveedor SL",
          "contact": "con_xxxxx",
          "date": "2026-01-15",
          "docNumber": {
            "series": "FC",
            "number": 1
          },
          "currency": "EUR",
          "total": 121.00,
          "lines": [
            {
              "text": "Servicio de hosting",
              "quantity": 1,
              "unitPrice": 100,
              "tax": ["P_IVA_21_BC"]
            }
          ],
          "state": "pending"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 150
  }
}

Campos principales

Campo	Tipo	Descripción
id	string	Identificador único de la factura
main.title	string	Título descriptivo de la factura
main.contact	string	ID del proveedor (puede ser null para tickets)
main.date	string	Fecha de la factura
main.docNumber	object	Número de documento del proveedor
main.currency	string	Moneda de la factura
main.total	number	Importe total
main.lines	array	Líneas de la factura
main.state	string	Estado de la factura

Estados de facturas de compra

Estado	Descripción
draft	Borrador: factura provisional sin validar
pending	Pendiente de pago
overdue	Vencida: ha pasado la fecha de vencimiento
paid	Pagada completamente
overpaid	Sobrepagada
voided	Anulada

API: Facturas de compra y gastos (bills)