Crear un albarà

Crea un nou albarà en estat `draft`. Els albarans registren les mercaderies enviades a un client i després es poden convertir en factures.

Clau única generada pel client per garantir la idempotència en els reintents. Et permet reenviar de manera segura la mateixa petició: la primera resposta es cacheja i es retorna sense tornar a executar la mutació. És una cadena opaca per al servidor; qualsevol valor únic de fins a 64 caràcters és vàlid (UUID v7, UUID v4, ULID, nanoid, etc.). Es recomana UUID v7 per coherència amb els identificadors de l'API. La mateixa clau reutilitzada amb un body diferent retorna 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

client_id*string

Formatuuid

series_id?|

Formatuuid

delivery_date?|

Formatdate

notes?|

Longitudlength <= 2000

internal_notes?|

Longitudlength <= 2000

reference_number?|

Longitudlength <= 255

transport_details?|

Longitudlength <= 2000

delivery_address?|

Longitudlength <= 500

delivery_city?|

Longitudlength <= 255

delivery_postal_code?|

Longitudlength <= 20

delivery_province?|

Longitudlength <= 255

delivery_country?|

Longitudlength <= 255

vehicle_plate?|

Extensió de logística (format semàntic validat a l'Aggregate)

Longitudlength <= 20

driver_name?|

Longitudlength <= 120

driver_tax_id?|

Longitudlength <= 20

tracking_number?|

Longitudlength <= 100

carrier_company?|

Longitudlength <= 120

received_by_name?|

Longitudlength <= 120

received_by_tax_id?|

Longitudlength <= 20

external_id?|

Longitudlength <= 100

currency?|

Valor a"EUR"

metadata?|

Un mapa lliure de fins a 50 parells clau→valor per emmagatzemar dades estructurades arbitràries (els valors són cadenes de fins a 500 caràcters). Això és DIFERENT de custom_fields: metadata és un mapa clau→valor SENSE ORDRE per a dades d'integració opaques, mentre que custom_fields (en els sis recursos de document) és una llista ORDENADA de parells tipats {field, value} amb semàntica de visualització. Un document pot portar tots dos. Els recursos mestres (Client, Supplier) no tenen custom_fields tipats: fes servir el seu metadata com a magatzem de camps personalitzats sense tipar.

Propietatsproperties <= 50

billing_emails?array<>|

Elementsitems <= 5

tags?array<>|

Elementsitems <= 30

custom_fields?array<>|

Elementsitems <= 50

lines*array<>

Elements1 <= items

Cos de la resposta

`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": "Caixes 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"
  }
}

{
  "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": "Caixes 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"
  }
}

{
  "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": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

{
  "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"
  }
}

Authorization

Paràmetres de capçalera

Cos de la petició

Cos de la resposta

200application/json

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

Falta l'API key

Format d'API key no vàlid

API key revocada

L'API key no té el scope requerit

Cal millorar el pla

L'add-on requerit no està actiu

Idempotency key reutilitzada amb un body diferent

Conflicte genèric de recurs

El paràmetre no ha superat la validació

Límit del pla assolit (autorització)

Format d'Idempotency-Key no vàlid

Modelo 303 sense trimestre

Modelo 347 amb trimestre

Any fora de rang

No hi ha factures en el període

Format no vàlid

No hi ha formatador disponible per a la combinació de tipus/format/any

Imatge de signatura massa gran (>2MB)

Transició d'estat de document no vàlida

Factura ja pagada

Pressupost ja acceptat

Límit de peticions superat

Massa errors d'autenticació (bloqueig temporal)

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`