Sections
On this page

How do I connect the requests and contracts API?

The read-only API provides one clinic’s current requests, contracts, payments and available receipts to 1C or another accounting system. It does not accept payments, close contracts or issue receipts.

Access and the shared key

First, a system administrator edits the clinic in /admin, opens the System tab, enables API available to the clinic and saves the changes. This permission is off by default. Without it, the API section is hidden in the clinic cabinet, and key management and API requests are blocked.

The clinic’s main administrator can then open Settings → General settings → External systems API, enable access and save the API settings. The same section provides Show, Copy and Reissue key actions. Ordinary administrators cannot manage the key. The clinic cannot grant itself system permission.

Revoking permission in /admin immediately hides the section and blocks the existing key. The key and the clinic’s enabled setting are preserved; granting permission again restores the previous state. Both system permission and clinic activation are required for API access.

API access settings and shared key controls

One key grants access to both resources. Authentication uses Authorization: Bearer <API_KEY>. Disabling access blocks requests immediately and preserves the key. Reissuing invalidates the previous key immediately.

The key determines the clinic. clinic_id is not a supported parameter. A record belonging to another clinic returns 404, just like a missing record.

Endpoints and formats

Base URL: https://medsenger.ru/api/integrations/v1.

Endpoint Purpose
GET /consulting-orders List requests or synchronize updates
GET /consulting-orders/{id} Get one request
GET /contracts List contracts or synchronize updates
GET /contracts/{id} Get one contract

Download the OpenAPI 3.0 specification for exact schemas, fields and statuses. Lists return data: [] and meta; detail responses return data: {}. All dates, including nested payment and receipt dates, are Unix timestamps in seconds (int64), amounts are integer kopecks in amount_minor, and currency is RUB. Unknown values are null.

curl --get 'https://medsenger.ru/api/integrations/v1/consulting-orders' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'limit=100'

List parameters

Parameters are passed in the query string. All parameters are optional. Requests are independent; no export session or continuation token is used.

Parameter Type Description
page integer Page number starting at 1. Default: 1.
limit integer Page size from 1 to 500. Default: 100.
updated_since integer, int64 Records changed at or after the specified Unix timestamp, inclusive. Without it, no modification-time restriction applies.
created_from integer, int64 Inclusive lower creation-time bound, in Unix seconds.
created_to integer, int64 Inclusive upper creation-time bound, in Unix seconds. The lower bound must not exceed the upper bound.
status string Current request or contract status; allowed values are listed below.
is_paid 0 or 1 Requests only: an existing unpaid or paid payment.

Time parameters accept integer seconds from 0 to 253402300799 (end of year 9999). Milliseconds and date strings are rejected. Bounds refer to exact seconds, without rounding to whole calendar days. All supplied filter conditions apply together.

updated_since refers to publication of exported changes, including payment, receipt and service-completion changes. Requests without a payment are excluded from both is_paid=0 and is_paid=1.

curl --get 'https://medsenger.ru/api/integrations/v1/contracts' \
  --header "Authorization: Bearer $MEDSENGER_API_KEY" \
  --data-urlencode 'updated_since=1791972000' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

List response

The list is returned in data; page metadata is returned in meta.

Field Type Description
meta.page integer Requested page number.
meta.limit integer Page size.
meta.has_more boolean Whether further records match the filters.
meta.generated_at integer, int64 Server time at the start of the current request, in Unix seconds.
{"data":[],"meta":{"has_more":false,"page":1,"limit":100,"generated_at":1791972060}}

Lists are ordered by ascending ID. The API returns current state and the latest change number, revision. Intermediate historical states are not returned. Data may change between page requests; responses do not form a single point-in-time snapshot.

Deleted records contain id, clinic_id, deleted: true, revision and updated_at. These markers also appear in lists without filters.

Request data

Requests include identity/dates, status (created, payment_required, accepted, declined), service, duration, selected doctor, customer name/email/phone, payment and linked contract progress. payment: null means no linked invoice, not a free service. A paid request may still have contract: null while fulfillment is pending.

service preserves the original offer rather than current catalog values. Old records without a captured offer have captured=false and unknown name/amount as null. The authoritative invoice amount is payment.amount_minor.

Contract data

All clinic contracts are available, including manually created contracts without requests or payments. Fields include number, patient/contact details, service, main/responsible doctor, contract type, start/end/activation dates, delayed and unlimited modes, conclusion progress, confirmed service completion and payments.

Field Meaning
status waiting_activation, active, expired, closed
awaiting_conclusion Whether the doctor’s conclusion is still pending
concluded_at Conclusion completion time
service_completed_at Explicitly confirmed service completion time
service_completed_by Confirming actor type and ID
consulting_order_id Linked request or null

Expiry or closure does not itself confirm service delivery. Completion is available without a cash register and is not inferred from a final receipt. Reactivation does not automatically undo a previously confirmed service. Changes to dates, doctors, activation, conclusions and time-based expiry appear in synchronization.

Diagnoses, chats, medical documents, conclusion text, gateway credentials and token-bearing login links are excluded.

Payments and optional receipts

A contract may have multiple payments. The same payment has the same ID in both resources. is_paid records confirmed payment. status=requires_review and issue may indicate a refund/reversal or another reconciliation issue even while is_paid=true.

payment.fiscalization describes Medsenger’s cloud receipt processing for the particular purchase. With enabled_for_order=false, no receipts are issued through this mechanism; this is not an error and does not imply that an external system or gateway issued no receipt. Enabled modes are on_contract and advance, with receipt kinds full, advance, settlement.

Receipt statuses are pending, submitting, accepted, processed, confirmed, failed. processed means formed but awaiting OFD transmission; confirmed means transmission is confirmed. Available fields include provider receipt ID, URL and fiscal identifiers. Historical purchase settings survive subsequent clinic setting changes.

Payment and cash register environments are separate: test, production, or null if unknown. null means the environment is unknown.

Errors and limits

Errors use {"error":{"code":"unauthorized","message":"…","details":{}}}. code is a stable error code, message is localized text, and details contains additional information.

HTTP Code Meaning
401 unauthorized No valid key.
403 api_disabled API disabled by the system or clinic.
404 not_found Missing or inaccessible record.
405 method_not_allowed Unsupported HTTP method.
422 invalid_parameters Invalid request parameters.
429 rate_limited Request limit exceeded.
503 export_preparing Data preparation is incomplete.
500 internal_error Internal server error.

The default limit is 120 requests/minute per clinic, shared by both resources. Responses 429 and 503 include Retry-After, a delay in seconds. Preparation of a large list may produce 503 export_preparing.