Factuarea API
Albarans

Anul·lar un albarà

Transiciona un albarà a l'estat `cancelled`. Reemplaçament REST canònic de l'obsolet `POST /change_status`. Retorna 409 `invalid_status_transition` si l'albarà no es pot cancel·lar (p. ex. ja facturat). Admet `Idempotency-Key` per a reintents segurs.

POST
/delivery_notes/{delivery_note}/cancel

Authorization

AuthorizationBearer <token>

A: header

Paràmetres de ruta

delivery_note*string

Paràmetres de capçalera

Idempotency-Key?string

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 resposta

application/json

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

{
  "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": "not_found_error",
    "code": "resource_not_found",
    "message": "El recurso solicitado no existe o pertenece a otra empresa.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_01HKQS5NEQ6X1R4N9B0C5DWTPG"
  }
}

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

Eliminació massiva d'albarans

Elimina diversos albarans en una sola petició. El body accepta un array `ids` d'`uuid`s. Retorna un `bulk_delete_result` amb el recompte d'albarans eliminats i una llista `failed` (`id` + `reason` en castellà) per als que no es van poder eliminar (p. ex. signats o facturats). Admet `Idempotency-Key` per a reintents segurs.

Convertir albarà en factura

Converteix un albarà en una factura de venda. L'albarà passa a `invoiced` amb `converted_to_id` emplenat i la nova factura es retorna a `data`. Només s'admet `target=invoice`.