TF Fiscal
开发文档

开票主体

关联数字证书

上传主体的 A1 数字证书（.pfx / .p12）与密码；支持 JSON + Base64 或 multipart。

POST/openapi/v1/empresas/{empresaId}/certificadoDigital

需要 token、timestamp、sign 三个签名头，参见认证与签名。

同一路径支持两种请求形态，按 Content-Type 分流：只持有证书字节（如从自己的存储读出）时用 JSON + Base64（本页主形态），免去拼装 multipart 与签名困扰；持有证书文件时用 multipart（见下方小节）。两种形态的校验与结果完全一致。上传成功即替换该主体旧证书。

参数

请求头

  • Content-Typestring必填

    JSON + Base64 形态为 application/json；multipart 形态为 multipart/form-data。

路径参数

请求体

  • senhastring必填

    证书密码。

    示例: certpass123
  • arquivoBase64string必填

    .pfx / .p12 文件内容的 Base64；允许换行与 data:...;base64, 前缀，解码后不超过 1MB。非法 Base64 或超限返回 10003035。

    示例: MIIKXQIBAzCCCicGCSqGSIb3DQEHAaCCChgEggoU...

响应

200

证书校验通过并已关联；无响应体。该主体旧证书被替换。

无响应体

错误

错误码HTTP
10003000404

empresaId 不存在或非本应用名下。

10003035400

Base64 非法或解码后超过 1MB（仅 JSON 形态）。

CER0005400

证书密码不符。核对密码。

10003010400

证书 CNPJ 与主体不一致。换正确证书。

10003011400

证书已过期。换有效证书。

10003012400

证书与当前生效证书重复。

JSON 形态的签名

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}"

替代形态：multipart 文件上传

以 Content-Type: multipart/form-data 发送下列表单字段。

表单字段类型必填说明
senhatext是证书密码
arquivofile是A1 数字证书文件（.pfx / .p12），不超过 1MB

签名注意：multipart 请求 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"

校验与结果（两种形态相同）

平台校验：Base64 合法性（仅 JSON 形态，10003035）、密码是否匹配（不匹配 CER0005）、证书是否过期（10003011）、证书 CNPJ 与主体是否一致（10003010）、是否与当前生效证书重复（10003012）。成功 HTTP 200 无响应体。上传成功即替换该主体旧证书。证书内容在平台侧加密存储，任何接口都不会回传证书内容与密码。

除证书之外还需运营审批通过，主体才可开票；生命周期见开票主体。

上一页注册开票主体下一页NF-e