RPA 自雇收据 · TF Fiscal API

说明

RPA — 自由职业者付款收据

RPA API 用于登记自然人服务提供方、计算并开具自由职业者付款收据、获取 PDF，以及生成提供给会计的月度结算数据。RPA 不是电子税务文件：不向税务局传输，没有数字签名、访问密钥和回执协议，因此也没有测试（homologação）环境。开具公司由 token 确定，而不是请求体。仅对已启用 NF-e 的公司开放。

接口	方法	说明
`/api/rpa/prestador/save`	POST	登记/更新服务提供方
`/api/rpa/prestador/get_list`	POST	服务提供方列表
`/api/rpa/preview`	POST	试算（不开具）
`/api/rpa/create`	POST	开具 RPA
`/api/rpa/get_list`	POST	RPA 列表
`/api/rpa/get_detail`	POST	RPA 详情
`/api/rpa/get_pdf`	POST	获取 RPA 的 PDF
`/api/rpa/estornar`	POST	冲销 RPA
`/api/rpa/report/monthly`	POST	月度结算

INSS 与 IRRF 按所属月份和个人计算，而不是按单张收据：INSS 上限与 IRRF 累进档位会计入当月已支付给同一 CPF 的全部金额。因此同月第二笔付款的代扣金额可能高于第一笔。INSS/IRRF 税率表由平台按年度维护，无需登记。在新年度的数值经会计验证之前，/preview 仍可计算，而 /create 会返回错误，不会以未经核验的代扣金额开具收据。

POST/api/rpa/prestador/save

登记/更新服务提供方

创建或更新自然人服务提供方档案。CPF 是该公司内的唯一标识，不允许存在两条相同 CPF 的记录。自然人不是开具方，无需账号和证书。

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
id	string	记录 ID。为空则新建，有值则更新
cpf *	string	服务提供方 CPF（11 位）
name *	string	服务提供方姓名
nit	string	NIT/PIS/PASEP。缺少该号码会计无法在 eSocial 申报
qtdDependentes	int	IRRF 抚养扣除人数（按月扣除，非按收据）
ativo	bool	是否启用

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/prestador/save" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "cpf": "12345678901",
          "nit": "12345678901",
          "name": "MARIA DA SILVA",
          "dataNascimento": "1990-05-12",
          "qtdDependentes": 0,
          "endereco": "Rua das Flores",
          "numero": "100",
          "bairro": "Centro",
          "city": "Sao Paulo",
          "uf": "SP",
          "cep": "01000000",
          "email": "maria@exemplo.com",
          "pix": "maria@exemplo.com",
          "ativo": true
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "id": "66c1f0a2e4b0a1c2d3e4f5a6",
            "cpf": "12345678901",
            "nit": "12345678901",
            "name": "MARIA DA SILVA",
            "qtdDependentes": 0,
            "ativo": true,
            "nitPendente": false
          }
        }

POST/api/rpa/prestador/get_list

服务提供方列表

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
page	int	页码（默认 1）
pageSize	int	每页条数（默认 20）
keyword	string	按姓名或 CPF 搜索
somenteAtivos	bool	仅返回启用的服务提供方

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/prestador/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "page": 1,
          "pageSize": 20,
          "keyword": "maria",
          "somenteAtivos": true
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "id": "66c1f0a2e4b0a1c2d3e4f5a6",
            "cpf": "12345678901",
            "nit": "12345678901",
            "name": "MARIA DA SILVA",
            "qtdDependentes": 0,
            "ativo": true,
            "nitPendente": false
          }
        }

POST/api/rpa/preview

试算（不开具）

仅计算代扣金额而不写入任何数据：不创建收据，也不占用编号。建议在确认付款前调用——在 RPA 中服务提供方实际收到的金额低于约定金额，且开具无法撤销（冲销不会退回号码）。preview 永远不会被拦截：若某年度的税率表尚未验证，它仍会计算并在 avisos 中提示，而 /create 会拒绝。

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
prestadorId *	string	服务提供方 ID（由 `/prestador/save` 返回）
dataPagamento *	string	支付日期（YYYY-MM-DD）。据此确定所属月份（收付实现制）
valorBruto *	decimal	服务总金额
outrasDeducoes	decimal	抚养费等其他扣除
baseInssOutrosTomadores	decimal	本月其他付款方已占用的 INSS 计税基数。按服务提供方提供的凭证填写的当月合计；INSS 上限属于个人而非付款方
valorInssOutrosTomadores	decimal	其他付款方已代扣的 INSS 金额（仅供参考）

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/preview" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "prestadorId": "66c1f0a2e4b0a1c2d3e4f5a6",
          "dataPagamento": "2026-08-20",
          "valorBruto": 3000.00,
          "outrasDeducoes": 0,
          "baseInssOutrosTomadores": 0,
          "valorInssOutrosTomadores": 0
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "competencia": 202608,
            "calculo": {
              "valorBruto": 3000.00,
              "baseInss": 3000.00,
              "aliquotaInssSegurado": 0.11,
              "valorInssSegurado": 330.00,
              "aliquotaInssPatronal": 0.20,
              "valorInssPatronal": 600.00,
              "baseIrrfAcumulada": 2392.80,
              "aliquotaIrrf": 0.00,
              "valorDescontoSimplificado": 607.20,
              "usouDescontoSimplificado": true,
              "irrfApuradoAcumulado": 0.00,
              "valorRedutorIrrf": 0.00,
              "valorIrrf": 0.00,
              "valorLiquido": 2670.00,
              "custoTotalEmpresa": 3600.00,
              "tabelaAno": 2026,
              "avisos": []
            },
            "acumulado": {
              "qtdRecibos": 0,
              "valorBruto": 0.00,
              "valorInssSegurado": 0.00,
              "valorIrrf": 0.00
            }
          }
        }

POST/api/rpa/create

开具 RPA

开具收据。保存时服务端会在 (CPF, 所属月份) 锁内重新计算，preview 返回的金额不会作为输入被采用。要求当年税率表已确认。

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
prestadorId *	string	服务提供方 ID（由 `/prestador/save` 返回）
dataPagamento *	string	支付日期（YYYY-MM-DD）。据此确定所属月份（收付实现制）
valorBruto *	decimal	服务总金额
descricaoServico *	string	所提供服务的描述
codigoServicoMunicipal	string	市级服务代码（可选）
outrasDeducoes	decimal	抚养费等其他扣除
baseInssOutrosTomadores	decimal	本月其他付款方已占用的 INSS 计税基数。按服务提供方提供的凭证填写的当月合计；INSS 上限属于个人而非付款方
serie	int	收据序列。省略时为 1

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "prestadorId": "66c1f0a2e4b0a1c2d3e4f5a6",
          "dataPagamento": "2026-08-20",
          "valorBruto": 3000.00,
          "descricaoServico": "Comissao de divulgacao - agosto/2026",
          "codigoServicoMunicipal": "",
          "outrasDeducoes": 0,
          "baseInssOutrosTomadores": 0,
          "serie": 1
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "id": "66c1f4b7e4b0a1c2d3e4f5b1",
            "serie": 1,
            "numero": 27,
            "cpf": "12345678901",
            "nomePrestador": "MARIA DA SILVA",
            "nit": "12345678901",
            "dataPagamento": "2026-08-20",
            "competencia": 202608,
            "descricaoServico": "Comissao de divulgacao - agosto/2026",
            "valorBruto": 3000.00,
            "valorInssSegurado": 330.00,
            "valorInssPatronal": 600.00,
            "valorIrrf": 0.00,
            "valorLiquido": 2670.00,
            "custoTotalEmpresa": 3600.00,
            "status": "emitido",
            "tabelaAno": 2026,
            "pdfUrl": "",
            "avisos": []
          }
        }

POST/api/rpa/get_list

RPA 列表

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
page	int	页码（默认 1）
pageSize	int	每页条数（默认 20）
competencia	int	所属月份（YYYYMM 格式）
cpf	string	服务提供方 CPF（11 位）
status	string	筛选：`emitido` 或 `estornado`

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "page": 1,
          "pageSize": 20,
          "competencia": 202608,
          "cpf": "",
          "status": "emitido"
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "items": [
              {
                "id": "66c1f4b7e4b0a1c2d3e4f5b1",
                "serie": 1,
                "numero": 27,
                "cpf": "12345678901",
                "nomePrestador": "MARIA DA SILVA",
                "dataPagamento": "2026-08-20",
                "competencia": 202608,
                "valorBruto": 3000.00,
                "valorInssSegurado": 330.00,
                "valorIrrf": 0.00,
                "valorLiquido": 2670.00,
                "status": "emitido"
              }
            ],
            "total": 1
          }
        }

POST/api/rpa/get_detail

RPA 详情

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
id *	string	收据 ID

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/get_detail" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "id": "66c1f4b7e4b0a1c2d3e4f5b1"
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "id": "66c1f4b7e4b0a1c2d3e4f5b1",
            "serie": 1,
            "numero": 27,
            "cpf": "12345678901",
            "nomePrestador": "MARIA DA SILVA",
            "nit": "12345678901",
            "dataPagamento": "2026-08-20",
            "competencia": 202608,
            "descricaoServico": "Comissao de divulgacao - agosto/2026",
            "valorBruto": 3000.00,
            "valorInssSegurado": 330.00,
            "valorInssPatronal": 600.00,
            "valorIrrf": 0.00,
            "valorLiquido": 2670.00,
            "custoTotalEmpresa": 3600.00,
            "status": "emitido",
            "tabelaAno": 2026,
            "pdfUrl": "",
            "avisos": []
          }
        }

POST/api/rpa/get_pdf

获取 RPA 的 PDF

返回收据 PDF 的 URL。首次调用时生成，之后复用。PDF 由已保存的数据（含已固化的计算过程）生成，因此 regerar 不会改变任何金额。

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
id *	string	收据 ID
regerar	bool	强制重新生成 PDF

* 必填字段。

POST/api/rpa/estornar

冲销 RPA

逻辑冲销——不存在"取消"，因为 RPA 不向任何机构传输。收据仍保留在列表中并标记为已冲销，从结算合计中剔除，且号码不会退回采番。同一所属月份的后续收据不会重算。

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
id *	string	收据 ID
motivo *	string	冲销原因（至少 5 个字符）

* 必填字段。

POST/api/rpa/report/monthly

月度结算

按收据返回 eSocial 所需信息（CPF、NIT、类别、各项代扣的计税基数与金额）、当月合计，以及会阻碍申报的提示：temEstorno 与 prestadoresSemNit。已冲销的收据出现在 itens 中，但不计入合计。

必需请求头

请求头	类型	说明
token	string	开具公司的 token
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
competencia *	int	所属月份（YYYYMM 格式）

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/rpa/report/monthly" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "competencia": 202608
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "competencia": 202608,
            "itens": [
              {
                "id": "66c1f4b7e4b0a1c2d3e4f5b1",
                "serie": 1,
                "numero": 27,
                "cpf": "12345678901",
                "nit": "12345678901",
                "nome": "MARIA DA SILVA",
                "categoria": "Contribuinte individual",
                "dataPagamento": "2026-08-20",
                "valorBruto": 3000.00,
                "baseInss": 3000.00,
                "valorInssSegurado": 330.00,
                "valorInssPatronal": 600.00,
                "valorIrrf": 0.00,
                "valorLiquido": 2670.00,
                "status": "emitido"
              }
            ],
            "totais": {
              "qtdRecibos": 1,
              "qtdPrestadores": 1,
              "valorBruto": 3000.00,
              "valorInssSegurado": 330.00,
              "valorInssPatronal": 600.00,
              "valorIrrf": 0.00,
              "valorLiquido": 2670.00
            },
            "temEstorno": false,
            "prestadoresSemNit": []
          }
        }