Custom Integrations

Overview

Custom integrations provide access to client-specific data sources that are not part of the standard provider catalog. Each integration is provisioned individually by MT2Data and requires authentication for access.

Base URL: https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>

Authentication

Two methods are accepted — use whichever fits the context:

Bearer secret (recommended for programmatic access):

Authorization: Bearer <tenant-secret>

The tenant secret is the long-lived key shown on the Integrations page after rotating.

Session cookie (dashboard / browser):

Cookie: colmeia_session=<session-token>

Access is also gated per tenant. If the manager has disabled this integration for a specific tenant, the endpoint returns integration_disabled.

Large numbers and precision

All SQL Server integrations (PIMS, Protheus, Farmtell, and any future bridge built on the same stack) apply the same precision-safe serialisation rule. Read this once and the contract holds for every bridge.

Why

SQL Server columns declared NUMERIC(p, s) / DECIMAL(p, s) with p > 15, and BIGINT values outside the safe-integer range (|v| > 2^53 − 1 = 9007199254740991), do not fit in a JavaScript / JSON number without losing trailing digits. For example, an Oracle-style NUMBER(22) column stored as 30448901015033924 would be silently rounded to 30448901015033920 by a naive JSON serialiser, and the resulting filter WHERE id = 30448901015033920 returns zero rows.

To prevent silent corruption, the bridge returns affected values as JSON strings.

Rules

Precision is column metadata, not value-level. A small value like 101 stored in a NUMERIC(22, 0) column still arrives as the string "101". Treat the column as string-typed across the entire result set.

How to handle the values

{
  "success": true,
  "data": [
    { "ID_UPNIVEL3": "101", "ID_INSUMO": "30448901015033924" }
  ]
}

Do:

• Keep the value as a string in your application memory. Use it directly in equality / filter round-trips.
• Pass the literal back into SQL Server either as a raw integer literal (WHERE id = 30448901015033924) or as a quoted string (WHERE CAST(id AS NVARCHAR(40)) = '30448901015033924'). Both work; SQL Server coerces.
• For sorting or grouping in the application layer, sort as strings only when every value has the same length and zero-padding; otherwise convert to BigInt (JavaScript) / decimal.Decimal (Python) / BigInteger (Java) etc.

Do not:

• Call parseFloat(value), Number(value), or +value on these strings. That re-introduces the precision loss the bridge just prevented.
• Concatenate filter values with + in a way that coerces to number before the SQL round-trip.

Worked example

Two-step round-trip — fetch an ID, then use it as a filter — demonstrates that no precision is lost in the proxy chain:

# 1. Fetch a bigint ID
curl -s "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/<TENANT_ID>/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT TOP 1 ID_INSUMO FROM <table>" }'
# → { "success": true, "data": [ { "ID_INSUMO": "30448901015033924" } ] }

# 2. Filter by the exact value returned (raw literal)
curl -s "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/<TENANT_ID>/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT COUNT(*) AS n FROM <table> WHERE ID_INSUMO = 30448901015033924" }'
# → { "success": true, "data": [ { "n": 1 } ]   }   ← matches, full precision preserved

PIMS ERP

Execute SQL queries against a PIMS ERP SQL Server database.

POST /api/<CLIENT_SLUG>/data/:tenantId/query

Request body:

Simple query

curl -s \
  "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/YOUR_TENANT_ID/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT TOP 10 * FROM <table_name>" }'

Multiline query

Save the SQL to a file (query.sql), then use jq to build the JSON payload:

-- query.sql
SELECT TOP 10
    <columns>
FROM <main_table> M
INNER JOIN <related_table> R ON R.<fk> = M.<pk>
LEFT JOIN <optional_table> O ON O.<fk> = M.<pk>
WHERE M.<date_column> >= '2026-01-01'
ORDER BY M.<date_column> DESC

curl -s \
  "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/YOUR_TENANT_ID/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile q query.sql '{"query": $q}')"

jq handles newlines, quotes, and special characters automatically. Install with brew install jq or apt install jq.

Consult the PIMS schema documentation provisioned to your tenant for table and column names.

Response:

{
  "success": true,
  "data": [
    { "<column_a>": "<value_a>", "<column_b>": "<value_b>" }
  ]
}

Error responses:

TOTVS Protheus ERP

Execute SQL queries against a TOTVS Protheus SQL Server database.

POST /api/<CLIENT_SLUG>/data/:tenantId/query

Request body:

Simple query

curl -s \
  "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/YOUR_TENANT_ID/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT TOP 10 * FROM <table_name>" }'

Multiline query

Save the SQL to a file (query.sql), then use jq to build the JSON payload:

-- query.sql
SELECT TOP 10
    <columns>
FROM <main_table> M
INNER JOIN <related_table> R ON R.<fk> = M.<pk>
                            AND R.D_E_L_E_T_ = ' '
WHERE M.D_E_L_E_T_ = ' '
  AND M.<date_column> >= '20260101'
ORDER BY M.<date_column> DESC

curl -s \
  "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/YOUR_TENANT_ID/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile q query.sql '{"query": $q}')"

jq handles newlines, quotes, and special characters automatically. Install with brew install jq or apt install jq.

Protheus tables follow the pattern <table_code><company_suffix> (e.g., <table_code>01). Always filter D_E_L_E_T_ = ' ' to exclude logically deleted records. Consult the Protheus schema documentation provisioned to your tenant for table and column names.

Response:

{
  "success": true,
  "data": [
    { "<column_a>": "<value_a>", "<column_b>": "<value_b>" }
  ]
}

Error responses:

Farmtell

Execute SQL queries against a Farmtell SQL Server database.

POST /api/<CLIENT_SLUG>/data/:tenantId/query

Request body:

Simple query

curl -s \
  "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/YOUR_TENANT_ID/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT TOP 10 * FROM <table_name>" }'

Multiline query

Save the SQL to a file (query.sql), then use jq to build the JSON payload:

-- query.sql
SELECT TOP 10
    <columns>
FROM <main_table> M
INNER JOIN <related_table> R ON R.<fk> = M.<pk>
LEFT JOIN <optional_table> O ON O.<fk> = M.<pk>
WHERE M.<date_column> >= '2026-01-01'
ORDER BY M.<date_column> DESC

curl -s \
  "https://colmeia.mt2data.cloud/api/<CLIENT_SLUG>/data/YOUR_TENANT_ID/query" \
  -H "Authorization: Bearer <tenant-secret>" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile q query.sql '{"query": $q}')"

jq handles newlines, quotes, and special characters automatically. Install with brew install jq or apt install jq.

Table and column names may vary across Farmtell deployments. Consult the schema of the specific database provisioned to your tenant.

Response:

{
  "success": true,
  "data": [
    { "<column_a>": "<value_a>", "<column_b>": "<value_b>" }
  ]
}

Error responses: