.pl API. Technical datasheet v Jacek Partyka, MSERWIS

Transcription

1 .pl API Technical datasheet v Jacek Partyka, MSERWIS 1

2 Contents Introduction...3 Command catalogue: check_domain check_multiple domain_book domain_transfer domain_info host_create host_info host_update contact_create contact_update contact_info domain_create domain_adddns domain_remdns domain_setcontact domain_renew account_balance account_last domain_getauthinfo domain_taste future_check future_info future_create...13 Example in PHP with curl:...14 Result codes:...15 Registry system parameters...18 API usage rules

3 Introduction Requirements for valid connection: 1. SSL protocol connection 2. Authorized IP 3. Correct information authorizing Partner (login/pwd) Test server: Live server: After signing up for the API, Partner is given access to test server with virtual amount of 5000 PLN. Operations are made on NASK test server, which consist small fragment of data of live server. To gain access to live server you have to execute each command correctly at least three times (except domain_transfer). Suggested scenario of tests: creation of two hosts in non-existent domain (e.g. ns1.domain.pl, ns2.domain.pl) creation of two contacts and collecting their id's execution of other commands After correct tests Partner will gain access to the live server. Operations made by Partner will be seen in administrative panel at Domeny.tv 3

4 Command catalogue: 1. check_domain Command checks if domain is available. command command, value = check_domain 2. check_multiple Command checks max. 10 domains command command, value = check_multiple s divided by semicolon (;) (each domain in separate line) 3. domain_book Command books domain for 14 days. command command, value = domain_book [dns1 first nameserver] [dns2 second nameserver] [dns3 third nameserver] [dns4 fourth nameserver] [dns5 fifth nameserver] Nameservers are optional. If you do not specify at least two nameservers the system will assign default ones. [;reservation_start_date;reservation_end_date] 4

5 4. domain_transfer Command transfers domain from other registrar. command command, value = domain_transfer param authinfo code [resend sends authorization once again, value=1 (option)] Authorization of domain transfer is accomplished after clicking on a link sent by NASK in , after transfer is initiated. Domain is added to Partner's account in one hour. 5. domain_info Shows information about domain. command command, value = domain_info [authinfo authinfo code (option)] Answer: domain_name;result [ crdate: <creation date> exdate: <expiry date> Status: <status> DNS[n]: <n-th dns> Registrant: <registrant id> Technical: <technical id> ] Command shows full data for domains registered by other registrants only in case of providing a valid authinfo code. 5

6 6. host_create Creates a host to system registry command command, value = host_create hostname host name hostip host IP Answer: host_name;result 7. host_info Shows information about host command command, value = host_info hostname host name Answer: host_name;result [ IP: <ip> [...] Status: <status> ] 8. host_update Upodates host information command command, value = host_update hostname host name hostip host IP Answer: host_name;result 6

7 9. contact_create Creates a contact and returns its ID Attention! All data must be provided in UTF-8 encoding. command command, value = contact_create address phone phone number in format: +country_code.phone_number, e.g name name or company name street street city city zip zip code district district country country (two-letter code, e.g.: pl) ctype company (0) or individual (1) cpubl publication agreement (1 = yes, 0 = no1) [org organisation name (optionally)] [fax fax number in format: +country_code.phone_number, e.g ] Answer: result[;contact_id] Attention! In case of choosing ctype=0 (company contact registration) ctype parameter must be set to contact_update Updates contact information Attention! All data must be provided in UTF-8 encoding. command command, value = contact_update address phone phone number in format: +country_code.phone_number, e.g name name or company name street street city city zip zip code district district country country (two-letter code, e.g.: pl) old_contact_id contact ID cpubl publication agreement (1 = yes, 0 = no1) [org organisation name (optionally)] [fax fax number in format: +country_code.phone_number, e.g ] 7

8 Answer: result 11. contact_info Shows information about contact command command, value = contact_info cid contact ID Answer: cid;result [ Consent: <publication agreement (true/false)> Individual: <true = individual, false = company> Name: <Name or company name> Org: <Organisation name> Street: <address> Street2: <address2> Street3: <address3> City: <city> District:<district> ZIP: <zip code> Country: <country> ] 12. domain_create Creates a domain command command, value = domain_create cid contact ID period number of years the domain is created {1-10} [dns1 first nameserver] [dns2 second nameserver] [dns3 third nameserver] [dns4 fourth nameserver] [dns5 fifth nameserver] Nameservers are optional. If you do not specify at least two nameservers the system will assign default ones. 8

9 13. domain_adddns Adds a dns to domain command command, value = domain_addns dns host name 14. domain_remdns Removes a DNS from domain Attention! Domain must have at least 2 DNS. command command, value = domain_remdns dns host name 15. domain_setcontact Command changes contact for domain Before you use this function be sure to have transfer form filled in. You can download them from: We reserve the right to ask you to present such form after each time this command is called. command command, value = domain_setcontact cid contact ID 9

10 16. domain_renew Command renews a domain command command, value = domain_renew period number of years {1-9} Attention! Renewal is only possible in x days before domain expiration. (Look at registry system parameters) 17. account_balance Command shows current account balance command command, value = account_balance Answer: account_balance; 18. account_last Command shows last 5 operations, which had influence on Partner's account (domain creation, renewal) command command, value = account_last Answer: operation_type;[domain_name/.];operation_value;amount 10

11 19. domain_getauthinfo command command, value = domain_getauthinfo Answer: domain_name;authinfo_code or domain_name;result This command has daily limit of executions which is set individually. 20. domain_taste Command registers domain for 14 days command command, value = domain_taste cid contact ID [dns1 first nameserver] [dns2 second nameserver] [dns3 third nameserver] [dns4 fourth nameserver] [dns5 fifth nameserver] Nameservers are optional. If you do not specify at least two nameservers the system will assign default ones. [;taste_start_date;taste_end_date] 21. future_check Checks if future exists command command, value = future_check 11

12 22. future_info Displays future info command command, value = future_check [ //if result == 4002 crdate: <date> exdate: <date> Registrant: <registrant's cid> ] 23. future_create Creates a future command command, value = future_check cid registrant's CID 12

13 Example in PHP with curl: function sendcommand($command){ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " curl_setopt($ch, CURLOPT_PORT, 443); curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5); curl_setopt($ch, CURLOPT_TIMEOUT, 15); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $command); $result=curl_exec($ch); curl_close($ch); return $result; } $command = array('login' => 'login', 'pwd' => 'pwd', 'command' => 'check_domain', 'domain' => 'domena.pl' ); $resp = sendcommand($command); var_dump($resp); 13

14 Result codes: 0 NASK server connection error 0001 Wrong domain format 0002 Domain available for registration 0003 No table with domains given 0004 Domain book error or domain unavailable 0005 Domain expired 0006 Domain registered, database error 0007 Wrong DNS server 0008 Wrong IP address 0009 Wrong host name 0010 Host name incorrect or host unavailable 0011 Host does not exist in NASK database 0012 No information in NASK registry 0013 Wrong Wrong phone number 0015 Wrong fax number 0016 Some data missing 0017 Wrong contact ID 0018 Contact does not exist in NASK database 0019 Host is not configured to handle this domain 0020 Improper renewal period 0021 Wrong period 0022 Wrong characters in given data 0023 You have no privileges to execute this command 0024 Domain does not exist in NASK database 0025 Too many command execution during this day 0026 Paid operations are not allowed 1000 Operation completed successfully 4000 No funds for this operation 4001 Future does not exist 4002 Future exists 4005 Futures not allowed in this zone 4006 Destination client of the transfer operation is contact sponsoring client 4007 Future authorization information missing 4008 Invalid future authorization information 4009 Domain name is banned 4010 Domain name is temporarily banned 4011 Registration of regional domain name is forbidden Domain is a zone 5050 Too many commands 7001 Wrong host name 7003 The same IP address entered twice 7004 Wrong IP address 7005 Host already exists 7006 Host does not exist 7007 Host is unresolvable 7008 Application of IP addresses is forbidden for this host 7009 Application of IP addresses is required for this host 8005 No address data for this contact given 8006 No different data for this contact given 8030 Companies must agree to publicate their data 9002 Invalid domain authorization information 9003 Period element is missing 9004 Period value is not multiplicity of one year 9005 Period value is not admissible 9007 Duplicate names of name server 9008 Host does not exist 9009 Host creation pending but it is not subordinate 9010 Host is not configured for domain 9011 Contact does not exist 14

15 9012 Too few name servers 9013 Too many name servers 9014 Domain name syntax error 9015 Domain name registration is forbidden 9016 Domain name is a zone name 9017 Zone is not managed by the system 9018 New registrant ID is current registrant ID 9019 Registration in this zone is forbidden 9020 Another domain renew in the same period 9021 Too few administrative contacts 9022 Too many administrative contacts 9023 Too few billing contacts 9024 Too many billing contacts 9025 Too few technical contacts 9026 Too many technical contacts 9027 Registrant id does not exist 9028 Domain name already exists 9029 Domain name is reserved by another client 9030 Period has been already set during domain reservation and cannot be set again 9031 Name servers have been already set during domain reservation and cannot be set again 9032 Registrant has been already set during domain reservation and cannot be set again 9033 Registrant element missing 9034 Contacts have been already set during domain reservation and cannot be set again 9035 Reason has been already set during domain reservation and cannot be set again 9036 Reason element missing 9037 Domain has subordinate hosts (so cannot be deleted) 9038 Destination client of the transfer operation is domain sponsoring client 9039 There is nothing to update 9040 Unsupported transfer option 9041 Domain is reserved 9042 Domain exists and is not reserved 9043 Domain has status clienttransferprohibited 9044 Domain has status servertransferprohibited 9045 Domain has status clientdeleteprohibited 9046 Domain has status serverdeleteprohibited 9047 Domain has status clientrenewprohibited 9048 Domain has status serverrenewprohibited 9049 Domain has status clientupdateprohibited 9050 Domain has status serverupdateprohibited 9051 Contact to addaddremaddrem is already associated with domain 9052 Contact to remove is not associated with domain 9053 Status to addaddremaddrem has not "client" prefix 9054 Status to remove has not "client" prefix 9055 Status to addaddremaddrem is already associated with domain 9056 Status to remove is not associated with domain 9057 Name server to addaddremaddrem is already associated with domain 9058 Name server to remove is not associated with domain 9059 DNS validator error 9060 Domain does not exist 9061 Duplicate contacts 9062 Domain:addAddRemAddRem element is empty 9063 Domain:remAddRemAddRem element is empty 9064 Domain:chgChg element is empty 9065 Domain registration is temporarily forbidden 9066 Regional domain registration is forbidden 9067 Reason text is too long 9068 Domain expired 9069 Setting domain status clienttransferprohibited is forbidden 9070 Confusable domain name exists 9071 Domain exists in state STATE_BLOCKED 9072 Domain exists in state STATE_BOOK_BLOCKED 9073 Domain exists in state STATE_DELETE_BLOCKED 9074 Domain exists in state STATE_EXPIRED 9075 Domain exists in state STATE_NULL 9076 Domain exists in state STATE_REGISTERED 9077 Domain exists in state STATE_RESERVED 15

16 9078 IDN domain reservation and registration is not allowed 9079 IDN domain reservation and registration is not allowed in this zone 9080 IDN validator initialization failed 9081 Name server to addaddremaddrem is subordinate for domain but has no IP addresses 9082 Renew is to early 9083 Invalid length of authinfo element 9084 Too many domain names 9085 Transfer is to early 9086 Lack of permissions to view status of domain transfer request 9087 Transfer period is not allowed 9088 Domain transfer pending 9089 Lack of permissions to cancel domain transfer request 9090 Domain transfer not pending 9091 Domain transfer confirmation link sending failed 9096 Domain name registration is forbidden due to the case in court of arbitration 9097 Domain transfer is not pending 9098 Request to resend confirmation link is not allowed for this command 9099 Domain exists in state STATE_TASTED 9100 Domain exists in state STATE_TESTED_BLOCKED 9101 Taste domain period is not allowed 9102 Taste domain book is not allowed 9103 This update is not allowed for taste domain 9104 Domain name is tasted by another client 9105 Registrant has been set already 9106 Contacts have been set already 9107 Book and Taste not allowed together 9999 Domain unavailable for registration (other reason) 16

17 Registry system parameters Parameter Test server Live server Minimal number of DNS' for domain 2 2 Maximal number of DNS' for domain 9 9 Maximal number of days until domain expiration, when renewal is possible Minimal number of days from last transfer (or creation) to next (first) transfer. Number of days before domain expiration, when transfer is not possible Time for transfer confirmation in days

18 API usage rules 1. The API is not intented for massive and repetetive calling of commands with same parameters. 2. All operations will be billed according to current pricelist assigned to Partner s account. 3. Partner is not allowed to call new command before current one has finished and sent response. Flooding the application may lead to banning of Partner's account. 4. Partner is solely liable for all operations performed using this API. 5. Partner is committed to all terms and conditions of usage of Domeny.tv's services and NASK Domain Name Regulations. 6. Partner acknowledges the fact that the API may be suspended temporarily without notice for technical maintenance or any other reason. 7. There is a limit of 1000 command per day. The limit may be changed at Domeny.tv s discretion. 8. Book, taste and register commands are executed with random delay, not exceeding few seconds. 9. Any API credential must be kept strictly confidential. 18