El recurso products te permite gestionar el catálogo de productos y servicios de tu empresa. Cada producto puede estar configurado para venta, para compra, o para ambos usos.

Este artículo incluye ejemplos prácticos para los casos más comunes: productos de venta, productos de compra y productos que se usan tanto en ventas como en compras.

💡 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}/products	Lista de productos (con filtros y paginación)
POST	/{companyId}/products	Crear un producto
GET	/{companyId}/products/{id}	Obtener un producto por ID
PUT	/{companyId}/products/{id}	Actualizar un producto
DELETE	/{companyId}/products/{id}	Eliminar un producto

Ejemplos de código

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

Producto de venta

El caso más común: un producto o servicio que vendes a tus clientes.

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "product",
      "main": {
        "sku": "PV001",
        "name": "Producto 001",
        "currency": "EUR",
        "sales": {
          "price": 125,
          "description": "Descripción del producto 001 que aparecerá en los documentos cuando se seleccione",
          "tax": ["S_IVA_21"],
          "account": "700000"
        }
      }
    }
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/products

Resultado: Un producto de venta con precio 125€ + IVA 21%, contabilizado en la cuenta 700000.

Producto de compra

Para gastos recurrentes que quieres tener catalogados (ej: suministros, servicios externos).

{
  "content": {
    "type": "product",
    "main": {
      "sku": "PC001",
      "name": "Producto comprado 001",
      "currency": "EUR",
      "purchases": {
        "price": 125,
        "description": "Descripción del producto de compra 001 que aparecerá en los documentos cuando se seleccione",
        "tax": ["P_IVA_21_BC"],
        "account": "600000"
      }
    }
  }
}

Nota: Los impuestos de compra usan el prefijo P_ (ej: P_IVA_21_BC) mientras que los de venta usan S_ (ej: S_IVA_21).

Producto de venta y compra

Útil para productos que compras y revendes, con diferentes precios y descripciones según el contexto.

{
  "content": {
    "type": "product",
    "main": {
      "sku": "PCV009",
      "name": "Producto 009",
      "currency": "EUR",
      "sales": {
        "price": 125,
        "description": "Descripción del producto en los documentos de venta",
        "tax": ["S_IVA_21"],
        "account": "700000"
      },
      "purchases": {
        "price": 75,
        "description": "Descripción del producto en los documentos de compra",
        "tax": ["P_IVA_21_BC"],
        "account": "600000"
      }
    }
  }
}

Resultado:

En facturas de venta: 125€ + IVA, cuenta 700000
En facturas de compra: 75€ + IVA, cuenta 600000
Margen bruto: 50€ por unidad

Campos importantes

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

Campos generales

Campo	Tipo	Descripción
name	string	Nombre del producto (obligatorio)
sku	string	Código de referencia (SKU). Debe ser único
currency	string	Moneda de los precios (ISO 4217: EUR, USD, etc.)
externalId	string	ID externo para integración con otros sistemas

Campos de venta (sales)

Campo	Tipo	Descripción
sales.price	number	Precio de venta unitario
sales.description	string	Descripción que aparece en facturas de venta
sales.tax	array	Impuestos de venta (ej: `["S_IVA_21"]`)
sales.account	string	Cuenta contable de ingresos (ej: 700000)

Campos de compra (purchases)

Campo	Tipo	Descripción
purchases.price	number	Precio de compra unitario
purchases.description	string	Descripción que aparece en facturas de compra
purchases.tax	array	Impuestos de compra (ej: `["P_IVA_21_BC"]`)
purchases.account	string	Cuenta contable de gastos (ej: 600000)

Códigos de impuestos

Los impuestos de productos tienen prefijos diferentes según su uso:

Impuestos de venta (prefijo S_)

Código	Descripción
S_IVA_21	IVA general 21%
S_IVA_10	IVA reducido 10%
S_IVA_4	IVA superreducido 4%

Impuestos de compra (prefijo P_)

Código	Descripción
P_IVA_21_BC	IVA soportado 21% (bien corriente)
P_IVA_10_BC	IVA soportado 10% (bien corriente)
P_IVA_4_BC	IVA soportado 4% (bien corriente)

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

Uso de productos en documentos

Cuando creas una factura, puedes referenciar un producto en el campo document de cada línea:

{
  "content": {
    "type": "invoice",
    "main": {
      "contact": "con_xxxxx",
      "currency": "EUR",
      "lines": [
        {
          "document": "pro_xxxxx",
          "quantity": 2,
          "unitPrice": 125,
          "tax": ["S_IVA_21"],
          "text": "Producto 001"
        }
      ]
    }
  }
}

Ventajas de referenciar productos:

Los documentos quedan vinculados para análisis y reporting
Puedes obtener estadísticas de ventas por producto
Facilita la creación de líneas con datos predefinidos

Errores comunes

Error: "name is required"

El campo name es obligatorio. Indica un nombre descriptivo para el producto.

Error: "sku must be unique"

Ya existe otro producto con el mismo SKU. Usa un código de referencia diferente.

Error: "sales or purchases required"

Un producto debe tener al menos una configuración de venta (sales) o de compra (purchases).

Error: "Invalid tax code"

El código de impuesto no existe. Verifica que usas el prefijo correcto:

S_ para impuestos de venta
P_ para impuestos de compra

API: Productos (products)