Docs menu: Connections

Connections

A merchant's credentials for one provider, in one mode.

On this page

Retrieve a connection
List a merchant's connections
Connect a merchant to a provider

Retrieve a connection #

GET /api/v1/connections/{id}

Returns one of your connections in your key's mode, without its credentials.

Bearer API key

Path parameters

idstringrequired: The connection's id (con_…).

Request

curl

curl -X GET 'https://tallio.dev/api/v1/connections/con_02y9O8rh7F50tGi0QcWRrx' \
  -H "Authorization: Bearer $TALLIO_API_KEY"

TypeScript SDK

import { createTallioClient, unwrap } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await unwrap(tallio.http.GET("/api/v1/connections/{id}", {
  params: {
    path: {
      id: "con_02y9O8rh7F50tGi0QcWRrx",
    },
  },
}));

Responses
Status	Description
`200`	The connection.
4XX, 5XX	An error: see Errors below.

Response body · 200

dataobjectrequired

A merchant's credentials for one provider in one mode. The credentials themselves are never returned.

Show nested fields (9)

idstringrequired

Id of the connection (con_…).

Show pattern

^con_[0-9A-Za-z]{22}$

objectstringrequired

Always "connection".

Always connection

merchantstringrequired

The merchant this connection belongs to (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

modestringrequired

live for a connection made with a live key, test for a test key.

One of: live, test

statusstringrequired

active (documents can be routed to it), invalid (the provider refused its credentials; fix and verify again), disconnected (no longer used; its credentials are deleted 30 days later).

One of: active, invalid, disconnected

verified_atstring | nullrequired

When the provider last accepted its credentials; null until then.

Format: date-time

last_errorobject | nullrequired

Why the provider last refused it; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: validation_failed, unauthorized, not_found, idempotency_conflict, idempotency_in_progress, already_exists, payload_too_large, unsupported_media_type, rate_limited, not_supported, provider_rejected, provider_unavailable, service_unavailable, internal_error
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload.

createdstringrequired

When the connection was created.

Format: date-time

Example response · 200

{
  "data": {
    "id": "con_02y9O8rh7F50tGi0QcWRrx",
    "object": "connection",
    "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
    "provider": "sandbox",
    "mode": "live",
    "status": "active",
    "verified_at": "2026-10-11T09:30:00.000Z",
    "last_error": {
      "code": "validation_failed",
      "message": "string",
      "provider_code": "string",
      "provider_message": "string",
      "retryable": false
    },
    "created": "2026-10-11T09:30:00.000Z"
  }
}

Response headers

x-request-idstring: The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.
With every response
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 200, 404, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 200, 404, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 200, 404, 429 · At least 0
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`unauthorized`	401	No	Authentication is required.
`not_found`	404	No	The requested resource was not found.
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.

List a merchant's connections #

GET /api/v1/merchants/{id}/connections

Returns the merchant's connections in your key's mode, newest first, without their credentials.

Bearer API key

Path parameters

idstringrequired: The merchant's id (mer_…).

Query parameters

limitinteger: How many items to return, 1 to 100; 10 by default.
From 1 to 100 · Default: 10
starting_afterstring: An id (con_…) from this list: return the items after it, older ones (pass the last id of the current page). Not with ending_before.
Up to 64 characters
ending_beforestring: An id (con_…) from this list: return the items before it, newer ones (pass the first id of the current page). Not with starting_after.
Up to 64 characters

Request

curl

curl -X GET 'https://tallio.dev/api/v1/merchants/mer_02y9O8rh7F50tGi0QcWRrx/connections' \
  -H "Authorization: Bearer $TALLIO_API_KEY"

TypeScript SDK

import { createTallioClient, unwrap } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await unwrap(tallio.http.GET("/api/v1/merchants/{id}/connections", {
  params: {
    path: {
      id: "mer_02y9O8rh7F50tGi0QcWRrx",
    },
  },
}));

Responses
Status	Description
`200`	A page of connections.
4XX, 5XX	An error: see Errors below.

Response body · 200

objectstringrequired

Always "list".

Always list

dataobject[]required

This page's items, newest first.

Each item: A merchant's credentials for one provider in one mode. The credentials themselves are never returned.

Show nested fields (9)

idstringrequired

Id of the connection (con_…).

Show pattern

^con_[0-9A-Za-z]{22}$

objectstringrequired

Always "connection".

Always connection

merchantstringrequired

The merchant this connection belongs to (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

modestringrequired

live for a connection made with a live key, test for a test key.

One of: live, test

statusstringrequired

active (documents can be routed to it), invalid (the provider refused its credentials; fix and verify again), disconnected (no longer used; its credentials are deleted 30 days later).

One of: active, invalid, disconnected

verified_atstring | nullrequired

When the provider last accepted its credentials; null until then.

Format: date-time

last_errorobject | nullrequired

Why the provider last refused it; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: validation_failed, unauthorized, not_found, idempotency_conflict, idempotency_in_progress, already_exists, payload_too_large, unsupported_media_type, rate_limited, not_supported, provider_rejected, provider_unavailable, service_unavailable, internal_error
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload.

createdstringrequired

When the connection was created.

Format: date-time

has_morebooleanrequired

Whether more items exist past this page in the direction you paged (starting_after or ending_before).

Example response · 200

{
  "object": "list",
  "data": [],
  "has_more": false
}

Response headers

x-request-idstring: The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.
With every response
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 200, 400, 404, 429 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 200, 400, 404, 429 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 200, 400, 404, 429 · At least 0
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`validation_failed`	400	No	Request validation failed.
`unauthorized`	401	No	Authentication is required.
`not_found`	404	No	The requested resource was not found.
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.

Connect a merchant to a provider #

POST /api/v1/merchants/{id}/connections

Connect a merchant to a provider with the merchant's own credentials, in the mode of your key (a test key connects to the provider's test environment). The credentials are encrypted at rest and never returned.

Bearer API key
Idempotency-Key required

Path parameters

idstringrequired: The merchant's id (mer_…).

Header parameters

idempotency-keystringrequired: A key you choose (1-255 printable ASCII characters, e.g. a UUID) that makes a create request safe to retry: the same key with the same body returns the first result instead of creating a second document.
1 to 255 characters
Show patternHide pattern
^[\x21-\x7E]+$

Request body

(the body)oneOfrequired

providerstringrequired

The provider: wrapp.

Option 1 of 2 · Always wrapp

credentialsobjectrequired

Wrapp credentials: api_key plus email or wrapp_user_id.

Option 1 of 2

Show nested fields (3)

api_keystringrequired: The merchant's Wrapp API key (in Wrapp: Στοιχεία API).
Option 1 of 2 · 1 to 200 characters
Show patternHide pattern
^(\S(.*\S)?)?$
emailstring: The email the merchant logs in to Wrapp with, instead of wrapp_user_id. It breaks if the merchant changes the login email; prefer wrapp_user_id.
Option 1 of 2 · Format: email · Up to 254 characters
wrapp_user_idstring: The merchant's Wrapp user id (preferred: it never changes, and Wrapp's onboarding hands it over), instead of the email.
Option 1 of 2 · 1 to 100 characters
Show patternHide pattern
^(\S(.*\S)?)?$

providerstringrequired

The provider: mydata.

Option 2 of 2 · Always mydata

credentialsobjectrequired

Direct myDATA credentials: the merchant's own AADE REST user and subscription key.

Option 2 of 2

Show nested fields (2)

user_idstringrequired: The myDATA REST API user name the merchant registered with AADE (aade-user-id).
Option 2 of 2 · 1 to 100 characters
Show patternHide pattern
^(\S(.*\S)?)?$
subscription_keystringrequired: The myDATA subscription key AADE issued for that user (ocp-apim-subscription-key).
Option 2 of 2 · 1 to 200 characters
Show patternHide pattern
^(\S(.*\S)?)?$

Request

JSON

{
  "provider": "wrapp",
  "credentials": {
    "api_key": "wrapp_api_key_from_the_merchant"
  }
}

curl

curl -X POST 'https://tallio.dev/api/v1/merchants/mer_02y9O8rh7F50tGi0QcWRrx/connections' \
  -H "Authorization: Bearer $TALLIO_API_KEY" \
  -H 'Idempotency-Key: order-1042' \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "wrapp",
  "credentials": {
    "api_key": "wrapp_api_key_from_the_merchant"
  }
}'

TypeScript SDK

import { createTallioClient, unwrap } from "@tallio/sdk";

const tallio = createTallioClient({
  apiKey: process.env.TALLIO_API_KEY!,
  baseUrl: "https://tallio.dev",
});

const result = await unwrap(tallio.http.POST("/api/v1/merchants/{id}/connections", {
  params: {
    path: {
      id: "mer_02y9O8rh7F50tGi0QcWRrx",
    },
  },
  body: {
    provider: "wrapp",
    credentials: {
      api_key: "wrapp_api_key_from_the_merchant",
    },
  },
}));

Responses
Status	Description
`201`	The connection, without its credentials. A replay returns the first answer.
4XX, 5XX	An error: see Errors below.

Response body · 201

dataobjectrequired

A merchant's credentials for one provider in one mode. The credentials themselves are never returned.

Show nested fields (9)

idstringrequired

Id of the connection (con_…).

Show pattern

^con_[0-9A-Za-z]{22}$

objectstringrequired

Always "connection".

Always connection

merchantstringrequired

The merchant this connection belongs to (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

modestringrequired

live for a connection made with a live key, test for a test key.

One of: live, test

statusstringrequired

active (documents can be routed to it), invalid (the provider refused its credentials; fix and verify again), disconnected (no longer used; its credentials are deleted 30 days later).

One of: active, invalid, disconnected

verified_atstring | nullrequired

When the provider last accepted its credentials; null until then.

Format: date-time

last_errorobject | nullrequired

Why the provider last refused it; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: validation_failed, unauthorized, not_found, idempotency_conflict, idempotency_in_progress, already_exists, payload_too_large, unsupported_media_type, rate_limited, not_supported, provider_rejected, provider_unavailable, service_unavailable, internal_error
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload.

createdstringrequired

When the connection was created.

Format: date-time

Example response · 201

{
  "data": {
    "id": "con_02y9O8rh7F50tGi0QcWRrx",
    "object": "connection",
    "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
    "provider": "sandbox",
    "mode": "live",
    "status": "active",
    "verified_at": "2026-10-11T09:30:00.000Z",
    "last_error": {
      "code": "validation_failed",
      "message": "string",
      "provider_code": "string",
      "provider_message": "string",
      "retryable": false
    },
    "created": "2026-10-11T09:30:00.000Z"
  }
}

Response headers

x-request-idstring: The request's correlation id; quote it when reporting a problem. One of: req_ plus a uuid (Tallio made it), client: plus the x-request-id you sent (8-128 of A-Z a-z 0-9 . _ : -), or the hosting platform's id.
With every response
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
ratelimit-limitinteger: Requests allowed in the current window for the bucket this request counted against.
With 201, 400, 404, 409, 413, 415, 429, 503 · At least 1
ratelimit-remaininginteger: Requests left in the current window; 0 means the next one is refused until the window resets.
With 201, 400, 404, 409, 413, 415, 429, 503 · At least 0
ratelimit-resetinteger: Seconds until the current window resets.
With 201, 400, 404, 409, 413, 415, 429, 503 · At least 0
idempotent-replayedstring: true when this answer replays an earlier request with the same Idempotency-Key (nothing new was created); absent on the request that created it.
With 201 · Always true
www-authenticatestring: The bearer challenge: send a vendor secret key as Authorization: Bearer <key>.
With 401 · Always Bearer realm="tallio"
retry-afterinteger: Seconds to wait before retrying a request refused with 429 rate_limited.
With 429 · At least 1

Errors
Code	Status	Retryable	Meaning
`validation_failed`	400	No	Request validation failed.
`unauthorized`	401	No	Authentication is required.
`not_found`	404	No	The requested resource was not found.
`idempotency_conflict`	409	No	This idempotency key was already used with a different request.
`idempotency_in_progress`	409	Yes	A request with this idempotency key is still in progress; retry it after Retry-After to get its answer.
`already_exists`	409	No	An object with this identifier already exists; look it up instead of creating it again.
`payload_too_large`	413	No	The request body is too large.
`unsupported_media_type`	415	No	The request body must be JSON (Content-Type: application/json).
`rate_limited`	429	Yes	A rate limit was reached. Retry later.
`internal_error`	500	No	An unexpected server error occurred.
`service_unavailable`	503	Yes	A service Tallio depends on is temporarily unavailable.