List all delivery notes
List your delivery notes with cursor-based pagination.
In: header
Query Parameters
Number of objects to return. Integer between 1 and 100. Defaults to 25.
251 <= value <= 100Cursor for forward pagination. Use the uuid of the last object on the previous page.
uuidCursor for backward pagination. Use the uuid of the first object on the current page.
uuidPublic delivery note status: draft, sent, signed, invoiced, cancelled (the same values returned by the resource status field). sent and signed filter by the internal delivered state (with/without signature); use the signed filter as well to distinguish them precisely. Exact match on status.
Public delivery note status: draft, sent, signed, invoiced, cancelled (the same values returned by the resource status field). sent and signed filter by the internal delivered state (with/without signature); use the signed filter as well to distinguish them precisely. Comma-separated list. Any of the values matches.
Client ID (UUID v7). Exact match on client_id.
uuidClient ID (UUID v7). Comma-separated list. Any of the values matches.
Series ID (UUID v7). Exact match on series_id.
uuidSeries ID (UUID v7). Comma-separated list. Any of the values matches.
Creation date (ISO 8601). Greater than or equal to the given value.
date-timeCreation date (ISO 8601). Less than or equal to the given value.
date-timeCreation date (ISO 8601). Strictly greater than the given value.
date-timeCreation date (ISO 8601). Strictly less than the given value.
date-timeDelivery date. Greater than or equal to the given value.
dateDelivery date. Less than or equal to the given value.
dateDelivery date. Strictly greater than the given value.
dateDelivery date. Strictly less than the given value.
dateFilter by signed delivery notes (true) or with no recorded signature (false). Exact match on signed.
License plate of the delivery vehicle (exact match). Exact match on vehicle_plate.
Transport / courier company (exact match). Exact match on carrier_company.
Filter by classification tag (lowercase slug). Supports multiple values with tags[in]=a,b (JSON_CONTAINS, OR semantics — matches delivery notes carrying ANY of the tags). Exact match on tags.
Filter by classification tag (lowercase slug). Supports multiple values with tags[in]=a,b (JSON_CONTAINS, OR semantics — matches delivery notes carrying ANY of the tags). Comma-separated list. Any of the values matches.
Sort order. Use a field for ascending or a - prefix for descending (e.g. -created). Allowed fields: created, number, delivery_date. Combined with the cursor, ordering stays deterministic (a stable secondary sort by the cursor id, Stripe-style). When omitted, results follow the default cursor order (created descending).
"created" | "-created" | "number" | "-number" | "delivery_date" | "-delivery_date"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });// List endpoints return an async-iterable Page (cursors handled for you).for await (const item of await factuarea.deliveryNotes.list({ limit: 25 })) { console.log(item.id);}{
"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"
}
}Find a delivery note by external ID
Look up a single delivery note by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Returns the matching delivery note or 404 `delivery_note_not_found` if no delivery note uses that external_id within your company.
Mark delivery note as delivered
Transition a delivery note to the `delivered` state (public `sent`). Canonical REST replacement for the deprecated `POST /change_status`. Returns 409 `invalid_status_transition` if the note cannot transition. Supports `Idempotency-Key` for safe retries.