简介

本文档是调用ipipv，开通代理的说明。

开通代理先向我方获取appKey 和 appSecret,在沙盒环境下调试。

沙盒环境地址: https://sandbox.ipipv.com/

沙盒调试成功后，可以切换至生产环境。

注意：生产环境测试会正式开通代理，产生费用。

生产环境地址: https://api.ipipv.com/

sdk

golang

https://github.com/clpublic/ipv-sdk

java（部分完成）

https://github.com/clpublic/ipv-java-sdk

php

https://github.com/clpublic/ipv-php-sdk.git

版本更新

全新对接，直接跳过当前，往后看，如果已经对接，看一下最新更新的内容

通用

请求统一加密传输

请求参数

返回数据

加密方式

接口通过aes 加密 cbc 模式 请求时序图如下

备注：

• 请求加密串最终存在params，返回数据加密串存在data参数
• 如果返回数据只有状态码，没有data数据，就不需要做加密返回。

数据加密

• 消息内容为： TestMessage （前后无空格）
• 密钥为： qwertyuiop123456 （前后无空格）
• 通过aes_cbc模式，并Base64后： 5cfJMwX0w65sEQVBxu9zHw==
• 初始向量参数为密钥前16位

请求json示例

{
    "version":"2.0",
    "reqId":"xxxxxx",
    "encrypt":"aes",
    "appKey":"testappid",
    "params":"5cfJMwX0w65sEQVBxu9zHw=="
}

返回json示例

{
    "reqId":"xxxxxx",
    "code":200,
    "msg":"ok",
    "data":"5cfJMwX0w65sEQVBxu9zHw=="
}

go aes cbc加解密函数

package cryptos

import (
	"bytes"
	"crypto/aes"
	"crypto/cipher"
)

// =================== CBC ======================

// key的长度必须为16, 24或者32
func AesEncryptCBC(origData []byte, key []byte) (encrypted []byte, err error) {
	// 分组秘钥

	block, _err := aes.NewCipher(key)
	if _err != nil {
		err = _err
		return
	}
	blockSize := block.BlockSize()                              // 获取秘钥块的长度
	origData = pkcs5Padding(origData, blockSize)                // 补全码
	blockMode := cipher.NewCBCEncrypter(block, key[:blockSize]) // 加密模式
	encrypted = make([]byte, len(origData))                     // 创建数组
	blockMode.CryptBlocks(encrypted, origData)                  // 加密
	return encrypted, nil
}

// key的长度必须为16, 24或者32
func AesDecryptCBC(encrypted []byte, key []byte) (decrypted []byte, err error) {
	block, _err := aes.NewCipher(key) // 分组秘钥
	if _err != nil {
		err = _err
		return
	}
	blockSize := block.BlockSize()                              // 获取秘钥块的长度
	blockMode := cipher.NewCBCDecrypter(block, key[:blockSize]) // 加密模式
	decrypted = make([]byte, len(encrypted))                    // 创建数组
	blockMode.CryptBlocks(decrypted, encrypted)                 // 解密
	decrypted = pkcs5UnPadding(decrypted)                       // 去除补全码
	return decrypted, nil
}
func pkcs5Padding(ciphertext []byte, blockSize int) []byte {
	padding := blockSize - len(ciphertext)%blockSize
	padtext := bytes.Repeat([]byte{byte(padding)}, padding)
	return append(ciphertext, padtext...)
}
func pkcs5UnPadding(origData []byte) []byte {
	length := len(origData)
	unpadding := int(origData[length-1])
	return origData[:(length - unpadding)]
}

java aes cbc加解密函数

package com.ipipv.open.utils;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class AESCBC {
    public static byte[] encryptCBC(byte[] data, byte[] key, byte[] iv) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException, InvalidAlgorithmParameterException {
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(key, "AES"), new IvParameterSpec(iv));
        byte[] result = cipher.doFinal(data);
        return result;
    }

    public static byte[] decryptCBC(byte[] data, byte[] key, byte[] iv) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException, InvalidAlgorithmParameterException {
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(key, "AES"), new IvParameterSpec(iv));
        byte[] result = cipher.doFinal(data);
        return result;
    }

    public static void main(String[] args) throws IllegalBlockSizeException, InvalidKeyException, BadPaddingException, NoSuchAlgorithmException, NoSuchPaddingException, InvalidAlgorithmParameterException {
        String data = "TestMessage"; // 待加密的原文
        String key = "qwertyuiop123456asdfghjk"; // key 长度只能是 16、24 或 32 字节
        String iv = key.substring(0,16); // CBC 模式需要用到初始向量参数

        byte[] ciphertext = encryptCBC(data.getBytes(), key.getBytes(), iv.getBytes());
        System.out.println("CBC 模式加密结果（Base64）：" + Base64.getEncoder().encodeToString(ciphertext));

        byte[] plaintext = decryptCBC(ciphertext, key.getBytes(), iv.getBytes());
        System.out.println("解密结果：" + new String(plaintext));
    }
}

同步地域

请求路径

/api/open/app/area/v2

请求参数

返回参数

同步地域

请求路径

/api/open/app/city/list/v2

请求参数

返回参数

获取产品库存

请求路径

/api/open/app/product/query/v2

请求参数

当主接口中的method为GetOrder时，该参数是主接口中的params参数

eg

{
    "proxyType":[103],
    "productNo":"productNo"
}

返回数据

开通代理

请求路径

/api/open/app/instance/open/v2

请求参数

主接口中的params参数

eg

{
    "appOrderNo":"TEST20240726094927",
    "params":[
        {
            "productNo":"ipideash_598",
            "count":20,
            "cycleTimes":1
        },
        {
            "productNo":"mb_gmhd5exp2",
            "count":20,
            "cycleTimes":12
        }
    ]
}

备注：

• 流量产品count 不起作用
• 流量产品只对flow起作用

返回数据

备注：订单为异步开通，具体查看回调章节

获取订单信息

请求路径

/api/open/app/order/v2

请求参数

返回参数

获取实例

获取实例的

请求路径

/api/open/app/instance/v2

请求参数

返回数据

续费代理

请求路径

/api/open/app/instance/renew/v2

请求参数

当主接口中的method为RewProxy时，该参数是主接口中的params参数

返回数据

备注：订单为异步开通，具体查看回调章节

释放代理

请求路径

/api/open/app/instance/release/v2

请求参数

当主接口中的method为DelProxy时，该参数是主接口中的params参数

返回数据

备注：订单为异步开通，具体查看回调章节

获取App信息

请求路径

/api/open/app/info/v2

请求参数

无

返回数据

指定ip开通代理

请求路径

/api/open/app/instance/open/assign/ip/v2

请求参数

主接口中的params参数

eg

{
    "appOrderNo":"TEST20240726094927",
    "productNo":"ipideash_598",
    "assignIp":"127.0.0.1",
    "cycleTimes":1
}

返回数据

备注：订单为异步开通，具体查看回调章节

查询指定Ip可用信息

请求路径

/api/open/app/assign/ip/info/v2

请求参数

主接口中的params参数

eg

{
    "ip":"127.0.0.1"
}

返回数据

动态

创建或修改主账户

该用户为动态用户的主账户，所有的流量分配都在主账户下，该用户下子账户可以使用主账户的流量。

请求路径

/api/open/app/user/v2

请求参数

返回参数

同步实名

请求路径

/api/open/app/userAuth/v2

请求参数

返回参数

动态产品区域列表

请求路径

/api/open/app/product/area/v2

请求参数

返回参数

[
    {"productNo":"out_dynamic_1","proxyType":104,"areaCode":"6","countryCode":"USA","stateCode":"","cityCode":"","status":1,"region":"us","supplierCode":"xxx"},
    {"productNo":"out_dynamic_1","proxyType":104,"areaCode":"2","countryCode":"FRA","stateCode":"","cityCode":"","status":1,"region":"fr","supplierCode":"xxx"},
    {"productNo":"out_dynamic_1","proxyType":104,"areaCode":"2","countryCode":"GBR","stateCode":"","cityCode":"","status":1,"region":"gb","supplierCode":"xxx"},
    {"productNo":"out_dynamic_1","proxyType":104,"areaCode":"1","countryCode":"JPN","stateCode":"","cityCode":"","status":1,"region":"jp","supplierCode":"xxx"}
]

获取代理余额信息

通过接口获取代理商户

请求路径

/api/open/app/proxy/info/v2

请求参数

返回参数

创建或修改代理用户（子账号）

请求路径

/api/open/app/proxy/user/v2

请求参数

返回数据

账密提取

请求路径

/api/open/app/proxy/draw/pwd/v2

请求参数

返回参数

Api提取代理请求

请求路径

/api/open/app/proxy/draw/api/v2

请求参数

返回数据

流量使用记录

请求路径

/api/open/app/proxy/flow/use/log/v2

请求参数

返回参数

添加ip白名单

请求路径

/api/open/app/proxy/addIpWhiteList/v2

请求参数

返回参数

删除ip白名单

请求路径

/api/open/app/proxy/delIpWhiteList/v2

请求参数

返回参数

动态代理流量回收

请求路径

/api/open/app/proxy/return/v2

请求参数

返回参数

回调

IPV系统存在三种回调：订单回调，实列回调，产品回调。 回调地址由客户提供，我们统一在后台配置。

假设用户设置的回调地址为 https://api.callback.com/ipv/callback

产生回调方式为,我方发起get请求

https://api.callback.com/ipv/callback?type={callbackType}&no={callbackNo}&op={opType}

用户收到回调处理后，要返回回调结果，否则会多次进行回调，因为网络波动等原因，用户对同一回调，做好幂等性操作。

回调结果定义

{
    "code":"",
    "msg":""
}

成功 code返回值 success 多次回调上一次已经成功，第二次还是返回success

订单回调

IPV系统的订单(开通，续费，释放)都是异步的，即用户下单 -> ipv返回订单 同时开通代理 -> 代理开通完成回调客户回调地址 ->客户通过回调订单返回信息并拉去订单信息

eg

https://api.callback.com/ipv/callback?type=order&no=C20240429162339417081&op=1

实例回调

当实例产生变化（比如网络不通，停机等）的时候，我方会主动回调

eg

https://api.callback.com/ipv/callback?type=instance&no=c_gz3h2igp6dz9cq3&op=

产品回调

当产品进行变动的时候，我方也会主动回调

eg

https://api.callback.com/ipv/callback?type=product&no=mb_gmfcq7blc&op=

数据字典

代理类型

代理协议

时长单位

ispType

返回状态码