Bitrix24#

Bitrix24 is registered for bounded, read-only task sync from standard-hosted Bitrix24 Cloud. An organization can connect either a dedicated incoming webhook or a Bitrix24 OAuth application with Tasks and Users (basic) access. Both methods feed the same adapter and create a reviewable TeamBoost import session; the same adapter also accepts the evidence-backed converted task CSV described below. The integration does not change Bitrix24 or create TeamBoost tasks.

The endpoints below live under /api/v1/providers/bitrix24/.... They are the generic provider endpoints and require an organization-scoped user token; see Authentication.

Discovery#

GET /api/v1/providers/bitrix24

{
  "status": "success",
  "data": { "provider": "bitrix24", "capabilities": ["CSV_IMPORT", "SYNC", "USER_IMPORT"] }
}

Incoming-Webhook Setup#

In Bitrix24 Cloud, create a dedicated incoming webhook and grant exactly the tasks and user_basic scopes. Store its complete base URL as the write-only credential for one TeamBoost organization:

PUT /api/v1/providers/bitrix24/credentials?organization_id=<id>
POST /api/v1/providers/bitrix24/credentials/verify?organization_id=<id>

{
  "secret": "https://YOUR_PORTAL.bitrix24.com/rest/YOUR_USER_ID/YOUR_WEBHOOK_TOKEN/"
}

The accepted credential shape is exact:

https://<standard-cloud-portal>/rest/<positive-user-id>/<webhook-token>/

Only HTTPS portals under the adapter's current standard Bitrix24 Cloud zone allowlist are accepted. Custom domains, on-premise installations, IP literals, ports, user information, query strings, fragments, method suffixes, encoded path data, and malformed or extra path segments are rejected before any network request.

Verification makes two bounded read-only probes: one REST 3 tasks.task.list request with the production selected-field contract and one first-page REST 2 user.get request. Invalid webhook credentials return invalid_api_key; missing task or user permission returns insufficient_permissions; rejected fixed requests return bad_request; throttling, transient transport failures, and response-contract failures return service_unavailable.

The webhook URL is encrypted at rest, scoped to one TeamBoost organization, replaceable through the same PUT, and never returned by the API. Because the token is part of every provider request path, do not paste the URL into logs, tickets, screenshots, or task descriptions.

OAuth Setup#

Register a Bitrix24 local or mass-market application with the tasks and user_basic scopes. Configure its callback URI to the generic Bitrix24 callback route, then set these service environment variables:

BITRIX24_CLIENT_ID=<application-client-id>
BITRIX24_CLIENT_SECRET=<application-client-secret>
BITRIX24_REDIRECT_URI=https://<integration-host>/api/v1/providers/bitrix24/oauth/callback

Start authorization through the generic endpoint. targetAccountId is required and must be the portal's bare standard-Cloud hostname, without a scheme, port, path, or trailing slash:

GET /api/v1/providers/bitrix24/oauth/authorize?organization_id=<id>&targetAccountId=YOUR_PORTAL.bitrix24.com

The returned authorization URL is hosted on that exact portal. Signed, expiring state binds the callback to the TeamBoost organization and requested portal. The callback's portal, Bitrix member identity, global OAuth server, and token response endpoints are validated before the encrypted credential is stored.

Bitrix access tokens are sent in JSON request bodies, never in task or user API URLs. The generic OAuth service refreshes an expiring access token and persists the new access and refresh token pair. OAuth credentials use the same verification and sync endpoints as incoming webhooks; callers never receive a token through the API.

Importing Tasks#

POST /api/v1/providers/bitrix24/imports/sync?organization_id=<id>

The adapter reads only tasks.task.list, in explicit task-id order, and preserves the returned selected fields in a snake-cased source record. It reads at most 100 tasks per page and refuses more than 500 tasks in one synchronous session. It does not call tasks.task.get per task.

The same conversation reads user.get in 50-user pages and refuses more than 1,000 directory users. Task and user pagination reject duplicate, non-advancing, malformed, inconsistent, or over-limit responses instead of persisting a partial import. The in-process coordinator paces request starts to the same portal at no more than two per second. Transport failures, transient HTTP 500, and QUERY_LIMIT_EXCEEDED use at most three attempts with bounded wait; OPERATION_TIME_LIMIT and OVERLOAD_LIMIT are surfaced without a hot retry. Redirects are never followed.

A valid empty result creates an empty reviewable session.

Importing Converted CSV#

Bitrix24 downloads task exports as HTML content with an .xls filename. The generic upload route does not accept that native file. In Bitrix24:

1. open Tasks → List;
2. open Settings (gear) → Export to Microsoft Excel;
3. choose All task fields, run the export, and download it;
4. open the downloaded file in spreadsheet software and save it as UTF-8 CSV without changing headers, row order, identifiers, or timestamps; and
5. upload the converted file:

POST /api/v1/providers/bitrix24/imports/csv?organization_id=<id>

The current contract is deliberately exact: UTF-8 text, semicolon delimiter, and the observed English All task fields header signature. Native XLS, comma-delimited or non-English variants, blank or duplicate headers, malformed row widths, and other encodings fail loudly instead of being guessed.

The converted export supplies stable task ids but only display names for Creator and Assignee. Those actors become name-only mapping entries for operator review; no provider account id or e-mail is invented. Present-but-unmapped Assignee still blocks confirmation, while an unresolved Creator leaves creator and requester unset with a note.

CSV timestamps use the observed MM/DD/YYYY hh:mm:ss AM/PM format without an offset. They are interpreted as UTC and carry an explicit review note. The Project title can populate projectTitle; Parent task ID is preserved as B24-<id>. The export has no task-priority field, so priority remains UNKNOWN; Rating is preserved only as source context. Participant, Observer, and Tags values remain source-only until populated exports prove their serialization.

User Mapping#

USER_IMPORT rides task sync; there is no standalone user-import route. user.get supplies stable ID values plus visible e-mail and name matching hints. Inactive or no-email directory users remain reviewable.

Creator, Responsible, Changed By, Status Changed By, and Closed By ids present on accepted task-list objects are also collected. If an actor is absent from user.get, the session keeps an id-only placeholder instead of dropping the reference. API actors are never resolved by display name. Converted CSV is the explicit exception described above because the export contains names but no stable actor ids; it uses reviewable name-only mapping entries.

A mapped Responsible user becomes the proposed ownerId; a present but unmapped Responsible user creates a blocking projection error. A mapped Creator becomes both creatorId and requestedById; otherwise both remain unset with a mapping note.

Projection Field Coverage#

Bitrix24 planned/actual effort stays in provider context and does not become TeamBoost duration. Parent context does not create a dependency. Group and flow ids do not become TeamBoost projects or task groups because first ship performs no name lookup.

Not Built Yet#

• Per-task detail enrichment. Participants, observers, dependencies, subtask/related-task flags, project/stage objects, epics, and story points are not imported and are never represented as empty list data.
• Native XLS upload and unproven CSV delimiter, locale, or header variants.
• Projecting CSV Participants, Observers, or Tags before populated export evidence proves how multiple values are serialized.
• Standalone full-directory user import.
• Outgoing task-event handling, verification, replay protection, or deduplication.
• Custom-domain or on-premise Bitrix24 support.
• Creating or changing Bitrix24 tasks.