domainnameapi 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1637 @@
1
+ Metadata-Version: 2.5
2
+ Name: domainnameapi
3
+ Version: 1.0.0
4
+ Summary: Python client for the DomainNameAPI (domainnameapi.com) REST API: register, transfer, renew and manage domains, contacts, DNS zones and forwarding.
5
+ Project-URL: Homepage, https://github.com/domainreseller/python-dna
6
+ Project-URL: Source, https://github.com/domainreseller/python-dna
7
+ Project-URL: Issues, https://github.com/domainreseller/python-dna/issues
8
+ Project-URL: Changelog, https://github.com/domainreseller/python-dna/blob/main/CHANGELOG.md
9
+ Project-URL: Releases, https://github.com/domainreseller/python-dna/releases
10
+ Author: Atak Domain
11
+ License-Expression: Apache-2.0
12
+ License-File: LICENSE
13
+ Keywords: dna,dns,domain,domain-name-api,domain-registration,domain-transfer,domainnameapi,domains,registrar,reseller,rest
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.8
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Topic :: Internet :: Name Service (DNS)
26
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
27
+ Classifier: Typing :: Typed
28
+ Requires-Python: >=3.8
29
+ Description-Content-Type: text/markdown
30
+
31
+ <div align="center">
32
+ <a href="README-TR.md" > TR <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/TR.png" alt="TR" height="20" /></a>
33
+ <a href="README.md"> | EN <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/US.png" alt="EN" height="20" /></a>
34
+ <a href="README-DE.md"> | DE <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/DE.png" alt="DE" height="20" /></a>
35
+ <a href="README-SA.md"> | SA <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/SA.png" alt="AR" height="20" /></a>
36
+ <a href="README-NL.md"> | NL <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/NL.png" alt="NL" height="20" /></a>
37
+ <a href="README-AZ.md"> | AZ <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/AZ.png" alt="AZ" height="20" /></a>
38
+ <a href="README-CN.md"> | CN <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/CN.png" alt="CN" height="20" /></a>
39
+ <a href="README-FR.md"> | FR <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/FR.png" alt="FR" height="20" /></a>
40
+ <a href="README-IT.md"> | IT <img style="padding-top: 8px" src="https://raw.githubusercontent.com/yammadev/flag-icons/master/png/IT.png" alt="IT" height="20" /></a>
41
+ </div>
42
+
43
+
44
+ # python-dna: DomainNameAPI client for Python
45
+
46
+ Python client for the [DomainNameAPI](https://www.domainnameapi.com) reseller REST API: search, register,
47
+ transfer and renew domains, manage contacts, nameservers, child nameservers, DNS zones and URL forwarding.
48
+ It is a faithful port of [php-dna](https://github.com/domainreseller/php-dna): same methods, same requests,
49
+ same return values, verified against php-dna's conformance fixtures.
50
+
51
+ ## 📦 Download — always use Releases!
52
+
53
+ ⬇️ **Get the latest tested version here: https://github.com/domainreseller/python-dna/releases/latest**
54
+
55
+ > ⚠️ Do **not** use the green **Code → Download ZIP** button — that downloads the raw development branch. Release packages are versioned, tested and production-ready.
56
+
57
+ ## Installation and Integration Guide
58
+
59
+ ### Minimum Requirements
60
+
61
+ - Python 3.8 or higher (3.12 recommended)
62
+ - No third-party packages: the library only uses the Python standard library (`urllib`, `json`, `ssl`).
63
+
64
+ ### A) Install with pip
65
+
66
+ ```bash
67
+ pip install domainnameapi
68
+ ```
69
+
70
+ ### B) Install a release package
71
+
72
+ Download the wheel (`domainnameapi-1.0.0-py3-none-any.whl`) or the source archive from the
73
+ [latest release](https://github.com/domainreseller/python-dna/releases/latest) and install it:
74
+
75
+ ```bash
76
+ pip install domainnameapi-1.0.0-py3-none-any.whl
77
+ ```
78
+
79
+ ### C) Use the source directly
80
+
81
+ Copy the `src/domainnameapi` folder next to your code (or add `src` to `PYTHONPATH`) and import it.
82
+ The [examples](examples) folder has one runnable script per method.
83
+
84
+ ## 🔑 API Credentials — Reseller ID & API Key
85
+
86
+ The library talks to the DomainNameAPI REST API and needs exactly two credentials, passed to the constructor:
87
+
88
+ | Parameter | Value |
89
+ |---|---|
90
+ | First | Reseller ID — UUID like `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
91
+ | Second | API Key |
92
+
93
+ > 💡 Find your **Reseller ID** and **API Key** in your DomainNameAPI panel under **API Settings**.
94
+ > ⚠️ These are **API credentials** — your panel login details will **not** work here.
95
+
96
+ ```python
97
+ from domainnameapi import DomainNameAPI
98
+
99
+ reseller_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
100
+ api_key = "your-api-key"
101
+
102
+ # Live environment
103
+ dna = DomainNameAPI(reseller_id, api_key)
104
+
105
+ # Test (OTE) environment
106
+ dna = DomainNameAPI(reseller_id, api_key, True)
107
+ ```
108
+
109
+ Leading and trailing whitespace around the credentials is removed automatically.
110
+
111
+ ## Quick Start
112
+
113
+ ```python
114
+ from domainnameapi import DomainNameAPI
115
+
116
+ dna = DomainNameAPI("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "your-api-key")
117
+
118
+ details = dna.get_details("example.com")
119
+ if details["result"] == "OK":
120
+ print(details["data"]["Dates"]["Expiration"])
121
+ else:
122
+ print(details["error"]["Code"], details["error"]["Message"])
123
+ ```
124
+
125
+ Method names are snake_case (`get_details`, `register_with_contact_info`). The php-dna names also work as
126
+ aliases, so code ported from PHP can keep `dna.GetDetails(...)` or `dna.getDetails(...)`.
127
+
128
+ ## Return Values and Error Handling
129
+
130
+ Methods return plain `dict`/`list` values with exactly the keys php-dna returns. They do **not** raise
131
+ exceptions for gateway or network problems; check `result` instead:
132
+
133
+ ```python
134
+ # Success
135
+ {"result": "OK", "data": {...}}
136
+
137
+ # Failure
138
+ {"result": "ERROR", "error": {"Code": "API_404", "Message": "...", "Details": "...",
139
+ "GatewayCode": "Dna.DomainService:Domain:10007"}}
140
+ ```
141
+
142
+ - `Code` is `API_<HTTP status>` for gateway errors (`API_400`, `API_404`, `API_429`, `API_500`, ...).
143
+ A redirect answer (wrong credentials) gives `API_302` with the message `Invalid API credentials`.
144
+ - `GatewayCode` is added to `API_<status>` errors when the gateway sent its own error code
145
+ (for example `Dna.DomainService:Domain:10007`), so you can tell "domain not found" from "TLD not supported".
146
+ - `Message` is the gateway's message. Empty error bodies become `HTTP <status> - <reason>`
147
+ (for example `HTTP 429 - Too Many Requests`).
148
+ - `Details` holds the gateway's details (or the raw response body when there are none); validation errors
149
+ are flattened into a readable list of fields, for example
150
+ `Admin PostalCode, Tech PostalCode - 'PostalCode' is required`.
151
+ - Network failures are errors too, never an empty success: a timeout returns `CURL_28` with
152
+ `Could not reach the DomainNameAPI service: the connection timed out. (...)`; DNS, connection and TLS
153
+ failures return `CURL_6`, `CURL_7`, `CURL_35`/`CURL_60` with `Curl error during request: ...`
154
+ (curl error numbers, the same codes php-dna reports). `API_` codes are only used for HTTP statuses.
155
+ - A refusal is an error even when the gateway answers HTTP 200: if registration, transfer or renewal comes
156
+ back with `success: false`, the method returns `REGISTER_DOMAIN`, `TRANSFER_DOMAIN` or `RENEW_DOMAIN`
157
+ with the gateway's message.
158
+ - Flags keep php-dna's types: `LockStatus` is the string `"true"`/`"false"`, prices are formatted strings
159
+ (`"11.9900"`).
160
+
161
+ A few methods use their own envelope, exactly as in php-dna:
162
+
163
+ | Method | On success | On failure |
164
+ |---|---|---|
165
+ | `check_availability` | a plain `list` of results | the `ERROR` envelope |
166
+ | `get_current_balance` | `OperationResult: "SUCCESS"` | `OperationResult: "FAILED"` with `ErrorCode` (`API_<status>`, `CURL_<errno>`, or `BALANCE` for a currency the account does not report) |
167
+ | `check_transfer` | `result: "OK"` only when the domain is transferable | `result: "ERROR"` with `data` and `error` |
168
+ | `is_tr_tld`, `validate_contact` | plain values (no network) | — |
169
+
170
+ Only programming errors (for example passing a string where `set_resource_record_set` expects a list)
171
+ raise a Python exception.
172
+
173
+ The timeouts are 30 seconds per call and 10 seconds to connect. Redirects are not followed.
174
+
175
+ ## Test Mode (OTE)
176
+
177
+ Pass `True` as the third argument to use the test environment `https://ote.domainresellerapi.com/api/v1`.
178
+ String values from configuration files are understood: `"true"`, `"1"`, `"on"`, `"yes"` enable test mode,
179
+ anything else (`"false"`, `"0"`, `"off"`, `""`) keeps the live environment.
180
+
181
+ ```python
182
+ dna = DomainNameAPI(reseller_id, api_key, True)
183
+ dna = DomainNameAPI(reseller_id, api_key, os.environ.get("DNA_TEST_MODE", "false"))
184
+ ```
185
+
186
+ ## Error Reporting (Telemetry)
187
+
188
+ When an API call fails, the library can send an error report to DomainNameAPI's own error tracker
189
+ (Sentry). A small random share of successful calls (4%, plus every call slower than 1 second) is sent as a
190
+ performance record. This helps DomainNameAPI find and fix problems. Error reporting is **on by default**.
191
+
192
+ > ℹ️ In version 1.0.0 the built-in Sentry address is still empty, because the Sentry project for
193
+ > python-dna has not been created yet: **nothing is sent** until a library update fills it in, or until you
194
+ > pass your own address with `DomainNameAPI(..., sentry_dsn="https://key@sentry.example.com/1")`.
195
+
196
+ Reports are sent from a background thread: they never slow down or break your call.
197
+ Expected, high-volume errors (domain not found, insufficient balance, invalid credentials, no forwarding
198
+ configured, ...) are never reported.
199
+
200
+ **What is sent:**
201
+
202
+ - error code and message
203
+ - called endpoint path and HTTP method
204
+ - call duration
205
+ - library name (`DomainNameAPI-Python`), library version and Python version
206
+ - reseller ID and domain name
207
+ - the server's public IP address (looked up via `api.ipify.org`) and the operating-system user name
208
+ - the API request and response, including the domain's contact details; only credentials are masked — EPP/auth codes, API keys, passwords and tokens are replaced with `***`
209
+
210
+ **What is never sent:** EPP/auth codes, API keys, passwords or tokens in readable form; function call arguments in stack traces.
211
+
212
+ **Why and how long:** the data is used only for usage measurement and early diagnosis of problems, and is kept for 30 days on DomainNameAPI's own Sentry server, after which it is deleted automatically.
213
+
214
+ **How to turn it off:** call `set_error_reporting_enabled(False)` after constructing the client:
215
+
216
+ ```python
217
+ dna = DomainNameAPI(reseller_id, api_key)
218
+ dna.set_error_reporting_enabled(False)
219
+ ```
220
+
221
+ **Minimal mode:** `set_telemetry_minimal(True)` sends only the error code and message, endpoint, timing,
222
+ versions and reseller ID — no request/response data, domain, IP address or user name.
223
+
224
+ ```python
225
+ dna.set_telemetry_minimal(True)
226
+ ```
227
+
228
+ > 🔒 **Security:** TLS certificate verification is on. On a host with an outdated CA bundle it can be switched off with `dna.set_ssl_verification(False)` — this is not recommended; updating the CA bundle is the better fix.
229
+
230
+ ## Usage
231
+
232
+ All examples below assume:
233
+
234
+ ```python
235
+ from domainnameapi import DomainNameAPI
236
+
237
+ dna = DomainNameAPI("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "your-api-key")
238
+ ```
239
+
240
+ The sample outputs are real return values of the library.
241
+
242
+ ### Account
243
+
244
+ #### Get Reseller Details
245
+
246
+ Reseller account details: ID, name and balances (USD and TL).
247
+
248
+ ```python
249
+ result = dna.get_reseller_details()
250
+ ```
251
+
252
+ <details>
253
+ <summary>Sample output</summary>
254
+
255
+ ```python
256
+ {'result': 'OK',
257
+ 'id': '00000000-0000-4000-8000-000000000001',
258
+ 'active': True,
259
+ 'name': 'example-reseller',
260
+ 'balance': '601.64',
261
+ 'currency': 'USD',
262
+ 'symbol': '$',
263
+ 'balances': [{'balance': '601.64', 'currency': 'USD', 'symbol': '$'},
264
+ {'balance': '1250.50', 'currency': 'TL', 'symbol': 'TL'}]}
265
+ ```
266
+
267
+ </details>
268
+
269
+
270
+ <hr style="border: 4px solid #000; border-style: dashed;">
271
+
272
+ #### Get Current Balance
273
+
274
+ Current balance in one currency: USD (default) or TRY. A currency the account does not report (EUR, GBP, ...) returns OperationResult FAILED with ErrorCode BALANCE.
275
+
276
+ ```python
277
+ result = dna.get_current_balance("USD")
278
+ ```
279
+
280
+ <details>
281
+ <summary>Sample output</summary>
282
+
283
+ ```python
284
+ {'ErrorCode': 0,
285
+ 'OperationMessage': 'Command completed succesfully.',
286
+ 'OperationResult': 'SUCCESS',
287
+ 'Balance': '601.64',
288
+ 'CurrencyId': 2,
289
+ 'CurrencyInfo': None,
290
+ 'CurrencyName': 'USD',
291
+ 'CurrencySymbol': '$'}
292
+ ```
293
+
294
+ </details>
295
+
296
+
297
+ ### Search and Lists
298
+
299
+ #### Domain Availability Check
300
+
301
+ Availability and price of every domain + extension combination. Returns a plain list on success, an error envelope on failure.
302
+
303
+ ```python
304
+ result = dna.check_availability(
305
+ ["dnaprobexyz123", "google", "premium"], # names without extension
306
+ ["com", "net"], # extensions
307
+ 1, # period (years)
308
+ "create", # command: create / renew / transfer
309
+ )
310
+ ```
311
+
312
+ <details>
313
+ <summary>Sample output</summary>
314
+
315
+ ```python
316
+ [{'TLD': 'com',
317
+ 'DomainName': 'dnaprobexyz123',
318
+ 'Status': 'available',
319
+ 'Command': 'create',
320
+ 'Period': 1,
321
+ 'IsFee': False,
322
+ 'Price': '11.9900',
323
+ 'Currency': 'USD',
324
+ 'Reason': None},
325
+ {'TLD': 'net',
326
+ 'DomainName': 'dnaprobexyz123',
327
+ 'Status': 'available',
328
+ 'Command': 'create',
329
+ 'Period': 1,
330
+ 'IsFee': False,
331
+ 'Price': '13.9900',
332
+ 'Currency': 'USD',
333
+ 'Reason': None},
334
+ {'TLD': 'com',
335
+ 'DomainName': 'google',
336
+ 'Status': 'notavailable',
337
+ 'Command': 'create',
338
+ 'Period': 1,
339
+ 'IsFee': False,
340
+ 'Price': '11.9900',
341
+ 'Currency': 'USD',
342
+ 'Reason': 'Domain exists'},
343
+ {'TLD': 'net',
344
+ 'DomainName': 'premium',
345
+ 'Status': 'available',
346
+ 'Command': 'create',
347
+ 'Period': 1,
348
+ 'IsFee': True,
349
+ 'Price': '2500.0000',
350
+ 'Currency': 'USD',
351
+ 'Reason': None}]
352
+ ```
353
+
354
+ </details>
355
+
356
+
357
+ <hr style="border: 4px solid #000; border-style: dashed;">
358
+
359
+ #### Domain List
360
+
361
+ Domains in the reseller account. Filters: PageNumber (0-based), PageSize, OrderColumn, OrderDirection, DomainName ...
362
+
363
+ ```python
364
+ result = dna.get_list({
365
+ "PageNumber": 0,
366
+ "PageSize": 50,
367
+ "OrderColumn": "ExpirationDate",
368
+ "OrderDirection": "DESC",
369
+ })
370
+ ```
371
+
372
+ <details>
373
+ <summary>Sample output</summary>
374
+
375
+ ```python
376
+ {'data': {'Domains': [{'ID': 11,
377
+ 'Status': 'ok',
378
+ 'DomainName': 'example.com',
379
+ 'AuthCode': '',
380
+ 'LockStatus': 'true',
381
+ 'PrivacyProtectionStatus': 'true',
382
+ 'IsChildNameServer': 'false',
383
+ 'Contacts': {'Billing': {'ID': ''},
384
+ 'Technical': {'ID': ''},
385
+ 'Administrative': {'ID': ''},
386
+ 'Registrant': {'ID': ''}},
387
+ 'Dates': {'Start': '2024-03-15T10:20:30',
388
+ 'Expiration': '2027-03-15T10:20:30',
389
+ 'RemainingDays': 126},
390
+ 'NameServers': ['ns1.example.net', 'ns2.example.net'],
391
+ 'Additional': [],
392
+ 'ChildNameServers': []},
393
+ {'ID': 12,
394
+ 'Status': 'Deleted',
395
+ 'DomainName': 'example.net',
396
+ 'AuthCode': '',
397
+ 'LockStatus': 'false',
398
+ 'PrivacyProtectionStatus': 'false',
399
+ 'IsChildNameServer': 'false',
400
+ 'Contacts': {'Billing': {'ID': ''},
401
+ 'Technical': {'ID': ''},
402
+ 'Administrative': {'ID': ''},
403
+ 'Registrant': {'ID': ''}},
404
+ 'Dates': {'Start': '2023-01-01T00:00:00',
405
+ 'Expiration': '2026-01-01T00:00:00',
406
+ 'RemainingDays': 0},
407
+ 'NameServers': [],
408
+ 'Additional': [],
409
+ 'ChildNameServers': []},
410
+ {'ID': 13,
411
+ 'Status': 'WaitingForRegistration',
412
+ 'DomainName': 'example.org',
413
+ 'AuthCode': '',
414
+ 'LockStatus': 'false',
415
+ 'PrivacyProtectionStatus': 'false',
416
+ 'IsChildNameServer': 'false',
417
+ 'Contacts': {'Billing': {'ID': ''},
418
+ 'Technical': {'ID': ''},
419
+ 'Administrative': {'ID': ''},
420
+ 'Registrant': {'ID': ''}},
421
+ 'Dates': {'Start': '', 'Expiration': '', 'RemainingDays': 0},
422
+ 'NameServers': [],
423
+ 'Additional': [],
424
+ 'ChildNameServers': []}]},
425
+ 'result': 'OK',
426
+ 'TotalCount': 3}
427
+ ```
428
+
429
+ </details>
430
+
431
+
432
+ <hr style="border: 4px solid #000; border-style: dashed;">
433
+
434
+ #### TLD List
435
+
436
+ TLD list with prices per period (registration, renew, transfer, restore ...).
437
+
438
+ ```python
439
+ result = dna.get_tld_list(100)
440
+ ```
441
+
442
+ <details>
443
+ <summary>Sample output</summary>
444
+
445
+ ```python
446
+ {'data': [{'id': 1,
447
+ 'status': 'Active',
448
+ 'maxchar': 63,
449
+ 'maxperiod': 10,
450
+ 'minchar': 1,
451
+ 'minperiod': 1,
452
+ 'tld': 'aero',
453
+ 'pricing': {'registration': {'1': '44.9900',
454
+ '2': '94.9100',
455
+ '3': '144.8300'},
456
+ 'renew': {'1': '49.9200', '2': '99.8400'},
457
+ 'transfer': {'1': '44.9900'}},
458
+ 'currencies': {'registration': 'USD', 'renew': 'USD', 'transfer': 'USD'}},
459
+ {'id': 2,
460
+ 'status': 'Passive',
461
+ 'maxchar': 50,
462
+ 'maxperiod': 10,
463
+ 'minchar': 2,
464
+ 'minperiod': 1,
465
+ 'tld': 'com.tr',
466
+ 'pricing': {'registration': {'1': '15.5000', '2': '30.0000'},
467
+ 'renew': {'1': '15.5000'},
468
+ 'transfer': {'1': '0.0000'}},
469
+ 'currencies': {'registration': 'TRY', 'renew': 'TRY', 'transfer': 'USD'}},
470
+ {'id': 3,
471
+ 'status': 'Active',
472
+ 'maxchar': 63,
473
+ 'maxperiod': 10,
474
+ 'minchar': 1,
475
+ 'minperiod': 1,
476
+ 'tld': 'xyz',
477
+ 'pricing': {},
478
+ 'currencies': {}}],
479
+ 'result': 'OK'}
480
+ ```
481
+
482
+ </details>
483
+
484
+
485
+ ### Domains
486
+
487
+ #### Domain Registration
488
+
489
+ Register a new domain. Contacts can be given flat (`AddressLine1`, `Phone`, ...) or nested (`Address.Line1`, `Phone.Phone.Number`, ...). Missing fields are completed and phone numbers are normalised (see `validate_contact`). An empty nameserver list falls back to `ns1.domainnameapi.com` / `ns2.domainnameapi.com`.
490
+
491
+ ```python
492
+ contact = {
493
+ "FirstName": "Ahmet",
494
+ "LastName": "Yilmaz",
495
+ "Company": "",
496
+ "EMail": "ahmet.yilmaz@example.com",
497
+ "AddressLine1": "Ornek Sokak No: 123",
498
+ "AddressLine2": "Daire 4",
499
+ "AddressLine3": "",
500
+ "City": "Istanbul",
501
+ "Country": "TR",
502
+ "Fax": "2121234567",
503
+ "FaxCountryCode": "90",
504
+ "Phone": "5551234567",
505
+ "PhoneCountryCode": 90,
506
+ "Type": "Contact",
507
+ "ZipCode": "34000",
508
+ "State": "Istanbul",
509
+ }
510
+
511
+ contacts = {
512
+ "Administrative": contact,
513
+ "Billing": contact,
514
+ "Technical": contact,
515
+ "Registrant": contact,
516
+ }
517
+
518
+ result = dna.register_with_contact_info(
519
+ "example.com",
520
+ 1, # period (years)
521
+ contacts,
522
+ ["ns1.example.com", "ns2.example.com"], # empty list -> default nameservers
523
+ True, # theft protection lock
524
+ False, # privacy protection
525
+ )
526
+ ```
527
+
528
+ <details>
529
+ <summary>Sample output</summary>
530
+
531
+ ```python
532
+ {'data': {'ID': 0,
533
+ 'Status': 'Active',
534
+ 'DomainName': '',
535
+ 'AuthCode': '',
536
+ 'LockStatus': 'false',
537
+ 'PrivacyProtectionStatus': 'false',
538
+ 'IsChildNameServer': 'false',
539
+ 'Contacts': {'Billing': {'ID': 0},
540
+ 'Technical': {'ID': 0},
541
+ 'Administrative': {'ID': 0},
542
+ 'Registrant': {'ID': 0}},
543
+ 'Dates': {'Start': '',
544
+ 'Expiration': '2027-11-09T12:00:00',
545
+ 'RemainingDays': 366},
546
+ 'NameServers': [],
547
+ 'Additional': [],
548
+ 'ChildNameServers': []},
549
+ 'result': 'OK'}
550
+ ```
551
+
552
+ </details>
553
+
554
+
555
+ <hr style="border: 4px solid #000; border-style: dashed;">
556
+
557
+ #### Domain Registration (.tr)
558
+
559
+ `.tr` domains need TRABIS attributes as the 7th argument. Individual owner: `TRABISDOMAINCATEGORY` = `1` and `TRABISCITIZENID` (identity number). Company owner: `TRABISDOMAINCATEGORY` = `0`, `TRABISTAXOFFICE` and `TRABISTAXNUMBER`. Legacy keys (`TRABISCITIZIENID`, `TRABISNAMESURNAME`, `TRABISCOUNTRYID`, ...) are accepted: they are converted to the REST schema, unsupported ones are dropped.
560
+
561
+ ```python
562
+ individual = {
563
+ "TRABISDOMAINCATEGORY": 1,
564
+ "TRABISCITIZIENID": "11111111111",
565
+ }
566
+
567
+ commercial = {
568
+ "TRABISDOMAINCATEGORY": 0,
569
+ "TRABISTAXOFFICE": "Istanbul VD",
570
+ "TRABISTAXNUMBER": "1234567890",
571
+ }
572
+
573
+ result = dna.register_with_contact_info(
574
+ "example.com.tr",
575
+ 1,
576
+ contacts,
577
+ ["ns1.example.com", "ns2.example.com"],
578
+ True,
579
+ False,
580
+ individual, # or commercial
581
+ )
582
+ ```
583
+
584
+ <details>
585
+ <summary>Sample output</summary>
586
+
587
+ ```python
588
+ {'data': {'ID': 0,
589
+ 'Status': 'Active',
590
+ 'DomainName': '',
591
+ 'AuthCode': '',
592
+ 'LockStatus': 'false',
593
+ 'PrivacyProtectionStatus': 'false',
594
+ 'IsChildNameServer': 'false',
595
+ 'Contacts': {'Billing': {'ID': 0},
596
+ 'Technical': {'ID': 0},
597
+ 'Administrative': {'ID': 0},
598
+ 'Registrant': {'ID': 0}},
599
+ 'Dates': {'Start': '',
600
+ 'Expiration': '2027-11-09T12:00:00',
601
+ 'RemainingDays': 366},
602
+ 'NameServers': [],
603
+ 'Additional': [],
604
+ 'ChildNameServers': []},
605
+ 'result': 'OK'}
606
+ ```
607
+
608
+ </details>
609
+
610
+
611
+ <hr style="border: 4px solid #000; border-style: dashed;">
612
+
613
+ #### Domain Renewal
614
+
615
+ Renew a domain for the given number of years.
616
+
617
+ ```python
618
+ result = dna.renew("example.com", 1)
619
+ ```
620
+
621
+ <details>
622
+ <summary>Sample output</summary>
623
+
624
+ ```python
625
+ {'result': 'OK', 'data': {'ExpirationDate': '2027-11-09T12:00:00'}}
626
+ ```
627
+
628
+ </details>
629
+
630
+
631
+ <hr style="border: 4px solid #000; border-style: dashed;">
632
+
633
+ #### Domain Details
634
+
635
+ Full details of one domain: status, dates, nameservers, lock/privacy flags, child nameservers.
636
+
637
+ ```python
638
+ result = dna.get_details("example.com")
639
+ ```
640
+
641
+ <details>
642
+ <summary>Sample output</summary>
643
+
644
+ ```python
645
+ {'data': {'ID': 4321,
646
+ 'Status': 'Active',
647
+ 'DomainName': 'example.com',
648
+ 'AuthCode': 'Ab1!xyZ9',
649
+ 'LockStatus': 'true',
650
+ 'PrivacyProtectionStatus': 'false',
651
+ 'IsChildNameServer': 'true',
652
+ 'Contacts': {'Billing': {'ID': 'DNA-B-4'},
653
+ 'Technical': {'ID': 'DNA-T-3'},
654
+ 'Administrative': {'ID': 'DNA-A-2'},
655
+ 'Registrant': {'ID': 'DNA-R-1'}},
656
+ 'Dates': {'Start': '2024-03-15T10:20:30',
657
+ 'Expiration': '2027-03-15T10:20:30',
658
+ 'RemainingDays': 126},
659
+ 'NameServers': ['ns1.example.net', 'ns2.example.net'],
660
+ 'Additional': {'TRABISDOMAINCATEGORY': '1'},
661
+ 'ChildNameServers': [{'ns': 'ns1.example.com', 'ip': '192.0.2.11'},
662
+ {'ns': 'ns2.example.com', 'ip': ''}]},
663
+ 'result': 'OK'}
664
+ ```
665
+
666
+ </details>
667
+
668
+
669
+ <hr style="border: 4px solid #000; border-style: dashed;">
670
+
671
+ #### Sync From Registry
672
+
673
+ Refresh a domain from the registry (same envelope as get_details).
674
+
675
+ ```python
676
+ result = dna.sync_from_registry("example.com")
677
+ ```
678
+
679
+ <details>
680
+ <summary>Sample output</summary>
681
+
682
+ ```python
683
+ {'data': {'ID': 4321,
684
+ 'Status': 'Active',
685
+ 'DomainName': 'example.com',
686
+ 'AuthCode': 'Ab1!xyZ9',
687
+ 'LockStatus': 'true',
688
+ 'PrivacyProtectionStatus': 'false',
689
+ 'IsChildNameServer': 'true',
690
+ 'Contacts': {'Billing': {'ID': 'DNA-B-4'},
691
+ 'Technical': {'ID': 'DNA-T-3'},
692
+ 'Administrative': {'ID': 'DNA-A-2'},
693
+ 'Registrant': {'ID': 'DNA-R-1'}},
694
+ 'Dates': {'Start': '2024-03-15T10:20:30',
695
+ 'Expiration': '2027-03-15T10:20:30',
696
+ 'RemainingDays': 126},
697
+ 'NameServers': ['ns1.example.net', 'ns2.example.net'],
698
+ 'Additional': {'TRABISDOMAINCATEGORY': '1'},
699
+ 'ChildNameServers': [{'ns': 'ns1.example.com', 'ip': '192.0.2.11'},
700
+ {'ns': 'ns2.example.com', 'ip': ''}]},
701
+ 'result': 'OK'}
702
+ ```
703
+
704
+ </details>
705
+
706
+
707
+ <hr style="border: 4px solid #000; border-style: dashed;">
708
+
709
+ #### Nameserver Modification
710
+
711
+ Replace the nameservers of a domain (entries are trimmed, lower-cased, de-duplicated).
712
+
713
+ ```python
714
+ result = dna.modify_name_server("example.com", ["ns1.example.net", "ns2.example.net"])
715
+ ```
716
+
717
+ <details>
718
+ <summary>Sample output</summary>
719
+
720
+ ```python
721
+ {'result': 'OK', 'data': {'NameServers': ['ns1.example.net', 'ns2.example.net']}}
722
+ ```
723
+
724
+ </details>
725
+
726
+
727
+ <hr style="border: 4px solid #000; border-style: dashed;">
728
+
729
+ #### Enable Domain Lock
730
+
731
+ Turn the registrar (theft protection) lock on.
732
+
733
+ ```python
734
+ result = dna.enable_theft_protection_lock("example.com")
735
+ ```
736
+
737
+ <details>
738
+ <summary>Sample output</summary>
739
+
740
+ ```python
741
+ {'result': 'OK', 'data': {'LockStatus': True}}
742
+ ```
743
+
744
+ </details>
745
+
746
+
747
+ <hr style="border: 4px solid #000; border-style: dashed;">
748
+
749
+ #### Disable Domain Lock
750
+
751
+ Turn the registrar (theft protection) lock off.
752
+
753
+ ```python
754
+ result = dna.disable_theft_protection_lock("example.com")
755
+ ```
756
+
757
+ <details>
758
+ <summary>Sample output</summary>
759
+
760
+ ```python
761
+ {'result': 'OK', 'data': {'LockStatus': False}}
762
+ ```
763
+
764
+ </details>
765
+
766
+
767
+ <hr style="border: 4px solid #000; border-style: dashed;">
768
+
769
+ #### Modify Domain Privacy
770
+
771
+ Turn WHOIS privacy protection on (True) or off (False). 1, "1", "on", "true" and "yes" also mean on; anything else means off. The reason argument is not sent to the gateway.
772
+
773
+ ```python
774
+ result = dna.modify_privacy_protection_status("example.com", True, "Owner request")
775
+ ```
776
+
777
+ <details>
778
+ <summary>Sample output</summary>
779
+
780
+ ```python
781
+ {'data': {'PrivacyProtectionStatus': True}, 'result': 'OK'}
782
+ ```
783
+
784
+ </details>
785
+
786
+
787
+ ### Contacts
788
+
789
+ #### Get Domain Contacts
790
+
791
+ Administrative, Billing, Registrant and Technical contacts of a domain.
792
+
793
+ ```python
794
+ result = dna.get_contacts("example.com")
795
+ ```
796
+
797
+ <details>
798
+ <summary>Sample output</summary>
799
+
800
+ ```python
801
+ {'data': {'contacts': {'Administrative': {'ID': 'DNA-A-2',
802
+ 'Status': 'Active',
803
+ 'AuthCode': '',
804
+ 'FirstName': 'Grace',
805
+ 'LastName': 'Hopper',
806
+ 'Company': '',
807
+ 'EMail': 'grace@example.com',
808
+ 'Type': 'Administrative',
809
+ 'Address': {'Line1': 'Example Street 2',
810
+ 'Line2': '',
811
+ 'Line3': '',
812
+ 'State': 'DC',
813
+ 'City': 'Washington',
814
+ 'Country': 'US',
815
+ 'ZipCode': '20001'},
816
+ 'Phone': {'Phone': {'Number': '2025550100',
817
+ 'CountryCode': '1'},
818
+ 'Fax': {'Number': '2025550101',
819
+ 'CountryCode': '1'}},
820
+ 'Additional': []},
821
+ 'Billing': {'ID': 'DNA-B-4',
822
+ 'Status': 'Active',
823
+ 'AuthCode': '',
824
+ 'FirstName': 'Ada',
825
+ 'LastName': 'Lovelace',
826
+ 'Company': 'Example Ltd',
827
+ 'EMail': 'billing@example.com',
828
+ 'Type': 'Billing',
829
+ 'Address': {'Line1': 'Example Street 1',
830
+ 'Line2': '',
831
+ 'Line3': '',
832
+ 'State': 'Istanbul',
833
+ 'City': 'Istanbul',
834
+ 'Country': 'TR',
835
+ 'ZipCode': '34000'},
836
+ 'Phone': {'Phone': {'Number': '5551234567',
837
+ 'CountryCode': '90'},
838
+ 'Fax': {'Number': '', 'CountryCode': ''}},
839
+ 'Additional': []},
840
+ 'Registrant': {'ID': 'DNA-R-1',
841
+ 'Status': 'Active',
842
+ 'AuthCode': '',
843
+ 'FirstName': 'Ada',
844
+ 'LastName': 'Lovelace',
845
+ 'Company': 'Example Ltd',
846
+ 'EMail': 'ada@example.com',
847
+ 'Type': 'Registrant',
848
+ 'Address': {'Line1': 'Example Street 1',
849
+ 'Line2': '',
850
+ 'Line3': '',
851
+ 'State': 'Istanbul',
852
+ 'City': 'Istanbul',
853
+ 'Country': 'TR',
854
+ 'ZipCode': '34000'},
855
+ 'Phone': {'Phone': {'Number': '5551234567',
856
+ 'CountryCode': '90'},
857
+ 'Fax': {'Number': '',
858
+ 'CountryCode': ''}},
859
+ 'Additional': []},
860
+ 'Technical': {'ID': 'DNA-T-3',
861
+ 'Status': 'Active',
862
+ 'AuthCode': '',
863
+ 'FirstName': 'Alan',
864
+ 'LastName': 'Turing',
865
+ 'Company': '',
866
+ 'EMail': 'alan@example.com',
867
+ 'Type': 'Technical',
868
+ 'Address': {'Line1': 'Example Street 3',
869
+ 'Line2': '',
870
+ 'Line3': '',
871
+ 'State': '',
872
+ 'City': 'London',
873
+ 'Country': 'GB',
874
+ 'ZipCode': 'SW1A 1AA'},
875
+ 'Phone': {'Phone': {'Number': '2071234567',
876
+ 'CountryCode': '44'},
877
+ 'Fax': {'Number': '',
878
+ 'CountryCode': ''}},
879
+ 'Additional': []}}},
880
+ 'result': 'OK'}
881
+ ```
882
+
883
+ </details>
884
+
885
+
886
+ <hr style="border: 4px solid #000; border-style: dashed;">
887
+
888
+ #### Save Domain Contacts
889
+
890
+ Replace the four contacts of a domain. `contacts` is the same dictionary as in the registration example.
891
+
892
+ ```python
893
+ result = dna.save_contacts("example.com", contacts)
894
+ ```
895
+
896
+ <details>
897
+ <summary>Sample output</summary>
898
+
899
+ ```python
900
+ {'result': 'OK', 'data': {'contacts': {}}}
901
+ ```
902
+
903
+ </details>
904
+
905
+
906
+ ### Child Nameservers
907
+
908
+ #### Add Child Nameserver
909
+
910
+ Create a child nameserver (glue record) under a domain.
911
+
912
+ ```python
913
+ result = dna.add_child_name_server("example.com", "ns1.example.com", "192.0.2.10")
914
+ ```
915
+
916
+ <details>
917
+ <summary>Sample output</summary>
918
+
919
+ ```python
920
+ {'result': 'OK',
921
+ 'data': {'NameServer': 'ns1.example.com', 'IPAdresses': ['192.0.2.10']}}
922
+ ```
923
+
924
+ </details>
925
+
926
+
927
+ <hr style="border: 4px solid #000; border-style: dashed;">
928
+
929
+ #### Delete Child Nameserver
930
+
931
+ Delete a child nameserver.
932
+
933
+ ```python
934
+ result = dna.delete_child_name_server("example.com", "ns1.example.com")
935
+ ```
936
+
937
+ <details>
938
+ <summary>Sample output</summary>
939
+
940
+ ```python
941
+ {'result': 'OK', 'data': {'NameServer': 'ns1.example.com'}}
942
+ ```
943
+
944
+ </details>
945
+
946
+
947
+ <hr style="border: 4px solid #000; border-style: dashed;">
948
+
949
+ #### Update Child Nameserver
950
+
951
+ Change the IP address of a child nameserver.
952
+
953
+ ```python
954
+ result = dna.modify_child_name_server("example.com", "ns1.example.com", "192.0.2.20")
955
+ ```
956
+
957
+ <details>
958
+ <summary>Sample output</summary>
959
+
960
+ ```python
961
+ {'result': 'OK',
962
+ 'data': {'NameServer': 'ns1.example.com', 'IPAdresses': ['192.0.2.20']}}
963
+ ```
964
+
965
+ </details>
966
+
967
+
968
+ ### Transfers
969
+
970
+ #### Domain Transfer
971
+
972
+ Start an incoming transfer with the domain's EPP/auth code. Contacts are never sent with a transfer (the request always carries `"contacts": []`): the registrar takes them over from the losing registrar, so `transfer` has no contacts parameter. A refusal (`success: false`) returns a `TRANSFER_DOMAIN` error.
973
+
974
+ ```python
975
+ result = dna.transfer("example.com", "Ab1!xyZ9", 1)
976
+ ```
977
+
978
+ <details>
979
+ <summary>Sample output</summary>
980
+
981
+ ```python
982
+ {'data': {'ID': 0,
983
+ 'Status': 'Active',
984
+ 'DomainName': '',
985
+ 'AuthCode': '',
986
+ 'LockStatus': 'false',
987
+ 'PrivacyProtectionStatus': 'false',
988
+ 'IsChildNameServer': 'false',
989
+ 'Contacts': {'Billing': {'ID': 0},
990
+ 'Technical': {'ID': 0},
991
+ 'Administrative': {'ID': 0},
992
+ 'Registrant': {'ID': 0}},
993
+ 'Dates': {'Start': '',
994
+ 'Expiration': '2027-11-09T12:00:00',
995
+ 'RemainingDays': 366},
996
+ 'NameServers': [],
997
+ 'Additional': [],
998
+ 'ChildNameServers': []},
999
+ 'result': 'OK'}
1000
+ ```
1001
+
1002
+ </details>
1003
+
1004
+
1005
+ <hr style="border: 4px solid #000; border-style: dashed;">
1006
+
1007
+ #### Check Transfer
1008
+
1009
+ Can the domain be transferred with this auth code? result is OK only when it can.
1010
+
1011
+ ```python
1012
+ result = dna.check_transfer("example.com", "Ab1!xyZ9")
1013
+ ```
1014
+
1015
+ <details>
1016
+ <summary>Sample output</summary>
1017
+
1018
+ ```python
1019
+ {'result': 'OK',
1020
+ 'data': {'TransferAvailabilityStatus': True,
1021
+ 'AuthCodeIsRequired': True,
1022
+ 'AuthCodeIsValid': True,
1023
+ 'UserTransferRequired': False,
1024
+ 'TransferLock': False,
1025
+ 'Message': 'Domain can be transferred',
1026
+ 'MessageKey': 'TransferAvailable',
1027
+ 'Additional': []}}
1028
+ ```
1029
+
1030
+ </details>
1031
+
1032
+
1033
+ <hr style="border: 4px solid #000; border-style: dashed;">
1034
+
1035
+ #### Cancel Transfer
1036
+
1037
+ Cancel a pending incoming transfer.
1038
+
1039
+ ```python
1040
+ result = dna.cancel_transfer("example.com")
1041
+ ```
1042
+
1043
+ <details>
1044
+ <summary>Sample output</summary>
1045
+
1046
+ ```python
1047
+ {'result': 'OK', 'data': {'DomainName': 'example.com', 'Status': 'Cancelled'}}
1048
+ ```
1049
+
1050
+ </details>
1051
+
1052
+
1053
+ <hr style="border: 4px solid #000; border-style: dashed;">
1054
+
1055
+ #### Approve Outgoing Transfer
1056
+
1057
+ Approve a pending outgoing transfer.
1058
+
1059
+ ```python
1060
+ result = dna.approve_transfer("example.com")
1061
+ ```
1062
+
1063
+ <details>
1064
+ <summary>Sample output</summary>
1065
+
1066
+ ```python
1067
+ {'result': 'OK', 'data': {'DomainName': 'example.com', 'Status': 'Approved'}}
1068
+ ```
1069
+
1070
+ </details>
1071
+
1072
+
1073
+ <hr style="border: 4px solid #000; border-style: dashed;">
1074
+
1075
+ #### Reject Outgoing Transfer
1076
+
1077
+ Reject a pending outgoing transfer.
1078
+
1079
+ ```python
1080
+ result = dna.reject_transfer("example.com")
1081
+ ```
1082
+
1083
+ <details>
1084
+ <summary>Sample output</summary>
1085
+
1086
+ ```python
1087
+ {'result': 'OK', 'data': {'DomainName': 'example.com', 'Status': 'Rejected'}}
1088
+ ```
1089
+
1090
+ </details>
1091
+
1092
+
1093
+ ### DNS Zone
1094
+
1095
+ The gateway stores DNS records as **sets**: one name + type holds a list of values. Writing a name + type
1096
+ replaces the whole set, and deleting by one value removes the whole set. The `*_record_set` and
1097
+ `*_record_value` methods handle this for you; prefer them over the low-level `add/edit/delete_resource_record`.
1098
+
1099
+ - Names may be given as `"@"`, `""`, `"www"`, `"www.example.com"` or `"www.example.com."`; they are sent as the
1100
+ relative label the gateway expects. `get_resource_records` returns fully qualified names (`"www.example.com."`).
1101
+ - Supported types: `A`, `AAAA`, `ALIAS`, `CAA`, `CNAME`, `DS`, `MX`, `NAPTR`, `PTR`, `SRV`, `TLSA`, `TXT`
1102
+ (others are rejected before any call is made). TTL is 1 to 86400 seconds.
1103
+ - Writes are applied immediately; pass `apply=False` to stage several changes and call
1104
+ `apply_resource_records` once. If the automatic apply fails, the method returns the apply error (the change
1105
+ stays staged but is not live).
1106
+ - The gateway rate-limits zone calls, so the library keeps zone calls at least one second apart
1107
+ (`dna.zone_min_interval`, in seconds).
1108
+
1109
+
1110
+ #### List Records
1111
+
1112
+ DNS zone of a domain, one row per record value. Names come back fully qualified.
1113
+
1114
+ ```python
1115
+ result = dna.get_resource_records("example.com")
1116
+ ```
1117
+
1118
+ <details>
1119
+ <summary>Sample output</summary>
1120
+
1121
+ ```python
1122
+ {'result': 'OK',
1123
+ 'data': {'records': [{'Name': 'example.com.',
1124
+ 'Type': 'A',
1125
+ 'TTL': 3600,
1126
+ 'Content': '192.0.2.1',
1127
+ 'Disabled': False},
1128
+ {'Name': 'www.example.com.',
1129
+ 'Type': 'CNAME',
1130
+ 'TTL': 300,
1131
+ 'Content': 'example.com.',
1132
+ 'Disabled': False},
1133
+ {'Name': 'example.com.',
1134
+ 'Type': 'MX',
1135
+ 'TTL': 3600,
1136
+ 'Content': '10 mx1.example.com.',
1137
+ 'Disabled': False},
1138
+ {'Name': 'example.com.',
1139
+ 'Type': 'MX',
1140
+ 'TTL': 3600,
1141
+ 'Content': '20 mx2.example.com.',
1142
+ 'Disabled': True},
1143
+ {'Name': 'example.com.',
1144
+ 'Type': 'TXT',
1145
+ 'TTL': 3600,
1146
+ 'Content': '"v=spf1 include:_spf.example.net ~all"',
1147
+ 'Disabled': False},
1148
+ {'Name': 'empty.example.com.',
1149
+ 'Type': 'AAAA',
1150
+ 'TTL': 60,
1151
+ 'Content': '',
1152
+ 'Disabled': False}]}}
1153
+ ```
1154
+
1155
+ </details>
1156
+
1157
+
1158
+ <hr style="border: 4px solid #000; border-style: dashed;">
1159
+
1160
+ #### Set a Record Set
1161
+
1162
+ Make a whole name + type look exactly like the given list (the gateway's own model). An empty list removes the set. Changes are applied immediately unless apply=False.
1163
+
1164
+ ```python
1165
+ result = dna.set_resource_record_set(
1166
+ "example.com",
1167
+ "@", # apex; "www", "www.example.com" also work
1168
+ "MX",
1169
+ ["10 mx1.example.com", "20 mx2.example.com"],
1170
+ 3600, # TTL (1..86400)
1171
+ )
1172
+ ```
1173
+
1174
+ <details>
1175
+ <summary>Sample output</summary>
1176
+
1177
+ ```python
1178
+ {'result': 'OK',
1179
+ 'data': {'Name': '',
1180
+ 'Type': 'MX',
1181
+ 'TTL': 3600,
1182
+ 'Contents': ['10 mx1.example.com', '20 mx2.example.com']}}
1183
+ ```
1184
+
1185
+ </details>
1186
+
1187
+
1188
+ <hr style="border: 4px solid #000; border-style: dashed;">
1189
+
1190
+ #### Add One Value
1191
+
1192
+ Add ONE value to a record set and keep the values already there (read-merge-write). Adding a value that is already present is a no-op.
1193
+
1194
+ ```python
1195
+ result = dna.add_resource_record_value("example.com", "@", "MX", "30 mx3.example.com")
1196
+ ```
1197
+
1198
+ <details>
1199
+ <summary>Sample output</summary>
1200
+
1201
+ ```python
1202
+ {'result': 'OK',
1203
+ 'data': {'Name': '',
1204
+ 'Type': 'MX',
1205
+ 'TTL': 3600,
1206
+ 'Contents': ['10 mx1.example.com.',
1207
+ '20 mx2.example.com.',
1208
+ '30 mx3.example.com']}}
1209
+ ```
1210
+
1211
+ </details>
1212
+
1213
+
1214
+ <hr style="border: 4px solid #000; border-style: dashed;">
1215
+
1216
+ #### Remove One Value
1217
+
1218
+ Remove ONE value from a record set, leaving the others in place.
1219
+
1220
+ ```python
1221
+ result = dna.remove_resource_record_value("example.com", "@", "MX", "20 mx2.example.com.")
1222
+ ```
1223
+
1224
+ <details>
1225
+ <summary>Sample output</summary>
1226
+
1227
+ ```python
1228
+ {'result': 'OK',
1229
+ 'data': {'Name': '', 'Type': 'MX', 'TTL': 3600, 'Contents': ['10 mx1.example.com.']}}
1230
+ ```
1231
+
1232
+ </details>
1233
+
1234
+
1235
+ <hr style="border: 4px solid #000; border-style: dashed;">
1236
+
1237
+ #### Replace One Value
1238
+
1239
+ Swap ONE value of a record set for another (the 'edit row' of a DNS panel).
1240
+
1241
+ ```python
1242
+ result = dna.replace_resource_record_value("example.com", "@", "A", "192.0.2.1", "192.0.2.2")
1243
+ ```
1244
+
1245
+ <details>
1246
+ <summary>Sample output</summary>
1247
+
1248
+ ```python
1249
+ {'result': 'OK',
1250
+ 'data': {'Name': '', 'Type': 'A', 'TTL': 3600, 'Contents': ['192.0.2.2']}}
1251
+ ```
1252
+
1253
+ </details>
1254
+
1255
+
1256
+ <hr style="border: 4px solid #000; border-style: dashed;">
1257
+
1258
+ #### Delete a Record Set
1259
+
1260
+ Remove every value under a name + type. Removing a set that does not exist is OK.
1261
+
1262
+ ```python
1263
+ result = dna.delete_resource_record_set("example.com", "@", "MX")
1264
+ ```
1265
+
1266
+ <details>
1267
+ <summary>Sample output</summary>
1268
+
1269
+ ```python
1270
+ {'result': 'OK',
1271
+ 'data': {'Name': 'example.com.', 'Type': 'MX', 'Content': '10 mx1.example.com.'}}
1272
+ ```
1273
+
1274
+ </details>
1275
+
1276
+
1277
+ <hr style="border: 4px solid #000; border-style: dashed;">
1278
+
1279
+ #### Add Record (low-level)
1280
+
1281
+ Low-level: write a record set (POST). The gateway replaces an existing name + type, so prefer add_resource_record_value() to append a value.
1282
+
1283
+ ```python
1284
+ result = dna.add_resource_record("example.com", "www", "A", "192.0.2.5", 300)
1285
+ ```
1286
+
1287
+ <details>
1288
+ <summary>Sample output</summary>
1289
+
1290
+ ```python
1291
+ {'result': 'OK',
1292
+ 'data': {'Name': 'www', 'Type': 'A', 'TTL': 300, 'Content': '192.0.2.5'}}
1293
+ ```
1294
+
1295
+ </details>
1296
+
1297
+
1298
+ <hr style="border: 4px solid #000; border-style: dashed;">
1299
+
1300
+ #### Edit Record (low-level)
1301
+
1302
+ Low-level: rewrite an existing record set (PUT), identified by its current name.
1303
+
1304
+ ```python
1305
+ result = dna.edit_resource_record("example.com", "www", "www", "A", "192.0.2.6", 600)
1306
+ ```
1307
+
1308
+ <details>
1309
+ <summary>Sample output</summary>
1310
+
1311
+ ```python
1312
+ {'result': 'OK',
1313
+ 'data': {'Name': 'www', 'Type': 'A', 'TTL': 600, 'Content': '192.0.2.6'}}
1314
+ ```
1315
+
1316
+ </details>
1317
+
1318
+
1319
+ <hr style="border: 4px solid #000; border-style: dashed;">
1320
+
1321
+ #### Delete Record (low-level)
1322
+
1323
+ Low-level: DELETE by name + value + type. The gateway removes the WHOLE set, so prefer remove_resource_record_value() to drop a single value.
1324
+
1325
+ ```python
1326
+ result = dna.delete_resource_record("example.com", "www", "192.0.2.5", "A")
1327
+ ```
1328
+
1329
+ <details>
1330
+ <summary>Sample output</summary>
1331
+
1332
+ ```python
1333
+ {'result': 'OK', 'data': {'Name': 'www', 'Type': 'A', 'Content': '192.0.2.5'}}
1334
+ ```
1335
+
1336
+ </details>
1337
+
1338
+
1339
+ <hr style="border: 4px solid #000; border-style: dashed;">
1340
+
1341
+ #### Apply Staged Changes
1342
+
1343
+ Commit staged zone changes (only needed after calls made with apply=False).
1344
+
1345
+ ```python
1346
+ dna.add_resource_record("example.com", "www", "A", "192.0.2.5", 300, False)
1347
+ dna.add_resource_record("example.com", "api", "A", "192.0.2.6", 300, False)
1348
+ result = dna.apply_resource_records("example.com")
1349
+ ```
1350
+
1351
+ <details>
1352
+ <summary>Sample output</summary>
1353
+
1354
+ ```python
1355
+ {'result': 'OK', 'data': {'DomainName': 'example.com'}}
1356
+ ```
1357
+
1358
+ </details>
1359
+
1360
+
1361
+ ### URL Forwarding
1362
+
1363
+ #### Get Forwarding
1364
+
1365
+ URL forwarding of a domain. Enabled is False when nothing is configured.
1366
+
1367
+ ```python
1368
+ result = dna.get_forwarding("example.com")
1369
+ ```
1370
+
1371
+ <details>
1372
+ <summary>Sample output</summary>
1373
+
1374
+ ```python
1375
+ {'result': 'OK',
1376
+ 'data': {'Enabled': True,
1377
+ 'RedirectAddress': 'https://www.example.org/landing',
1378
+ 'ForwardType': 'Frame'}}
1379
+ ```
1380
+
1381
+ </details>
1382
+
1383
+
1384
+ <hr style="border: 4px solid #000; border-style: dashed;">
1385
+
1386
+ #### Set Forwarding
1387
+
1388
+ Forward the domain to a URL: 'Standard' (plain redirect) or 'Frame' (masked).
1389
+
1390
+ ```python
1391
+ result = dna.set_forwarding("example.com", "https://www.example.org", "Standard")
1392
+ ```
1393
+
1394
+ <details>
1395
+ <summary>Sample output</summary>
1396
+
1397
+ ```python
1398
+ {'result': 'OK',
1399
+ 'data': {'RedirectAddress': 'https://www.example.org', 'ForwardType': 'Standard'}}
1400
+ ```
1401
+
1402
+ </details>
1403
+
1404
+
1405
+ <hr style="border: 4px solid #000; border-style: dashed;">
1406
+
1407
+ #### Delete Forwarding
1408
+
1409
+ Remove URL forwarding. Removed is False (and result OK) when nothing was configured.
1410
+
1411
+ ```python
1412
+ result = dna.delete_forwarding("example.com")
1413
+ ```
1414
+
1415
+ <details>
1416
+ <summary>Sample output</summary>
1417
+
1418
+ ```python
1419
+ {'result': 'OK', 'data': {'DomainName': 'example.com', 'Removed': True}}
1420
+ ```
1421
+
1422
+ </details>
1423
+
1424
+
1425
+ ### Utilities
1426
+
1427
+ #### Is .tr Domain
1428
+
1429
+ Is this a .tr domain? Local check, no network call.
1430
+
1431
+ ```python
1432
+ result = dna.is_tr_tld("example.com.tr")
1433
+ ```
1434
+
1435
+ <details>
1436
+ <summary>Sample output</summary>
1437
+
1438
+ ```python
1439
+ True
1440
+ ```
1441
+
1442
+ </details>
1443
+
1444
+
1445
+ <hr style="border: 4px solid #000; border-style: dashed;">
1446
+
1447
+ #### Validate Contact
1448
+
1449
+ Complete and normalise a contact the way the gateway expects it (local, no network): missing fields get placeholders, names lose digits/punctuation, phone numbers are split into number + country code, State falls back to City.
1450
+
1451
+ ```python
1452
+ result = dna.validate_contact({
1453
+ "FirstName": " Jo ",
1454
+ "Phone": "+1 (202) 555-0100",
1455
+ "Country": "Turkey",
1456
+ "City": "",
1457
+ "Fax": "0090 212 123 45 67",
1458
+ })
1459
+ ```
1460
+
1461
+ <details>
1462
+ <summary>Sample output</summary>
1463
+
1464
+ ```python
1465
+ {'FirstName': 'Jo',
1466
+ 'Phone': '2025550100',
1467
+ 'Country': 'TR',
1468
+ 'City': 'ISTANBUL',
1469
+ 'Fax': '2121234567',
1470
+ 'LastName': 'Isimyok',
1471
+ 'AddressLine1': 'Addres yok',
1472
+ 'ZipCode': '34000',
1473
+ 'PhoneCountryCode': '1',
1474
+ 'State': 'ISTANBUL',
1475
+ 'FaxCountryCode': '90'}
1476
+ ```
1477
+
1478
+ </details>
1479
+
1480
+
1481
+ ### Diagnostics and Settings
1482
+
1483
+ ```python
1484
+ dna.get_details("example.com")
1485
+
1486
+ dna.get_request_data() # {'url': ..., 'method': 'GET', 'payload': {...}} of the last call
1487
+ dna.get_response_data() # decoded response body of the last call ({'raw_response': ...} if not JSON)
1488
+ dna.get_parsed_response_data() # body on success, {'Code', 'Message', 'Details'} on failure
1489
+ dna.get_response_headers() # {'url', 'http_code', 'content_type', 'total_time', 'headers'}
1490
+ dna.get_last_function() # 'request:GET domains/info'
1491
+ dna.get_service_url() # 'https://api.domainresellerapi.com/api/v1'
1492
+
1493
+ dna.set_service_url("https://ote.domainresellerapi.com/api/v1")
1494
+ dna.set_error_reporting_enabled(False)
1495
+ dna.set_telemetry_minimal(True)
1496
+ dna.set_ssl_verification(True)
1497
+ dna.zone_min_interval = 1.0
1498
+ ```
1499
+
1500
+ A custom HTTP transport (proxy handling, logging, tests) can be passed to the constructor: any object with a
1501
+ `send(request)` method that returns a `domainnameapi.HttpResponse`:
1502
+
1503
+ ```python
1504
+ from domainnameapi import DomainNameAPI, HttpResponse, UrllibTransport
1505
+
1506
+
1507
+ class LoggingTransport(UrllibTransport):
1508
+ def send(self, request):
1509
+ print(request.method, request.url)
1510
+ return super().send(request)
1511
+
1512
+
1513
+ dna = DomainNameAPI(reseller_id, api_key, transport=LoggingTransport())
1514
+ ```
1515
+
1516
+ ## Testing
1517
+
1518
+ The test suite needs no credentials and makes no external network calls:
1519
+
1520
+ ```bash
1521
+ python -m unittest discover -s tests -v
1522
+ ```
1523
+
1524
+ | Test file | Description |
1525
+ |-----------|-------------|
1526
+ | `tests/test_conformance.py` | Runs all 134 php-dna conformance fixtures: same requests on the wire, same return values |
1527
+ | `tests/test_edge_cases.py` | Extra edge cases recorded from php-dna (unusual gateway responses and inputs) |
1528
+ | `tests/test_http.py` | HTTP layer: headers, query strings, JSON bodies, timeouts, redirects |
1529
+ | `tests/test_errors.py` | Error mapping of gateway responses |
1530
+ | `tests/test_telemetry.py` | Telemetry payloads, credential masking, opt-out |
1531
+ | `tests/test_utils.py` | Utilities and PHP-compatible value handling |
1532
+
1533
+ <hr style="border: 4px solid #000; border-style: dashed;">
1534
+
1535
+
1536
+ ## Return and Error Codes with Descriptions
1537
+
1538
+ | Code | Description | Detail |
1539
+ |------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
1540
+ | 1000 | Command completed successfully | Operation successful. |
1541
+ | 1001 | Command completed successfully; action pending | Operation successful. However, the operation is currently queued for completion. |
1542
+ | 2003 | Required parameter missing | Parameter missing error. For example, no phone entry in contact information. |
1543
+ | 2105 | Object is not eligible for renewal | Domain status is not suitable for renewal, locked for update operations. Status should not be "clientupdateprohibited". May be due to other status conditions. |
1544
+ | 2200 | Authentication error | Authorization error, security code is incorrect or domain is registered with another registrar. |
1545
+ | 2302 | Object exists | Domain name or nameserver information already exists in database. Cannot be registered. |
1546
+ | 2303 | Object does not exist | Domain name or nameserver information does not exist in database. New registration required. |
1547
+ | 2304 | Object status prohibits operation | Domain status is not suitable for updates, locked for update operations. Status should not be "clientupdateprohibited". May be due to other status conditions. |
1548
+
1549
+ | CODE | DETAIL |
1550
+ |------|--------------------------------------------------------------------------------------------------------------------------------------|
1551
+ | 101 | System Error Detailed For ({0})! |
1552
+ | 102 | Multiple Errors Detailed For ({0})! |
1553
+ | 103 | Unknown Errors Detailed For ({0})! |
1554
+ | 200 | API command not found ({0})! |
1555
+ | 210 | API service not found ({0})! |
1556
+ | 211 | API service provider not set! |
1557
+ | 300 | Reseller not found! |
1558
+ | 301 | Your current IP address is not authorized to access. Please make sure you are connecting from an authorized IP address and try again |
1559
+ | 310 | TLD is not supported! |
1560
+ | 320 | API not found! |
1561
+ | 321 | Currency is not supported! |
1562
+ | 330 | Required parameter(s) not set ({0}). |
1563
+ | – | Make sure you send all contact objects full |
1564
+ | 340 | Price definition not found ({0}[{1}]-{2}{3}). |
1565
+ | 350 | Insufficient reseller balance. (Reseller Id : {0} - Current Balance : {1} {2}). |
1566
+ | 350 | Accounting currency does not match or the balance is not sufficient. |
1567
+ | 360 | Invalid API request for field ({0}). |
1568
+ | 360 | API quota exceeded! |
1569
+ | 361 | Throttled error! |
1570
+ | 362 | Premium domain is not available to register right now. |
1571
+ | 363 | Operation cancelled because domain in auto-renewal period |
1572
+ | 364 | This domain is currently unavailable for transaction due to a problem with the registry |
1573
+
1574
+ | CODE | DETAIL |
1575
+ |------|---------------------------------------------------------------------------------------------|
1576
+ | 400 | Invalid contact ({0}). |
1577
+ | 401 | Contact info can not sync. |
1578
+ | 402 | No access to contact information from registry. |
1579
+ | 403 | THE SYSTEM HAS MISSING INFORMATION. ENTER YOUR DEFAULT INFORMATION OR CONTACT SUPPORT TEAM. |
1580
+ | 404 | DOMAIN CONTACT CANNOT UPDATE. PERMISSION FROM THE REGISTRY. |
1581
+ | 410 | Contact not found. |
1582
+ | 410 | Contact not found ({0}). |
1583
+ | 420 | Invalid Api command for contact {0}. |
1584
+ | 430 | Contact api not found. |
1585
+ | 440 | Contact is not synced. |
1586
+ | 450 | Too many domain contacts! |
1587
+ | 451 | Failed to proceed with contact update. |
1588
+
1589
+ | CODE | DETAIL |
1590
+ |------|--------------------------------------------------------------------------------------------------------------------------------------|
1591
+ | 500 | Invalid domain id. |
1592
+ | 500 | Invalid domain id ({0}). |
1593
+ | 501 | Domain could not synchronized({0}) |
1594
+ | 502 | Internal transfer failed |
1595
+ | 503 | Domain registration is not available. |
1596
+ | 504 | Domain information does not match. Before :{0} |
1597
+ | 505 | Enter the Ip Address. |
1598
+ | 506 | Domain Transfer Has Been Started But Contact Info Not Read. |
1599
+ | 507 | Authorization error. |
1600
+ | 510 | Domain not found. |
1601
+ | 511 | Expired domains cannot be found. |
1602
+ | 512 | Domain is not renewable. |
1603
+ | 513 | Domain is not in updateable status. It must be active for to be updated |
1604
+ | 514 | Redemption Period Expected. |
1605
+ | 520 | Invalid Api command for domain "{0}". |
1606
+ | 530 | Invalid domain period. Period must be {0} to {1} years. Requested period is {2} years. |
1607
+ | 540 | Domain cannot be extended beyond {0} years from current date. |
1608
+ | 550 | Invalid domain name. Domain must be {0} to {1} characters length. Requested domain name is {2} characters. |
1609
+ | 560 | Invalid name server count. Domain must have {0} to {1} name servers. Requested name server count is {2}. |
1610
+ | 561 | No name server information found in the incoming request |
1611
+ | 570 | Idn not supported for tld "{0}". |
1612
+ | 571 | Period invalid. |
1613
+ | 572 | Command invalid. |
1614
+ | 573 | Domain names not found. |
1615
+ | 574 | TLD names not found. |
1616
+ | 575 | Domain is not in updateable status. It must be active for name servers to be updated |
1617
+ | 576 | Domain can be renewed in the last 1 month before the expire date |
1618
+ | 580 | Transfer not supported for tld "{0}". |
1619
+ | 581 | Child name server not found |
1620
+ | 582 | Transfer started by other reseller. |
1621
+ | 583 | Transfer not initialized. Please contact the support team. |
1622
+ | 584 | Object status prohibits operation |
1623
+ | 590 | Auth code is required for this transfer. |
1624
+ | 591 | Auth code is not valid. |
1625
+ | 592 | Transfer lock exists on domain. |
1626
+ | 593 | Domain cannot be transferred, Status Information and Transfer Lock must comply with the required criteria. (Status Information: #ok) |
1627
+ | 594 | Domain name server address could not resolved ({0}) |
1628
+ | 595 | Contact information can not be read (whois.registrar.tld) Please make sure that privacy protection status open |
1629
+ | 596 | Contact information could not verified |
1630
+ | 597 | Tld Not Found |
1631
+ | 598 | Unknown error occurred |
1632
+ | 599 | Domain Forward Not Found |
1633
+
1634
+
1635
+ ## License
1636
+
1637
+ Apache License 2.0 — see [LICENSE](LICENSE).