TF FISCAL - API de Factura Brasileña

URL Base: https://api.tffiscal.com

La API TF FISCAL permite la integración con el sistema de factura electrónica (NF-e) de Brasil. Actualmente soporta emisión de facturas para productos en todo el territorio brasileño.

Flujo del Sistema

Datos de Entrada

Información del Cliente (comprador)
Información de Productos
Información Fiscal (impuestos)
Información de Transporte

Procesamiento

Validación de datos
Cálculo de impuestos
Generación del XML de NF-e
Autorización en SEFAZ

Salida

XML de la factura
PDF de la factura
DANFE (Documento Auxiliar)
Estado de autorización

Autenticación

Todas las solicitudes deben incluir los siguientes encabezados:

Parámetro	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	application/json;charset=utf-8
sign	string	Sí	Firma digital de la solicitud
timestamp	string	Sí	Timestamp UTC de la solicitud
token	string	Sí	Token de autenticación

Nota: Para crear empresa y obtener lista de empresas, use el token del distribuidor (b2b_token).

Algoritmo de Firma (SIGN)

static string GetSign(string AppKey, string Path, string bodyString, string timestamp)
{
    string input = AppKey + Path + bodyString + timestamp;
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);
        
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < hashBytes.Length; i++)
        {
            sb.Append(hashBytes[i].ToString("x2"));
        }
        return sb.ToString();
    }
}

Endpoints Disponibles

Endpoint	Método	Funcionalidad
`/api/company/create`	POST	Crear empresa
`/api/company/get_detail`	GET	Consultar empresa
`/api/company/edit`	POST	Editar empresa
`/api/company/get_list`	GET	Listar empresas
`/api/category/get_list`	GET	Listar categorías
`/api/invoice/create`	POST	Crear factura
`/api/invoice/get_list`	GET	Listar facturas
`/api/invoice/get_detail`	GET	Consultar factura
`/api/invoice/refresh`	POST	Actualizar estado de factura
`/api/invoice/cancel`	POST	Cancelar factura
`/api/invoice/invalid`	POST	Invalidar factura

Parámetros Tributarios

Los parámetros tributarios son esenciales para la correcta clasificación fiscal de las operaciones.

Parámetros ICMS

11.1 Escenario de Tributación

padrao Estándar (aplicable a todos los escenarios, excepto ICMS)

saida_fora_estado Venta fuera del estado (interestadual)

saida_dentro_estado Venta dentro del estado (intraestadual)

entrada_fora_estado Compra de fuera del estado

entrada_dentro_estado Compra dentro del estado

11.2 Situación Tributaria

Valor	Descripción
00	Entrada con recuperación de crédito
01	Entrada gravada con alícuota cero
02	Entrada exenta
03	Entrada no gravada
04	Entrada inmune
05	Entrada con suspensión
49	Otras entradas
01	Operación Gravada - Base de Cálculo = Valor de la Operación Alícuota Normal
02	Operación Gravada - Base de Cálculo = Valor de la Operación (Alícuota diferenciada)
03	Operación Gravada - Base de Cálculo = Cantidad Vendida X Alícuota por Unidad de Producto
04	Operación Gravada - Tributación Monofásica - (Alícuota Cero)
05	Operación Gravada - (Sustitución Tributaria)
06	Operación Gravada (Alícuota Cero)
07	Operación Exenta de Contribución

11.3 Tipo de Persona

fisica Persona Física

juridica Persona Jurídica

Parámetros PIS/COFINS

12.1 Escenario de Tributación

padrao Estándar (aplicable a todos los escenarios)

saida_fora_estado Venta fuera del estado

saida_dentro_estado Venta dentro del estado

entrada_fora_estado Compra de fuera del estado

entrada_dentro_estado Compra dentro del estado

12.2 Situación Tributaria - PIS/COFINS

Valor	Descripción
71	Operación de Adquisición con Exención
72	Operación de Adquisición con Suspensión
73	Operación de Adquisición a Alícuota Cero
74	Operación de Adquisición sin Incidencia de la Contribución
75	Operación de Adquisición por Sustitución Tributaria
98	Otras Operaciones de Entrada
99	Otras Operaciones

12.3 Tipo de Persona

fisica Persona Física

juridica Persona Jurídica

Parámetros de Pago

Configuración de los métodos de pago e información de tarjeta para la factura.

13. Indicador de Pago

Valor	Descripción
0	Al contado
1	A plazos

14. Método de Pago

Valor	Descripción
01	Efectivo
02	Cheque
03	Tarjeta de Crédito
04	Tarjeta de Débito
05	Tarjeta de la Tienda
10	Vale Alimentación
11	Vale Refeição
12	Vale Regalo

15. Información de Tarjeta

Nota: Rellenar solo cuando payment_method sea 03 (Tarjeta de Crédito) o 04 (Tarjeta de Débito).

15.1 Tipo de Integración

Valor	Descripción	Explicación
1	Pago integrado con el sistema de automatización de la empresa	Como TEF o gateway de pago integrado
2	Pago no integrado con el sistema de automatización de la empresa	POS independiente, sin sincronización automática

15.2 Código de Marca

Valor	Marca
01	Visa
02	Mastercard
03	American Express
04	Sorocred
05	Diners Club
06	Elo
07	Hipercard
08	Aura
09	Cabal
10	Alelo
11	Banes Card
12	CalCard
13	Credz
14	Discover
15	GoodCard
16	GreenCard
17	Hiper
18	JCB
19	Mais
20	MaxVan
21	Policard
22	RedeCompras
23	Sodexo
24	ValeCard
25	Vercoheque
26	VR
27	Ticket
99	Otros

Solución de Problemas con XML

Rechazo 225 - Fallo en Esquema XML

Escenario: Cuando intenta cancelar, descargar XML, inutilizar número, o hacer manifestación del destinatario de una NF-e que no fue registrada con éxito en la base de datos de SEFAZ.

1

Verificar Estado de la NF-e

Confirme si la NF-e fue autorizada con éxito (estado "Autorizada") usando la funcionalidad de consulta de estado.

2

Reemitir la NF-e

Si no fue autorizada, intente reemitir la NF-e (rehacer la emisión).

3

Inutilizar Número

Si el número de factura no fue utilizado y facturas subsiguientes ya fueron autorizadas, considere inutilizar el número de factura.

Cómo Identificar el Error Específico

Cuando el error es "fallo en esquema", significa que algunas informaciones en el XML no están de acuerdo con el layout válido de SEFAZ. En el camino indicado en rojo, siempre indicará cuál XML TAG es inválida.

Ejemplo de Error

Resultado de la Validación del Esquema y de Reglas de Negocio:
- Parecer XML: Ningún error encontrado
- Tipo de Mensaje: Documento de NF-e
- Esquema XML: The http://www.portalfiscal.inf.br/nfe element is invalid
  The value '$86.300' is invalid according to its datatype 'String'
  The Pattern constraint failed
  Camino: NF-e[1]/infNFe[1]/det[1]/prod[1]/NCM

Herramientas de Validación

Validación Online de SEFAZ

Use el validador oficial de SEFAZ para identificar problemas en el XML:

URL: https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx

1

Copiar Contenido del XML

Acceda al sistema y copie todo el contenido del archivo XML.

2

Pegar en Validador

Pegue el contenido XML en el campo apropiado del validador.

3

Analizar Resultados

Verifique los errores específicos señalados por el validador.

Problemas Comunes

Dirección del destinatario incompleta o con datos anormales (símbolos especiales)
Informaciones fiscales del producto incorrectas (NCM inválido, clasificaciones tributarias erróneas)
Formato de valores incorrecto (puntos, comas, decimales)
Campos obligatorios ausentes

Información de Certificado

Días Restantes del Certificado

Es esencial monitorear la validez del certificado digital. Certificados expirados causan rechazo de las NF-e.

Recomendaciones

Renueve el certificado al menos 30 días antes de la expiración
Mantenga backup del certificado y contraseña en lugar seguro
Pruebe el nuevo certificado antes de la expiración del actual
Configure alertas para expiración del certificado

Verificación de la Validez

Para verificar los días restantes del certificado:

Windows

1. Abra Internet Explorer
2. Vaya a Herramientas → Opciones de Internet → Contenido → Certificados
3. Seleccione su certificado y haga clic en "Ver"
4. Verifique la fecha de validez en la pestaña "General"

Seleccionar Idioma