Factuarea API
Albaranes

Listar todos los albaranes

Lista tus albaranes con paginación por cursor.

GET
/delivery_notes

Authorization

AuthorizationBearer <token>

En: header

Parámetros de consulta

limit?integer

Número de objetos a devolver. Entero entre 1 y 100. Por defecto 25.

Predeterminado25
Rango1 <= value <= 100
starting_after?string

Cursor para paginación hacia delante. Usa el uuid del último objeto de la página anterior.

Formatouuid
ending_before?string

Cursor para paginación hacia atrás. Usa el uuid del primer objeto de la página actual.

Formatouuid
status?string

Estado público del albarán: draft, sent, signed, invoiced, cancelled (los mismos valores que devuelve el campo status del recurso). sent y signed filtran por el estado interno entregado (con/sin firma); usa también el filtro signed para distinguirlos con precisión. Coincidencia exacta en status.

status[in]?string

Estado público del albarán: draft, sent, signed, invoiced, cancelled (los mismos valores que devuelve el campo status del recurso). sent y signed filtran por el estado interno entregado (con/sin firma); usa también el filtro signed para distinguirlos con precisión. Lista separada por comas. Coincide cualquiera de los valores.

client_id?string

Client ID (UUID v7). Coincidencia exacta con client_id.

Formatouuid
client_id[in]?string

Client ID (UUID v7). Lista separada por comas. Coincide cualquiera de los valores.

series_id?string

Series ID (UUID v7). Coincidencia exacta con series_id.

Formatouuid
series_id[in]?string

Series ID (UUID v7). Lista separada por comas. Coincide cualquiera de los valores.

created[gte]?string

Fecha de creación (ISO 8601). Mayor o igual que el valor dado.

Formatodate-time
created[lte]?string

Fecha de creación (ISO 8601). Menor o igual que el valor dado.

Formatodate-time
created[gt]?string

Fecha de creación (ISO 8601). Estrictamente mayor que el valor dado.

Formatodate-time
created[lt]?string

Fecha de creación (ISO 8601). Estrictamente menor que el valor dado.

Formatodate-time
delivery_date[gte]?string

Fecha de entrega. Mayor o igual que el valor dado.

Formatodate
delivery_date[lte]?string

Fecha de entrega. Menor o igual que el valor dado.

Formatodate
delivery_date[gt]?string

Fecha de entrega. Estrictamente mayor que el valor dado.

Formatodate
delivery_date[lt]?string

Fecha de entrega. Estrictamente menor que el valor dado.

Formatodate
signed?boolean

Filtra por albaranes firmados (true) o sin firma registrada (false). Coincidencia exacta en signed.

vehicle_plate?string

Matrícula del vehículo de reparto (coincidencia exacta). Coincidencia exacta con vehicle_plate.

carrier_company?string

Empresa de transporte / mensajería (coincidencia exacta). Coincidencia exacta en carrier_company.

tags?string

Filtrar por tag de clasificación (slug en minúscula). Admite múltiples valores con tags[in]=a,b (JSON_CONTAINS, semántica OR — coincide con los albaranes que llevan CUALQUIERA de los tags). Coincidencia exacta sobre tags.

tags[in]?string

Filtrar por tag de clasificación (slug en minúscula). Admite múltiples valores con tags[in]=a,b (JSON_CONTAINS, semántica OR — coincide con los albaranes que llevan CUALQUIERA de los tags). Lista separada por comas. Coincide cualquiera de los valores.

sort?string

Orden de los resultados. Usa un campo para ascendente o un prefijo - para descendente (p. ej. -created). Campos permitidos: created, number, delivery_date. Combinado con el cursor, el orden se mantiene determinista (un orden secundario estable por el id del cursor, al estilo Stripe). Si se omite, los resultados siguen el orden de cursor por defecto (created descendente).

Valor en"created" | "-created" | "number" | "-number" | "delivery_date" | "-delivery_date"

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06",
      "object": "delivery_note",
      "number": "A-2026-00031",
      "series": {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
        "code": "F-2026"
      },
      "client": {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "name": "Acme Corporation"
      },
      "status": "signed",
      "issued_on": "2026-01-19",
      "delivery_date": "2026-01-21",
      "signed_at": "2026-01-21T14:50:00Z",
      "signed_by": "María García López",
      "signature_image_url": "https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png",
      "vehicle_plate": "5678JKL",
      "driver": {
        "name": "Pedro Sánchez Ruiz",
        "tax_id": "12345678Z"
      },
      "tracking": {
        "number": "TRK-2026-0099",
        "carrier": "SEUR"
      },
      "received_by": {
        "name": "María García López",
        "tax_id": "87654321X"
      },
      "billing_emails": [
        "administracion@cliente.com"
      ],
      "subtotal": 800,
      "taxes_total": 168,
      "total": 968,
      "currency": "EUR",
      "notes": "Entregado en almacén central.",
      "external_id": "ERP-ALB-2026-0031",
      "lines": [
        {
          "object": "delivery_note_line",
          "description": "Cajas de material A4 (500u)",
          "product": {
            "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
            "name": "Consultoría hora estándar"
          },
          "quantity": 2,
          "unit_price": 400,
          "tax_rate": 21,
          "retention_rate": 0,
          "surcharge_rate": 0,
          "discount_percent": 0,
          "subtotal": 800,
          "taxes": 168,
          "total": 968
        }
      ],
      "metadata": {
        "erp_code": "IVA-GEN",
        "ledger_account": "477000"
      },
      "tags": [
        "logistica",
        "almacen-central"
      ],
      "custom_fields": [
        {
          "field": "muelle_carga",
          "value": "Muelle 3"
        }
      ],
      "converted_to_id": null,
      "created_at": "2026-01-19T08:00:00Z",
      "updated_at": "2026-01-21T14:50:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "El parámetro 'per_page' no está reconocido por este endpoint.",
    "param": "per_page",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01HKQS5N7UR6PWJ8K2T5BWPMZ9"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Buscar un albarán por external ID

Busca un único albarán por su `external_id` (enviado en el body JSON), la clave de integración que lo mapea a un registro en un sistema de terceros (ERP/CRM/e-commerce). Devuelve el albarán coincidente o 404 `delivery_note_not_found` si ningún albarán usa ese external_id dentro de tu empresa.

Marca el albarán como entregado

Transiciona un albarán al estado `delivered` (público `sent`). Reemplazo REST canónico del obsoleto `POST /change_status`. Devuelve 409 `invalid_status_transition` si el albarán no puede transicionar. Admite `Idempotency-Key` para reintentos seguros.