RPA · TF Fiscal API

Nota

RPA — Recibo de Pagamento a Autônomo

A API de RPA permite cadastrar prestadores pessoa física, calcular e emitir recibos de pagamento a autônomo, obter o PDF e gerar o fechamento mensal para a contabilidade. O RPA não é documento fiscal eletrônico: não há transmissão ao Fisco, assinatura digital, chave de acesso nem protocolo — e, por isso, também não existe ambiente de homologação. A empresa emitente é resolvida pelo token, nunca pelo corpo da requisição. Disponível apenas para empresas emitentes de NF-e.

Endpoint	Método	Descrição
`/api/rpa/prestador/save`	POST	Cadastrar/atualizar prestador
`/api/rpa/prestador/get_list`	POST	Listar prestadores
`/api/rpa/preview`	POST	Calcular sem emitir
`/api/rpa/create`	POST	Emitir RPA
`/api/rpa/get_list`	POST	Listar RPA
`/api/rpa/get_detail`	POST	Detalhar RPA
`/api/rpa/get_pdf`	POST	Obter PDF do RPA
`/api/rpa/estornar`	POST	Estornar RPA
`/api/rpa/report/monthly`	POST	Fechamento mensal

INSS e IRRF são apurados por competência e por pessoa, não por recibo: o teto do INSS e a faixa progressiva do IRRF consideram tudo o que já foi pago ao mesmo CPF no mês. Por isso o segundo pagamento do mês ao mesmo prestador pode ter retenção maior que o primeiro. A tabela de INSS/IRRF é mantida pela plataforma por ano-calendário — não há nada a cadastrar. Enquanto os valores de um novo ano não tiverem sido validados por profissional contábil, o /preview continua calculando e o /create responde com erro, em vez de gerar recibo com retenção não conferida.

POST/api/rpa/prestador/save

Cadastrar/atualizar prestador

Cria ou atualiza o cadastro do prestador pessoa física. O CPF identifica o prestador dentro da empresa: não é possível ter dois cadastros com o mesmo CPF. A PF não é emissora — não precisa de conta nem de certificado.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
id	string	ID do cadastro. Vazio cria; preenchido atualiza
cpf *	string	CPF do prestador (11 dígitos)
name *	string	Nome completo do prestador
nit	string	NIT/PIS/PASEP. Sem ele a contabilidade não consegue lançar no eSocial
qtdDependentes	int	Dependentes para dedução do IRRF (dedução mensal, não por recibo)
ativo	bool	Prestador ativo

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Listar prestadores

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
page	int	Página (padrão 1)
pageSize	int	Itens por página (padrão 20)
keyword	string	Busca por nome ou CPF
somenteAtivos	bool	Retorna apenas prestadores ativos

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Calcular sem emitir

Calcula a retenção sem gravar nada: não cria recibo e não consome numeração. É o caminho recomendado antes de confirmar um pagamento — no RPA o valor que o prestador recebe é menor que o combinado, e a emissão não pode ser desfeita (o estorno não devolve o número). O preview nunca é bloqueado: caso a tabela de um ano ainda não tenha sido validada, ele calcula assim mesmo e sinaliza em avisos, enquanto o /create recusa.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
prestadorId *	string	ID do prestador (retornado por `/prestador/save`)
dataPagamento *	string	Data do pagamento (AAAA-MM-DD). Define a competência — regime de caixa
valorBruto *	decimal	Valor bruto do serviço
outrasDeducoes	decimal	Pensão alimentícia e afins
baseInssOutrosTomadores	decimal	Base de INSS já consumida por outros tomadores na competência. É um total do mês, informado conforme comprovante do prestador — o teto do INSS é da pessoa, não do pagador
valorInssOutrosTomadores	decimal	Valor de INSS já retido por outros tomadores (informativo)

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Emitir RPA

Emite o recibo. O cálculo é refeito no servidor no momento da gravação, sob trava por (CPF, competência) — o valor enviado no preview não é aceito como entrada. Exige a tabela do ano confirmada.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
prestadorId *	string	ID do prestador (retornado por `/prestador/save`)
dataPagamento *	string	Data do pagamento (AAAA-MM-DD). Define a competência — regime de caixa
valorBruto *	decimal	Valor bruto do serviço
descricaoServico *	string	Descrição do serviço prestado
codigoServicoMunicipal	string	Código do serviço no município (opcional)
outrasDeducoes	decimal	Pensão alimentícia e afins
baseInssOutrosTomadores	decimal	Base de INSS já consumida por outros tomadores na competência. É um total do mês, informado conforme comprovante do prestador — o teto do INSS é da pessoa, não do pagador
serie	int	Série do recibo. Omitido usa 1

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Listar RPA

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
page	int	Página (padrão 1)
pageSize	int	Itens por página (padrão 20)
competencia	int	Competência no formato AAAAMM
cpf	string	CPF do prestador (11 dígitos)
status	string	Filtro: `emitido` ou `estornado`

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Detalhar RPA

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
id *	string	ID do recibo

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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

Obter PDF do RPA

Retorna a URL do PDF do recibo. É gerado na primeira chamada e reaproveitado depois. O PDF deriva do que está gravado — inclusive da memória de cálculo congelada — então regerar nunca altera valores.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
id *	string	ID do recibo
regerar	bool	Força remontar o PDF em vez de reaproveitar

* Campo obrigatório.

POST/api/rpa/estornar

Estornar RPA

Estorno lógico — não existe cancelamento, porque o RPA não é transmitido a lugar nenhum. O recibo permanece na listagem marcado como estornado, sai de todos os totais do fechamento, e o número não retorna para a numeração. Recibos posteriores da mesma competência não são recalculados.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
id *	string	ID do recibo
motivo *	string	Motivo do estorno (mínimo 5 caracteres)

* Campo obrigatório.

POST/api/rpa/report/monthly

Fechamento mensal

Devolve, por recibo, o que o eSocial exige (CPF, NIT, categoria, bases e valores de cada retenção), os totais da competência e os alertas que impedem a declaração: temEstorno e prestadoresSemNit. Recibos estornados aparecem em itens mas não entram nos totais.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
competencia *	int	Competência no formato AAAAMM

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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": []
          }
        }