Actividad

El registro de actividad es el historial de lo que pasa en la empresa: altas, modificaciones y eliminaciones de documentos, envíos por email y su entrega, accesos de los usuarios, sincronizaciones bancarias, envíos a la AEAT y a FACe, ejecuciones de tareas automáticas, cambios de ajustes… Es la misma información que muestra la página Actividad de la aplicación.

La API expone una sola operación de lectura con paginación por cursor. Sirve para auditar quién hizo qué y cuándo, para ver el historial de un documento concreto o para llevar a otro sistema la actividad nueva desde la última consulta.

Cada registro trae un núcleo común con forma fija (fecha, tipo, usuario, descripción, elemento afectado y origen de la petición) y un objeto details con algunos datos propios de su tipo. El contenido de los documentos no viaja en la actividad: qué campos cambió cada modificación, sus valores y la copia de cada momento están en las versiones del documento.

Permisos#

• El scope es activity:read.
• Con OAuth, además, el rol del usuario en la empresa necesita el permiso de actividad completo (ver la actividad de todos), como los roles Administrador y Asesor. Los roles que solo ven su propia actividad (en los predefinidos, Sólo lectura, Ventas, Compras y Ventas y compras) reciben un 403: la API no filtra la actividad por usuario.
• Una API key accede si tiene el scope. Al crearla, solo puede concederle activity:read quien tiene el permiso de actividad completo.
• Una aplicación conectada (servidor MCP y CLI) necesita además el permiso Registro de actividad en la conexión, en la empresa consultada. Solo puede concederlo quien tiene el permiso de actividad completo, y da acceso a la actividad de toda la empresa.

Estructura de un registro#

{
  "id": 482913,
  "timestamp": "2026-09-15T08:42:17.351Z",
  "type": "send",
  "subtype": null,
  "username": "ana.garcia@ejemplo.es",
  "description": "Enviado",
  "document": {
    "id": "inv_7c1e2f40-5a8b-4d3c-9e6f-2b1a0c9d8e7f",
    "type": "invoice",
    "title": "F2026-0123",
    "archived": false
  },
  "request": {
    "ip": "88.12.34.56",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
  },
  "details": {
    "actionSource": "user",
    "to": "pedidos@clienteejemplo.es"
  }
}

El elemento afectado: document#

• id — identificador del elemento: una factura (inv_…), un contacto (con_…), un banco, una tarea automática, un cobro…
• type — tipo del documento (invoice, bill, contact, product…). Es null cuando el elemento no es un documento.
• title — título del documento, por ejemplo el número de una factura o el nombre de un contacto.
• archived — true si el documento está eliminado.

Con el id puedes pedir el detalle en el recurso correspondiente (facturas, contactos…), con el scope de ese recurso.

Datos del tipo: details#

details no copia el registro interno: es una selección de campos de cada tipo. Incluye identificadores de otros elementos, resultados (estados, contadores, errores) y datos de la acción (formato, canal, destinatarios de un envío). Un campo que el registro no tiene no aparece, y la lista puede ampliarse con campos nuevos sin aviso, así que tu integración debe ignorar los campos que no conozca.

Muchos tipos devuelven un objeto vacío. Las altas y modificaciones de documentos no traen el contenido del documento: qué cambió en cada una se consulta en las versiones del documento, donde el id del registro de actividad es el identificador de la versión.

Las sincronizaciones bancarias del sistema anterior tienen sus propios tipos y devuelven los mismos campos que bankSync (más error) y bankSyncWarning. El resto de tipos devuelve un objeto vacío.

Tipos de actividad#

Los valores de type son los del filtro type de la operación (la lista completa está en el openapi). Los más habituales:

• Documentos: inserted (alta), updated (modificación, con subtype cuando es una acción concreta como voided, unvoided, addAttachments o updateTags), archived (eliminación), unarchived (recuperación), comment_inserted, file (generación de un PDF, Facturae o remesa).
• Envíos por email: send, send_queued, send_delivered, send_failed_temporary, send_failed_permanent, send_dropped, send_complained, y portalView para las consultas del documento en el portal de cliente. portalPaymentFinalizeFailed indica que se ha cobrado por el portal una factura provisional que no se ha podido emitir.
• Usuarios y empresa: access (entrada de un usuario), updateSettings, leaveCompany.
• Bancos: bankSync, bankSyncWarning (subtype indica el canal: psd2 para la conexión automática con el banco y paymentGateway para las pasarelas de pago).
• Fiscalidad: verifactu_send_aeat, verifactu_send_invoice, ticketbai_accepted, ticketbai_rejected, ticketbai_error, face_send_invoice, face_refresh_status, face_cancel_invoice.
• Tareas automáticas: automation, automationError, automationInfo, automationReport.
• Webhooks: webhook (entrega), webhook_endpoint_created y el resto de cambios de endpoints.
• Informes: report_subscription_created, report_subscription_updated, report_subscription_paused, report_subscription_resumed y report_subscription_deleted (el ciclo de vida de un envío programado, lo haga un usuario o el sistema), report_subscription_sent y report_subscription_failed (cada envío que sale por correo, también los de prueba) y report_export (cada exportación de un informe a un fichero). No incluyen la configuración ni los filtros del informe.

Los registros antiguos pueden tener tipos que ya no se generan. Trata type como un valor abierto: si no lo conoces, usa description.

Operaciones#

• Listar la actividad

Listar la actividad#

GET /{companyId}/activity devuelve la actividad con paginación por cursor (ver el patrón B en la guía de paginación).

Respuesta: { items: Activity[], hasMore: boolean, nextCursor: string | null }. Para pedir la página siguiente, pasa nextCursor en cursor; cuando es null, no hay más.

Parámetros de consulta:

• limit — número máximo de resultados, entre 1 y 100. Por defecto, 50.
• cursor — el nextCursor de la página anterior, tal cual se recibió. Devuelve la página que va detrás de ella en el orden pedido. Para la primera página, se omite. Es un valor opaco: uno que no haya devuelto la API responde 400.
• sortBy — -timestamp (por defecto) devuelve primero lo más reciente; timestamp, lo más antiguo. A igual fecha, se ordena por id.
• type — tipos de actividad a incluir. Se repite para indicar varios (type=inserted&type=archived) y se incluye la actividad de cualquiera de ellos.
• username — usuarios (email) que registraron la actividad. Admite varios, como type.
• documentId — identificador del elemento al que se refiere la actividad. Devuelve el historial de ese elemento.
• documentType — tipos del documento afectado (invoice, bill, contact…). Admite varios.
• minDate / maxDate — fecha y hora mínima y máxima, ambas incluidas, en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ). Los : pueden ir sin codificar; el + de un desfase horario se codifica como %2B, o llega como un espacio. Admiten también solo la fecha (YYYY-MM-DD), que cuenta el día entero en la zona horaria de la empresa (por defecto, Europe/Madrid): minDate=2026-09-01&maxDate=2026-09-30 es todo septiembre.

Parámetros globales aceptados:

Acepta además el header accept-version. Ver Autenticación.

Este endpoint no acepta offset ni los filtros estándar minCreationDate/maxCreationDate/minModificationDate/maxModificationDate.

Ejemplo de respuesta

{
  "items": [
    {
      "id": 482913,
      "timestamp": "2026-09-15T08:42:17.351Z",
      "type": "send",
      "subtype": null,
      "username": "ana.garcia@ejemplo.es",
      "description": "Enviado",
      "document": {
        "id": "inv_7c1e2f40-5a8b-4d3c-9e6f-2b1a0c9d8e7f",
        "type": "invoice",
        "title": "F2026-0123",
        "archived": false
      },
      "request": { "ip": "88.12.34.56", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" },
      "details": { "actionSource": "user", "to": "pedidos@clienteejemplo.es" }
    },
    {
      "id": 482877,
      "timestamp": "2026-09-15T07:00:04.120Z",
      "type": "bankSync",
      "subtype": "psd2",
      "username": "ami@facturadirecta.com",
      "description": "Sincronización bancaria realizada",
      "document": { "id": "<id-banco>", "type": "bank", "title": "Cuenta principal", "archived": false },
      "request": null,
      "details": {
        "processedTransactions": 12,
        "loadedTransactions": 9,
        "repeatedTransactions": 3,
        "ignoredTransactions": 0
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "NDgyODc3"
}

<id-banco> es un placeholder: cada empresa tiene sus propios identificadores.

Copy as cURL

Primera página:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/activity?limit=100"

Siguiente página, con el nextCursor de la anterior:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/activity?limit=100&cursor=NDgyODc3"

Historial de una factura, del más antiguo al más reciente:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/activity?documentId=inv_7c1e2f40-5a8b-4d3c-9e6f-2b1a0c9d8e7f&sortBy=timestamp"

Documentos eliminados en septiembre:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/activity?type=archived&minDate=2026-09-01T00:00:00.000Z&maxDate=2026-09-30T23:59:59.999Z"

Recomendaciones#

• Para llevar la actividad nueva a otro sistema, pide en orden ascendente (sortBy=timestamp) y guarda el nextCursor de la última página que procesaste. En la siguiente consulta, pásalo en cursor: recibes solo lo posterior, sin repetir ni saltar registros.
• Para auditar un documento, filtra por documentId en lugar de recorrer toda la actividad. Para ver qué valores cambiaron y recuperar datos, usa las versiones del documento.
• Acota con minDate/maxDate las consultas de históricos largos: la actividad de una empresa crece sin límite. Con type, añade también las fechas si buscas un tipo que no es reciente; si no, la consulta repasa toda la actividad posterior hasta encontrarlo. Una consulta que tarda demasiado se corta con un 422.
• No dependas de description para automatizar. Es texto para personas y puede cambiar; usa type, subtype y details.

Errores comunes#

• 400 ValidationError — cursor no es un cursor devuelto por la API, minDate/maxDate no son una fecha o una fecha y hora ISO 8601 que exista, type o sortBy tienen un valor desconocido, o limit está fuera de 1–100.
• 422 Unprocessable Entity (code: "activity_query_timeout") — la consulta ha tardado demasiado. Acota la búsqueda con minDate y maxDate o con más filtros.
• 403 Forbidden (code: "token_scope_missing") — falta el scope activity:read.
• 403 Forbidden (code: "user_role_insufficient") — el rol del usuario no tiene el permiso de actividad completo.

Ver Errores y validaciones para el formato general.

Referencia exhaustiva#

Esta página cubre los matices funcionales y los casos típicos. Para el contrato completo del registro, consulta el Swagger UI o el openapi crudo.

Endpoints#

Scopes#

• activity:read — Lectura del registro de actividad de la empresa.