> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Non-Functional Requirements

> Requirements for the export log an accounting integration must keep and let users download: Export Job and Export Item details, sync and token refresh logs, and a configuration snapshot. Logs are kept for 30 days. For the setup settings, see User-Facing Configurations.

This page describes the requirements that apply to your integration as a whole, beyond any single export or sync workflow. At present there is one: the integration must keep logs and let users download them.

## Logs

Bookkeepers need to review exported expenses, see their details and resolve export issues when they occur. To support this, your integration must save information about every Export Job and every Export Item within it. It must also let users download that information as a file.

### What the Log File Contains

The downloaded file must contain the following information.

**Context**

* A snapshot of the configuration parameters and their values at the time of download. See [User-Facing Configurations](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/integration-design-user-facing-configurations.md).
* The Accounting System version, if it applies.
* The connected Pleo entity, with its `company_id`.
* The connected company in the Accounting System.

**Export logs**

For each Export Job, include at least these fields.

| Field | API field | Description |
| - | - | - |
| Export date | `createdAt` | When the user started the Export Job, by selecting Export in Pleo. |
| Status | `status` | The status of the Export Job. |
| Number of expenses | `numberOfItems` | How many Export Items the Export Job contains. |
| Failure reason | `failureReason` | Why the Export Job failed, if it did. |
| Failure reason type | `failureReasonType` | The category of the failure. |

For each Export Item in the Export Job, include at least these fields.

| Field | API field | Description |
| - | - | - |
| Export date | `exportedAt` | When the integration exported the Export Item. |
| Status | `status` | The status of the Export Item. |
| Failure reason | `failureReason` | Why the Export Item failed, if it did. |
| Failure reason type | `failureReasonType` | The category of the failure. |
| Pleo ID | `accountingEntryId` | The Pleo identifier of the Export Item. |
| Accounting System ID | `externalId` | The identifier of the entry in the Accounting System, if your integration sent one. |
| Line amount | `accountingEntryLines.lineAmount` | The amount of each entry line. |
| Account | `accountingEntryLines.account` | The account of each entry line. |
| Tags | `accountingEntryLines.tags` | The Tags on each entry line. |
| Reconciliation ID | `additionalInformation.reconciliationId` | The reconciliation identifier of the entry. |
| Bookkeeping method | `bookkeeping.method` | The method the integration used to record the Export Item. |
| Expense type | `type` and `subType` | The type of the expense. |
| File info | `files` | Details of the attachments sent with the Export Item. |
| Vendor | `vendor` | The Vendor on the expense. |

**Other logs**

Record each of the following operations with a timestamp and a success status.

* Token refresh operations
* Tags sync operations
* Tax Codes sync operations
* Accounts sync operations
* Vendor sync operations

### Retention

Keep each log for 30 days. Delete any log that is older than 30 days automatically.

### Where the Data Comes From

Most of the Export Job and Export Item fields come from the values your integration already sends when it updates statuses. Use the same `failureReason` and `failureReasonType` values you report to Pleo, so the log and Pleo always agree. See [Update Export Items](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-update-export-items.md) for the values.

## Related Logging Guidance

The export log file above is the log that your integration must let users download. Other pages describe how to log specific operations, and what you must never log. Use them as guidance when you record the "Other logs". They do not add fields to the export log file.

### Never Log Credentials

Do not write tokens or full API Keys to logs, error messages or debug output. If you need an identifier for debugging, keep at most the last 4 characters of an API Key.

* [Secure Token Storage](https://developers.pleo.io/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-secure-token-storage.md#general-security-guidelines): avoid logging tokens or including them in error messages.
* [Security and Credential Management for Standalone API Keys](https://developers.pleo.io/docs/current/integration-design/auth/api-keys/integration-design-security-for-standalone-api-keys.md#logging-and-monitoring): see "Logging and Monitoring".
* [Security and Credential Management for Integrated API Keys](https://developers.pleo.io/docs/current/integration-design/auth/integrated-api-keys/integration-design-security-for-integrated-api-keys.md#logging-and-monitoring): see "Logging and Monitoring".

### Token Refresh and Authentication

* [How to Refresh Tokens](https://developers.pleo.io/docs/current/how-tos/oauth/how-to-refresh-tokens.md#7-log-refresh-activity): log each refresh attempt with a timestamp, the outcome and the failure reason where available.
* [How to Handle Token Expiry or Revocation](https://developers.pleo.io/docs/current/how-tos/oauth/how-to-handle-token-expiry-or-revocation.md#5-log-and-observe-failures): log refresh failures, the detection of expiry or revocation, and reauthentication triggers.
* [Race Condition Prevention](https://developers.pleo.io/docs/current/integration-design/auth/oauth/token-lifecycle/integration-design-auth-oauth-race-condition-prevention.md#implementation-tips): track refresh attempts, lock waits and failures.
* [How to Call Pleo APIs Using an Access Token](https://developers.pleo.io/docs/current/how-tos/oauth/how-to-call-pleo-apis-using-access-tokens.md#6-follow-security-best-practices): log authentication failures with enough context to troubleshoot.

### Sync Operations

* [Vendor Sync Workflow Guide](https://developers.pleo.io/docs/current/guides/accounting-integrations/imports/vendor-sync-workflow-guide.md#observability-and-recovery): add a sync-run ID to every log line, log how many Vendors you created, updated, unarchived and archived, and keep an audit trail for each write.
* [Vendor Creation Workflow Guide](https://developers.pleo.io/docs/current/guides/vendor-creation-workflow-guide.md#observability-and-recovery): use one correlation ID for each Vendor, and log the detection, the creation attempt and the activation.
* [Sync Vendors](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync.md#invalid-or-duplicate-externalid): log and skip Vendors with an empty or duplicate `externalId`.
* [Vendor Sync Data Mapping](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-data-mapping.md#handling-invalid-as-field-values): log invalid `country` or `defaultCurrency` values for investigation.
* [How to Handle a High-Volume Chart of Accounts](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-handle-high-volume-accounts.md#5-handle-a-rejection-from-pleo): log rejected batches and the items in the `failed` array.

### Export Processing

* [Attachment Handling](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-attachment-handling.md#4-failure-handling): log every failed attachment, and never drop one silently.

***

## Related Reading

* [User-Facing Configurations](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/integration-design-user-facing-configurations.md)
* [Update Export Items](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-update-export-items.md)
* [Integration Design Catalogue](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/integration-design-overview.md)

***
