Gastos

Gastos de la empresa. Hay dos modos, según el cuerpo.

1. Lista con totales (sin updatedSince ni cursor). Gastos activos del filtro, del más reciente al más antiguo (expenseDate y, a igualdad, expenseId, descendentes), con los totales de todo el filtro en totals. Como mucho 1000 gastos por respuesta: si el filtro tiene más, truncated: true y conviene acotarlo (month, vehicleId, types). Este modo no pagina.

2. Sincronización incremental (con updatedSince o cursor). Entrega todos los gastos cuyo último cambio (alta, corrección, ticket o anulación) cae en (updatedSince, syncedUntil], anulados incluidos (active: false), en orden de cambio y, a igualdad, por expenseId. Sin totals ni truncated.

1. Primera página: { "updatedSince": "<instante>", "limit": 200, ...filtros }. La primera vez, "1970-01-01T00:00:00Z".
2. Mientras nextCursor no sea null: { "cursor": "<nextCursor>", "limit": 200, ...los mismos filtros }. El cursor no guarda los filtros: repítelos en cada página. Si llegan cursor y updatedSince, manda cursor.
3. Con nextCursor: null has terminado: guarda syncedUntil y úsalo como updatedSince de la sincronización siguiente (nunca la hora de tu sistema).

• syncedUntil lo fija la primera página (la hora de la base de datos menos 60 s de margen de asentamiento) y viaja en el cursor: es el mismo en todas las páginas del recorrido. Un cambio tarda hasta 1 minuto en aparecer.
• Sin duplicados ni huecos: un gasto que cambia mientras recorres no se repite en ese recorrido; llega en la sincronización siguiente con su versión nueva.
• Si updatedSince va por delante de esa hora, la página sale vacía y syncedUntil es el propio updatedSince (nunca retrocede).
• limit (de 1 a 200, por defecto 200) solo vale en este modo.
• Los filtros se aplican al estado actual del gasto: uno corregido que deja de cumplirlos (otra fecha, otro vehículo u otro tipo) ya no sale y no se avisa. Para una copia completa, sincroniza sin filtros.
• Lo que borra la purga por retención (ejercicio + 5 años) no se avisa.

Filtros (los dos modos; opcionales y combinables): vehicleId, userId (el conductor del gasto), tripId (los peajes y aparcamientos ligados a ese viaje), types y el periodo por expenseDate: month, o from y to (incluidos). month no se combina con from/to.

Con clave API actúas como el owner que la creó: ves los gastos de toda la empresa, de todos los conductores. Leer no exige complementos: los gastos de un complemento que la empresa ya no tiene siguen saliendo.

Errores propios

• 422 invalid_input con error.fields, todos a la vez:
  • month: invalid (mal formado, o junto a from/to).
  • from, to: invalid (no es una fecha real YYYY-MM-DD); to: out_of_range (from > to).
  • types: invalid (no es una lista, está vacía o trae un tipo desconocido).
  • vehicleId, userId, tripId: invalid (no es un entero positivo).
  • updatedSince: invalid (sin hora, sin zona, fecha imposible o anterior a 1970).
  • cursor: invalid (no es un nextCursor emitido por el servidor).
  • limit: invalid (no es un entero > 0), out_of_range (> 200) o unexpected_field (sin updatedSince ni cursor).
  • Cualquier otra clave: unexpected_field.
• 422 invalid_input sin fields: el cuerpo no es un objeto JSON.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/list" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "month": "2026-09",
    "vehicleId": 7,
    "types": [
      "fuel",
      "ev_charge"
    ]
  }'

{
  "updatedSince": "2026-10-01T00:00:00Z",
  "limit": 200
}

{
  "cursor": "eyJ2IjoxLCJ1IjoiMjAyNi0xMC0xM1QwOTo1OTowMC4wMDAwMDBaIiwidCI6IjIwMjYtMTAtMTNUMDg6MTU6MDIuMTIzNDU2WiIsImkiOjgyfQ",
  "limit": 200
}

{
  "data": {
    "expenses": [
      {
        "expenseId": 81,
        "tenantId": 42,
        "vehicleId": 7,
        "vehiclePlate": "1234ABC",
        "userId": 11,
        "userName": "Bea Conductora",
        "type": "fuel",
        "addon": null,
        "expenseDate": "2026-09-10",
        "supplierName": "Repsol Getafe",
        "supplierTaxId": "A12345678",
        "baseAmount": 41.32,
        "vatRate": 21,
        "vatAmount": 8.68,
        "totalAmount": 50,
        "liters": 30.12,
        "kwh": null,
        "odometerKm": 120800,
        "notes": null,
        "attachment": {
          "filename": "ticket-repsol.jpg",
          "contentType": "image/jpeg",
          "sizeBytes": 184320
        },
        "ocrExtractionId": null,
        "tripId": null,
        "active": true,
        "integration": {
          "apiKeyId": 7,
          "name": "ERP Contable",
          "prefix": "fd_live_Ab12"
        },
        "createdAt": "2026-09-10T08:12:00.000Z",
        "updatedAt": "2026-09-10T08:12:00.000Z"
      }
    ],
    "totals": {
      "count": 1,
      "baseAmount": 41.32,
      "vatAmount": 8.68,
      "totalAmount": 50,
      "liters": 30.12,
      "kwh": 0,
      "missingBreakdown": 0,
      "toReview": 0,
      "byType": [
        {
          "type": "fuel",
          "totalAmount": 50
        }
      ]
    },
    "truncated": false
  }
}

{
  "data": {
    "expenses": [
      {
        "expenseId": 82,
        "tenantId": 42,
        "vehicleId": 7,
        "vehiclePlate": "1234ABC",
        "userId": 11,
        "userName": "Bea Conductora",
        "type": "toll",
        "addon": "tolls_parking",
        "expenseDate": "2026-10-12",
        "supplierName": "Autopistas AP-6",
        "supplierTaxId": null,
        "baseAmount": null,
        "vatRate": null,
        "vatAmount": null,
        "totalAmount": 12.4,
        "liters": null,
        "kwh": null,
        "odometerKm": null,
        "notes": null,
        "attachment": null,
        "ocrExtractionId": null,
        "tripId": 120,
        "active": false,
        "integration": null,
        "createdAt": "2026-10-12T17:40:11.250Z",
        "updatedAt": "2026-10-13T08:15:02.123Z"
      }
    ],
    "nextCursor": "eyJ2IjoxLCJ1IjoiMjAyNi0xMC0xM1QwOTo1OTowMC4wMDAwMDBaIiwidCI6IjIwMjYtMTAtMTNUMDg6MTU6MDIuMTIzNDU2WiIsImkiOjgyfQ",
    "syncedUntil": "2026-10-13T09:59:00.000000Z"
  }
}

Un gasto activo de la empresa. Un gasto anulado responde 404, igual que uno inexistente o de otra empresa: los anulados solo salen en la sincronización de list (active: false) y en history.

Con clave API actúas como el owner que la creó: alcanzas los gastos de todos los conductores. Un gasto dado de alta por la API lleva en integration la clave con la que se registró.

Errores propios

• 404 expense_not_found: no existe, está anulado o es de otra empresa (no se distingue).
• 422 invalid_input: fields.expenseId = required o invalid; otra clave, unexpected_field.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/get" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expenseId": 81
  }'

{
  "data": {
    "expense": {
      "expenseId": 81,
      "tenantId": 42,
      "vehicleId": 7,
      "vehiclePlate": "1234ABC",
      "userId": 11,
      "userName": "Bea Conductora",
      "type": "fuel",
      "addon": null,
      "expenseDate": "2026-10-01",
      "supplierName": "Repsol Getafe",
      "supplierTaxId": "A12345678",
      "baseAmount": 41.32,
      "vatRate": 21,
      "vatAmount": 8.68,
      "totalAmount": 50,
      "liters": 30.12,
      "kwh": null,
      "odometerKm": 120800,
      "notes": null,
      "attachment": {
        "filename": "ticket-repsol.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 184320
      },
      "ocrExtractionId": null,
      "tripId": null,
      "active": true,
      "integration": {
        "apiKeyId": 7,
        "name": "ERP Contable",
        "prefix": "fd_live_Ab12"
      },
      "createdAt": "2026-10-01T09:30:12.345Z",
      "updatedAt": "2026-10-01T09:30:12.345Z"
    }
  }
}

Versiones selladas de un gasto cuando la empresa tiene activos los registros inalterables: alta (create), correcciones (correct, también al adjuntar o sustituir el ticket) y anulación (void), de la primera a la última. Cada versión lleva autor, hora, motivo, la instantánea fiscal del gasto después del cambio, la huella de su ticket y qué campos cambiaron respecto a la anterior.

• Vale también para un gasto anulado (su historial termina en void).
• Un gasto de antes de activar el ajuste, o de una empresa sin él, da versions: [].
• Una versión cuyo contenido falta o no se entiende sale con redacted: true y sin datos: es una alteración, y POST /movimientos/integridad/verify da la cadena por rota.
• Hasta 500 versiones por gasto.

Con clave API actúas como el owner que la creó: alcanzas los gastos de todos los conductores. El autor de lo registrado por la API es ese owner.

Errores propios

• 404 expense_not_found: no existe o es de otra empresa.
• 422 invalid_input: fields.expenseId = required o invalid; otra clave, unexpected_field.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/history" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expenseId": 81
  }'

{
  "data": {
    "expenseId": 81,
    "versions": [
      {
        "seq": 12,
        "version": 1,
        "change": "create",
        "author": {
          "userId": 10,
          "name": "Ana Titular"
        },
        "recordedAt": "2026-10-01T09:30:12.345Z",
        "reason": null,
        "snapshot": {
          "vehicleId": 7,
          "userId": 11,
          "type": "fuel",
          "expenseDate": "2026-10-01",
          "supplierName": "Repsol Getafe",
          "supplierTaxId": "A12345678",
          "baseAmount": 41.32,
          "vatRate": 21,
          "vatAmount": 8.68,
          "totalAmount": 50,
          "liters": 30.12,
          "kwh": null,
          "odometerKm": 120800,
          "notes": null,
          "tripId": null,
          "ticketSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
        },
        "files": [
          {
            "kind": "ticket",
            "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
            "bytes": 184320
          }
        ],
        "changed": [],
        "entryHash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "redacted": false
      },
      {
        "seq": 15,
        "version": 2,
        "change": "correct",
        "author": {
          "userId": 10,
          "name": "Ana Titular"
        },
        "recordedAt": "2026-10-02T10:02:40.120Z",
        "reason": "El importe estaba mal tecleado",
        "snapshot": {
          "vehicleId": 7,
          "userId": 11,
          "type": "fuel",
          "expenseDate": "2026-10-01",
          "supplierName": "Repsol Getafe",
          "supplierTaxId": "A12345678",
          "baseAmount": 45.45,
          "vatRate": 21,
          "vatAmount": 9.55,
          "totalAmount": 55,
          "liters": 30.12,
          "kwh": null,
          "odometerKm": 120800,
          "notes": null,
          "tripId": null,
          "ticketSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
        },
        "files": [
          {
            "kind": "ticket",
            "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
            "bytes": 184320
          }
        ],
        "changed": [
          "baseAmount",
          "totalAmount",
          "vatAmount"
        ],
        "entryHash": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9",
        "redacted": false
      }
    ]
  }
}

Los nueve tipos de gasto, siempre en el mismo orden, con el complemento que exige cada uno (addon; null = plan base) y si la empresa lo tiene activo (available).

• available es true en el plan base o si el complemento está activo (pagado o regalado; en la prueba, solo los regalados). Es la misma regla que aplica save, que sigue siendo quien decide: guardar un tipo no disponible responde 403 feature_not_included.
• No dice si la cuenta admite escrituras: eso lo responde cada escritura (423 account_read_only).

El cuerpo va vacío o como {}.

Errores propios

• 422 invalid_input: cualquier clave del cuerpo es unexpected_field; sin fields si el cuerpo no es un objeto JSON.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/types-list" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "types": [
      {
        "type": "fuel",
        "addon": null,
        "available": true
      },
      {
        "type": "ev_charge",
        "addon": null,
        "available": true
      },
      {
        "type": "toll",
        "addon": "tolls_parking",
        "available": true
      },
      {
        "type": "parking",
        "addon": "tolls_parking",
        "available": true
      },
      {
        "type": "maintenance",
        "addon": "maintenance_itv",
        "available": false
      },
      {
        "type": "itv",
        "addon": "maintenance_itv",
        "available": false
      },
      {
        "type": "insurance",
        "addon": "insurance_tax_renting",
        "available": false
      },
      {
        "type": "vehicle_tax",
        "addon": "insurance_tax_renting",
        "available": false
      },
      {
        "type": "renting",
        "addon": "insurance_tax_renting",
        "available": false
      }
    ]
  }
}

URL prefirmada de S3 para descargar el ticket (foto o PDF) de un gasto activo. Caduca a los 300 segundos (expiresIn).

• Descárgalo con un GET a url, sin cabecera Authorization: la firma de la URL es la credencial. No la guardes ni la registres en logs.
• S3 lo sirve con el contentType y el filename guardados, como Content-Disposition: attachment (descarga) o, con inline: true, inline (para mostrarlo).
• Es una lectura: funciona aunque la cuenta esté en solo lectura o el mes esté cerrado, y no exige complementos.
• El ticket de un gasto anulado no se puede descargar por aquí (404).

Errores propios

• 404 expense_not_found: el gasto no existe, está anulado o es de otra empresa.
• 404 attachment_not_found: el gasto no tiene ticket.
• 422 invalid_input: fields.expenseId = required o invalid; fields.inline = invalid (no es booleano); otra clave, unexpected_field.
• 502 storage_unavailable: S3 no pudo firmar la URL. Reintenta.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/attachment-download-url" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expenseId": 81,
    "inline": false
  }'

{
  "data": {
    "url": "https://pfens-flotadoc-documents-production.s3.eu-west-1.amazonaws.com/42/expenses/u10/9f1c2a1b0d4e5f60718293a4b5c6d7e8/ticket-repsol.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Date=20261013T091500Z&X-Amz-Signature=5d41402abc4b2a76b9719d911017c592",
    "filename": "ticket-repsol.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 184320,
    "expiresIn": 300
  }
}

{
  "error": {
    "code": "storage_unavailable",
    "message": "No se pudo acceder al almacen de documentos"
  }
}

Alta (sin expenseId) o corrección (con expenseId) de un gasto. Es un guardado completo: manda siempre todos los campos; un campo opcional ausente, null o "" se guarda vacío (también en una corrección: no mandar tripId suelta el viaje). La excepción es el ticket: solo cambia si llega attachmentKey con una clave distinta de la que ya tiene.

Con clave API actúas como el owner que la creó (misma empresa, complementos, cuenta, mes cerrado y registros inalterables) y registras en nombre de un conductor:

• En el alta, driverUserId es obligatorio (el id de POST /auth/usuarios/list). El gasto es suyo (userId): sale en su lista y en la del owner. Tiene que poder registrarlo él: persona activa de la empresa con rol user u owner (una invitada que aún no ha entrado vale) y, si es user, en un vehículo que puede usar (variable, o fijo con él entre sus conductores).
• El alta queda marcada con la clave (integration). Una corrección no cambia ni el conductor ni el origen; driverUserId, si viene, tiene que ser el del gasto.
• El autor del sello (registros inalterables) y de la auditoría es el owner de la clave.
• ocrExtractionId es de la app (el OCR no está en la API): la lectura tendría que haberla pedido el propio owner. Una integración manda los campos y lo omite.

Ticket con el gasto. Pide la URL con attachment-upload-url, sube el fichero con el PUT y manda aquí su key en attachmentKey antes de 24 h: el gasto y su ticket se guardan en la misma operación (o ninguno). El servidor comprueba en S3 que el fichero está y es una imagen o PDF de hasta 20 MB, y calcula su huella SHA-256. La subida tiene que haberla pedido el mismo owner (con cualquiera de sus claves) y no puede estar adjunta a otro gasto. Para adjuntarlo después: attachment-attach.

Reglas de negocio

• fuel solo en vehículos de combustión o híbridos y con liters; ev_charge solo en eléctricos o híbridos y con kwh. liters y kwh están prohibidos en los demás tipos.
• tripId solo en toll y parking: viaje activo de la empresa y del mismo vehículo. Una corrección que mantiene el mismo viaje y vehículo no lo vuelve a comprobar.
• Si llegan baseAmount y vatAmount, base + cuota = total con ±0,02 € de margen.
• Vehículo activo de la empresa; una corrección que no cambia de vehículo admite uno ya de baja.
• Registrar o corregir un tipo de complemento exige tenerlo (en una corrección, también el del tipo que tenía): types-list dice cuáles están disponibles.
• Mes cerrado: el mes de destino (vehículo y fecha) y, en una corrección, el mes donde está hoy el gasto tienen que estar abiertos.
• Registros inalterables: el alta sella una versión create (sin motivo); la corrección, una correct que exige reason. Sin el ajuste, reason es opcional y no se guarda.

Orden de comprobación: puerta → cuenta (423) → cuerpo (422) → driverUserId obligatorio → attachmentKey → gasto a corregir (404) y subida del ticket (422) → complemento (403) → vehículo (404) y energía (422) → conductor (422) → viaje (404/422) → ticket en S3 (422/502) → lectura OCR (422) → escritura: mes cerrado (409), subida caducada (422), motivo (422).

Errores propios

• 403 feature_not_included (con feature): el tipo, o en una corrección el que tenía, es de un complemento que la empresa no tiene.
• 404 expense_not_found: corrección de un gasto inexistente, anulado o de otra empresa.
• 404 vehicle_not_found: el vehículo no existe, es de otra empresa o está de baja.
• 404 trip_not_found: el viaje de tripId no existe, está anulado o descartado, o es de otra empresa.
• 409 period_closed (con periods: [{ vehicleId, month: "YYYY-MM" }]): algún mes afectado está cerrado; hay que pedir a la empresa que lo reabra. También 409 idempotency_* de la puerta.
• 422 invalid_input con error.fields. Los de formato llegan todos a la vez: required, invalid, too_long, out_of_range, in_future (expenseDate posterior a hoy en Madrid), mismatch (totalAmount no cuadra con base + cuota), not_for_type (liters, kwh o tripId en un tipo que no los admite), unexpected_field. Llegan solos, porque se comprueban después: driverUserId = required (alta sin conductor), not_found (no es conductor activo de la empresa), vehicle_not_allowed (no puede usar ese vehículo) o immutable (corrección con otro conductor); attachmentKey = invalid (no es una clave emitida para este owner en esta empresa); type = not_for_vehicle (energía del vehículo); tripId = not_for_vehicle (el viaje es de otro vehículo); ocrExtractionId = invalid.
• 422 reason_required: corrección sin reason con registros inalterables (no se guardó nada).
• 422 attachment_not_uploaded: la subida de attachmentKey no está registrada, tiene más de 24 h, se descartó, ya es el ticket de otro gasto, o el fichero no está en S3 (no se hizo el PUT o no terminó). Vuelve a subirlo.
• 422 attachment_invalid: el fichero de S3 no es una imagen JPEG/PNG/WebP o un PDF de 1 byte a 20 MB.
• 423 account_read_only (con reason: account, suspended o pending_payment): la cuenta no admite registros (prueba, contrato o pago vencidos). Leer sigue funcionando.
• 502 storage_unavailable: S3 no respondió al comprobar o leer el ticket.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/save" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "driverUserId": 11,
    "vehicleId": 7,
    "type": "fuel",
    "expenseDate": "2026-10-01",
    "totalAmount": 50,
    "baseAmount": 41.32,
    "vatRate": 21,
    "vatAmount": 8.68,
    "supplierName": "Repsol Getafe",
    "supplierTaxId": "A12345678",
    "liters": 30.12,
    "odometerKm": 120800,
    "notes": null,
    "attachmentKey": "42/expenses/u10/9f1c2a1b0d4e5f60718293a4b5c6d7e8/ticket-repsol.jpg"
  }'

{
  "expenseId": 81,
  "vehicleId": 7,
  "type": "fuel",
  "expenseDate": "2026-10-01",
  "totalAmount": 55,
  "baseAmount": 45.45,
  "vatRate": 21,
  "vatAmount": 9.55,
  "supplierName": "Repsol Getafe",
  "supplierTaxId": "A12345678",
  "liters": 30.12,
  "odometerKm": 120800,
  "reason": "El importe estaba mal tecleado"
}

{
  "data": {
    "expense": {
      "expenseId": 81,
      "tenantId": 42,
      "vehicleId": 7,
      "vehiclePlate": "1234ABC",
      "userId": 11,
      "userName": "Bea Conductora",
      "type": "fuel",
      "addon": null,
      "expenseDate": "2026-10-01",
      "supplierName": "Repsol Getafe",
      "supplierTaxId": "A12345678",
      "baseAmount": 41.32,
      "vatRate": 21,
      "vatAmount": 8.68,
      "totalAmount": 50,
      "liters": 30.12,
      "kwh": null,
      "odometerKm": 120800,
      "notes": null,
      "attachment": {
        "filename": "ticket-repsol.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 184320
      },
      "ocrExtractionId": null,
      "tripId": null,
      "active": true,
      "integration": {
        "apiKeyId": 7,
        "name": "ERP Contable",
        "prefix": "fd_live_Ab12"
      },
      "createdAt": "2026-10-01T09:30:12.345Z",
      "updatedAt": "2026-10-01T09:30:12.345Z"
    }
  }
}

{
  "error": {
    "code": "storage_unavailable",
    "message": "No se pudo acceder al almacen de documentos"
  }
}

Anula un gasto activo. Es un borrado lógico: el gasto y su ticket se conservan como justificante fiscal, pero sale de las listas, de los totales y del precio del combustible del mes. La sincronización de list lo entrega después con active: false.

• No exige complemento: se puede anular un peaje aunque la empresa ya no tenga ese complemento.
• Registros inalterables: anular sella una versión void y exige reason. Sin el ajuste, reason es opcional y no se guarda.
• Mes cerrado: si el mes del gasto (su vehículo y su fecha) está cerrado, no se anula.

Con clave API actúas como el owner que la creó: puedes anular cualquier gasto de la empresa.

Errores propios

• 404 expense_not_found: no existe, ya está anulado o es de otra empresa.
• 409 period_closed (con periods: [{ vehicleId, month: "YYYY-MM" }]): el mes del gasto está cerrado. También 409 idempotency_* de la puerta.
• 422 invalid_input: fields.expenseId = required o invalid; fields.reason = invalid o too_long; otra clave, unexpected_field.
• 422 reason_required: sin reason con registros inalterables (no se anuló).
• 423 account_read_only (con reason: account, suspended o pending_payment).

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/delete" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "expenseId": 81,
    "reason": "Ticket duplicado"
  }'

{
  "data": {
    "deleted": true,
    "expenseId": 81
  }
}

Primer paso para guardar el ticket (foto o PDF) de un gasto. Declaras nombre, tipo y tamaño exacto del fichero y el servidor compone la clave de S3 y firma un PUT directo a S3: los bytes nunca pasan por la API. No pide gasto: el ticket se sube antes de guardarlo.

Subida (PUT). En menos de 300 s (expiresIn):

PUT <url>
Content-Type: <contentType, el mismo que declaraste>
Content-Length: <sizeBytes, exactamente>

<bytes del fichero>

• Content-Type y Content-Length van en la firma (X-Amz-SignedHeaders=content-length;content-type;host): otro tipo u otro tamaño hace que S3 responda 403 y no guarde nada.
• Sin cabecera Authorization: la firma de la URL es la credencial. No la guardes ni la registres en logs. S3 responde 200 con el cuerpo vacío.
• Por ejemplo: curl -X PUT "$URL" -H 'Content-Type: image/jpeg' --data-binary @ticket.jpg.

Después, antes de 24 h desde esta llamada, liga el ticket a un gasto con su key: save con attachmentKey (alta o corrección; el gasto y el ticket se guardan juntos) o attachment-attach (gasto ya existente). Una subida que nadie adjunta en 24 h se borra sola.

• Cada llamada crea una subida nueva (key distinta, aunque el nombre se repita): nunca pisa un ticket ya adjuntado.
• filename vuelve saneado: es el nombre con el que se guardará y descargará el ticket.
• Con clave API, la subida es del owner que creó la clave (la key lleva u{su id}), aunque el gasto sea de un conductor; solo ese owner (con cualquiera de sus claves) puede adjuntarla.
• Sin Idempotency-Key: la operación solo firma una URL, así que no guarda respuesta y la cabecera se ignora (como en las lecturas). Repetir la llamada da otra url válida y otra key, nunca una URL caducada; la subida que no uses se borra sola a las 24 h. Si se corta la conexión, vuelve a pedirla.

Errores propios

• 413 payload_too_large (con maxBytes: 20971520): sizeBytes supera 20 MB y el resto del cuerpo es válido.
• 422 invalid_input con error.fields: filename = required o invalid (no queda nada útil al sanearlo); contentType = required o invalid (no es application/pdf, image/jpeg, image/png ni image/webp); sizeBytes = required, invalid (no es un entero > 0) o too_large (junto a otros errores); otra clave, unexpected_field.
• 423 account_read_only (con reason: account, suspended o pending_payment): se comprueba antes que el cuerpo.
• 502 storage_unavailable: S3 no pudo firmar. Pide otra URL.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/attachment-upload-url" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "ticket-repsol.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 184320
  }'

{
  "data": {
    "url": "https://pfens-flotadoc-documents-production.s3.eu-west-1.amazonaws.com/42/expenses/u10/9f1c2a1b0d4e5f60718293a4b5c6d7e8/ticket-repsol.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost&X-Amz-Date=20261013T091500Z&X-Amz-Signature=5d41402abc4b2a76b9719d911017c592",
    "key": "42/expenses/u10/9f1c2a1b0d4e5f60718293a4b5c6d7e8/ticket-repsol.jpg",
    "filename": "ticket-repsol.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 184320,
    "expiresIn": 300
  }
}

{
  "error": {
    "code": "payload_too_large",
    "message": "El ticket supera el tamano maximo",
    "maxBytes": 20971520
  }
}

{
  "error": {
    "code": "storage_unavailable",
    "message": "No se pudo acceder al almacen de documentos"
  }
}

Liga a un gasto ya existente el ticket subido con attachment-upload-url y el PUT. Si el gasto ya tenía ticket, lo sustituye. Para un alta con ticket es más simple mandar la key en save (attachmentKey).

• La key tiene que ser una subida del mismo owner (con cualquiera de sus claves), de menos de 24 h y no adjunta a otro gasto. El servidor comprueba en S3 que el fichero está y es una imagen o PDF de hasta 20 MB, y calcula su huella SHA-256.
• Repetir la llamada con la key que ya es el ticket del gasto responde 200 sin cambiar nada.
• Adjuntar a un gasto de complemento exige tener el complemento.
• Mes cerrado: el ticket de un mes cerrado queda congelado (tampoco se sustituye).
• Registros inalterables: adjuntar es una corrección sellada (correct). El primer ticket de un gasto que no tenía no necesita reason (el servidor pone «Se añade el ticket»); sustituirlo exige reason. El ticket sustituido se conserva en la versión anterior. Sin el ajuste, reason es opcional y no se guarda, y el ticket sustituido se descarta.

Con clave API actúas como el owner que la creó: puedes adjuntar el ticket a un gasto de cualquier conductor de la empresa.

Errores propios

• 403 feature_not_included (con feature): el gasto es de un complemento que la empresa no tiene.
• 404 expense_not_found: el gasto no existe, está anulado o es de otra empresa.
• 409 period_closed (con periods: [{ vehicleId, month: "YYYY-MM" }]): el mes del gasto está cerrado. También 409 idempotency_* de la puerta.
• 422 invalid_input con error.fields: expenseId = required o invalid; key = required o invalid (también, sola, si no es una clave emitida para este owner en esta empresa); reason = invalid o too_long; otra clave, unexpected_field.
• 422 attachment_not_uploaded: la subida no está registrada, tiene más de 24 h, se descartó, ya es el ticket de otro gasto, o el fichero no está en S3. Vuelve a subirlo.
• 422 attachment_invalid: el fichero de S3 no es una imagen JPEG/PNG/WebP o un PDF de 1 byte a 20 MB.
• 422 reason_required: sustituir el ticket sin reason con registros inalterables (no se cambió nada).
• 423 account_read_only (con reason: account, suspended o pending_payment).
• 502 storage_unavailable: S3 no respondió al comprobar o leer el fichero.

curl -sS -X POST "https://app.flotadoc.com/api/movimientos/gastos/attachment-attach" \
  -H "Authorization: Bearer $FLOTADOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "expenseId": 81,
    "key": "42/expenses/u10/9f1c2a1b0d4e5f60718293a4b5c6d7e8/ticket-repsol.jpg"
  }'

{
  "data": {
    "expense": {
      "expenseId": 81,
      "tenantId": 42,
      "vehicleId": 7,
      "vehiclePlate": "1234ABC",
      "userId": 11,
      "userName": "Bea Conductora",
      "type": "fuel",
      "addon": null,
      "expenseDate": "2026-10-01",
      "supplierName": "Repsol Getafe",
      "supplierTaxId": "A12345678",
      "baseAmount": 41.32,
      "vatRate": 21,
      "vatAmount": 8.68,
      "totalAmount": 50,
      "liters": 30.12,
      "kwh": null,
      "odometerKm": 120800,
      "notes": null,
      "attachment": {
        "filename": "ticket-repsol.jpg",
        "contentType": "image/jpeg",
        "sizeBytes": 184320
      },
      "ocrExtractionId": null,
      "tripId": null,
      "active": true,
      "integration": {
        "apiKeyId": 7,
        "name": "ERP Contable",
        "prefix": "fd_live_Ab12"
      },
      "createdAt": "2026-10-01T09:30:12.345Z",
      "updatedAt": "2026-10-01T11:02:05.871Z"
    }
  }
}

{
  "error": {
    "code": "storage_unavailable",
    "message": "No se pudo acceder al almacen de documentos"
  }
}