specification: API Commons Conventions
specificationVersion: '0.1'
provider: OnlineNIC
providerId: onlinenic
generated: '2026-09-17'
method: searched
source: https://www.onlinenic.com/cp_english/template_api/download/Onlinenic_API_v4.0.9.2_Reseller_Guide.pdf
docs: https://www.onlinenic.com/cp_english/template_api/api_help.php
description: >-
  Cross-cutting runtime semantics for the OnlineNIC Reseller API v4, read from the provider's own
  API 4.0.9 Reseller Guide and confirmed against live unauthenticated probes of the API host. There
  is no OpenAPI to derive from; OnlineNIC publishes its reference only as a PDF, so every statement
  here cites a section of that document or a probed response.
interface_style: rpc-over-http
resource_model:
  shape: command
  description: >-
    Not REST despite the marketing label. Two PHP endpoints carry the whole surface and the verb
    travels in a `command` query parameter, e.g.
    https://api.onlinenic.com/api4/domain/index.php?command=registerDomain. There are no resource
    paths, no path parameters and no HTTP verb semantics.
  endpoints:
    - surface: SSL
      url: https://api.onlinenic.com/api4/ssl/index.php
      commands: 17
    - surface: Domain
      url: https://api.onlinenic.com/api4/domain/index.php
      commands: 26
  command_count: 43
request:
  transport: https
  http_method: POST
  http_method_note: >-
    "the request type must be POST" (guide 2.1). A GET returns {"code":1001,"msg":"Invalid request."}
    — probed live 2026-09-17.
  encoding: form-encoded body
  charset: UTF-8
  content_negotiation: none
response:
  media_type: application/json
  charset: UTF-8
  envelope:
    code: integer status code from the error registry; 1000 = success
    msg: human-readable message
    data: command-specific payload, present on success only
  http_status: >-
    Always 200. Every documented failure — including authentication failure — is returned as HTTP 200
    with a non-1000 `code` in the body. A client that branches on HTTP status will treat every error
    as a success.
  cross_link: errors/onlinenic-error-codes.yml
authentication:
  summary: apikey + MD5 request token + optional IP allowlist, all in the POST body
  cross_link: authentication/onlinenic-authentication.yml
  replay_protection:
    mechanism: timestamp inside the signed token
    window: 10 minutes
    source: guide 2.2 — "The duration of validity of a request is 10 mins"
pagination:
  style: page-number
  request_params:
    - name: page
      required: false
      default: 1
      description: Page number; each page contains 100 orders by default
  response_fields:
    - name: page
      description: Page number echoed back
    - name: pagesum
      description: Total number of pages
  page_size: 100
  page_size_configurable: false
  applies_to:
    - getSSLOrderList
    - getSSLProductDetails
  note: >-
    Introduced in API 4.08 (guide 6.7 Change Log). Only the list commands paginate; there is no
    cursor, no total-record count and no Link header.
field_expansion:
  supported: false
sparse_fieldsets:
  supported: false
metadata:
  supported: false
  note: No customer-defined metadata field on any object.
request_id:
  supported: false
  note: >-
    No request-id or correlation header is documented for API v4. The deprecated v3.4 socket API did
    carry a client transaction id (`cltrid`, built as client<user><datetime><rand> in the first-party
    PHP SDK); v4 dropped it, so there is no way for a caller to correlate a retried request with the
    original.
versioning:
  style: path-segment
  current: api4
  current_build: 4.0.9.2
  previous:
    - version: '3.4'
      status: deprecated
      note: >-
        Labelled "Deprecated — Domain Functions Only, XML response" on the provider's own API page.
        Transport is a raw TCP socket on port 30009, not HTTP.
  breaking_change_policy: none published
  sunset_header: false
  deprecation_header: false
  cross_link: lifecycle/onlinenic-lifecycle.yml
rate_limit_signaling:
  headers: none
  documented_limits: false
  note: >-
    No rate limit is published, no RateLimit-*/X-RateLimit-* header is documented, and no 429 appears
    in the error registry. Error 1074 ("Server too busy, please try again") is the only back-pressure
    signal and carries no retry hint.
  cross_link: rate-limits/onlinenic-rate-limits.yml
idempotency:
  supported: false
  coverage: none
  mechanism: none
  key_header: none
  note: >-
    There is no client-supplied idempotency key anywhere in the 43 documented commands. The nearest
    thing is server-side duplicate rejection on SSL ordering — 1014 "Order is already exists" and
    1032 "You have already submitted a similar order" — but that is an ERROR, not replay safety: a
    client that retries after a timeout (error 1024 "Operation timed out") gets a rejection rather
    than the original result, and cannot tell whether the first call took effect. Domain register,
    renew and transfer commands have no duplicate protection documented at all. Recorded as `none`
    deliberately; no Idempotency pointer is wired into apis.yml.
dry_run_mode:
  supported: false
  note: >-
    No preview, validate-only or dry-run flag on any mutating command. The closest surface is the OTE
    test environment, which is a separate host rather than a rehearsal mode on production.
  cross_link: sandbox/onlinenic-sandbox.yml
reversibility:
  applicable: true
  grade: verified
  summary: >-
    SSL ordering has a documented reversal path with a stated window; domain registration does not.
  surfaces:
    - write_operation: orderSSL
      reversal_operation: cancelSSL
      reversal_kind: cancel-and-refund
      window: within 30 days of issuance
      window_stated: true
      window_source: >-
        API 4.0.9 Reseller Guide, "Cancel SSL order": "Use that option to request
        cancellation/refund of any order within 30 days of issuance."
      docs: https://www.onlinenic.com/cp_english/template_api/download/Onlinenic_API_v4.0.9.2_Reseller_Guide.pdf
      constraints:
        - Only from an order status that permits it (error 1029 otherwise).
        - Already-refunded orders reject with 1028.
        - Sectigo orders require a separate email to OnlineNIC before the refund lands (error 1031).
      grade: verified
    - write_operation: orderSSL
      reversal_operation: revokeSSL
      reversal_kind: revoke
      window: null
      window_stated: false
      note: >-
        Distinct from cancel and explicitly so in the guide: revoke invalidates an issued certificate
        whose private key is compromised. No refund, no stated window.
      grade: documented
    - write_operation: transferDomain
      reversal_operation: cancelDomainTransfer
      reversal_kind: cancel
      window: null
      window_stated: false
      note: >-
        Cancels a transfer-in. The guide states no window; registry transfer rules apply but OnlineNIC
        does not restate them.
      grade: documented
    - write_operation: applyIDShield
      reversal_operation: suspendIDShield
      reversal_kind: suspend
      window: null
      window_stated: false
      paired_with: resumeIDShield
      grade: documented
    - write_operation: createHost
      reversal_operation: deleteHost
      reversal_kind: delete
      window: null
      window_stated: false
      grade: documented
    - write_operation: registerDomain
      reversal_operation: null
      reversal_kind: none
      window: null
      window_stated: false
      note: >-
        NO reversal path is exposed. There is no deleteDomain command in API v4 (the deprecated v3.4
        socket SDK shipped one), and no grace-period refund is documented for a registration. An agent
        that registers a domain through this API cannot undo it through this API. Error 1048 "Failed
        to delete domain" exists in the registry with no command that raises it.
      grade: none
    - write_operation: renewDomain
      reversal_operation: null
      reversal_kind: none
      window: null
      window_stated: false
      grade: none
  note: >-
    Grade is `verified` because at least one write surface pairs a reversal operation with a window the
    provider states in its own reference. The registration surface is the gap worth flagging to a buyer:
    the most consequential and least reversible write in the catalogue.
error_semantics:
  style: integer-code-in-body
  catalog: errors/onlinenic-error-codes.yml
  code_count: 79
async_operations:
  present: true
  note: >-
    Registrant contact change is asynchronous — code 2000 tells the caller an approval email was sent
    to the current registrant, 2001 that one is already pending, 2002 that the request is queued. There
    is no webhook or callback: the caller must poll (infoContact / infoDomain / queryTransferStatus).
  polling_commands:
    - queryTransferStatus
    - checkWhoisVF
    - getSSLOrderInfo
webhooks:
  supported: false
  note: >-
    No webhook, callback URL, event stream or notification surface is documented anywhere in the 4.0.9
    guide. Every state change must be discovered by polling. No AsyncAPI is emitted, and no Webhooks
    pointer is wired — a measured absence, not an omission.
machine_readable_contract:
  openapi: false
  asyncapi: false
  graphql: false
  wsdl: false
  postman: false
  json_schema: false
  note: >-
    The contract ships as a 60-page PDF plus a downloadable PHP SDK. This is the single largest gap in
    OnlineNIC's API posture: the surface is real, live, and fully specified in prose, and no machine can
    read it. Probed 2026-09-17 — /openapi.json, /swagger.json and /api-docs all 404 on both
    www.onlinenic.com and api.onlinenic.com, and ?wsdl returns the ordinary JSON error envelope.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com