Ir al contenido principal

Albaranes

Crea, consulta, actualiza y elimina albaranes de entrega mediante la API. Incluye ejemplos de albaranes valorados y no valorados.

Albaranes

Un albarán documenta la entrega de bienes o servicios a un cliente. Es el justificante de que el suministro se ha realizado, normalmente antes de emitir la factura correspondiente. Tiene líneas de detalle, estados de entrega y un ciclo de vida propio.

En los ejemplos de esta página:

  • Los UUIDs (con_2c4f8e21-…, den_3a7b9c14-…, upl_6f8e9b42-…) son ilustrativos. Cada empresa tiene los suyos; sustitúyelos por los identificadores reales que devuelve la API.

  • El ID de impuesto S_IVA_21 es el del catálogo por defecto para IVA 21% en ventas. Recupera el catálogo real con GET /{companyId}/settings/taxes/sales. Ver Impuestos.

Relación con la factura

La API pública no expone una operación de conversión albarán → factura. La conversión, cuando aplica, se hace desde la interfaz. Si necesitas emitir una factura a partir de los datos de uno o varios albaranes, crea la factura directamente con POST /invoices con las líneas que correspondan.

Un albarán convertido o asociado a una factura mantiene su estado en baseState, pero puede aparecer en su related con el documento de venta resultante cuando se consulta.

Estados

content.main.baseState controla el estado declarado del albarán:

  • pending — emitido pero pendiente de entrega.

  • delivered — entregado al cliente.

  • closed — cerrado sin entregar (caducado, cancelado o anulado).

  • rejected — el cliente ha rechazado la entrega.

Campos que se rellenan típicamente al cambiar baseState:

  • deliveredDate, deliveredTo — fecha de entrega y persona del cliente que la ha recibido (firmante o responsable de recepción).

  • rejectedDate, rejectedBy — fecha y responsable del rechazo, si aplica.

Ninguno de estos campos es obligatorio al crear el albarán; se rellenan al evolucionar el documento.

Estructura del albarán

Forma común a los documentos de venta de FacturaDirecta:

  • content.type — siempre "deliveryNote".

  • content.uuid — identificador inmutable.

  • content.main — datos del documento (contacto, fechas, divisa, líneas, totales, condiciones, plantilla).

  • content.attachments — adjuntos vinculados (ver Adjuntos).

  • content.meta — metadatos internos.

En respuestas, además, en el nivel raíz: tags, creationDate, modificationDate, related.

Líneas de detalle

content.main.lines es un array. Cada línea requiere text, quantity y unitPrice. Otros campos relevantes:

  • discount o discountRate — descuento absoluto o porcentual.

  • tax — array de identificadores de impuesto (TaxId) que aplican a la línea. Los IDs se obtienen del catálogo de ventas de la empresa con GET /{companyId}/settings/taxes/sales. Ver Impuestos.

  • lineTotal — total de la línea; la API lo calcula si lo omites.

  • document — ID del producto del catálogo si la línea proviene de uno.

  • account — cuenta contable de la línea; por defecto se toma de la cuenta asociada al producto o, en su defecto, la de ventas de la empresa.

Importes y totales. Los totales del documento (total, totalBeforeTaxes, linesTotal, taxes) se calculan a partir de las líneas. Conviene dejarlos vacíos al crear o actualizar y leerlos de la respuesta.

taxIncludedPrices: true indica que unitPrice ya incluye IVA. Por defecto es false.

Operaciones

Lista de albaranes

GET /{companyId}/deliveryNotes devuelve los albaranes de la empresa, paginados.

Parámetros de consulta principales:

  • minDate, maxDate — rango de fechas del documento (YYYY-MM-DD).

  • series, formattedSeries — serie de numeración.

  • minNumber, maxNumber — rango de número de documento.

  • contact — ID de contacto.

  • hasContact — true/false para filtrar con o sin contacto.

  • minTotal, maxTotal — rango de importe.

  • currency — código ISO 4217.

  • country — código país ISO 3166-1 Alpha-2.

  • emails — buscar por destinatario.

  • allTheseTags, anyOfTheseTags, hasTags — filtros por etiquetas.

  • sortBy — campo de orden.

  • related — recursos a expandir.

Ver Paginación para los parámetros comunes.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes?minDate=2026-01-01&limit=50"

Crear albarán

POST /{companyId}/deliveryNotes crea un albarán.

Parámetros del body:

  • content.type — siempre "deliveryNote".

  • content.main — campos del documento. contact y lines son las partes esenciales.

  • tags (opcional).

Notas:

  • Si contact apunta a un ID existente, sus datos se toman del contacto.

  • series y docNumber se asignan automáticamente si no los envías, según la numeración configurada para albaranes.

  • La respuesta es el albarán creado completo, en el mismo formato que Obtener un albarán.

Ejemplo de request JSON

{
  "content": {
    "type": "deliveryNote",
    "main": {
      "docNumber": { "series": "AL" },
      "baseState": "pending",
      "contact": "con_2c4f8e21-7b3a-4d9c-9e1f-a8b7c6d5e4f3",
      "currency": "EUR",
      "lines": [
        {
          "quantity": 1,
          "unitPrice": 50,
          "tax": ["S_IVA_21"],
          "text": "Descripción del producto 1"
        }
      ]
    }
  }
}

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '@deliveryNote.json' \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes"

Obtener un albarán

GET /{companyId}/deliveryNotes/{id} devuelve un albarán por ID.

Parámetros:

  • related (opcional) — recursos relacionados a expandir, por ejemplo invoices para ver si el albarán está vinculado a alguna factura.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c?related=invoices"

Actualizar albarán

PUT /{companyId}/deliveryNotes/{id} sustituye el contenido completo del albarán. No es un PATCH: lo que no envíes, se borra.

Para cambiar el estado del documento, envía el contacto y las líneas inalterados junto con el nuevo baseState (y, si aplica, deliveredDate/deliveredTo o rejectedDate/rejectedBy).

Restricciones:

  • Si el albarán está vinculado a una factura ya emitida, las modificaciones pueden producir efectos secundarios. Antes de actualizar, consulta su related.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \
  -d '@deliveryNote.json' \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c"

Borrar albarán

DELETE /{companyId}/deliveryNotes/{id} elimina un albarán.

Restricciones. No se puede borrar un albarán vinculado a una factura emitida. La API devuelve 409 Conflict con el detalle del documento que bloquea el borrado.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c"

Actualizar etiquetas de albarán

PUT /{companyId}/deliveryNotes/{id}/tags reemplaza el conjunto de etiquetas sin tocar el resto del contenido.

Ejemplo de request JSON

{
  "tags": ["q2-2026", "logística"]
}

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \
  -d '{"tags":["q2-2026","logística"]}' \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c/tags"

Enviar albarán por correo

PUT /{companyId}/deliveryNotes/{id}/send envía el albarán por correo electrónico. Los destinatarios, asunto y cuerpo se toman de la plantilla configurada para albaranes; los campos del body permiten sobreescribirlos puntualmente.

Parámetros del body (todos opcionales):

  • to, cc, bcc — listas de destinatarios.

  • from — remitente; debe ser una dirección autorizada en la empresa.

  • subject — asunto.

  • html — cuerpo del email en HTML.

Si no envías body, se usa enteramente la plantilla del albarán.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \
  -d '{"to":["recepcion@acme.es"],"subject":"Albarán 2026/AL/0012"}' \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c/send"

Generar el albarán en PDF

PUT /{companyId}/deliveryNotes/{id}/pdf genera una URL temporal con el albarán en PDF.

Parámetros del body:

  • mode (opcional) — "attachment" (URL para descargar como adjunto, por defecto), "inline" (visualización en línea) o "print" (URL HTML que carga el PDF y lo envía a imprimir).

La URL devuelta es válida solo durante el periodo indicado en la respuesta.

Copy as cURL

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" -X PUT \
  -d '{"mode":"inline"}' \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c/pdf"

Adjuntos

Un albarán puede tener varios adjuntos vinculados (PDFs firmados por el cliente, documentación de logística, fotos de la entrega...). Los adjuntos no se suben en el body del albarán: primero se crean con POST /uploads y después se vinculan con POST /deliveryNotes/{id}/attachments enviando los uploadIds.

Listar adjuntos

GET /{companyId}/deliveryNotes/{id}/attachments devuelve los adjuntos vinculados al albarán.

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c/attachments"

Vincular adjuntos

POST /{companyId}/deliveryNotes/{id}/attachments añade adjuntos al albarán a partir de uploads previos.

Parámetros del body:

  • uploadIds — array de identificadores upl_<uuid> obtenidos con POST /uploads. Mínimo uno.

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"uploadIds":["upl_6f8e9b42-1d3c-4a7f-b2e4-9c1d5e7f3a6b","upl_7a9b0c53-2e4d-4b8a-a3f5-0d2e6f8a4b7c"]}' \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c/attachments"

Eliminar un adjunto

DELETE /{companyId}/deliveryNotes/{id}/attachments/{attachmentIndex} elimina un adjunto del albarán. attachmentIndex es la posición en el array (basada en cero).

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \
  "https://app.facturadirecta.com/api/$COMPANY_ID/deliveryNotes/den_3a7b9c14-2f5e-4a7b-b0c8-1d2e3f4a5b6c/attachments/0"

Errores comunes

  • 400 ValidationError — falta contact o lines con quantity / unitPrice inválidos.

  • 400 ValidationError — baseState con valor no admitido (debe ser pending, delivered, closed o rejected).

  • 409 Conflict — borrado o modificación incompatible con una factura ya emitida vinculada al albarán.

  • 409 Conflict — series o docNumber duplicado en la empresa.

Ver Errores y validaciones para el formato general de respuestas de error.

Endpoints

Método

Path

operationId

Scopes

Descripción

GET

/{companyId}/deliveryNotes

getDeliveryNotes

deliveryNotes:read

Lista de albaranes

GET

/{companyId}/deliveryNotes/{id}

getDeliveryNote

deliveryNotes:read

Obtener un albarán

GET

/{companyId}/deliveryNotes/{id}/attachments

getDeliveryNoteAttachments

deliveryNotes:read

Listar adjuntos de un albarán

POST

/{companyId}/deliveryNotes

createDeliveryNote

deliveryNotes:write

Crear albarán

POST

/{companyId}/deliveryNotes/{id}/attachments

addDeliveryNoteAttachments

deliveryNotes:write

Vincular adjuntos a un albarán

PUT

/{companyId}/deliveryNotes/{id}

updateDeliveryNote

deliveryNotes:write

Actualizar albarán

PUT

/{companyId}/deliveryNotes/{id}/pdf

createDeliveryNotePDF

deliveryNotes:read

Generar el albarán en formato PDF

PUT

/{companyId}/deliveryNotes/{id}/send

sendDeliveryNote

deliveryNotes:write

Enviar albarán por correo electrónico

PUT

/{companyId}/deliveryNotes/{id}/tags

updateDeliveryNoteTags

deliveryNotes:write

Actualizar etiquetas de albarán

DELETE

/{companyId}/deliveryNotes/{id}

deleteDeliveryNote

deliveryNotes:write

Borrar albarán

DELETE

/{companyId}/deliveryNotes/{id}/attachments/{attachmentIndex}

deleteDeliveryNoteAttachment

deliveryNotes:write

Eliminar adjunto de un albarán

Scopes

  • deliveryNotes:read — Lectura de albaranes.

  • deliveryNotes:write — Modificación de albaranes.

Artículos relacionados
Facturas de compra y tickets
Presupuestos
Facturas de venta
Nóminas
Productos
¿Ha quedado contestada tu pregunta?