Download the PHP package iperson1337/nct-client-bundle without Composer

NCT Client Bundle

English · Қазақша

Symfony client for the National Catalog of Goods of Kazakhstan (НКТ): the complete nationalcatalog.kz portal API (product requests and their lifecycle, files, duplicates, cards, attributes, dictionaries) and the public nct.gov.kz API (search, timestamp export). Ships with retries, Redis-backed rate limiting, typed exceptions and value objects for the protocol's data.

The bundle knows the portal protocol and nothing about your domain model: responses come back as decoded arrays (or small value objects), and what to do with them is up to the application.

Coverage: all 23 operations of the official portal specification (https://nationalcatalog.kz/gwp/docs) and all 5 requests of the public nct.gov.kz collection.

Features

• Portal API (nationalcatalog.kz, X-API-KEY): create, update, delete, cancel, moderate and publish product requests; create an edit request for a published card by NTIN; list requests with a status filter; read status and details; resolve duplicates; upload photos and PDF documents; look cards up by NTIN/GTIN (single and list); base and extended-card attribute definitions; dictionaries (list, roots, children, paged items).
• Public API (nct.gov.kz): search cards by one code, by a batch of up to 100 codes, or by name; fetch a card by id; JWT-protected export of changed products by timestamp with a count.
• One façade — NctClient::fetchProductByGtin() picks the configured lookup source.
• Rate limiting — a proactive sliding-window limiter per host (Redis, Lua, shared between processes) plus reactive retries after 429 / 422 TOO_MANY_REQUESTS.
• Per-call overrides — short timeout and single attempt for synchronous UI checks.
• Typed exceptions — all extend \RuntimeException and implement NctExceptionInterface.
• Value objects — AttributeDefinition, DictionaryItem, ProductRequestPayload (with order-insensitive comparison), RequestStatus / ExtendedRequestStatus / ImageType / DuplicateDecision enums, RequestDetailsParser, NationalCatalogIdentifier.

Requirements

• PHP 8.3+
• Symfony 7.4 (config, dependency-injection, http-kernel, cache)
• Guzzle 7
• Optional: the redis extension or predis/predis for the Redis rate limiter

Installation

Without Symfony Flex, register the bundle:

Configuration

config/packages/iperson1337_nct_client.yaml:

All keys are optional; the values above are the defaults (except api_key, which is empty, and redis_dsn, which is null).

Registered services (autowire by class): NctClient, NctPortalClient, NctGovClient, NctHttpClient, RequestDetailsParser, NationalCatalogIdentifier.

Usage

Product by GTIN

A short timeout and a single attempt for a synchronous check in a UI action (don't wait the full timeout and don't sleep on 429):

GTIN is not unique on the portal — a GTIN may belong to several cards. To see all of them:

Product request lifecycle

The portal rejects an NTIN attribute in a create request. To edit a published card either pass ntin in the payload of submitProductRequest() or start from the card itself:

name_ru, name_kk, ntin and tnved cannot be changed on an edit request; extended cards (with a KZTIN) are not editable through the API.

ProductRequestPayload compares bodies regardless of key and attribute order — use it to decide whether a stored request actually changed before sending a PUT that would re-trigger moderation:

Request status and details

Base statuses (RequestStatus): new, onModeration, accepted, underRevision, cancelled, readyToPublish, existingProductSelected, completed, rejected. Extended-card statuses in gzStatus (ExtendedRequestStatus): acceptedGz, underRevisionGz, rejectedGz, publishingGz.

Duplicates

When moderation sends a request back for DUPLICATE_REVIEW:

Photos and documents

Files are uploaded to the request first (statuses new, underRevision, cancelled; 5 MB max), then referenced by filename in the payload:

An extended card (isGov: true) needs front and back photos, the brand attribute and at least five additional characteristics before it can go to moderation.

Attribute definitions and dictionaries

nct.gov.kz: search, card, export

Timestamp export needs an nct.gov.kz account (limit: 120 requests per minute):

After several failed logins the portal locks the account for 10 minutes (403, locked_seconds).

NTIN / XTIN format

Identifiers are strings: leading zeros matter.

Exceptions

Every exception extends \RuntimeException and implements NctExceptionInterface, so an existing catch (\RuntimeException) keeps working and catch (NctExceptionInterface) catches any NCT failure.

A 404 with a {"Message": "product … not found"} body counts as "not found" only for requests that opted in (NctRequest::$notFoundAsEmpty): a 404 caused by a changed API path must not look like a missing product.

Rate limiting and retries

Two layers protect every request:

1. Proactive limit — RateLimiterInterface::waitIfNeeded() before the request, one limiter per host (NctTarget::Portal / NctTarget::Gov). The Redis implementation keeps a sorted set of timestamps; an atomic Lua script counts requests in the window and, when full, returns the time until the oldest one leaves it. If Redis fails, the limit is skipped with a warning — a limiter must never stop the host process.
2. Retry after 429 — up to retry_count retries with the host's retry_after_seconds pause; maxAttempts: 1 on a call turns retries off and surfaces NctRateLimitExceededException at once.

One Guzzle client serves both hosts. Portal requests carry Content-Type: application/json, Accept and X-API-KEY (multipart uploads let Guzzle set the boundary); nct.gov.kz requests carry Accept only, plus Authorization: JWT … for the export — the API key never leaves for the public host.

Endpoints

Testing

NctHttpClientTest is a snapshot test of the transport (31 scenarios: retries, 422, every kind of 404, timeouts, error bodies, headers per host); the baseline lives in tests/Http/__snapshots__/. To re-record it deliberately: UPDATE_SNAPSHOTS=1 vendor/bin/phpunit. NctPortalClientTest and NctGovClientTest pin method, path, query, body and headers of every operation against a Guzzle MockHandler.

NctClient, NctPortalClient and NctGovClient are not final, so they can be stubbed in the consumer's own tests.

Scope

The bundle implements the portal protocol. It deliberately does not store requests or their statuses, decide when an identifier may be written to a product, build request payloads from a domain model, or map attribute and dictionary rows into the consumer's own reference data. The value objects give those rows a predictable shape; the mapping stays in the application.

License

MIT — see LICENSE.