Tripletex API

https://tripletex.no/v2-docs
Admin
Tripletex API provides an interface for developers to integrate with Tripletex services, offering...
Tokens:3,469
Snippets:24
Trust Score:8.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### GET /employee

Source: https://tripletex.no/v2-docs/index

Retrieves a list of employees.

```APIDOC
## GET /employee

### Description
Retrieves a list of all employees. Use the `fields` parameter to specify which employee details to include.

### Method
GET

### Endpoint
`/employee`

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include, e.g., `id,name,email` or `*,changes`.
```

--------------------------------

### GET /company

Source: https://tripletex.no/v2-docs/index

Retrieves information about the company.

```APIDOC
## GET /company

### Description
Fetches details for the company associated with the API key.

### Method
GET

### Endpoint
`/company`

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Specifies the fields to return, e.g., `*` or `name,id`.
```

--------------------------------

### Using Fields Parameter for Data Filtering

Source: https://tripletex.no/v2-docs/index

Examples of the `fields` parameter to specify which fields to return from API requests, including nested fields and wildcards.

```http
# Returns project, activity, and hours fields
?fields=project,activity,hours

# Returns only the name field from the project sub-resource
?fields=project(name)

# Returns all fields from project and the name from activity
?fields=project(*),activity(name)
```

--------------------------------

### Using Sorting Parameter for Data Ordering

Source: https://tripletex.no/v2-docs/index

Examples of the `sorting` parameter to control the order of results, including sorting by fields and sub-object fields, and specifying descending order.

```http
# Sort by date in ascending order
?sorting=date

# Sort by project name in ascending order, then by date in descending order
?sorting=project.name,-date
```

--------------------------------

### GET /accountingOffice/reconciliations/{reconciliationId}/control

Source: https://tripletex.no/v2-docs/index

API for managing reconciliation controls within Tripletex.

```APIDOC
## GET /accountingOffice/reconciliations/{reconciliationId}/control

### Description
Retrieves reconciliation controls for a specific reconciliation.

### Method
GET

### Endpoint
`/accountingOffice/reconciliations/{reconciliationId}/control`

### Parameters
#### Path Parameters
- **reconciliationId** (integer) - Required - The ID of the reconciliation.

#### Query Parameters
- **fields** (string) - Optional - Specifies which fields to include in the response, e.g., `*,changes`.

### Response
#### Success Response (200)
Returns an object containing reconciliation controls.
```

--------------------------------

### Generating API Client with Swagger Codegen

Source: https://tripletex.no/v2-docs/index

Instructions on generating an API client using swagger-codegen, recommending the --removeOperationIdPrefix flag for forward compatibility and cleaner code.

```bash
# Example command for swagger-codegen
# swagger-codegen generate -i openapi.json -l python --removeOperationIdPrefix
```

--------------------------------

### Tripletex API Overview

Source: https://tripletex.no/v2-docs/index

General information about the Tripletex API, including version, specification format, base URL, and client generation.

```APIDOC
## Tripletex API Documentation

**Version:** 2.72.06
**Specification Format:** OAS3
**OpenAPI Spec:** [/v2/openapi.json](/v2/openapi.json)
**Base URL:** https://tripletex.no/v2

### Usage Guidelines
*   **Download Spec:** Obtain the OpenAPI Specification file for client generation.
*   **Client Generation:** Use tools like openapi-generator or swagger-codegen with `--removeOperationIdPrefix` for cleaner code.
*   **Package Dependencies:** Be aware that endpoint availability may depend on your Tripletex package.

### Key Concepts
*   **Partial Updates:** Use `PUT` with optional fields instead of `PATCH`.
*   **Actions/Commands:** Indicated by a colon `:` in the RESTful path (e.g., `/hours/123/:approve`).
*   **Summaries/Aggregations:** Indicated by a greater-than sign `>` in the RESTful path (e.g., `/hours/>thisWeeksBillables`).
*   **Request ID:** `x-tlx-request-id` header in responses for validation and error tracking.
*   **Resource Version:** The `version` field prevents accidental overwrites during PUT/POST operations.
*   **Date/DateTime Format:** ISO 8601 (`YYYY-MM-DD` for dates, `YYYY-MM-DDThh:mm:ss` for date-times).
*   **Searching:** Utilize optional fields with categories like `range`, `in`, `exact`, and `like`.
*   **Authorization Filtering:** Missing fields or no response data may be due to authorization restrictions.
*   **Further Resources:** Refer to GitHub for more documentation and examples, and Tripletex for Developers for practical information and support.
```

--------------------------------

### Tripletex API Authentication Header

Source: https://tripletex.no/v2-docs/index

Demonstrates how to construct the 'Authorization' header for Basic access authentication using a session token and target company ID.

```http
Authorization: Basic <encoded token>
# where <encoded token> is base64(target_company_id:session_token)
```

--------------------------------

### Tripletex API Field Selection and Sorting

Source: https://tripletex.no/v2-docs/index

Information on how to use the `fields` parameter for selecting specific resource fields and the `sorting` parameter for ordering results.

```APIDOC
## Fields and Sorting

### Field Selection (`fields` parameter)
*   Specify fields to return using the `fields` query parameter.
*   Supports selecting fields from sub-elements using `field(subResourceFields)`.
*   `*` selects all fields for a resource.

**Examples:**
*   `fields=project,activity,hours` returns `{project:..., activity:..., hours:...}`.
*   `fields=project` returns `"project": { "id": 12345, "url": "tripletex.no/v2/projects/12345" }`.
*   `fields=project(*)` returns `"project": { "id": 12345, "name": "ProjectName", "number$": ".....", "startDate": "2013-01-07" }`.
*   `fields=project(name)` returns `"project": { "name": "ProjectName" }`.
*   `fields=*,activity(name),employee(*)` returns all fields plus specific fields from sub-resources.

### Sorting (`sorting` parameter)
*   Specify sorting using a comma-separated list.
*   Prefix a field with `-` for descending order.
*   Sort by sub-object fields using the format `<field>.<subObjectField>`.

**Examples:**
*   `sorting=date` sorts by date in ascending order.
*   `sorting=project.name` sorts by project name in ascending order.
*   `sorting=project.name,-date` sorts by project name ascending, then by date descending.
```

--------------------------------

### Tripletex API Authentication

Source: https://tripletex.no/v2-docs/index

Details on how to authenticate with the Tripletex API using consumer tokens, employee tokens, and session tokens via Basic access authentication.

```APIDOC
## Authentication

### Token Types
*   **consumerToken:** Provided by Tripletex after API 2.0 registration.
*   **employeeToken:** Created by an administrator in Tripletex with specific entitlements.
*   **sessionToken:** Generated via `/token/session/:create`, requires `consumerToken` and `employeeToken` from the same consumer.

### Authentication Method
*   **Type:** Basic access authentication.
*   **Username:** Specifies the company to access.
    *   `0` or blank: Accesses the employee's company.
    *   Other values: Accesses accountant clients. Use `/company/>withLoginAccess` to list these.
*   **Password:** The `sessionToken`.

### Authorization Header
*   Format: `Authorization: Basic <encoded token>`
*   `<encoded token>`: Base64 encoding of the string `<target company id or 0>:<your session token>`.
```

--------------------------------

### API Tags

Source: https://tripletex.no/v2-docs/index

Explanation of special tags used in the API documentation, such as [BETA] and [DEPRECATED].

```APIDOC
## API Tags

*   **[BETA]:** Indicates an endpoint that is in beta and may change in future releases.
*   **[DEPRECATED]:** Indicates a feature or capability that is planned for removal or change in a future major API release. Use is discouraged.
```

--------------------------------

### Status Codes / Error Codes

Source: https://tripletex.no/v2-docs/index

Overview of common HTTP status codes and specific Tripletex API error codes.

```APIDOC
## Status Codes / Error Codes

* **200 OK**
* **201 Created**
* **204 No Content**
* **400 Bad Request**:
    * `4000` Bad Request Exception
    * `11000` Illegal Filter Exception
    * `12000` Path Param Exception
    * `24000` Cryptography Exception
* **401 Unauthorized**:
    * `3000` Authentication Exception
* **403 Forbidden**:
    * `9000` Security Exception
* **404 Not Found**:
    * `6000` Not Found Exception
* **409 Conflict**:
    * `7000` Object Exists Exception
    * `8000` Revision Exception
    * `10000` Locked Exception
    * `14000` Duplicate entry
* **422 Unprocessable Entity** (Bad Request):
    * `15000` Value Validation Exception
    * `16000` Mapping Exception
    * `17000` Sorting Exception
    * `18000` Validation Exception
    * `21000` Param Exception
    * `22000` Invalid JSON Exception
    * `23000` Result Set Too Large Exception
* **429 Too Many Requests**
* **500 Internal Error**:
    * `1000` Exception
```

--------------------------------

### OpenAPI Specification (OAS3)

Source: https://tripletex.no/v2-docs/index

This is the OpenAPI Specification file for the Tripletex API, version 2.72.06. It details the API's structure, endpoints, parameters, and responses.

```yaml
OAS3

/v2/openapi.json 
[ Base URL: https://tripletex.no/v2 ]
```

--------------------------------

### Changes

Source: https://tripletex.no/v2-docs/index

To retrieve changes for a resource, the 'changes' parameter must be explicitly included in the 'fields' parameter (e.g., '*,changes'). Two change types are available: 'CREATE' and 'UPDATE'. Note that for objects created before October 24th, 2018, the change list may be incomplete.

```APIDOC
## Changes

To retrieve changes for a resource, include `changes` in the `fields` parameter (e.g., `*,changes`).

### Change Types
* `CREATE`: Resource creation.
* `UPDATE`: Resource update.

**Note:** For objects created before October 24th, 2018, the change list might be incomplete but will include the `CREATE` event and the last `UPDATE` if applicable.
```

--------------------------------

### Response Envelope

Source: https://tripletex.no/v2-docs/index

The API uses different response envelopes for multiple values, single values, webhooks, and errors/warnings.

```APIDOC
## Response Envelope

### Multiple Values
```json
{
  "fullResultSize": ###, 
  "from": ###, 
  "count": ###, 
  "versionDigest": "###", 
  "values": [...]
}
```

### Single Value
```json
{
  "value": {...}
}
```
```

--------------------------------

### Retrieve Resource Changes (Generic)

Source: https://tripletex.no/v2-docs/index

To obtain change information for a resource, the 'changes' field must be included in the 'fields' parameter. Supported change types are 'CREATE' and 'UPDATE'. Note that data before October 24th, 2018 may have incomplete change lists.

```curl
GET /resource?fields=*,changes
```

--------------------------------

### Webhook Envelope

Source: https://tripletex.no/v2-docs/index

The webhook envelope contains information about subscribed events, including subscription ID, event type, object ID, and the event value.

```APIDOC
## Webhook Envelope

```json
{
  "subscriptionId": ###,
  "event": "object.verb",
  "id": ###,
  "value": {...}
}
```
```

--------------------------------

### Error/Warning Envelope

Source: https://tripletex.no/v2-docs/index

This JSON envelope details API errors or warnings. It includes an HTTP status code, an internal code, user-friendly and developer-focused messages, optional validation messages per field, and a request ID.

```json
{
  "status": ###,
  "code": #####,
  "message": "###",
  "link": "###",
  "developerMessage": "###",
  "validationMessages": [
    {
      "field": "###",
      "message": "###"
    }
  ],
  "requestId": "###"
}
```

--------------------------------

### Error/Warning Envelope

Source: https://tripletex.no/v2-docs/index

The error/warning envelope provides detailed information about API errors, including status codes, messages, and validation details.

```APIDOC
## Error/Warning Envelope

```json
{
  "status": ###,
  "code": #####,
  "message": "###",
  "link": "###",
  "developerMessage": "###",
  "validationMessages": [
    {
      "field": "###",
      "message": "###"
    }
  ],
  "requestId": "###"
}
```
```

--------------------------------

### Response Envelope - Multiple Values

Source: https://tripletex.no/v2-docs/index

This JSON structure represents a paginated response containing multiple resource objects. It includes pagination details ('from', 'count'), a version hash, and an array of 'values'. The 'fullResultSize' field is deprecated.

```json
{
  "fullResultSize": ###, 
  "from": ###, 
  "count": ###, 
  "versionDigest": "###", 
  "values": [...{...object...}, {...object...}, {...object...}...]
}
```

--------------------------------

### Webhook Envelope

Source: https://tripletex.no/v2-docs/index

This is the structure for webhook notifications. It includes the 'subscriptionId', the 'event' type (e.g., 'object.verb'), the 'id' of the affected object, and the 'value' (the object itself, or null if deleted).

```json
{
  "subscriptionId": ###,
  "event": "object.verb",
  "id": ###,
  "value": {... single object, null if object.deleted ...}
}
```

--------------------------------

### API Rate Limit Headers

Source: https://tripletex.no/v2-docs/index

Rate limiting is applied per employee and API consumer. Response headers indicate the current rate limit status: X-Rate-Limit-Limit (total allowed requests), X-Rate-Limit-Remaining (remaining requests), and X-Rate-Limit-Reset (seconds until reset). Exceeding the limit results in a 429 status code.

```http-headers
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 50
X-Rate-Limit-Reset: 300
```

--------------------------------

### Rate Limiting

Source: https://tripletex.no/v2-docs/index

API calls are rate-limited per employee and per API consumer. Rate limit status is provided in response headers: `X-Rate-Limit-Limit`, `X-Rate-Limit-Remaining`, and `X-Rate-Limit-Reset`. Exceeding the limit results in a `429 Too Many Requests` status code.

```APIDOC
## Rate Limiting

Rate limiting is applied to API calls on a per-employee and per-API-consumer basis.

### Response Headers
* `X-Rate-Limit-Limit`: The maximum number of requests allowed in the current period.
* `X-Rate-Limit-Remaining`: The number of requests remaining in the current period.
* `X-Rate-Limit-Reset`: The time in seconds until the current period resets.

**Note:** If the rate limit is hit, all subsequent requests within the current period will return an HTTP status code of `429`.
```

--------------------------------

### Response Envelope - Single Value

Source: https://tripletex.no/v2-docs/index

This JSON structure is used when the API returns a single resource object. It contains a 'value' field holding the object.

```json
{
  "value": {...single object...}
}
```
Tokens:
Raw