# Truto connector

> Source: https://docs.clonepartner.com/connectors/truto/

The Truto connector gives Envoy tasks access to Truto integrated accounts. Use unified methods when you want a stable model across providers, proxy methods when you need provider-specific endpoints, and custom methods for an approved endpoint not covered by the standard helpers.

## Prerequisites

You need:

- a Truto API token stored as a secret;
- the Truto API base URL used by your environment;
- at least one active integrated account;
- the target account ID;
- permission for the resources and operations the task will use.

Create the connector from **Connectors**, test it, then use discovery to verify the account and resource before authoring a task.

## Keep account selection explicit

The connector can access more than one integrated account. Pass `integrated_account_id` on calls:

```yaml
arguments:
  integrated_account_id:
    type: string
    required: true

steps:
  - name: list_tickets
    type: call_method
    config: |
      {
        "connector": "truto",
        "method": "list",
        "args": {
          "integrated_account_id": arguments.integrated_account_id,
          "resource": "tickets",
          "unified_model": "ticketing"
        }
      }
```

Use a connector-backed [template argument](/guides/template-arguments) to let the job creator choose an account from a searchable list.

## Unified methods

Use unified operations when the resource exists in a Truto unified API:

- `list` and `get` common resources;
- `create`, `update`, or `delete` supported records;
- keep task mappings stable when changing integration providers.

Every unified call requires `unified_model`. Consult that model for supported fields. Provider-specific fields can differ even when the unified resource name is the same.

## Proxy methods

Use proxy methods when you need the third-party provider's native resource or shape:

```yaml
- name: list_native_tickets
  type: call_method
  config: |
    {
      "connector": "truto",
      "method": "proxy_list",
      "args": {
        "integrated_account_id": arguments.integrated_account_id,
        "resource": "tickets",
        "query": {
          "status": "open"
        }
      }
    }
```

Proxy task logic is provider-specific. Document the provider and API version assumptions and retest after provider changes.

## Pagination and streaming

List methods expose a streaming cursor to `call_method`. Let the step consume it with backpressure. Do not collect all pages with `$callMethod()` inside a transform.

For discovery pickers, request one page and return its `next_cursor`. Search on the server rather than filtering a complete account or resource list in the browser.

## Custom operations

A custom operation can describe an approved HTTP request through method configuration. Use it only when a unified or proxy helper is insufficient.

Mutating `custom_create`, `custom_update`, `custom_request`, and `custom_upsert` calls require a `methodConfig` object inside `args.data`. Without an appropriate `body_format`, the provider can receive an empty request body:

```yaml
- name: create_custom_record
  type: call_method
  config: |
    {
      "connector": "truto",
      "method": "custom_create",
      "args": {
        "integrated_account_id": arguments.integrated_account_id,
        "path": arguments.custom_path,
        "data": $merge([
          input,
          {
            "methodConfig": {
              "method": "POST",
              "body_format": "json"
            }
          }
        ])
      }
    }
```

Keep:

- the integrated account ID explicit;
- the HTTP method and path fixed by authored configuration;
- secrets in the connector;
- pagination bounded;
- write payloads validated;
- response extraction documented.

Do not expose free-form method configuration to untrusted dashboard users.

## Writes and retries

Before enabling writes:

1. verify the integrated account points to the intended tenant;
2. run a bounded read;
3. confirm required scopes;
4. send one test write;
5. inspect the provider response and Truto request identifiers;
6. retry only after reconciling ambiguous outcomes;
7. use a stable external or mapping key to avoid duplicates.

Provider rate limits and error shapes vary. Keep concurrency conservative and use [idempotent migration patterns](/guides/migration-and-idempotency).

## Troubleshooting

- **Account not listed:** verify it is active and visible to the token.
- **Unauthorized:** verify token, account ID, and scopes without logging the token.
- **Resource not found:** confirm unified versus proxy resource naming.
- **No more records:** preserve and pass the returned cursor exactly.
- **Unexpected shape:** inspect a bounded response and update the mapping; do not assume provider-native fields match a unified model.

See [Connector catalog and connected accounts](/connectors/catalog-and-connected-accounts) and [Connector reference](/reference/connectors).