El recurso deliveryNotes te permite gestionar los albaranes de entrega de tu empresa. Puedes crear albaranes, consultarlos, actualizarlos, eliminarlos y enviarlos por email.

Los albaranes tienen una estructura muy similar a las facturas y presupuestos, por lo que si ya has trabajado con esos recursos, te resultará familiar.

💡 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}/deliveryNotes	Lista de albaranes (con filtros y paginación)
POST	/{companyId}/deliveryNotes	Crear un albarán
GET	/{companyId}/deliveryNotes/{id}	Obtener un albarán por ID
PUT	/{companyId}/deliveryNotes/{id}	Actualizar un albarán
DELETE	/{companyId}/deliveryNotes/{id}	Eliminar un albarán
PUT	/{companyId}/deliveryNotes/{id}/pdf	Generar PDF del albarán
PUT	/{companyId}/deliveryNotes/{id}/send	Enviar albarán por email
PUT	/{companyId}/deliveryNotes/{id}/tags	Actualizar etiquetas del albarán

Ejemplos de código

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

Albarán valorado

Un albarán que incluye precios y servirá como base para generar una factura.

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

Resultado: Un albarán valorado con total 50€ + 21% IVA = 60,50€.

Albarán no valorado

Un albarán que solo registra la entrega sin mostrar precios. Útil para entregas donde el precio se acordará después.

{
  "content": {
    "type": "deliveryNote",
    "main": {
      "docNumber": {
        "series": "AL"
      },
      "baseState": "pending",
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "currency": "EUR",
      "showPriceColumn": false,
      "showAmountColumn": false,
      "lines": [
        {
          "quantity": 5,
          "unitPrice": 0,
          "tax": ["S_IVA_21"],
          "text": "Producto A - Referencia ABC123"
        },
        {
          "quantity": 10,
          "unitPrice": 0,
          "tax": ["S_IVA_21"],
          "text": "Producto B - Referencia XYZ789"
        }
      ]
    }
  }
}

Opciones de visualización:

showPriceColumn: false oculta la columna de precio unitario
showAmountColumn: false oculta la columna de importe

Albarán con múltiples productos

Un albarán típico de entrega de mercancía.

{
  "content": {
    "type": "deliveryNote",
    "main": {
      "docNumber": {
        "series": "AL"
      },
      "baseState": "delivered",
      "contact": "con_10000000-0000-4000-8000-000000000000",
      "date": "2026-01-28",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 100,
          "unitPrice": 2.50,
          "tax": ["S_IVA_21"],
          "text": "Producto A - Caja de 100 unidades"
        },
        {
          "quantity": 50,
          "unitPrice": 4.00,
          "tax": ["S_IVA_21"],
          "text": "Producto B - Pack de 50 unidades"
        },
        {
          "quantity": 25,
          "unitPrice": 8.00,
          "tax": ["S_IVA_10"],
          "text": "Producto C - IVA reducido"
        }
      ]
    }
  }
}

Campos importantes

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 entrega (formato YYYY-MM-DD)
docNumber	object	Número de documento: `series` (obligatorio), `number` (opcional)
baseState	string	Estado del albarán (ver sección Estados)
lines	array	Líneas del albarán (obligatorio, mínimo 1)
showPriceColumn	boolean	Mostrar columna de precio unitario en el PDF
showAmountColumn	boolean	Mostrar columna de importe en el PDF
emails	string	Emails destinatarios separados por comas

Campos de cada línea

Campo	Tipo	Descripción
text	string	Descripción del producto (obligatorio)
quantity	number	Cantidad entregada (obligatorio)
unitPrice	number	Precio unitario (obligatorio, puede ser 0)
tax	array	Array de IDs de impuestos (obligatorio)
discount	number	Descuento en importe absoluto
discountRate	number	Descuento en porcentaje (0-100)
document	string	ID del producto de referencia

Estados de un albarán

Los albaranes pueden tener los siguientes estados base:

Estado	Descripción
pending	Pendiente: preparado pero no entregado aún
delivered	Entregado: la mercancía ha sido entregada al cliente
closed	Cerrado: facturado o finalizado
rejected	Rechazado: el cliente ha rechazado la entrega

Nota: El estado final del albarán puede variar si se ha generado una factura a partir de él.

Convertir albarán a factura

Cuando quieras facturar los productos entregados, puedes crear una factura referenciando el albarán. El flujo típico es:

Actualizar el albarán a estado "delivered"
Crear una factura con las líneas del albarán

Al crear la factura, indica el origen de cada línea para vincular los documentos:

{
  "content": {
    "type": "invoice",
    "main": {
      "contact": "con_xxxxx",
      "currency": "EUR",
      "lines": [
        {
          "origin": "del_xxxxx",
          "quantity": 100,
          "unitPrice": 2.50,
          "tax": ["S_IVA_21"],
          "text": "Producto A - Albarán AL-2026-001"
        }
      ]
    }
  }
}

Errores comunes

Error: "contact is required"

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

Error: "Invalid baseState"

El valor de baseState no es válido. Usa uno de: pending, delivered, closed, rejected.

Error: "lines must have at least 1 item"

Un albarán necesita al menos una línea. Verifica que el array lines no está vacío.

API: Albaranes (deliveryNotes)