RPA Receipts · TF Fiscal API

Note

RPA — Self-Employed Payment Receipt

The RPA API lets you register individual (natural person) service providers, calculate and issue self-employed payment receipts, retrieve the PDF and generate the monthly closing report for accounting. RPA is not an electronic tax document: there is no transmission to the tax authority, no digital signature, no access key and no protocol — and therefore no homologation environment either. The issuing company is resolved from the token, never from the request body. Available only to companies that issue NF-e.

Endpoint	Method	Description
`/api/rpa/prestador/save`	POST	Create/update provider
`/api/rpa/prestador/get_list`	POST	List providers
`/api/rpa/preview`	POST	Calculate without issuing
`/api/rpa/create`	POST	Issue RPA
`/api/rpa/get_list`	POST	List RPA
`/api/rpa/get_detail`	POST	Get RPA detail
`/api/rpa/get_pdf`	POST	Get RPA PDF
`/api/rpa/estornar`	POST	Reverse RPA
`/api/rpa/report/monthly`	POST	Monthly closing

INSS and IRRF are assessed per period and per person, not per receipt: the INSS ceiling and the progressive IRRF bracket take into account everything already paid to the same CPF within the month. That is why the second payment of the month to the same provider may be withheld at a higher amount than the first. The INSS/IRRF table is maintained by the platform per calendar year — there is nothing to register. Until a new year's figures have been validated by an accountant, /preview keeps calculating while /create returns an error, instead of issuing a receipt with unverified withholding.

POST/api/rpa/prestador/save

Create/update provider

Creates or updates the individual provider record. The CPF identifies the provider within the company: two records with the same CPF are not allowed. The individual is not an issuer — no account and no certificate required.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
id	string	Record ID. Empty creates; filled updates
cpf *	string	Provider CPF (11 digits)
name *	string	Provider full name
nit	string	NIT/PIS/PASEP. Without it accounting cannot file in eSocial
qtdDependentes	int	Dependents for IRRF deduction (monthly deduction, not per receipt)
ativo	bool	Provider active

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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

List providers

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
page	int	Page (default 1)
pageSize	int	Items per page (default 20)
keyword	string	Search by name or CPF
somenteAtivos	bool	Return only active providers

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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

Calculate without issuing

Calculates the withholding without persisting anything: no receipt is created and no number is consumed. This is the recommended step before confirming a payment — in an RPA the provider receives less than the agreed amount, and issuing cannot be undone (a reversal does not return the number). Preview is never blocked: if a year's table has not been validated yet, it still calculates and flags this in avisos, while /create refuses.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
prestadorId *	string	Provider ID (returned by `/prestador/save`)
dataPagamento *	string	Date of payment (YYYY-MM-DD). Defines the period — cash basis
valorBruto *	decimal	Gross amount of the service
outrasDeducoes	decimal	Alimony and similar deductions
baseInssOutrosTomadores	decimal	INSS base already consumed by other payers in the period. It is a monthly total, taken from the provider's proof of withholding — the INSS ceiling belongs to the person, not to the payer
valorInssOutrosTomadores	decimal	INSS already withheld by other payers (informational)

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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

Issue RPA

Issues the receipt. The calculation is redone server-side at write time, under a (CPF, period) lock — the amount returned by preview is not accepted as input. Requires the year's table to be confirmed.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
prestadorId *	string	Provider ID (returned by `/prestador/save`)
dataPagamento *	string	Date of payment (YYYY-MM-DD). Defines the period — cash basis
valorBruto *	decimal	Gross amount of the service
descricaoServico *	string	Description of the service rendered
codigoServicoMunicipal	string	Municipal service code (optional)
outrasDeducoes	decimal	Alimony and similar deductions
baseInssOutrosTomadores	decimal	INSS base already consumed by other payers in the period. It is a monthly total, taken from the provider's proof of withholding — the INSS ceiling belongs to the person, not to the payer
serie	int	Receipt series. Defaults to 1 when omitted

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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

List RPA

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
page	int	Page (default 1)
pageSize	int	Items per page (default 20)
competencia	int	Period in YYYYMM format
cpf	string	Provider CPF (11 digits)
status	string	Filter: `emitido` or `estornado`

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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

Get RPA detail

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
id *	string	Receipt ID

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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

Get RPA PDF

Returns the receipt PDF URL. It is generated on the first call and reused afterwards. The PDF derives from stored data — including the frozen calculation memo — so regerar never changes any amount.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
id *	string	Receipt ID
regerar	bool	Force PDF rebuild instead of reusing

* Required field.

POST/api/rpa/estornar

Reverse RPA

Logical reversal — there is no cancellation, because the RPA is not transmitted anywhere. The receipt stays in the listing flagged as reversed, drops out of every closing total, and the number does not return to the sequence. Later receipts in the same period are not recalculated.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
id *	string	Receipt ID
motivo *	string	Reversal reason (minimum 5 characters)

* Required field.

POST/api/rpa/report/monthly

Monthly closing

Returns, per receipt, what eSocial requires (CPF, NIT, category, bases and amounts of each withholding), the period totals and the alerts that block filing: temEstorno and prestadoresSemNit. Reversed receipts appear in itens but are excluded from the totals.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
competencia *	int	Period in YYYYMM format

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the placeholders
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": []
          }
        }