开票主体
关联数字证书
上传主体的 A1 数字证书（.pfx / .p12）与密码；支持 JSON + Base64 或 multipart。
POST
/openapi/v1/empresas/{empresaId}/certificadoDigital需要
token、timestamp、sign 三个签名头，参见认证与签名。同一路径支持两种请求形态，按 Content-Type 分流：只持有证书字节时用 JSON + Base64（本页主形态）；持有证书文件时用 multipart（见下方小节）。两种形态的校验与结果完全一致。上传成功即替换该主体旧证书。
请求头
Content-Type* | string | 请求体类型 |
* 必填字段
路径参数
empresaId* | string | 开票主体标识 |
* 必填字段
请求体
senha* | string | 证书密码 |
arquivoBase64* | string | 证书文件 Base64 |
* 必填字段
200
证书校验通过并已关联；无响应体。该主体旧证书被替换。
无响应体
JSON 形态 body 参与签名：原文去除 CR/LF，与其他 JSON 接口一致。建议生成不带换行的标准 Base64。
bash
APP_SECRET="sk_live_9f8e7d6c5b4a"P="/openapi/v1/empresas/1934811222334455/certificadoDigital"TS=$(date +%s)BODY=$(printf '{"senha":"certpass123","arquivoBase64":"%s"}' "$(base64 -w0 uploaded-cert.pfx)")SIGN=$(printf '%s' "${APP_SECRET}${P}${BODY}${TS}" | md5sum | cut -d' ' -f1)curl -X POST "https://api.v2.tffiscal.com${P}" \-H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" \-H "Content-Type: application/json" --data-binary "${BODY}"
以 Content-Type: multipart/form-data 发送下面两个表单字段。签名时 body 按空字符串：sign = MD5(token + path + timestamp)。
bash
APP_SECRET="sk_live_9f8e7d6c5b4a"P="/openapi/v1/empresas/1934811222334455/certificadoDigital"TS=$(date +%s)SIGN=$(printf '%s' "${APP_SECRET}${P}${TS}" | md5sum | cut -d' ' -f1)curl -X POST "https://api.v2.tffiscal.com${P}" \-H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" \-F "senha=certpass123" -F "arquivo=@uploaded-cert.pfx"
表单字段
senha* | text | 证书密码 |
arquivo* | file | 证书文件 |
* 必填字段
成功 HTTP 200 无响应体。任何接口都不会回传证书内容与密码。
除证书之外还需运营审批通过，主体才可开票；生命周期见开票主体。
Content-Type请求形态
| 取值 | 含义 |
|---|---|
| application/json | JSON + Base64：请求体传 senha 与 arquivoBase64；body 参与签名 |
| multipart/form-data | multipart：表单字段 senha 与 arquivo；签名时 body 按空串 |
| 错误码 | HTTP | |
|---|---|---|
| 10003000 | 404 | empresaId 不存在或非本应用名下。 |
| 10003035 | 400 | Base64 非法或解码后超过 1MB。仅 JSON 形态。 |
| 10003008 | 400 | 证书密码不符。核对密码。 |
| 10003010 | 400 | 证书 CNPJ 与主体不一致。换正确证书。 |
| 10003011 | 400 | 证书已过期。换有效证书。 |
| 10003012 | 400 | 证书与当前生效证书重复。 |