RPA · TF Fiscal API

Nota

RPA — Recibo de Pago a Trabajador Autónomo

La API de RPA permite registrar prestadores persona física, calcular y emitir recibos de pago a autónomos, obtener el PDF y generar el cierre mensual para la contabilidad. El RPA no es un documento fiscal electrónico: no hay transmisión a la autoridad fiscal, ni firma digital, ni clave de acceso, ni protocolo — y por eso tampoco existe entorno de homologación. La empresa emisora se resuelve por el token, nunca por el cuerpo de la solicitud. Disponible solo para empresas emisoras de NF-e.

Endpoint	Método	Descripción
`/api/rpa/prestador/save`	POST	Registrar/actualizar prestador
`/api/rpa/prestador/get_list`	POST	Listar prestadores
`/api/rpa/preview`	POST	Calcular sin emitir
`/api/rpa/create`	POST	Emitir RPA
`/api/rpa/get_list`	POST	Listar RPA
`/api/rpa/get_detail`	POST	Detallar RPA
`/api/rpa/get_pdf`	POST	Obtener PDF del RPA
`/api/rpa/estornar`	POST	Revertir RPA
`/api/rpa/report/monthly`	POST	Cierre mensual

INSS e IRRF se calculan por período y por persona, no por recibo: el tope del INSS y el tramo progresivo del IRRF consideran todo lo ya pagado al mismo CPF en el mes. Por eso el segundo pago del mes al mismo prestador puede tener una retención mayor que el primero. La tabla de INSS/IRRF la mantiene la plataforma por año calendario — no hay nada que registrar. Mientras los valores de un año nuevo no hayan sido validados por un contador, /preview sigue calculando y /create responde con error, en lugar de emitir un recibo con retención no verificada.

POST/api/rpa/prestador/save

Registrar/actualizar prestador

Crea o actualiza el registro del prestador persona física. El CPF identifica al prestador dentro de la empresa: no se permiten dos registros con el mismo CPF. La persona física no es emisora — no necesita cuenta ni certificado.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
id	string	ID del registro. Vacío crea; con valor actualiza
cpf *	string	CPF del prestador (11 dígitos)
name *	string	Nombre completo del prestador
nit	string	NIT/PIS/PASEP. Sin él la contabilidad no puede declarar en eSocial
qtdDependentes	int	Dependientes para deducción del IRRF (deducción mensual, no por recibo)
ativo	bool	Prestador activo

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
page	int	Página (predeterminado 1)
pageSize	int	Ítems por página (predeterminado 20)
keyword	string	Búsqueda por nombre o CPF
somenteAtivos	bool	Devuelve solo prestadores activos

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 sin emitir

Calcula la retención sin guardar nada: no crea recibo ni consume numeración. Es el paso recomendado antes de confirmar un pago — en el RPA el prestador recibe menos que el importe acordado, y la emisión no se puede deshacer (la reversión no devuelve el número). El preview nunca se bloquea: si la tabla de un año todavía no fue validada, calcula igualmente y lo señala en avisos, mientras que /create lo rechaza.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
prestadorId *	string	ID del prestador (devuelto por `/prestador/save`)
dataPagamento *	string	Fecha del pago (AAAA-MM-DD). Define el período — régimen de caja
valorBruto *	decimal	Importe bruto del servicio
outrasDeducoes	decimal	Pensión alimenticia y similares
baseInssOutrosTomadores	decimal	Base de INSS ya consumida por otros pagadores en el período. Es un total mensual, según el comprobante del prestador — el tope del INSS es de la persona, no del pagador
valorInssOutrosTomadores	decimal	INSS ya retenido por otros pagadores (informativo)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 el recibo. El cálculo se rehace en el servidor al guardar, bajo bloqueo por (CPF, período) — el importe devuelto por preview no se acepta como entrada. Exige la tabla del año confirmada.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
prestadorId *	string	ID del prestador (devuelto por `/prestador/save`)
dataPagamento *	string	Fecha del pago (AAAA-MM-DD). Define el período — régimen de caja
valorBruto *	decimal	Importe bruto del servicio
descricaoServico *	string	Descripción del servicio prestado
codigoServicoMunicipal	string	Código del servicio en el municipio (opcional)
outrasDeducoes	decimal	Pensión alimenticia y similares
baseInssOutrosTomadores	decimal	Base de INSS ya consumida por otros pagadores en el período. Es un total mensual, según el comprobante del prestador — el tope del INSS es de la persona, no del pagador
serie	int	Serie del recibo. Si se omite, usa 1

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
page	int	Página (predeterminado 1)
pageSize	int	Ítems por página (predeterminado 20)
competencia	int	Período en formato AAAAMM
cpf	string	CPF del prestador (11 dígitos)
status	string	Filtro: `emitido` o `estornado`

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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

Detallar RPA

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
id *	string	ID del recibo

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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

Obtener PDF del RPA

Devuelve la URL del PDF del recibo. Se genera en la primera llamada y se reutiliza después. El PDF deriva de lo almacenado — incluida la memoria de cálculo congelada — por lo que regerar nunca altera importes.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
id *	string	ID del recibo
regerar	bool	Fuerza regenerar el PDF en lugar de reutilizar

* Campo obligatorio.

POST/api/rpa/estornar

Revertir RPA

Reversión lógica — no existe cancelación, porque el RPA no se transmite a ningún lugar. El recibo permanece en el listado marcado como revertido, sale de todos los totales del cierre y el número no vuelve a la numeración. Los recibos posteriores del mismo período no se recalculan.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
id *	string	ID del recibo
motivo *	string	Motivo de la reversión (mínimo 5 caracteres)

* Campo obligatorio.

POST/api/rpa/report/monthly

Cierre mensual

Devuelve, por recibo, lo que eSocial exige (CPF, NIT, categoría, bases e importes de cada retención), los totales del período y las alertas que impiden la declaración: temEstorno y prestadoresSemNit. Los recibos revertidos aparecen en itens pero no entran en los totales.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
competencia *	int	Período en formato AAAAMM

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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": []
          }
        }