REST API v2.5 SYSTEM OPERATIONAL

Documentación NFE API

Bienvenido a la documentación de NFE API. API completa para emisión, consulta y cancelación de Facturas Electrónicas (NF-e) en Brasil. Soporta cálculo automático de impuestos (ICMS, IPI, PIS/COFINS), generación de XML, autorización SEFAZ e integración con sistemas de gestión.

list_alt

Campos Importantes de la API

Interpretación de Campos Críticos

Esta sección explica los campos más importantes de NFE API que son esenciales para el correcto funcionamiento de la emisión de facturas.

⚠️ ATENCIÓN: La configuración correcta de estos campos es fundamental para la emisión válida de facturas. Consulte siempre la legislación tributaria vigente.

Campo	Descripción	Valores Posibles	Importancia
`invoice_type`	Tipo de empresa (persona jurídica/física)	`juridica`, `fisica`	Alta - Define el régimen tributario
`nature_of_operation`	Naturaleza de la operación (venta, devolución, etc.)	Ej: `VENDA`, `DEVOLUCAO`	Alta - Determina el CFOP
`transaction_type`	Tipo de transacción (entrada/salida)	`ENTRADA`, `SAIDA`	Alta - Dirige el flujo fiscal
`model`	Modelo de la factura	`nfe`, `nfce`	Alta - Modelo del documento
`issuance_type`	Tipo de emisión (normal, contingencia)	`NORMAL`, `CONTINGENCIA`	Media - Modo de emisión
`ambiente`	Ambiente de procesamiento	`PRODUCAO`, `HOMOLOGACAO`	Alta - Define SEFAZ destino
`cliente`	Tipo de cliente/comprador	`CONSUMIDOR`, `CONTRIBUINTE`	Alta - Impacta en los impuestos
`products.origem`	Origen del producto (nacional/importado)	`0` a `8`	Alta - Determina tributación
`products.indicador_total`	Si el producto entra en el total de la NF	`true`, `false`	Media - Para ítems de muestra

💡 CONSEJO: Para productos, el campo origem es crítico: 0-Nacional, 1-Extranjera importación directa, 2-Extranjera adquirida en el mercado interno, etc. Consulte la tabla completa de origen de mercancías.

sync_alt

Flujo del Proceso de Emisión

Diagrama completo de la emisión de NF-e

El flujo completo de emisión de factura electrónica en Brasil, desde la creación de la empresa hasta la generación de los archivos finales.

business

1. Crear Empresa

Crear información fiscal de la empresa local en Brasil

send

2. Push de Información

Datos del pedido (usuario, dirección, impuestos del producto)

receipt

3. Emitir Factura

Procesar y enviar para autorización SEFAZ

assignment_returned

4. Retornar Resultado

Estado de la emisión y datos de la NF-e

description

5. Generar Archivos

XML y PDF de la factura

published_with_changes

Verificación Fiscal

Validación con SEFAZ

check_circle

Éxito

error

Fallo

Configuración Inicial

Procesamiento de Datos

Emisión Fiscal

Resultados Positivos

📊 Flujo Detallado: El proceso sigue una secuencia lógica: (1) Configuración de la empresa → (2) Recepción de los datos del pedido → (3) Procesamiento y emisión de la NF-e → (4) Retorno del estado → (5) Generación de los archivos. El punto de decisión (Verificación Fiscal) determina si la emisión fue autorizada por la SEFAZ.

flash_on

Referencia Rápida de Endpoints

Todos los endpoints de NFE API

Visión general completa de todos los endpoints disponibles en la API. Use esta tabla como referencia rápida para navegar en la documentación.

URL Base

https://api.tffiscal.com

Path	Método HTTP	Función
business Gestión de Empresas
`/api/company/create`	POST	Crear empresa
`/api/company/v2/create`	POST	Crear empresa (simplificado)
`/api/company/get_detail`	GET	Consultar empresa
`/api/company/edit`	POST	Modificar empresa
`/api/company/get_list`	GET	Listar empresas
`/api/company/get_cep_detail`	GET	Consultar CEP
`/api/company/get_export_invoice_month_files`	GET	Archivos exportados mensuales
category Gestión de Categorías/Impuestos
`/api/category/get_list`	GET	Listar categorías de impuestos
`/api/category/create`	POST	Crear categoría de impuestos
`/api/category/get_detail`	GET	Consultar detalles de la categoría
`/api/category/edit`	POST	Editar categoría de impuestos
`/api/category/delete`	POST	Eliminar categoría de impuestos
receipt Gestión de Facturas
`/api/invoice/create`	POST	Emitir factura
`/api/invoice/get_list`	GET	Listar facturas
`/api/invoice/get_detail`	GET	Consultar detalles de la factura
`/api/invoice/refresh`	POST	Actualizar estado de la factura
`/api/invoice/cancel`	POST	Cancelar factura
`/api/invoice/invalid`	POST	Invalidar número de la factura
`/api/invoice/return`	POST	Devolución de factura
`/api/invoice/get_xml`	POST	Exportar XML de la factura
receipt NFC-e (Factura de Consumidor)
`/api/nfce/company/create`	POST	Registrar empresa NFC-e
`/api/nfce/company/update`	POST	Actualizar empresa NFC-e
`/api/nfce/company/get`	POST	Consultar empresa NFC-e
`/api/nfce/create`	POST	Emitir NFC-e
`/api/nfce/cancel`	POST	Cancelar NFC-e
`/api/nfce/get_detail`	POST	Consultar NFC-e
`/api/nfce/get_danfe`	POST	Obtener DANFE NFC-e
description NFS-e (Nota de Servicio)
`/api/nfse/create`	POST	Emitir NFS-e
`/api/nfse/cancel`	POST	Cancelar NFS-e
`/api/nfse/get_danfse`	POST	Obtener DANFSE (PDF)
`/api/nfse/get_xml`	POST	Descargar XML NFS-e

📋 Notas Importantes:

Todos los endpoints requieren autenticación via headers: sign, timestamp, token
Para crear empresa y listar empresas, use el token del distribuidor (b2b_token)
El Content-Type debe ser siempre application/json;charset=utf-8
Las respuestas siguen el patrón JSON con campos success, message y data

200

Éxito

Petición procesada con éxito

400

Error del Cliente

Datos inválidos o faltantes

500

Error del Servidor

Error interno en el servidor

account_balance

NFE API

Factura Electrónica Brasileña (NF-e)

API completa para emisión, consulta y cancelación de Facturas Electrónicas (NF-e) en Brasil. Soporta cálculo automático de impuestos (ICMS, IPI, PIS/COFINS), generación de XML, autorización SEFAZ e integración con sistemas de gestión. Actualmente soporta emisión de facturas para productos en todo territorio brasileño.

Base URL (Producción)

https://api.tffiscal.com/v1

Autenticación

Headers: sign, timestamp, token

Requisitos

Certificado Digital A1 válido

sync_alt Flujo del Sistema

input Datos de Entrada

Información del Cliente
Datos de los Productos
Información Fiscal
Datos de Transporte

settings Procesamiento

Validación de los datos
Cálculo de impuestos
Generación del XML
Autorización SEFAZ

download Salida

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

Endpoints Principales

POST /api/company/create

Registrar nueva empresa emisora

Registra una empresa emisora vinculada a una cuenta de distribuidor (b2b). Use este endpoint cuando los datos de la empresa ya estén disponibles. Para extracción automática desde el certificado digital, use /api/company/v2/create.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token del distribuidor (b2b — la cuenta debe tener `isb2b=true`)
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
Identificación
cnpj *	string	CNPJ de la empresa emisora
name *	string	Razón social
ie *	string	Inscripción Estatal (Inscrição Estadual)
invoice_type *	string	Régimen tributario (ej.: `"simples_nacional"`, `"normal"`)
unit *	string	Tipo de unidad
email	string	Correo electrónico de la empresa
Dirección
cep *	string	Código postal
address *	string	Dirección (calle)
house_number *	string	Número de dirección
town *	string	Barrio
city *	string	Ciudad
state *	string	UF (sigla del estado)
Certificado digital
cert_file *	string	URL HTTPS del certificado digital A1 (.pfx o .p12)
cert_pwd *	string	Contraseña del certificado
Numeración y configuración
serie *	int	Serie de la NF-e
number *	int	Número inicial de la numeración
is_create_category_template	boolean	Crea categorías fiscales por defecto automáticamente. Default: `true`

* Campo obligatorio.

Ejemplo de carga útil

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "UN",
          "email": "contacto@empresa.com",
          "cep": "01001000",
          "address": "Calle Ejemplo",
          "house_number": "100",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://ejemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1
        }

Respuesta

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/v2/create

Registrar empresa con autocompletado mediante certificado

Versión simplificada de /api/company/create: la API valida el certificado digital y extrae automáticamente razón social, IE, dirección y otros datos mediante consulta interna. Solo cnpj, cert_file y cert_pwd son obligatorios.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token del distribuidor (b2b — la cuenta debe tener `isb2b=true`)
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
cnpj *	string	CNPJ de la empresa emisora
cert_file *	string	URL HTTPS del certificado digital A1 (.pfx o .p12)
cert_pwd *	string	Contraseña del certificado
is_create_category_template	boolean	Crea categorías fiscales por defecto automáticamente. Default: `true`

* Campo obligatorio.

Ejemplo de carga útil

        {
          "cnpj": "12345678000199",
          "cert_file": "https://ejemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado"
        }

Respuesta

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/edit

Editar datos de la empresa

Actualiza los datos de la empresa emisora. Envíe solo los campos que desea modificar — todos excepto company_id son opcionales. El CNPJ es inmutable: enviarlo devuelve error. Al actualizar cep, el sistema resuelve automáticamente stateCode e ibge. Cuando cert_file y cert_pwd vienen juntos, el certificado se valida antes de guardar.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
company_id *	string	ID de la empresa a editar
name	string	Razón social
invoice_type	string	Régimen tributario
ie	string	Inscripción Estatal
unit	string	Tipo de unidad
email	string	Correo electrónico
cep	string	Código postal (actualiza automáticamente `stateCode` e `ibge`)
address	string	Dirección
house_number	string	Número
town	string	Barrio
city	string	Ciudad
state	string	UF
cert_file	string	URL HTTPS del nuevo certificado (.pfx o .p12). Si se envía junto con `cert_pwd`, se valida antes de guardar
cert_pwd	string	Nueva contraseña del certificado
serie	int	Nueva serie de la NF-e
number	int	Nuevo número inicial

* Campo obligatorio. Enviar cnpj devuelve error.

Ejemplo de carga útil

                {
                  "company_id": "comp_789012",
                  "name": "Nova Razão Social LTDA",
                  "email": "nuevo@empresa.com",
                  "cep": "01310100"
                }

Respuesta

                {
                  "success": true
                }

GET /api/company/get_list

Listar empresas del distribuidor

Lista, con paginación, las empresas emisoras vinculadas a la cuenta de distribuidor (b2b). Parámetros vía query string.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token del distribuidor (b2b — la cuenta debe tener `isb2b=true`)
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–20)

* Campo obligatorio.

Ejemplo de llamada

GET /api/company/get_list?page=1&page_size=10

Respuesta

        {
          "success": true,
          "data": {
            "companys": [
              {
                "company_id": "comp_789012",
                "invoice_type": "simples_nacional",
                "token": "eyJhbGciOiJIUzI1NiIs...",
                "cnpj": "12345678000199",
                "name": "Empresa Exemplo LTDA",
                "ie": "123456789",
                "unit": "UN",
                "email": "contacto@empresa.com",
                "cep": "01001000",
                "address": "Calle Ejemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://ejemplo.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET /api/company/get_detail

Detalles de la empresa autenticada

Devuelve los datos completos de la empresa identificada por el header token, incluida la lista de categorías fiscales registradas. No acepta body ni query string.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Ejemplo de llamada

GET /api/company/get_detail

Respuesta

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "name": "Empresa Exemplo LTDA",
            "token": "eyJhbGciOiJIUzI1NiIs...",
            "invoice_type": "simples_nacional",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "unit": "UN",
            "email": "contacto@empresa.com",
            "cep": "01001000",
            "address": "Calle Ejemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://ejemplo.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET /api/category/get_list

Listar categorías de productos

Retorna todas las categorías disponibles para clasificación fiscal.

POST /api/invoice/create

Emitir nueva factura

Emite una NF-e (modelo 55). La empresa emisora se identifica mediante el header token; no envíe company_id en el cuerpo.

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 (ventana de 5 minutos)

Body — campos de nivel superior

Campo	Tipo	Descripción
Identificación y operación
id	string	ID único del cliente para idempotencia (compone la clave de deduplicación)
nature_of_operation *	string	Naturaleza de la operación (ej.: "Venta de mercancía")
transaction_type *	string	Tipo: `"0"`=entrada, `"1"`=salida, `"2"`=importación, `"3"`=exportación
model *	string	Modelo del documento: `"55"`=NF-e
issuance_type *	string	Tipo de emisión (`"1"`=normal, `"9"`=contingencia, etc.)
ambiente *	string	`"1"`=producción, `"2"`=homologación
finalidade	string	Finalidad: `"1"`=normal, `"2"`=complementaria, `"3"`=ajuste, `"4"`=devolución
ref_nfe_chave	string	Clave de acceso de 44 dígitos de la NF-e referenciada (complementaria/ajuste/devolución)
is_reopen	boolean	Reabrir/sobrescribir una NF-e ya emitida
dh_sai_ent	string	Fecha/hora de salida o entrada (ISO 8601). Por defecto: timestamp actual
Importes y descuentos
total_discount_amount	decimal	Descuento total de la factura
troco	decimal	Vuelto (típico en NFC-e)
seguro	decimal	Importe de seguro (prorrateado entre productos como `vSeg` en XML)
outras_despesas	decimal	Otros gastos (prorrateados entre productos como `vOutro` en XML)
Indicadores e información adicional
ind_final	string	Consumidor final: `"0"`=B2B, `"1"`=B2C
ind_pres	string	Indicador de presencia: `"1"`=presencial, `"2"`=internet, `"3"`=tele-atención, etc.
informacoes_complementares	string	Información complementaria (escrita en `infAdic.infCpl`)
informacoes_fisco	string	Información para el fisco (escrita en `infAdic.infAdFisco`)

Body — `cliente` (objeto, obligatorio)

Para operaciones nacionales (transaction_type 0 o 1): cpf o cnpj, name, endereco, bairro (mín. 2 caracteres), city, uf y cep son obligatorios. Para importación/exportación (transaction_type 2 o 3): solo name es obligatorio.

Campo	Tipo	Descripción
cpf	string	CPF del cliente (alternativa a cnpj)
cnpj	string	CNPJ del cliente (alternativa a cpf)
ie	string	Inscripción Estatal (Inscrição Estadual)
name *	string	Razón social / nombre del cliente
endereco	string	Dirección (calle)
complemento	string	Complemento de dirección
numero	string	Número de dirección
bairro	string	Barrio (mínimo 2 caracteres en operaciones nacionales)
city	string	Ciudad
uf	string	Estado (UF) — se sobrescribe con el UF resuelto desde el CEP
cep	string	Código postal (valida UF y ciudad)
telefone	string	Teléfono
email	string	Correo electrónico
id_estrangeiro	string	ID extranjero (uso en importación/exportación)
c_pais	int	Código BACEN del país. Por defecto: `1058` (Brasil)
x_pais	string	Nombre del país. Por defecto: `"BRASIL"`

Body — `products[]` (array, mínimo 1 elemento)

Cada producto requiere tributación: o bien category_id (referencia a una categoría fiscal pre-registrada), o el objeto impostos/tax_info con la configuración en línea.

Campo	Tipo	Descripción
codigo	string	Código interno del producto
name *	string	Descripción del producto (los caracteres CJK se eliminan)
ncm *	string	NCM con 8 dígitos
cest	string	Código CEST (obligatorio cuando aplica ICMS-ST)
gtin	string	GTIN / código de barras
gtin_tributavel	string	GTIN de la unidad tributable
count *	decimal	Cantidad
unit *	string	Unidad comercial (ej.: "UN", "KG", "MT")
unit_price *	decimal	Precio unitario
total_price *	decimal	Valor total del ítem
discount_price	decimal	Descuento aplicado al ítem
origem *	int	Origen de la mercancía (`0`=Nacional, `1`=Extranjera — importación directa, etc.)
indicador_total *	int	Compone el total de la NF-e: `0`=no, `1`=sí
category_id	string	ID de categoría fiscal pre-registrada (obligatorio si no envía `impostos`/`tax_info`)
impostos	object	Configuración de tributos en línea (alternativa a `category_id`). Vea la estructura abajo
tax_info	object	Alias de `impostos` (misma estructura)
disable_difal	boolean	Desactiva el cálculo de DIFAL para este ítem
desconta_icms_pis_cofins	boolean	Descuenta el ICMS de la base de PIS/COFINS solo para este ítem (anula la categoría)
ii	object	Impuesto de Importación — obligatorio para CFOP 3.xxx. Vea la estructura abajo
import_declarations	array	Declaraciones de Importación (DI) — obligatorio cuando `transaction_type="2"`. Vea la estructura abajo
nItemPed	int	Ítem del Pedido de Compra (I61). Número secuencial del ítem dentro del pedido referenciado en `xPed` (viene de `id` de raíz). Valores válidos: 1–999999. Default: omitido.

Body — `products[].impostos` / `products[].tax_info`

Campo	Tipo	Descripción
industria	string	Industria/alícuota base (alias: `aliquota`)
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	CST/CSOSN del ICMS
icms.industria	string	Industria ICMS
icms.tipo_pessoa	string	Tipo de persona (PF/PJ)
icms.codigo_beneficio_fiscal	string	cBenef (código de beneficio fiscal)
ipi
ipi.codigo_enquadramento	string	Código de encuadre legal del IPI
ipi.situacao_tributaria	string	CST IPI
ipi.aliquota	string	Alícuota IPI
ipi.tipo_pessoa	string	Tipo de persona
pis
pis.situacao_tributaria	string	CST PIS
pis.aliquota	string	Alícuota PIS
pis.tipo_pessoa	string	Tipo de persona
cofins
cofins.situacao_tributaria	string	CST COFINS
cofins.aliquota	string	Alícuota COFINS
cofins.tipo_pessoa	string	Tipo de persona
is (Impuesto Selectivo)
is.cenario	string	Escenario IS
is.situacao_tributaria	string	CST IS
is.aliquota	string	Alícuota IS
is.tipo_pessoa	string	Tipo de persona
ibs_cbs (Reforma Tributaria)
ibs_cbs.situacao_tributaria	string	CST IBS/CBS
ibs_cbs.tipo_pessoa	string	Tipo de persona
ibs_cbs.classificacao_tributaria	string	Clasificación tributaria IBS/CBS
difal
difal.disable_difal	boolean	Desactiva DIFAL para el ítem (alternativa al `disable_difal` en el producto)

Body — `products[].ii` (Impuesto de Importación)

Campo	Tipo	Descripción
vBC	decimal	Base de cálculo del II
vDespAdu	decimal	Gastos aduaneros
vII	decimal	Valor del II
vIOF	decimal	Valor del IOF

Body — `products[].import_declarations[]`

Campo	Tipo	Descripción
nDI	string	Número de DI
dDI	string (date)	Fecha de DI
xLocDesemb	string	Lugar de desaduanaje
UFDesemb	string	UF de desaduanaje
dDesemb	string (date)	Fecha de desaduanaje
cExportador	string	Código del exportador
tpViaTransp	int	Vía de transporte internacional
tpIntermedio	int	Tipo de intermediación
vAFRMM	decimal	Valor del AFRMM
additions	array	Adiciones de DI (campos: `nAdicao`, `nSeqAdic`, `cFabricante`, `vDescDI`, `nDraw`)

Body — `shipping_address` / `delivery_address` (objetos, opcionales)

shipping_address es el lugar de recogida (origen físico, si difiere del emisor). delivery_address es el lugar de entrega (destino físico, si difiere del cliente). Cuando están presentes, ambos requieren: cpf o cnpj, name, endereco, bairro (mín. 2 caracteres), city, uf y cep. Ambos objetos tienen la misma estructura.

Campo	Tipo	Descripción
cpf	string	CPF (alternativa a cnpj)
cnpj	string	CNPJ (alternativa a cpf)
ie	string	Inscripción Estatal
name *	string	Razón social / nombre
endereco *	string	Dirección
complemento	string	Complemento
number	string	Número (atención: el campo es `number`, no `numero`)
bairro *	string	Barrio
city *	string	Ciudad
uf *	string	Estado
cep *	string	Código postal
telefone	string	Teléfono
email	string	Correo electrónico

Body — `transportation` (objeto, opcional)

Si transportation se omite, el sistema asume transport_mode="9" (sin flete).

Campo	Tipo	Descripción
transport_mode	string	Modalidad del flete: `"0"`=por cuenta del emisor, `"1"`=por cuenta del destinatario, `"2"`=por cuenta de terceros, `"3"`=transporte propio del remitente, `"4"`=transporte propio del destinatario, `"9"`=sin flete
freight_amount	decimal	Valor total del flete
carrier_info — transportista
carrier_info.cpf	string	CPF del transportista (alternativa a cnpj)
carrier_info.cnpj	string	CNPJ del transportista (alternativa a cpf)
carrier_info.ie	string	Inscripción Estatal
carrier_info.name	string	Razón social
carrier_info.endereco	string	Dirección
carrier_info.city	string	Ciudad
carrier_info.uf	string	Estado
carrier_info.cep	string	Código postal
vehicle_info — vehículo
vehicle_info.plate	string	Placa
vehicle_info.uf	string	UF de la placa
vehicle_info.rntc	string	RNTC (Registro Nacional de Transportistas de Carga)
trailer_info — remolque (misma estructura que vehicle_info)
trailer_info.plate	string	Placa del remolque
trailer_info.uf	string	UF
trailer_info.rntc	string	RNTC
packages[] — volúmenes
packages[].qty	int	Cantidad
packages[].gross_weight	decimal	Peso bruto
packages[].net_weight	decimal	Peso neto
packages[].packaging_type	string	Especie
packages[].number	string	Numeración
packages[].mark	string	Marca
packages[].seals	array<string>	Precintos
transport_tax_retention_info — retención de ICMS sobre flete
transport_tax_retention_info.freight_service_amount	decimal	Valor del servicio de transporte
transport_tax_retention_info.tax_base	decimal	Base de cálculo de la retención
transport_tax_retention_info.tax_rate	decimal	Alícuota de la retención
transport_tax_retention_info.cfop	string	CFOP
transport_tax_retention_info.cep	string	Código postal

Body — `pag_info[]` (array, opcional)

Si se omite, el sistema asume [{ "payment_method": "01", "payment_indicator": "0" }] (efectivo, al contado).

Campo	Tipo	Descripción
payment_method *	string	Forma de pago: `"01"`=efectivo, `"02"`=cheque, `"03"`=tarjeta de crédito, `"04"`=tarjeta de débito, `"05"`=crédito tienda, `"10"`=vale alimentación, `"11"`=vale comida, `"15"`=boleto, `"17"`=PIX, `"90"`=sin pago, `"99"`=otros
payment_indicator *	string	Indicador: `"0"`=al contado, `"1"`=a plazo
payment_value	decimal	Importe pagado
card_info — datos de la tarjeta (para payment_method 03/04)
card_info.integration_type *	string	Tipo de integración de la terminal (obligatorio si `card_info` está presente)
card_info.brand_code *	string	Marca de la tarjeta (obligatorio si `card_info` está presente)
card_info.acquirer_cnpj	string	CNPJ de la adquirente
card_info.authorization_code	string	Código de autorización

* Campo obligatorio.

Ejemplo simplificado

{
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "cliente": {
    "cpf": "12345678909",
    "name": "Cliente Exemplo",
    "endereco": "Rua Exemplo",
    "numero": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000",
    "email": "cliente@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Produto Exemplo",
      "ncm": "85176277",
      "count": 2,
      "unit": "UN",
      "unit_price": 150.00,
      "total_price": 300.00,
      "category_id": "SEU_CATEGORY_ID",
      "origem": 0,
      "indicador_total": 1
    }
  ],
  "pag_info": [
    { "payment_method": "01", "payment_indicator": "0", "payment_value": 300.00 }
  ]
}

Ejemplo completo (todos los campos)

{
  "id": "PEDIDO-2026-0001",
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "finalidade": "1",
  "ref_nfe_chave": "",
  "is_reopen": false,
  "dh_sai_ent": "",
  "total_discount_amount": 0.00,
  "troco": 0.00,
  "seguro": 0.00,
  "outras_despesas": 0.00,
  "ind_final": "1",
  "ind_pres": "9",
  "informacoes_complementares": "Entrega via transportadora",
  "informacoes_fisco": "ICMS recolhido conforme legislação",
  "cliente": {
    "cpf": "",
    "cnpj": "12345678000199",
    "ie": "123456789",
    "name": "Cliente Exemplo LTDA",
    "endereco": "Av. Paulista",
    "numero": "1000",
    "complemento": "Sala 200",
    "bairro": "Bela Vista",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "telefone": "11999998888",
    "email": "cliente@exemplo.com",
    "id_estrangeiro": "",
    "c_pais": 1058,
    "x_pais": "BRASIL"
  },
  "shipping_address": {
    "cnpj": "98765432000111",
    "name": "Depósito Origem LTDA",
    "ie": "987654321",
    "endereco": "Rua do Depósito",
    "number": "50",
    "complemento": "Galpão 3",
    "bairro": "Industrial",
    "city": "Guarulhos",
    "uf": "SP",
    "cep": "07000000",
    "telefone": "11988887777",
    "email": "deposito@exemplo.com"
  },
  "delivery_address": {
    "cnpj": "12345678000199",
    "name": "Cliente Exemplo LTDA",
    "ie": "123456789",
    "endereco": "Rua de Entrega",
    "number": "25",
    "complemento": "Loja 2",
    "bairro": "Centro",
    "city": "Campinas",
    "uf": "SP",
    "cep": "13010000",
    "telefone": "11977776666",
    "email": "entrega@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Notebook Dell",
      "ncm": "84713012",
      "cest": "",
      "gtin": "7891234567890",
      "gtin_tributavel": "7891234567890",
      "count": 2,
      "unit": "UN",
      "unit_price": 3500.00,
      "total_price": 7000.00,
      "discount_price": 0.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001",
      "nItemPed": 1
    },
    {
      "codigo": "PROD002",
      "name": "Mouse sem fio",
      "ncm": "84716053",
      "count": 5,
      "unit": "UN",
      "unit_price": 80.00,
      "total_price": 400.00,
      "origem": 0,
      "indicador_total": 1,
      "nItemPed": 2,
      "impostos": {
        "icms": {
          "codigo_cfop": "5102",
          "situacao_tributaria": "00",
          "industria": "",
          "tipo_pessoa": "juridica",
          "codigo_beneficio_fiscal": ""
        },
        "ipi": {
          "codigo_enquadramento": "999",
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "pis": {
          "situacao_tributaria": "01",
          "aliquota": "0.65",
          "tipo_pessoa": "juridica"
        },
        "cofins": {
          "situacao_tributaria": "01",
          "aliquota": "3.00",
          "tipo_pessoa": "juridica"
        },
        "ibs_cbs": {
          "situacao_tributaria": "000",
          "tipo_pessoa": "juridica",
          "classificacao_tributaria": "000001"
        }
      }
    }
  ],
  "transportation": {
    "transport_mode": "1",
    "freight_amount": 150.00,
    "carrier_info": {
      "cnpj": "11222333000144",
      "ie": "112223334",
      "name": "Transportadora Exemplo LTDA",
      "endereco": "Rod. BR-101, km 50",
      "city": "Santos",
      "uf": "SP",
      "cep": "11000000"
    },
    "vehicle_info": {
      "plate": "ABC1D23",
      "uf": "SP",
      "rntc": "12345"
    },
    "trailer_info": {
      "plate": "DEF4G56",
      "uf": "SP",
      "rntc": "67890"
    },
    "packages": [
      {
        "qty": 3,
        "gross_weight": 12.500,
        "net_weight": 11.000,
        "packaging_type": "CAIXA",
        "number": "001-003",
        "mark": "FRAGIL",
        "seals": ["LACRE001", "LACRE002"]
      }
    ],
    "transport_tax_retention_info": {
      "freight_service_amount": 150.00,
      "tax_base": 150.00,
      "tax_rate": 12.00,
      "cfop": "5932",
      "cep": "11000000"
    }
  },
  "pag_info": [
    {
      "payment_indicator": "1",
      "payment_method": "03",
      "payment_value": 7400.00,
      "card_info": {
        "integration_type": "1",
        "brand_code": "01",
        "acquirer_cnpj": "01234567000189",
        "authorization_code": "AUTH987654"
      }
    }
  ]
}

GET /api/invoice/get_list

Listar NF-e (paginado)

Lista las NF-e de la empresa con paginación. Los parámetros se pasan por query string (no en el body). El filtro de tiempo es opcional, pero si se envía requiere tanto start_create_time como end_create_time.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–50)
start_create_time	long	Unix timestamp en milisegundos — inicio (requiere `end_create_time`)
end_create_time	long	Unix timestamp en milisegundos — fin
status	string	Filtrar por estado (valores: `"Authorized"`, `"Canceled"`, `"Processing"`, `"Rejected"`, etc.)

* Campo obligatorio.

Ejemplo de llamada

GET /api/invoice/get_list?page=1&page_size=20&status=Authorized

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Authorized",
                "create": "2024-01-10T10:30:00Z",
                "issue_time": "2024-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

GET /api/invoice/get_detail

Consultar detalles de la NF-e

Devuelve los detalles de una NF-e específica por UUID. Incluye URL del XML, URLs del DANFE (completo, simplificado y de etiqueta) y metadatos.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
uuid *	string	UUID de la NF-e

* Campo obligatorio.

Ejemplo de llamada

GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

Respuesta

        {
          "success": true,
          "data": {
            "id": "pedido-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Authorized",
            "total_price": 300.00,
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave.pdf",
            "danfe_simples": "https://oss.example.com/.../chave_simplie.pdf",
            "danfe_etiqueta": "https://oss.example.com/.../chave_etiqueta.pdf",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/invoice/refresh

Actualizar estado de la factura

Consulta el estado actual de la NF-e en SEFAZ y actualiza el registro local. Útil cuando la emisión quedó en procesamiento o contingencia.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
uuid *	string	UUID de la NF-e a consultar

* Campo obligatorio.

Ejemplo de carga útil

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/cancel

Cancelar factura

Cancela una NF-e ya autorizada. La justificación enviada a SEFAZ es fija: "Erro no preenchimento da nota fiscal." — no se puede configurar mediante el payload.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
uuid *	string	UUID de la NF-e a cancelar (identificador interno devuelto por `/api/invoice/create`)

* Campo obligatorio.

Ejemplo de carga útil

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/invalid

Inutilizar rango de numeración

Inutiliza un rango continuo de numeración de NF-e que nunca fue autorizado (no confundir con cancelación — la cancelación se aplica a facturas ya autorizadas). La operación queda registrada en SEFAZ y es irreversible.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
modelo *	string	Modelo del documento: `"55"`=NF-e, `"65"`=NFC-e. (Atención: el campo es `modelo`, no `model`)
ambiente *	string	`"1"`=producción, `"2"`=homologación
serie *	int	Serie de la numeración a inutilizar
start_number *	int	Número inicial del rango
end_number *	int	Número final del rango
motivo *	string	Justificación de la inutilización (mínimo 15 caracteres por exigencia de SEFAZ)

* Campo obligatorio.

Ejemplo de carga útil

        {
          "modelo": "55",
          "ambiente": "2",
          "serie": 1,
          "start_number": 100,
          "end_number": 105,
          "motivo": "Falha no sistema durante a emissao do lote"
        }

POST /api/invoice/get_danfe

Obtener DANFE (PDF) de la NF-e

Devuelve tres URLs del DANFE de una NF-e: el DANFE completo (PDF), el DANFE simplificado en PDF (formato cupón) y el DANFE simplificado en PNG (etiqueta/imagen). Los PDFs se generan bajo demanda a partir del XML autorizado y se cachean en OSS. En llamadas posteriores, si el estado de la factura no cambió, devuelve el caché existente; si el estado cambió (ej.: factura cancelada), los PDFs se regeneran.

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 (ventana de 5 minutos)

Body

Campo	Tipo	Descripción
uuid ⚠	string	UUID interno de la NF-e (devuelto por `/api/invoice/create`)
chave ⚠	string	Clave de acceso de la NF-e (44 dígitos)

⚠ uuid o chave, uno de los dos es obligatorio.

Ejemplo de payload

                {
                  "uuid": "abc123-def456-..."
                }

Respuesta

                {
                  "success": true,
                  "data": {
                    "danfe": "https://storage.../uid/dd-MM-yyyy/companyId/.pdf",
                    "danfe_simples": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.pdf",
                    "danfe_simples_png": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.png"
                  }
                }

Campos de la respuesta

Campo	Tipo	Descripción
danfe	string	URL del PDF del DANFE completo (formato A4)
danfe_simples	string	URL del PDF del DANFE simplificado (formato cupón)
danfe_simples_png	string	URL del PNG del DANFE simplificado (etiqueta/imagen)

Respuestas de error

Mensaje	Causa
uuid/chave不能为空	Ni `uuid` ni `chave` fueron enviados
发票不存在	Factura no encontrada para el usuario del token, o XML autorizado faltante
发票详情不存在	Detalle de la factura (con protocolo) no encontrado
获取PDF失败:<motivo>	Fallo al generar el PDF a partir del XML

POST /api/invoice/get_xml

Exportar XML/Excel en lote (asíncrono)

Inicia una tarea asíncrona de exportación en lote de las facturas del usuario, filtrando por período y estado. Puede generar una hoja Excel (solo metadatos) o un paquete ZIP con los XMLs. La primera llamada crea la tarea y devuelve status: "Processing"; llamadas posteriores con los mismos parámetros devuelven el progreso hasta status: "Success", cuando el campo url contiene el enlace de descarga.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
type *	string	Formato de salida: `"excel"` (hoja de metadatos) o cualquier otro valor (ej.: `"xml"`) para ZIP con XMLs
status	string	Filtra por estado de la factura (ej.: `"Success"`, `"Canceled"`, `"Voided"`). Para `type=excel`, se convierte a minúsculas
month	int	Mes (1–12). Si se informa, sustituye `start_create_time`/`end_create_time`; usa zona horaria `America/Sao_Paulo` y año actual (o anterior si el mes es futuro)
start_create_time	long	Inicio del período (Unix timestamp en milisegundos)
end_create_time	long	Fin del período (Unix timestamp en milisegundos)

* Campo obligatorio.

Ejemplo de payload

                {
                  "type": "xml",
                  "status": "Success",
                  "month": 5
                }

Respuesta — procesando

                {
                  "success": true,
                  "data": {
                    "status": "Processing",
                    "progress_count": 120,
                    "total_count": 543,
                    "url": ""
                  }
                }

Respuesta — concluido

                {
                  "success": true,
                  "data": {
                    "status": "Success",
                    "progress_count": 543,
                    "total_count": 543,
                    "url": "https://storage.../exports/uid/.zip"
                  }
                }

Campos de la respuesta

Campo	Tipo	Descripción
status	string	`"Processing"` mientras se ejecuta, `"Success"` cuando el archivo está listo
progress_count	int	Cantidad de facturas ya procesadas
total_count	int	Total de facturas a procesar
url	string	URL de descarga del archivo final (vacío mientras `status = Processing`)

Idempotencia: las tareas se deduplican por hash de los parámetros (uid + token + período + status + type). Llamadas repetidas con los mismos parámetros devuelven el progreso de la misma tarea, sin disparar nuevas ejecuciones.

Respuestas de error

Mensaje	Causa
发票类型字段不能为空	`type` ausente

POST /api/invoice/consultar_status

Consultar estado de la NF-e/NFC-e en SEFAZ

Consulta el estado actual de una NF-e o NFC-e directamente en SEFAZ usando la clave de acceso (44 dígitos), vía el servicio NfeConsultaProtocolo4. Funciona tanto para facturas propias (emitidas por la empresa del token) como para facturas de terceros (ej.: capturadas vía DistDFe). El modelo (NF-e/NFC-e) se detecta automáticamente desde las posiciones 20-21 de la clave.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa (cuyo certificado se usará en la consulta)
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body

Campo	Tipo	Descripción
chave *	string	Clave de acceso (44 dígitos numéricos). UF del emisor se extrae de las posiciones 0-1; modelo de las posiciones 20-21 (`55`=NF-e, `65`=NFC-e).

* Campo obligatorio.

Ejemplo de carga útil

        {
          "chave": "35260512345678000199550010000000011000000018"
        }

Respuesta

        {
          "success": true,
          "message": "Sucesso",
          "data": {
            "chave": "35260512345678000199550010000000011000000018",
            "status": "autorizada",
            "cstat": 100,
            "motivo": "Autorizado o uso da NF-e"
          }
        }

Campos de la respuesta

Campo	Tipo	Descripción
chave	string	Clave de acceso consultada
status	string	Estado normalizado (ver tabla abajo)
cstat	int	Código `cStat` bruto de SEFAZ
motivo	string	Mensaje `xMotivo` bruto de SEFAZ

Mapeo de estados

`status`	cStat de SEFAZ	Significado
autorizada	`100`, `150`	NF-e autorizada para uso
cancelada	`101`, `151`	Cancelada (también devuelto si hay un evento de cancelación vinculado, incluso con `cStat=100`)
denegada	`110`, `301`, `302`	Uso denegado por SEFAZ
inutilizada	`102`	Número inutilizado (rango de numeración)
nao_encontrada	`217`	NF-e no consta en la base de SEFAZ
desconhecido	otros	cStat no mapeado — consulte `cstat` y `motivo` brutos

Respuestas de error

Mensaje	Causa
chave inválida: deve ter 44 dígitos	Clave ausente, con tamaño diferente de 44 o conteniendo caracteres no numéricos
empresa não possui certificado configurado	La empresa del token no tiene `cert_file` registrado
SEFAZ retornou resposta vazia	SEFAZ no devolvió respuesta (timeout, fuera del aire)
erro ao consultar SEFAZ: <detalle>	Excepción al llamar al servicio (XML inválido, timeout, certificado expirado, etc.)

POST /api/category/create

Crear categoría fiscal

Crea una nueva categoría fiscal (plantilla de impuestos) vinculada a la empresa autenticada. Cada categoría agrega escenarios de ICMS, IPI, PIS, COFINS, y opcionalmente IBS/CBS e IS. Para editar una existente, use /api/category/edit.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body — nivel superior

Campo	Tipo	Descripción
descricao *	string	Descripción de la categoría fiscal
category_id	string	ID personalizado. Si se omite, se genera automáticamente como `"TF"` + número incremental
disable_difal	boolean	Desactiva el cálculo de DIFAL para esta categoría. Default: `false`
desconta_icms_pis_cofins	boolean	Descuenta el ICMS de la base de cálculo de PIS/COFINS (base = vProd − vICMS). Default: `false`
icms[] *	array	Escenarios ICMS (estructura abajo)
ipi[] *	array	Escenarios IPI (estructura abajo)
pis[] *	array	Escenarios PIS (estructura abajo)
cofins[] *	array	Escenarios COFINS (estructura abajo)
ibs_cbs[]	array	Escenarios IBS/CBS — reforma tributaria (estructura abajo)
is[]	array	Escenarios IS — Impuesto Selectivo (estructura abajo)

Body — `icms[]`

Campo	Tipo	Descripción
tipo_tributacao *	string	Tipo de tributación ICMS
cenario *	string	Escenario (ej.: `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` o `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	CST/CSOSN del ICMS
nao_contribuinte	boolean	Cliente no-contribuyente
aliquota_importacao	string	Alícuota de importación
aliquota_credito	decimal	Alícuota de crédito (% para Simples Nacional)
aliquota_diferimento	decimal	Porcentaje de diferimiento
aliquota_diferimentoFcp	string	Diferimiento de FCP (atención: el campo usa camelCase `diferimentoFcp`)
aliquota_reducao	decimal	Porcentaje de reducción de base ICMS
aliquota_reducaoSt	decimal	Porcentaje de reducción de base ICMS-ST (atención: `reducaoSt` camelCase)
motivo_desoneracao	string	Código del motivo de exoneración ICMS
motivo_desoneracaoSt	string	Código del motivo de exoneración ICMS-ST (atención: camelCase)
Alícuotas por estado — opcional
aliquota_mva[]	array	MVA por UF — ítems: `{ estado, aliquota }`
aliquota_icms[]	array	Alícuota ICMS por UF — ítems: `{ estado, aliquota }`
aliquota_icms_st[]	array	Alícuota ICMS-ST por UF — ítems: `{ estado, aliquota }`
aliquota_fcp[]	array	Alícuota FCP por UF — ítems: `{ estado, aliquota }`
aliquota_fcp_st[]	array	Alícuota FCP-ST por UF — ítems: `{ estado, aliquota }`
beneficio_fiscal[]	array	Código de beneficio fiscal por UF — ítems: `{ estado, codigo }`

Body — `ipi[]`

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST IPI
codigo_enquadramento *	string	Código de encuadre legal
aliquota *	string	Alícuota IPI

Body — `pis[]` y `cofins[]` (misma estructura)

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST PIS/COFINS
aliquota *	string	Alícuota

Body — `ibs_cbs[]` (Reforma Tributaria)

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST IBS/CBS
classificacao_tributaria *	string	Clasificación tributaria

Body — `is[]` (Impuesto Selectivo)

Campo	Tipo	Descripción
cenario *	string	Escenario
tipo_pessoa *	string	`"fisica"` o `"juridica"`
situacao_tributaria *	string	CST IS
aliquota *	string	Alícuota IS

* Campo obligatorio.

Ejemplo mínimo

        {
          "descricao": "Venda de mercadoria padrão",
          "icms": [{
            "tipo_tributacao": "normal",
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "codigo_cfop": "5102",
            "situacao_tributaria": "00"
          }],
          "ipi":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "99", "codigo_enquadramento": "999", "aliquota": "0" }],
          "pis":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "0.65" }],
          "cofins":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "3" }]
        }

Respuesta

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET /api/category/get_detail

Detalles de la categoría fiscal

Devuelve la configuración completa de una categoría fiscal: todos los escenarios de ICMS, IPI, PIS, COFINS, IBS/CBS, incluidas las matrices por UF (MVA, alícuotas, beneficios fiscales).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
category_id *	string	ID de la categoría fiscal

* Campo obligatorio.

Ejemplo de llamada

GET /api/category/get_detail?category_id=TF123

Respuesta

        {
          "success": true,
          "data": {
            "category_id": "TF123",
            "descricao": "Venda de mercadoria padrão",
            "disable_difal": false,
            "desconta_icms_pis_cofins": false,
            "icms": [{
              "tipo_tributacao": "normal",
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "nao_contribuinte": false,
              "codigo_cfop": "5102",
              "situacao_tributaria": "00",
              "aliquota_importacao": "",
              "aliquota_credito": 0,
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "motivo_desoneracao": "",
              "motivo_desoneracao_st": "",
              "aliquota_icms": [{"estado":"SP","aliquota":18}]
            }],
            "ipi":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"99","codigo_enquadramento":"999","aliquota":"0"}],
            "pis":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"0.65"}],
            "cofins": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"3"}],
            "ibs_cbs":[]
          }
        }

GET /api/category/get_list

Listar categorías fiscales

Lista las categorías fiscales de la empresa autenticada con paginación. Devuelve solo category_id y descricao de cada una — use /api/category/get_detail para la configuración completa.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–50)

* Campo obligatorio.

Ejemplo de llamada

GET /api/category/get_list?page=1&page_size=20

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF123", "descricao": "Venda de mercadoria padrão" },
              { "category_id": "TF124", "descricao": "Devolução de venda" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/category/edit

Editar categoría fiscal

Edita una categoría fiscal existente. El cuerpo es idéntico al de /api/category/create, con la única diferencia de que category_id es obligatorio y debe corresponder a una categoría existente. El upsert reemplaza completamente las matrices icms, ipi, pis, cofins, ibs_cbs, is — envíe todos los escenarios actualizados (no hay merge por escenario).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

La estructura completa del body está documentada en /api/category/create. Solo category_id tiene un tratamiento diferente aquí:

Campo	Tipo	Descripción
category_id *	string	ID de la categoría a editar (debe existir; en caso contrario devuelve error)
descricao *	string	Descripción
icms[] *	array	Escenarios ICMS (reemplaza completamente)
ipi[] *	array	Escenarios IPI
pis[] *	array	Escenarios PIS
cofins[] *	array	Escenarios COFINS
ibs_cbs[]	array	Escenarios IBS/CBS (opcional)
is[]	array	Escenarios IS (opcional)
disable_difal	boolean	Default: `false`
desconta_icms_pis_cofins	boolean	Default: `false`

* Campo obligatorio. Para los campos internos de cada array (icms[].codigo_cfop etc.), vea /api/category/create.

Respuesta

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

POST /api/category/delete

Eliminar categoría fiscal

Elimina una categoría fiscal de la empresa. Operación irreversible. Los productos vinculados a esta categoría seguirán referenciando el category_id eliminado, por lo que la emisión de NFe fallará — actualice los productos antes de eliminar.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
category_id *	string	ID de la categoría a eliminar

* Campo obligatorio.

Ejemplo de carga útil

        {
          "category_id": "TF123"
        }

Respuesta

        {
          "success": true
        }

GET /api/company/get_cep_detail

Consultar dirección por CEP

Resuelve un CEP brasileño devolviendo UF, código IBGE del municipio y datos de la dirección. Útil para rellenar direcciones de empresas y clientes. Requiere cuenta de distribuidor (b2b).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token del distribuidor (b2b — la cuenta debe tener `isb2b=true`)
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
cep *	string	CEP brasileño (8 dígitos, con o sin guion)

* Campo obligatorio.

Ejemplo de llamada

GET /api/company/get_cep_detail?cep=01001000

Respuesta

        {
          "success": true,
          "data": {
            "cep": "01001-000",
            "uf": "SP",
            "ibge": 3550308,
            "logradouro": "Praça da Sé",
            "bairro": "Sé",
            "localidade": "São Paulo",
            "ddd": "11"
          }
        }

GET /api/company/get_export_invoice_month_files

Listar archivos de exportación mensual ya generados

Devuelve la lista de archivos de exportación mensual ya generados para la empresa en el año actual (timezone America/Sao_Paulo). Cada mes puede tener hasta 4 archivos: 1 planilla Excel (solo estado Success) + 3 XMLs (por estado Success, Canceled y Voided). Solo aparecen los archivos efectivamente exportados — use /api/invoice/get_xml para generar nuevos.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Ejemplo de llamada

GET /api/company/get_export_invoice_month_files

Respuesta

Campo	Tipo	Descripción
files[]	array	Lista de archivos disponibles
files[].url	string	URL del archivo en OSS
files[].year	int	Año del periodo
files[].month	string	Mes (1–12)
files[].type	string	Tipo de archivo: `"xlsx"` o `"xml"`
files[].status	string	Estado de las facturas en el archivo: `"Success"`, `"Canceled"` o `"Voided"`
files[].create	datetime	Cuándo se generó el archivo

Ejemplo de respuesta

        {
          "success": true,
          "data": {
            "files": [
              {
                "url": "https://oss.example.com/.../2024_01_success.xlsx",
                "year": 2024,
                "month": "1",
                "type": "xlsx",
                "status": "Success",
                "create": "2024-02-01T03:15:00Z"
              },
              {
                "url": "https://oss.example.com/.../2024_01_success.zip",
                "year": 2024,
                "month": "1",
                "type": "xml",
                "status": "Success",
                "create": "2024-02-01T03:15:30Z"
              }
            ]
          }
        }

POST /api/invoice/return

Emitir NF-e de devolución

Emite una NF-e de devolución (modelo 55, finalidad 4) a partir de una NF-e original. Se admiten dos modos: devolución total (referencia la factura original mediante uuid o chave) o devolución parcial/personalizada (envía el cuerpo completo mediante return_detail).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body — campos de nivel superior

Campo	Tipo	Descripción
uuid	string	UUID de la NF-e original (obligatorio si `chave` está ausente; no se usa en modo `return_detail`)
chave	string	Clave de 44 dígitos de la NF-e original (obligatorio en modo `return_detail`; alternativa a `uuid` en modo simple)
cfop *	string	CFOP de la devolución (ej.: `"1202"`, `"1411"`, `"2202"`, `"5202"`, `"5411"`, `"6202"`)
natureza_operacao	string	Naturaleza de la operación (ej.: "Devolución de venta"). Alias aceptado: `nature_of_operation`
return_detail	object	Cuerpo completo de la NF-e de devolución. Misma estructura que `/api/invoice/create`, con una particularidad: dentro de `return_detail.cliente` el campo del número de dirección es `number` (en inglés), no `numero`. Cuando está ausente, la devolución es total y clona la NF-e original.

* Campo obligatorio. uuid O chave también es obligatorio (exactamente uno).

Ejemplo — devolución total

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolución de venta"
        }

Ejemplo — devolución parcial vía return_detail

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolución parcial",
          "return_detail": {
            "nature_of_operation": "Devolución parcial",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "cliente": { "cnpj": "12345678000199", "name": "Fornecedor", "endereco": "...", "bairro": "...", "city": "...", "uf": "SP", "cep": "01001000" },
            "products": [ { "name": "...", "ncm": "...", "count": 1, "unit": "UN", "unit_price": 100, "total_price": 100, "category_id": "...", "origem": 0, "indicador_total": 1 } ]
          }
        }

code Ejemplos Completos de Emisión de Factura

Ejemplo Completo con Transporte

{
  "nature_of_operation": "Venta de mercancía",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_final": "0",
  "ind_pres": "1",
  "cliente": {
    "cnpj": "12345678000199",
    "ie": "123456789",
    "name": "Empresa Cliente Ltda",
    "endereco": "Calle Ejemplo",
    "number": "123",
    "complemento": "Sala 45",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01234567",
    "telefone": "11999999999",
    "email": "contacto@empresa.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Smartphone XYZ",
      "ncm": "85171210",
      "cest": "2804000",
      "count": 2,
      "unit": "UN",
      "unit_price": 1500.00,
      "total_price": 3000.00,
      "category_id": "SU_CATEGORY_ID",
      "origem": "0",
      "indicador_total": "1"
    }
  ],
  "transportation": {
    "transport_mode": "0",
    "freight_amount": 30.00,
    "carrier_info": {
      "cnpj": "12345678000188",
      "name": "Transportadora Expressa",
      "endereco": "Calle de la Transportadora",
      "city": "São Paulo",
      "uf": "SP"
    },
    "vehicle_info": {
      "plate": "ABC1234",
      "uf": "SP",
      "rntc": "123456"
    },
    "packages": [
      {
        "qty": 1,
        "packaging_type": "CX",
        "gross_weight": 2.500,
        "net_weight": 2.000
      }
    ]
  },
  "shipping_address": {
    "cnpj": "12345678000199",
    "name": "Remetente Ltda",
    "endereco": "Calle del Remitente",
    "number": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000"
  },
  "delivery_address": {
    "cnpj": "98765432000111",
    "name": "Destinatário Ltda",
    "endereco": "Calle del Destinatario",
    "number": "200",
    "bairro": "Centro",
    "city": "Rio de Janeiro",
    "uf": "RJ",
    "cep": "20040020"
  },
  "pag_info": [
    {
      "payment_method": "03",
      "payment_indicator": "0",
      "card_info": {
        "integration_type": "1",
        "brand_code": "01"
      }
    }
  ],
  "informacoes_complementares": "Sem informações adicionais",
  "informacoes_fisco": "ICMS recolhido conforme legislação"
}

💡 INFORMACIÓN: Este ejemplo incluye todos los campos importantes mencionados en las capturas de pantalla, incluyendo transporte, información fiscal detallada y pago. Adapte los valores según su necesidad específica.

Ejemplo Completo Importación

{
  "id": "PED-IMP-001",
  "nature_of_operation": "Importacao para revenda",
  "transaction_type": "2",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "1",
  "finalidade": "1",
  "ind_final": "0",
  "ind_pres": "9",
  "cliente": {
    "name": "EXPORTADOR EXTERIOR CO LTD",
    "endereco": "Pudong District",
    "numero": "456",
    "city": "Shanghai",
    "id_estrangeiro": "CN-EXP-001",
    "c_pais": 1600,
    "x_pais": "CHINA"
  },
  "products": [
    {
      "name": "Fonte chaveada 12V 2A Quickfitting",
      "codigo": "123450000888",
      "ncm": "85044090",
      "count": 2,
      "unit": "PC",
      "unit_price": 0.25,
      "total_price": 0.50,
      "origem": 1,
      "indicador_total": "1",
      "category_id": "SU_CATEGORY_ID",
      "import_declarations": [
        {
          "nDI": "2312345678",
          "dDI": "2026-04-12",
          "xLocDesemb": "PORTO DE SANTOS",
          "UFDesemb": "SP",
          "dDesemb": "2026-04-15",
          "tpViaTransp": 1,
          "vAFRMM": 0.01,
          "tpIntermedio": 1,
          "cExportador": "EXP-CN-001",
          "additions": [
            {
              "nAdicao": 1,
              "nSeqAdic": 1,
              "cFabricante": "FAB-CN-001",
              "vDescDI": 0,
              "nDraw": ""
            }
          ]
        }
      ]
    },
    {
      "name": "Quick fitting MA",
      "codigo": "123450000157",
      "ncm": "85044090",
      "count": 2,
      "unit": "PC",
      "unit_price": 0.25,
      "total_price": 0.50,
      "origem": 1,
      "indicador_total": "1",
      "category_id": "SU_CATEGORY_ID",
      "ii": {
        "vBC": 0.50,
        "vDespAdu": 0.00,
        "vII": 0.00,
        "vIOF": 0.00
      },
      "import_declarations": [
        {
          "nDI": "2312345678",
          "dDI": "2026-04-12",
          "xLocDesemb": "PORTO DE SANTOS",
          "UFDesemb": "SP",
          "dDesemb": "2026-04-15",
          "tpViaTransp": 1,
          "vAFRMM": 1.00,
          "tpIntermedio": 1,
          "cExportador": "EXP-CN-001",
          "additions": [
            {
              "nAdicao": 1,
              "nSeqAdic": 2,
              "cFabricante": "FAB-CN-001",
              "vDescDI": 0,
              "nDraw": ""
            }
          ]
        }
      ]
    }
  ],
  "pag_info": [
    {
      "payment_method": "90",
      "payment_indicator": "0"
    }
  ]
}

💡 INFORMACIÓN: Ejemplo para NFe de Importación (CFOP 3.xxx). Diferencias respecto a una NFe nacional:

transaction_type: "2" — operación de entrada (importación).
cliente sin cnpj/cpf/uf/cep; usa id_estrangeiro, c_pais (tabla BACEN — China = 1600) y x_pais.
category_id debe apuntar a una categoría fiscal con CFOP 3.xxx y CST/CSOSN compatibles con importación.
origem del producto = 1 (extranjera — importación directa) o 2 (extranjera — adquirida en el mercado interno).
El bloque ii (Impuesto de Importación) es obligatorio cuando el CFOP es 3.xxx. Los valores provienen de la DI emitida por el despachante aduanero (vBC, vDespAdu, vII, vIOF). Puede ser cero en pruebas.
El bloque import_declarations (Declaración de Importación) contiene datos del despacho aduanero: nDI, dDI, lugar/UF/fecha de despacho, vía de transporte, intermediario, exportador y adiciones.
vAFRMM es obligatorio cuando tpViaTransp = 1 (Marítima).

vpn_key Autenticación

Todas las peticiones deben incluir los siguientes headers:

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

Observación: 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();
    }
}

Importante: Al calcular el sign, el Path incluye la query string para solicitudes GET. Ejemplo: /api/nfce/category/get_detail?category_id=TF123. Para solicitudes POST, el Path es solo la ruta (ej: /api/company/create).

percent Parámetros Tributarios Detallados

scale_balance Parámetros ICMS

Escenario de Tributación

padrao salida_fuera_estado salida_dentro_estado entrada_fuera_estado entrada_dentro_estado

Situación Tributaria (CST)

00: Tributada integralmente

02: Tributada exenta

10: Tributada con cobro del ICMS

20: Con reducción de base de cálculo

30: Exenta o no tributada

40: Exenta

41: No tributada

50: Suspensión

51: Diferimiento

60: ICMS cobrado anteriormente

70: Reducción y cobro

90: Otras

pie_chart Parámetros PIS/COFINS

Escenario de Tributación

padrao salida_fuera_estado salida_dentro_estado entrada_fuera_estado entrada_dentro_estado

Situación Tributaria (CST)

01: Operación Tributable (alícuota normal)

02: Operación Tributable (alícuota diferenciada)

03: Operación Tributable (exenta)

04: Operación Tributable (suspensión)

05: Operación Tributable (ST)

06: Operación Tributable (alícuota cero)

07: Operación Exenta de la Contribución

08: Operación sin Incidencia de la Contribución

09: Operación con Suspensión de la Contribución

49: Otras Operaciones de Salida

50: Derecho a crédito (operaciones propias)

51: Derecho a crédito (adquisiciones)

52: Asiento a crédito

53: Asiento a débito

54: Asiento a crédito (extemporáneo)

55: Asiento a débito (extemporáneo)

56: Crédito Presunto

60: Crédito Presunto (adquisiciones)

61: Crédito Presunto (importación)

62: Crédito Presunto (actividad rural)

63: Crédito Presunto (otras)

64: Crédito Presunto (no generador)

65: Crédito Presunto (sustitución)

66: Crédito Presunto (sustitución)

67: Crédito Presunto (exportación)

70: Operación de Adquisición sin Derecho a Crédito

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

75: Operación de Adquisición por Sustitución

98: Otras Operaciones de Entrada

99: Otras Operaciones

💡 INFORMACIÓN: Los campos tipo_pessoa aceptan valores fisica (persona física) o juridica (persona jurídica). Para PIS/COFINS, el campo aliquota debe ser formateado como string con dos decimales (ej: "1.65").

credit_card Parámetros de Pago

Indicador de Pago

`0`	Al contado
`1`	A plazos

Métodos de Pago

`01`	Efectivo
`02`	Cheque
`03`	Tarjeta de Crédito
`04`	Tarjeta de Débito
`05`	Crédito Tienda
`10`	Vale Alimentación
`11`	Vale Comida
`12`	Vale Regalo
`13`	Vale Combustible
`15`	Boleto Bancario
`90`	Sin Pago
`99`	Otros

Banderas de Tarjeta

`01`	Visa
`02`	Mastercard
`03`	American Express
`04`	Sorocred
`05`	Diners Club
`06`	Elo
`07`	Hipercard
`08`	Aura
`09`	Cabal
`99`	Otros

bug_report Solución de Problemas con XML

warning Rechazo 225 - Fallo en el Schema XML

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

Verificar si la NF-e fue autorizada (estado "Autorizada")

Reemitir la NF-e si no fue autorizada

Inutilizar número si no fue utilizado

lightbulb Validación Online de la SEFAZ

Use el validador oficial para identificar problemas en el XML:


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

Problemas comunes: Dirección incompleta, NCM inválido, formato de valores incorrecto, campos obligatorios ausentes.

error Códigos de Error de la SEFAZ

Código	Descripción	Solución
`217`	Fecha de emisión muy atrasada	Emitir en contingencia o regularizar
`404`	CNPJ/CPF del destinatario inválido	Verificar documento del cliente
`563`	CFOP no permitido para la operación	Revisar CFOP de la operación

Otros Endpoints

4. Listar Categorías: GET /api/category/get_list

5. Detalles de la Categoría: GET /api/category/get_detail

6. Editar Categoría: POST /api/category/edit

7. Eliminar Categoría: POST /api/category/delete

Ejemplos de CFOP (Código Fiscal de Operaciones):

5102: Venta de mercancía adquirida de terceros - dentro del estado

6102: Venta de mercancía adquirida de terceros - para otro estado

6108: Venta de mercancía adquirida de terceros - para otro estado (persona física)

1000: Entrada de mercancía

speed

Límites y Rate Limiting

Políticas de uso de la API

Límites por Plan

Plan Free	100 peticiones/día
Plan Basic	1.000 peticiones/día
Plan Pro	10.000 peticiones/día
Plan Enterprise	Personalizado

Valores para `transport_mode`:

0: Contratación del Flete por cuenta del Remitente (CIF)

1: Contratación del Flete por cuenta del Destinatario (FOB)

2: Contratación del Flete por cuenta de Terceros

3: Transporte Propio por cuenta del Remitente

4: Transporte Propio por cuenta del Destinatario

9: Sin Ocurrencia de Transporte

Ejemplos de CFOP (Código Fiscal de Operaciones):

5102: Venta de mercancía adquirida de terceros - dentro del estado

6102: Venta de mercancía adquirida de terceros - para otro estado

6108: Venta de mercancía adquirida de terceros - para otro estado (persona física)

1000: Entrada de mercancía

assessment Informes NFe

Genere informes detallados de las Facturas Electrónicas (NF-e) emitidas, con filtros por período, estado y tipo de operación. Ideal para seguimiento fiscal, auditorías y control gerencial.

1. Informe de Facturas Emitidas

GET /api/invoice/report

Parámetros de Solicitud (Query)

Parámetro	Obligatorio	Tipo	Descripción
company_id	Sí	String	ID de la empresa
start_date	Sí	Date	Fecha de inicio del período (YYYY-MM-DD)
end_date	Sí	Date	Fecha final del período (YYYY-MM-DD)
status	No	String	Filtrar por estado: `AUTHORIZED`, `CANCELED`, `DENIED`, `ALL` (predeterminado)
model	No	String	Modelo del documento: `nfe`, `nfce`, `all` (predeterminado)
format	No	String	Formato de salida: `json` (predeterminado), `csv`, `pdf`
page	No	Integer	Número de página (predeterminado: 1)
per_page	No	Integer	Registros por página (predeterminado: 50, máx: 200)

Ejemplo de Solicitud

GET /api/invoice/report?company_id=comp_123456&start_date=2024-01-01&end_date=2024-01-31&status=AUTHORIZED&format=json

Ejemplo de Respuesta

{
  "success": true,
  "data": {
    "summary": {
      "total_invoices": 152,
      "total_value": 458320.50,
      "authorized": 145,
      "canceled": 5,
      "denied": 2
    },
    "invoices": [
      {
        "invoice_id": "nf_789012",
        "number": 1045,
        "series": 1,
        "access_key": "35210112345678901234...",
        "status": "AUTHORIZED",
        "issue_date": "2024-01-10T10:30:00Z",
        "total_value": 3000.00,
        "customer_name": "Empresa Cliente Ltda",
        "customer_document": "12.345.678/0001-99",
        "nature_of_operation": "VENDA",
        "model": "nfe"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_pages": 4,
      "total_records": 152
    }
  }
}

2. Informe Resumido por Período

GET /api/invoice/report/summary

Retorna un resumen consolidado de las operaciones fiscales agrupadas por mes, con totales de valor, cantidad e impuestos.

Parámetros de Solicitud (Query)

Parámetro	Obligatorio	Tipo	Descripción
company_id	Sí	String	ID de la empresa
year	Sí	Integer	Año de referencia (ej: 2024)
group_by	No	String	Agrupar por: `month` (predeterminado), `week`, `day`

Ejemplo de Respuesta

{
  "success": true,
  "data": {
    "company_id": "comp_123456",
    "year": 2024,
    "periods": [
      {
        "period": "2024-01",
        "total_invoices": 152,
        "total_value": 458320.50,
        "total_tax": 82497.69,
        "authorized": 145,
        "canceled": 5,
        "denied": 2
      },
      {
        "period": "2024-02",
        "total_invoices": 178,
        "total_value": 523180.75,
        "total_tax": 94172.54,
        "authorized": 170,
        "canceled": 6,
        "denied": 2
      }
    ]
  }
}

3. Exportar Informe

POST /api/invoice/report/export

Genera y exporta el informe completo en formato PDF o CSV. La exportación se procesa de forma asíncrona y devuelve una URL de descarga cuando se completa.

Payload Request

{
  "company_id": "comp_123456",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "format": "pdf",
  "status": "ALL",
  "include_details": true,
  "include_taxes": true
}

Ejemplo de Respuesta

{
  "success": true,
  "message": "Informe en procesamiento",
  "data": {
    "report_id": "rpt_abc123",
    "status": "processing",
    "estimated_time": "30s",
    "callback_url": "https://api.tffiscal.com/v1/report/status/rpt_abc123"
  }
}

Respuesta Después del Procesamiento

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "status": "completed",
    "download_url": "https://storage.tffiscal.com/reports/rpt_abc123.pdf",
    "expires_at": "2024-02-01T23:59:59Z",
    "file_size": "2.4 MB"
  }
}

💡 CONSEJO: Use el parámetro format=csv para integrar los datos con sistemas ERP u hojas de cálculo. El formato PDF es ideal para presentaciones y auditorías fiscales.

⚠️ ATENCIÓN: El período máximo permitido por consulta es de 12 meses. Para informes anuales completos, utilice el endpoint de exportación (/report/export). Las consultas con grandes volúmenes de datos pueden tardar algunos segundos en procesarse.

vpn_key Autenticación Global del TF Hub

Todas las APIs del TF Hub utilizan un sistema unificado de autenticación.

Headers Obligatorios

Header	Valor	Descripción
X-API-Key	String	Clave de la API proporcionada en el panel
X-Timestamp	Unix Timestamp	Timestamp de la petición en milisegundos
X-Signature	String	Firma HMAC-SHA256

point_of_sale NFC-e — Factura Electrónica de Consumidor

Base URL (Producción)

https://api.tffiscal.com

Autenticación

Headers: sign, timestamp, token

Requisitos

Certificado Digital A1 válido (.pfx o .p12)
CSC (Código de Seguridad del Contribuyente)
CSC ID (Identificador del CSC en SEFAZ)

La NFC-e (modelo 65) es el documento fiscal electrónico para ventas minoristas al consumidor final, ya sea presencial o por entrega a domicilio. Reemplaza el antiguo cupón fiscal (ECF).

Características de la NFC-e:

Siempre operación interna (dentro del estado) — sin DIFAL
Sin IPI (Impuesto sobre Producto Industrializado)
Destinatario opcional para ventas presenciales (ind_pres: "1")
Destinatario obligatorio para entregas a domicilio (ind_pres: "4")
Requiere CSC (Código de Seguridad del Contribuyente) para generación del código QR

Autenticación

Todos los endpoints NFC-e utilizan la misma autenticación de la API principal:

Header	Tipo	Descripción
token	string	Token de la empresa (obtenido en el registro)
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Importante: Al calcular el sign, el path incluye la query string para solicitudes GET. Ejemplo: /api/nfce/category/get_detail?category_id=TF123. Para solicitudes POST, el path es solo la ruta (ej: /api/nfce/company/create).

compare_arrows NFe vs NFC-e — ¿Qué cambia para el integrador?

Si ya ha integrado la NFe (modelo 55), la integración de la NFC-e (modelo 65) es muy similar. A continuación se detallan las diferencias clave que necesita conocer.

apartment Registro de Empresa

Aspecto	NFe `/api/company/create`	NFC-e `/api/nfce/company/create`
Campos básicos	cnpj, name, alias, ie, invoice_type, dirección, certificado digital	Iguales a NFe — mismos campos obligatorios
CSC	No se utiliza	Obligatorio — `csc_id` y `csc` (obtenidos en el portal de la SEFAZ)
Serie / Numeración	`serie` y `number`	`serie_nfce` y `number_nfce` — numeración independiente de la NFe
Token retornado	Mismo `token` — si la empresa ya existe, los campos NFC-e se añaden automáticamente

Consejo: Si la empresa ya fue registrada para NFe, simplemente llame a /api/nfce/company/create con el mismo CNPJ. El sistema reconocerá la empresa existente y añadirá los campos NFC-e (CSC, serie, numeración). El token permanece igual.

receipt_long Emisión de Factura

Aspecto	NFe `/api/invoice/create`	NFC-e `/api/nfce/create`
Destinatario	Siempre obligatorio (CNPJ/CPF, nombre, dirección completa)	Opcional para ventas presenciales; obligatorio solo para entrega a domicilio (`ind_pres: "4"`)
Indicador de presencia	No se utiliza	Obligatorio — `ind_pres`: `"1"` presencial, `"4"` entrega a domicilio
Impuestos calculados	ICMS, PIS, COFINS, IPI, DIFAL (interestatal)	ICMS, PIS, COFINS — sin IPI, sin DIFAL (siempre operación interna)
CFOP	Varía (5xxx interno, 6xxx interestatal)	Siempre 5xxx (operación interna) — ej: `5102`
Pago	Opcional	Obligatorio — `pag_info` con forma de pago (efectivo, PIX, tarjeta, etc.)
Campos del producto	Iguales — misma estructura (codigo, name, ncm, count, unit, unit_price, total_price, category_id, cfop, origem)
Cancelación	Plazo de 24 horas	Plazo de 30 minutos (varía por estado)
DANFE	PDF A4	Cupón térmico (rollo 80mm) con código QR

Resumen: Si ya integró la NFe, para integrar la NFC-e solo necesita:

Registrar el CSC de la empresa (/api/nfce/company/create)
Cambiar el endpoint de emisión a /api/nfce/create
Agregar ind_pres y pag_info al payload
Eliminar datos de IPI/DIFAL (si los hay)

POST /api/nfce/company/create

Registrar empresa para NFC-e

Registra (o actualiza) una empresa para la emisión de NFC-e. Razón social, IE, dirección y otros datos se extraen automáticamente vía SintegraWS a partir del CNPJ. Si el CNPJ ya existe para el usuario, se actualizan los campos NFC-e y se devuelve la empresa existente.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token del distribuidor (b2b)
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
cnpj *	string	CNPJ de la empresa emisora
cert_file *	string	URL HTTPS del certificado digital A1 (.pfx o .p12)
cert_pwd *	string	Contraseña del certificado
csc_id *	string	ID del CSC (Código de Seguridad del Contribuyente) en SEFAZ
csc *	string	Token CSC (secreto compartido con SEFAZ)
serie_nfce	int	Serie de la NFC-e
number_nfce	int	Número inicial de NFC-e
telefone	string	Teléfono de la empresa

* Campo obligatorio. Los demás datos (nombre, IE, dirección, etc.) se extraen automáticamente vía SintegraWS desde el CNPJ.

Ejemplo de carga útil

        {
          "cnpj": "12345678000199",
          "cert_file": "https://ejemplo.com/cert.pfx",
          "cert_pwd": "senha_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

Respuesta

        {
          "success": true,
          "message": "Empresa registrada para NFC-e",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/nfce/company/update

Actualizar datos de la empresa NFC-e

Actualiza la empresa NFC-e identificada por el header token. Todos los campos del body son opcionales — envíe solo los que desee modificar. Al actualizar cep, el sistema resuelve automáticamente stateCode e ibge. Cuando cert_file y cert_pwd vienen juntos, el certificado se valida antes de guardar.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body (todos los campos opcionales — envíe ≥ 1)

Campo	Tipo	Descripción
Identificación
name	string	Razón social
alias	string	Nombre comercial
ie	string	Inscripción Estatal
invoice_type	string	Régimen tributario
email	string	Correo electrónico
telefone	string	Teléfono
Dirección
cep	string	Código postal (actualiza automáticamente `stateCode` e `ibge`)
address	string	Dirección
house_number	string	Número
complemento	string	Complemento
town	string	Barrio
city	string	Ciudad
state	string	UF
NFC-e
csc_id	string	ID del CSC
csc	string	Token CSC
serie_nfce	int	Serie
number_nfce	int	Próximo número
cert_file	string	URL HTTPS del nuevo certificado A1 (.pfx o .p12)
cert_pwd	string	Contraseña del certificado

Al menos 1 campo en el body es obligatorio. CNPJ es inmutable.

Ejemplo de carga útil

        {
          "alias": "Tienda Centro - Sucursal 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

Respuesta

        {
          "success": true,
          "message": "Empresa NFC-e actualizada con éxito"
        }

POST /api/nfce/company/get

Consultar empresa NFC-e

Devuelve los datos de la empresa NFC-e identificada por el header token. Atención: el método es POST pero no hay campos en el body — la empresa se resuelve solo por el token.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Vacío. Puede enviarse {}.

Respuesta

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "cnpj": "12345678000199",
            "name": "Empresa Exemplo LTDA",
            "alias": "Tienda Centro",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contacto@empresa.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Calle Ejemplo",
            "house_number": "100",
            "complemento": "Sala 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://ejemplo.com/cert.pfx",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

Gestión de Categorías Fiscales NFC-e

Las categorías fiscales definen las reglas tributarias aplicadas a los productos al emitir NFC-e. A diferencia de la NFe, la NFC-e solo opera con ventas intraestatales, por lo que la estructura es simplificada: un solo objeto por impuesto, sin necesidad de múltiples escenarios.

Nota: Las categorías NFC-e se almacenan por separado de las categorías NFe. Cada categoría incluye configuraciones de ICMS, PIS, COFINS e IBS/CBS. Todos los endpoints de esta sección requieren los headers token, sign y timestamp.

POST /api/nfce/category/create

Crear categoría fiscal NFC-e

Crea una categoría fiscal NFC-e. Cada categoría tiene un único escenario (salida interna) y usa objetos planos para ICMS, PIS, COFINS e IBS/CBS (sin array, ya que NFC-e no permite múltiples escenarios por categoría). No incluye IPI.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body (raíz)

Campo	Tipo	Descripción
descricao *	string	Descripción de la categoría
codigo_cfop *	string	Código CFOP (ej.: 5102, 5405)
icms *	object	Configuración de ICMS (objeto plano)
pis *	object	Configuración de PIS (objeto plano)
cofins *	object	Configuración de COFINS (objeto plano)
ibs_cbs	object	Configuración de IBS/CBS (Reforma Tributaria, opcional)

icms

Campo	Tipo	Descripción
situacao_tributaria *	string	CST/CSOSN (ej.: 102, 500)
aliquota_reducao	decimal	Porcentaje de reducción de base
motivo_desoneracao	string	Código del motivo de exoneración
aliquota_icms	array	Alícuotas por estado: `[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_fcp	array	FCP por estado: `[{ "estado": "SP", "aliquota": 0.00 }]`
beneficio_fiscal	array	Beneficio fiscal por estado: `[{ "estado": "SP", "codigo": "SP800001" }]`

pis / cofins

Campo	Tipo	Descripción
situacao_tributaria *	string	CST PIS/COFINS
aliquota *	string	Alícuota porcentual (ej.: "0.00", "1.65", "7.60")

ibs_cbs (opcional)

Campo	Tipo	Descripción
situacao_tributaria *	string	CST IBS/CBS
classificacao_tributaria *	string	Código de clasificación tributaria

* Campo obligatorio.

Ejemplo de payload

        {
          "descricao": "Bebidas não alcoólicas",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

Respuesta

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

GET /api/nfce/category/get_detail

Obtener detalles de la categoría fiscal NFC-e

Devuelve los datos completos de una categoría fiscal NFC-e (descripción, CFOP, ICMS, PIS, COFINS y IBS/CBS).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Query string

Campo	Tipo	Descripción
category_id *	string	ID de la categoría NFC-e

* Campo obligatorio.

Ejemplo de solicitud

GET /api/nfce/category/get_detail?category_id=TF00001

Respuesta

        {
          "success": true,
          "data": {
            "category_id": "TF00001",
            "descricao": "Bebidas não alcoólicas",
            "codigo_cfop": "5102",
            "icms": {
              "situacao_tributaria": "102",
              "aliquota_icms": [
                { "estado": "SP", "aliquota": 18.00 }
              ],
              "aliquota_fcp": [
                { "estado": "SP", "aliquota": 0.00 }
              ],
              "beneficio_fiscal": [
                { "estado": "SP", "codigo": "SP800001" }
              ]
            },
            "pis": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "cofins": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "ibs_cbs": {
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001"
            }
          }
        }

GET /api/nfce/category/get_list

Listar categorías fiscales NFC-e

Devuelve una lista paginada de categorías fiscales NFC-e registradas para la empresa autenticada.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Query string

Campo	Tipo	Descripción
page *	int	Número de página (mínimo 1)
page_size *	int	Ítems por página (1 a 50)

* Campo obligatorio.

Ejemplo de solicitud

GET /api/nfce/category/get_list?page=1&page_size=20

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF00001", "descricao": "Bebidas não alcoólicas" },
              { "category_id": "TF00002", "descricao": "Alimentos industrializados" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/nfce/category/edit

Editar categoría fiscal NFC-e

Nota: Misma estructura que el endpoint /api/nfce/category/create, con el campo adicional obligatorio category_id. Los campos icms, pis, cofins y ibs_cbs se reemplazan íntegramente (no se fusionan).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Campo adicional

Campo	Tipo	Descripción
category_id *	string	ID de la categoría a editar

* Campo obligatorio.

Ejemplo de payload

        {
          "category_id": "TF00001",
          "descricao": "Bebidas não alcoólicas — atualizado",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

Respuesta

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

POST /api/nfce/category/delete

Eliminar categoría fiscal NFC-e

Elimina una categoría fiscal NFC-e. Operación irreversible. Los productos vinculados a esta categoría seguirán referenciando el category_id eliminado — actualícelos primero.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
category_id *	string	ID de la categoría NFC-e a eliminar

* Campo obligatorio.

Ejemplo de carga útil

        {
          "category_id": "TF123"
        }

Respuesta

        {
          "success": true
        }

POST /api/nfce/create

Emitir NFC-e

Emite una NFC-e (modelo 65, siempre salida interna al estado, sin flete). Diferencias clave respecto al endpoint de NFe: el objeto del consumidor se llama client (no cliente); el número del domicilio es client.number; el consumidor es opcional; no existen impostos.ipi, shipping_address, delivery_address ni transportation. El campo de valor en pag_info se llama amount.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa NFC-e
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body (raíz)

Campo	Tipo	Descripción
nature_of_operation *	string	Naturaleza de la operación (ej.: "Venta de mercadería")
issuance_type *	string	Tipo de emisión: "1" (normal), "9" (contingencia off-line NFC-e)
ambiente *	string	"1" producción, "2" homologación
products *	array	Lista de productos (ver detalles abajo)
id	string	Identificador externo
ind_pres	string	Presencia del comprador: "1" presencial (default), "4" entrega a domicilio, "5" presencial fuera del establecimiento, "9" no aplica
ind_intermed	string	"0" sin intermediario, "1" marketplace. Obligatorio cuando `ind_pres` = 2, 3 o 4
total_discount_amount	decimal	Descuento total de la factura
troco	decimal	Valor del vuelto
seguro	decimal	Valor del seguro
outras_despesas	decimal	Otros gastos accesorios
informacoes_complementares	string	Información complementaria al consumidor
informacoes_fisco	string	Información de interés fiscal
client	object	Datos del consumidor (opcional — ver tabla)
pag_info	array	Pagos (default: dinero al contado — ver tabla)

client (opcional)

Complete solo si el consumidor está identificado. CPF o CNPJ deben enviarse solo con dígitos.

Campo	Tipo	Descripción
cpf	string	CPF (define persona física)
cnpj	string	CNPJ (persona jurídica)
ie	string	Inscripción estatal
name	string	Nombre / razón social
endereco	string	Dirección
number	string	Número del domicilio (atención: distinto de la NFe, que usa `numero`)
complemento	string	Complemento
bairro	string	Barrio
city	string	Ciudad
uf	string	UF (validada por el CEP, si se informa)
cep	string	Código postal (solo dígitos)
telefone	string	Teléfono
email	string	E-mail

products[] (cada ítem)

Campo	Tipo	Descripción
name *	string	Nombre del producto (caracteres CJK se eliminan)
ncm *	string	NCM (8 dígitos)
count *	decimal	Cantidad
unit *	string	Unidad comercial (ej.: "UN", "KG")
unit_price *	decimal	Precio unitario
total_price *	decimal	Valor total del ítem
origem *	int	Origen de la mercadería (0..8)
indicador_total *	int	1 = compone el total de la factura; 0 = no compone
category_id ⚠	string	ID de categoría fiscal NFC-e (obligatorio si no envía `impostos`)
impostos ⚠	object	Impuestos manuales (alternativa a `category_id`; sin IPI)
tax_info ⚠	object	Alias de `impostos` (misma estructura). Solo se usa si `impostos` está ausente
codigo	string	Código interno del producto
cest	string	CEST
gtin	string	GTIN/EAN comercial
gtin_tributavel	string	GTIN tributable
discount_price	decimal	Descuento del ítem
nItemPed	int	Ítem del Pedido de Compra (I61). Número secuencial del ítem dentro del pedido referenciado en `xPed` (viene de `id` de raíz). Valores válidos: 1–999999. Default: omitido.

pag_info[] (cada ítem)

Campo	Tipo	Descripción
payment_indicator *	string	"0" contado, "1" a crédito
payment_method *	string	Forma de pago (01=efectivo, 03=tarjeta crédito, 04=tarjeta débito, 17=PIX, 99=otros, etc.)
amount	decimal	Monto pagado en esta forma
card_info.integration_type	string	"1" integrado, "2" no integrado (obligatorio para tarjeta 03/04)
card_info.brand_code	string	Marca de la tarjeta (obligatorio para tarjeta 03/04)
card_info.acquirer_cnpj	string	CNPJ del adquirente
card_info.authorization_code	string	Código de autorización

* Campo obligatorio. ⚠ category_id, impostos o tax_info, uno de los tres es obligatorio.

Ejemplo simplificado

{
  "nature_of_operation": "Venda de mercadoria",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_pres": "1",
  "client": {
    "cpf": "12345678909",
    "name": "Consumidor Final"
  },
  "products": [
    {
      "name": "Refrigerante 2L",
      "ncm": "22021000",
      "count": 2,
      "unit": "UN",
      "unit_price": 10.50,
      "total_price": 21.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001"
    }
  ],
  "pag_info": [
    {
      "payment_indicator": "0",
      "payment_method": "17",
      "amount": 21.00
    }
  ]
}

Ejemplo completo (todos los campos)

{
  "id": "PEDIDO-2026-0001",
  "nature_of_operation": "Venda de mercadoria",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_pres": "1",
  "ind_intermed": "0",
  "total_discount_amount": 0.00,
  "troco": 0.00,
  "seguro": 0.00,
  "outras_despesas": 0.00,
  "informacoes_complementares": "Pedido entregue na loja",
  "informacoes_fisco": "ICMS recolhido conforme legislação",
  "client": {
    "cpf": "12345678909",
    "cnpj": "",
    "ie": "",
    "name": "Consumidor Final",
    "endereco": "Rua das Flores",
    "number": "100",
    "complemento": "Sala 5",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000",
    "telefone": "11999998888",
    "email": "cliente@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Refrigerante 2L",
      "ncm": "22021000",
      "cest": "0300100",
      "gtin": "7891234567890",
      "gtin_tributavel": "7891234567890",
      "count": 2,
      "unit": "UN",
      "unit_price": 10.50,
      "total_price": 21.00,
      "discount_price": 0.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001",
      "nItemPed": 1
    },
    {
      "codigo": "PROD002",
      "name": "Salgadinho 100g",
      "ncm": "19053100",
      "count": 1,
      "unit": "UN",
      "unit_price": 8.00,
      "total_price": 8.00,
      "origem": 0,
      "indicador_total": 1,
      "impostos": {
        "icms": {
          "codigo_cfop": "5102",
          "situacao_tributaria": "102",
          "industria": "",
          "tipo_pessoa": "juridica"
        },
        "pis": {
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "cofins": {
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "ibs_cbs": {
          "situacao_tributaria": "000",
          "tipo_pessoa": "juridica",
          "classificacao_tributaria": "000001"
        }
      }
    }
  ],
  "pag_info": [
    {
      "payment_indicator": "0",
      "payment_method": "03",
      "amount": 24.00,
      "card_info": {
        "integration_type": "1",
        "brand_code": "01",
        "acquirer_cnpj": "01234567000189",
        "authorization_code": "AUTH123456"
      }
    }
  ]
}

Respuesta

        {
          "success": true,
          "data": {
            "uuid": "abc123...",
            "chave": "35..."
          }
        }

POST /api/nfce/cancel

Cancelar NFC-e

Cancela una NFC-e ya autorizada. A diferencia de la NFe, aquí el motivo de la cancelación lo proporciona el cliente y se envía a SEFAZ. La ventana de cancelación en SEFAZ es corta (normalmente 15-30 minutos tras la autorización).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chave *	string	Clave de 44 dígitos de la NFC-e (atención: aquí es `chave`, no `uuid` como en otros endpoints)
motivo *	string	Justificación de la cancelación (mínimo 15 caracteres por exigencia SEFAZ)

* Campo obligatorio.

Ejemplo de carga útil

        {
          "chave": "35210112345678901234650010000000051234567890",
          "motivo": "Cancelamento por erro de operacao do caixa"
        }

GET /api/nfce/get_detail

Consultar detalles de la NFC-e

Devuelve los detalles de una NFC-e específica por UUID. Incluye URLs del XML y del DANFE (cupón térmico), además de los datos del cliente cuando se proporcionan.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
uuid *	string	UUID de la NFC-e

* Campo obligatorio.

Ejemplo de llamada

GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

Respuesta

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234650010000000051234567890",
            "serie": 1,
            "number": 5,
            "status": "Authorized",
            "modelo": "nfce",
            "total_price": 145.90,
            "nprot": "135210000123456",
            "motivo": "",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave_nfce.pdf",
            "client_cpf": "12345678909",
            "client_cnpj": "",
            "client_name": "Cliente",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/nfce/get_danfe

Generar / obtener DANFE NFC-e (cupón térmico)

Devuelve la URL del DANFE NFC-e (cupón fiscal electrónico) en PDF, con código QR para consulta en SEFAZ. Generación bajo demanda con caché por hash (clave + estado); las llamadas repetidas devuelven la URL existente.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
uuid *	string	UUID de la NFC-e (atención: aquí es `uuid`, a diferencia de `cancel` que usa `chave`)

* Campo obligatorio.

Ejemplo de carga útil

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

Respuesta

        {
          "success": true,
          "data": {
            "danfe": "https://oss.example.com/.../chave_nfce.pdf"
          }
        }

codeEjemplos Completos NFC-e

Ejemplo 1 — Venta Presencial (sin destinatario)

{
  "nature_of_operation": "Venda de mercadoria", "ambiente": "2", "ind_pres": "1",
  "products": [{ "codigo": "001", "name": "Refrigerante 350ml", "ncm": "22021000", "count": 3,
    "unit": "UN", "unit_price": 5.50, "total_price": 16.50, "category_id": "BEBIDAS",
    "origem": "0", "indicador_total": "1", "cfop": "5102" }],
  "pag_info": [{ "payment_indicator": "0", "payment_method": "17" }]
}

Ejemplo 2 — Entrega a Domicilio (con destinatario)

{
  "nature_of_operation": "Venda de mercadoria", "ambiente": "2", "ind_pres": "4",
  "client": { "cpf": "12345678900", "name": "Maria Silva", "endereco": "Rua das Flores",
    "number": "456", "bairro": "Jardim Primavera", "city": "São Paulo", "uf": "SP", "cep": "04567000" },
  "products": [{ "codigo": "PIZZA01", "name": "Pizza Grande Marguerita", "ncm": "19059090", "count": 1,
    "unit": "UN", "unit_price": 45.90, "total_price": 45.90, "category_id": "ALIMENTOS",
    "origem": "0", "indicador_total": "1", "cfop": "5102" }],
  "pag_info": [{ "payment_indicator": "0", "payment_method": "03" }],
  "frete": 8.00, "informacoes_complementares": "Entrega em até 40 minutos"
}

tune NFe Ajuste / Complementaria

La NFe Complementaria y la NFe de Ajuste son facturas fiscales emitidas para corregir valores fiscales de una factura ya autorizada. A diferencia de la CC-e, que solo corrige datos de registro, estas facturas permiten alterar valores de impuestos, cantidades y precios.

NFe Complementaria (finalidade = 2):

Utilizada para agregar valores que fueron informados de menos en la factura original
Complemento de precio, cantidad o valor del impuesto
Ejemplo: se emitio factura con ICMS del 12% pero lo correcto era 18% — se emite complementaria con la diferencia

NFe de Ajuste (finalidade = 3):

Utilizada para ajustes fiscales diversos previstos en la legislacion
Ajuste de inventario, transferencia de credito, regularizacion fiscal
Ejemplo: ajuste de ICMS por liquidacion, transferencia de credito entre sucursales

Importante:

Ambas son facturas fiscales nuevas — generan nueva clave de acceso y nuevo numero
Deben referenciar la factura original por el campo ref_nfe_chave (clave de 44 digitos)
La factura original necesita estar autorizada
Consumen 1 credito cada una (como una emision normal)

Autenticacion

Utiliza el mismo endpoint y autenticacion de la emision de NFe:

Header	Tipo	Descripcion
token	string	Token de la empresa (obtenido en el registro)
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

description NFS-e - Factura Electronica de Servicios

La API de NFS-e permite emitir, cancelar y consultar Facturas Electronicas de Servicio. El sistema detecta automaticamente el municipio de la empresa y enruta a la API correcta:

Sao Paulo (SP) - Emision via Nota Fiscal Paulistana (SOAP)
Otros municipios - Emision via API Nacional (ADN/SEFIN)

El integrador no necesita preocuparse por cual API usar - solo envie los datos y el sistema enruta automaticamente por el codigo IBGE del municipio registrado en la empresa.

Endpoint	Metodo	Descripcion
`/api/nfse/create`	POST	Emitir NFS-e
`/api/nfse/cancel`	POST	Cancelar NFS-e
`/api/nfse/get_danfse`	POST	Obtener DANFSE (PDF)
`/api/nfse/get_xml`	POST	Descargar XML

POST /api/nfs/company/create

Registrar empresa para emisión de NFS-e

Registra (o actualiza) una empresa para emisión de NFS-e. Si el CNPJ ya existe para el usuario, solo los campos NFS-e y el certificado se actualizan; de lo contrario, se crea una nueva empresa y se devuelve un token dedicado. Atención al path: /api/nfs/... (sin la "e"), distinto de los demás endpoints NFS-e.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token B2B del integrador
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
cnpj *	string	CNPJ de la empresa (solo dígitos)
name *	string	Razón social
cep *	string	Código postal (solo dígitos)
address *	string	Dirección
house_number *	string	Número del domicilio
town *	string	Barrio
city *	string	Ciudad
state *	string	UF (2 dígitos, ej.: "SP")
cert_file *	string	URL del certificado digital A1 (.pfx)
cert_pwd *	string	Contraseña del certificado digital
im *	string	Inscripción Municipal
codigo_municipio_nfse *	string	Código IBGE del municipio emisor
codigo_servico_nfse *	string	Código de servicio por defecto (LC 116)
alias	string	Nombre comercial
ie	string	Inscripción estatal
invoice_type	string	Régimen tributario
unit	string	Unidad / sucursal
email	string	E-mail de contacto
telefone	string	Teléfono
complemento	string	Complemento del domicilio
cnae_nfse	string	CNAE de la actividad por defecto
serie_nfse	int	Serie inicial de la NFS-e
number_nfse	int	Número inicial de la NFS-e
regime_especial_tributacao	int	Código del régimen especial de tributación
optante_simples_nacional	bool	Optante por Simples Nacional

* Campo obligatorio.

Ejemplo de payload

        {
          "cnpj": "43649380000100",
          "name": "EMPRESA EXEMPLO LTDA",
          "alias": "Ejemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contacto@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Calle Ejemplo",
          "house_number": "86",
          "complemento": "Piso 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.ejemplo.com/cert.pfx",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

Respuesta

        {
          "success": true,
          "message": "Empresa cadastrada para NFS-e",
          "data": {
            "company_id": 12345,
            "token": "token-dedicado-da-empresa"
          }
        }

Nota: El token devuelto debe usarse en las demás llamadas NFS-e (/api/nfse/create, /cancel, /get_danfse, /get_xml). Si la empresa ya existe, el mensaje será "Empresa atualizada para NFS-e" y el token devuelto es el existente.

POST /api/nfse/create

Emitir NFS-e

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Payload

{
  "ambiente": "1",
  "id": "REF-001",
  "descricao_servico": "Desenvolvimento de sistemas",
  "valor_servico": 10000.00,
  "aliquota_iss": 2.90,
  "iss_retido": false,
  "codigo_servico": "",
  "cnae": "",
  "valor_deducoes": 0,
  "desconto_incondicionado": 0,
  "desconto_condicionado": 0,
  "valor_iss": 0,
  "valor_pis": 0,
  "valor_cofins": 0,
  "valor_inss": 0,
  "valor_ir": 0,
  "valor_csll": 0,
  "tomador": {
    "cnpj": "43649380000100",
    "cpf": "",
    "name": "EMPRESA TOMADORA LTDA",
    "email": "contato@empresa.com",
    "telefone": "11999999999",
    "inscricao_municipal": "",
    "cep": "03027020",
    "endereco": "Rua Exemplo",
    "numero": "86",
    "complemento": "Andar 2",
    "bairro": "Centro",
    "city": "Sao Paulo",
    "uf": "SP",
    "codigo_municipio": "3550308"
  }
}

Campos Principales

Campo	Tipo	Descripcion
ambiente	string	`"1"` = Produccion, `"2"` = Homologacion
id	string	ID de referencia externa (opcional)
descricao_servico	string	Descripcion del servicio prestado (obligatorio)
valor_servico	decimal	Valor total del servicio en R$ (obligatorio)
aliquota_iss	decimal	Alicuota ISS en % (ej: 2.90)
iss_retido	boolean	`false` = No retenido, `true` = Retenido por el tomador
valor_iss	decimal	Override del valor del ISS. Si mayor que 0, sustituye el calculo automatico (base_calculo x aliquota_iss div 100). Default: calculado automaticamente
codigo_servico	string	Codigo del servicio. Si vacio, usa el predeterminado de la empresa
cnae	string	CNAE. Si vacio, usa el predeterminado de la empresa
tomador	object	Datos del tomador del servicio (obligatorio)

Tomador - Campos

Campo	Tipo	Descripcion
cnpj	string	CNPJ del tomador (solo numeros)
cpf	string	CPF del tomador (usar cnpj O cpf)
name	string	Nombre/Razon Social (obligatorio)
email	string	Email del tomador
telefone	string	Telefono
cep	string	Codigo postal (obligatorio)
endereco	string	Direccion (obligatorio)
numero	string	Numero (obligatorio)
complemento	string	Complemento
bairro	string	Barrio (obligatorio)
city	string	Ciudad
uf	string	Estado (2 digitos)
codigo_municipio	string	Codigo IBGE del municipio

Respuesta Exitosa

{
  "success": true,
  "data": {
    "_id": "661234abcdef...",
    "uuid": "guid-unico",
    "status": "autorizada",
    "nfse": "48",
    "serie": 1,
    "chave": "Z685RI9C",
    "codigoVerificacao": "Z685RI9C",
    "modelo": "nfse",
    "tipoEmissao": "paulistana",
    "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
  }
}

POST /api/nfse/cancel

Cancelar NFS-e

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Payload

{
  "chave": "Z685RI9C",
  "motivo": "Cancelamento da NFS-e por erro na emissao"
}

Campos

Campo	Tipo	Descripcion
chave	string	Codigo de verificacion de la NFS-e (obligatorio)
motivo	string	Motivo de la cancelación (obligatorio)

Respuesta Exitosa

{
  "success": true,
  "message": "Nota de servico cancelada com sucesso"
}

POST /api/nfse/get_danfse

Obtener DANFSE (PDF)

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Payload

{
  "chave": "Z685RI9C"
}

Campos

Campo	Tipo	Descripcion
chave	string	Codigo de verificacion de la NFS-e (obligatorio)

Respuesta

{
  "success": true,
  "data": {
    "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
  }
}

Nota: Para Paulistana (SP), retorna la URL directa del PDF de la prefectura. Para API Nacional, retorna el PDF en base64.

POST /api/nfse/get_xml

Descargar XML de NFS-e

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Payload

{
  "chave": "Z685RI9C"
}

Campos

Campo	Tipo	Descripcion
chave	string	Codigo de verificacion de la NFS-e (obligatorio)

Respuesta

{
  "success": true,
  "data": {
    "dpsXml": "<PedidoEnvioRPS>...</PedidoEnvioRPS>",
    "nfseXml": "<RetornoEnvioRPS>...</RetornoEnvioRPS>"
  }
}

dpsXml: XML enviado a la prefectura/ADN. nfseXml: XML de retorno con el resultado de la emision.

POST /api/invoice/create

Emitir NFe Complementaria (finalidade = 2)

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Payload

{
  "finalidade": "2",
  "ref_nfe_chave": "CHAVE_NFE_AQUI",
  "nature_of_operation": "Complemento de precio",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "1",
  "ind_final": "1",
  "ind_pres": "2",
  "cliente": {
    "cpf": "264.438.800-72",
    "name": "Nome do Destinatário",
    "endereco": "Rua Example",
    "number": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "indIEDest": "9"
  },
  "products": [
    {
      "codigo": "001",
      "name": "Complemento de valor - Produto X",
      "ncm": "82100090",
      "count": 1,
      "unit": "UN",
      "unit_price": 5.00,
      "total_price": 5.00,
      "category_id": "SEU_CATEGORY_ID",
      "origem": "0",
      "indicador_total": "1",
      "cfop": "5102"
    }
  ],
  "pag_info": [
    {
      "payment_method": "90",
      "payment_indicator": "0"
    }
  ]
}

Campos especificos

Campo	Tipo	Descripcion
finalidade	string	`"2"` para Complementaria (obligatorio)
ref_nfe_chave	string	Clave de acceso de la factura original — 44 digitos (obligatorio)

Nota: Los demas campos siguen el mismo patron del endpoint /api/invoice/create para emision normal. Consulte la documentacion de emision de NFe para detalles de todos los campos.

Pago: En facturas complementarias, el pago generalmente es "90" (Sin Pago) pues se trata solo de complemento de valores fiscales.

Respuesta Exitosa

{
  "success": true,
  "data": {
    "uuid": "a1b2c3d4-e5f6-...",
    "chave": "35260312345678000195550010000004051234567890",
    "status": "Success",
    "motivo": "Autorizado o uso da NF-e",
    "nfe": 405,
    "serie": 1,
    "danfe": "https://storage.../danfe.pdf",
    "xml": "https://storage.../xml.xml"
  }
}

POST /api/invoice/create

Emitir NFe de Ajuste (finalidade = 3)

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Payload

{
  "finalidade": "3",
  "ref_nfe_chave": "CHAVE_NFE_AQUI",
  "nature_of_operation": "Ajuste fiscal",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "1",
  "ind_final": "1",
  "ind_pres": "2",
  "cliente": {
    "cpf": "264.438.800-72",
    "name": "Nome do Destinatário",
    "endereco": "Rua Example",
    "number": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "indIEDest": "9"
  },
  "products": [
    {
      "codigo": "001",
      "name": "Ajuste fiscal - Regularização",
      "ncm": "82100090",
      "count": 1,
      "unit": "UN",
      "unit_price": 0.01,
      "total_price": 0.01,
      "category_id": "SEU_CATEGORY_ID",
      "origem": "0",
      "indicador_total": "1",
      "cfop": "5949"
    }
  ],
  "pag_info": [
    {
      "payment_method": "90",
      "payment_indicator": "0"
    }
  ]
}

Campos especificos

Campo	Tipo	Descripcion
finalidade	string	`"3"` para Ajuste (obligatorio)
ref_nfe_chave	string	Clave de acceso de la factura original — 44 digitos (obligatorio)

Valores de finalidade disponibles:

Valor	Descripcion
1	Normal (predeterminado)
2	Complementaria
3	Ajuste
4	Devolucion

Diferencia entre Complementaria y Ajuste:

Complementaria (2): Complementa valores de la factura original (precio, impuesto, cantidad informados de menos)
Ajuste (3): Ajustes fiscales previstos en la legislacion (regularizacion, transferencia de credito, ajuste de inventario)

edit_note CC-e — Carta de Correccion Electronica

La CC-e (Carta de Correccion Electronica) es un evento vinculado a la NF-e que permite corregir informacion de la factura fiscal ya autorizada, sin alterar valores fiscales. Regulada por el Ajuste SINIEF 01/07.

Que se puede corregir via CC-e:

Direccion del destinatario o del emisor
Razon social del destinatario (sin alterar CNPJ/CPF)
Codigo fiscal de operacion (CFOP), siempre que no cambie la naturaleza de los impuestos
Descripcion de la mercancia
Datos adicionales e informaciones complementarias

Que NO se puede corregir via CC-e:

Valores fiscales (base de calculo, alicuota, valor del impuesto)
Cantidad y valor de la mercancia
CNPJ/CPF del emisor o destinatario
Datos que alteren el calculo de los impuestos

Reglas:

Solo facturas con estado autorizada (Success) pueden recibir CC-e
El texto de correccion debe tener entre 15 y 1000 caracteres
Es posible emitir hasta 20 CC-e para la misma factura fiscal
Cada CC-e consume 1 credito

Autenticacion

Todos los endpoints CC-e utilizan la misma autenticacion de la API principal:

Header	Tipo	Descripcion
token	string	Token de la empresa (obtenido en el registro)
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

POST /api/invoice/cce/send

Enviar Carta de Corrección (CC-e)

Envía una CC-e (evento 110110) a SEFAZ para corregir datos de una NF-e ya autorizada. La secuencia (nSeqEvento) se calcula automáticamente — no la envíe. Solo se pueden corregir datos no fiscales (no corrige importes, CNPJ, IE, etc.).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
uuid	string	UUID de la NF-e (obligatorio si `chave` está ausente)
chave	string	Clave de 44 dígitos de la NF-e (obligatorio si `uuid` está ausente)
correcao *	string	Texto de la corrección (límite SEFAZ: 15–1000 caracteres)

* Campo obligatorio. Al menos uno entre uuid y chave también es obligatorio.

Ejemplo de carga útil

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "correcao": "Corrigir nome do destinatario para Empresa XYZ LTDA"
        }

Respuesta

        {
          "success": true,
          "data": {
            "nProt": "135210000123456",
            "nSeqEvento": 1,
            "xml": "https://oss.example.com/.../cce.xml"
          }
        }

POST /api/invoice/cce/get_list

Listar CC-e de una NF-e

Devuelve todas las CC-e (Cartas de Corrección) emitidas para una NF-e específica, ordenadas de la más reciente a la más antigua.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
uuid	string	UUID de la NF-e (obligatorio si `chave` está ausente)
chave	string	Clave de 44 dígitos de la NF-e (obligatorio si `uuid` está ausente)

Al menos uno entre uuid y chave es obligatorio.

Ejemplo de carga útil

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

Respuesta

        {
          "success": true,
          "data": {
            "items": [
              {
                "id": "65fa1b2c3d4e5f6a7b8c9d0e",
                "detail": "Corregir nombre del destinatario a Empresa XYZ LTDA",
                "nProt": "135210000123456",
                "nSeqEvento": 1,
                "date": "15/01/2024 14:30:00",
                "pdfUrl": "https://oss.example.com/.../cce_seq1.pdf",
                "xmlUrl": "https://oss.example.com/.../cce.xml"
              }
            ],
            "total": 1
          }
        }

POST /api/invoice/cce/download_pdf

Descargar PDF de la CC-e

Devuelve la URL del PDF de la CC-e. El PDF se genera bajo demanda en la primera llamada (renderizado desde el XML de la factura + XML de la CC-e) y se almacena en OSS; las llamadas posteriores devuelven la URL existente.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
cce_id *	string	ID de la CC-e (ObjectId) devuelto por `/api/invoice/cce/get_list` en el campo `id`

* Campo obligatorio.

Ejemplo de carga útil

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

Respuesta

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce_seq1.pdf"
          }
        }

POST /api/invoice/cce/download_xml

Descargar XML de la CC-e

Devuelve la URL del XML firmado de la CC-e (ya almacenado en OSS tras el envío a SEFAZ).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
cce_id *	string	ID de la CC-e (ObjectId) devuelto por `/api/invoice/cce/get_list` en el campo `id`

* Campo obligatorio.

Ejemplo de carga útil

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

Respuesta

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce.xml"
          }
        }

how_to_reg Manifestación del Destinatario

La Manifestación del Destinatario permite que el destinatario de una NF-e se posicione formalmente sobre una factura emitida contra su CNPJ. Hay 4 tipos de eventos previstos por SEFAZ, cada uno con su propio significado legal.

Tipos de Evento

Código	Nombre	Significado	Justificación
210210	Conocimiento de la Operación	El destinatario toma conocimiento de la NF-e, pero aún no la ha confirmado ni rechazado. Generalmente es el primer evento enviado, y es requisito para descargar el XML completo vía DistDFe.	No obligatoria
210200	Confirmación de la Operación	El destinatario confirma que la operación ocurrió y la mercancía/servicio fue recibido. Evento final, comprueba la recepción.	No obligatoria
210220	Desconocimiento de la Operación	El destinatario declara que NO reconoce la operación (sospecha de fraude, uso indebido del CNPJ, etc.).	Obligatoria (15-255 caracteres)
210240	Operación No Realizada	El destinatario reconoce la operación pero declara que NO se concretó (devolución, rechazo de recepción, etc.).	Obligatoria (15-255 caracteres)

Regla de secuencia: Tras enviar Conocimiento (210210), se puede enviar Confirmación (210200) O Desconocimiento (210220) U Operación No Realizada (210240). Confirmación/Desconocimiento/No Realizada son estados finales — no pueden sobreescribirse.

Atención: El CNPJ enviado en el campo cnpj debe ser el del destinatario de la NF-e (quien manifiesta) y debe estar registrado en el sistema vinculado al token utilizado. De lo contrario SEFAZ devolverá el rechazo "El autor del evento difiere del destinatario de la NF-e".

Códigos cStat de Retorno

cStat	Significado
135	✅ Evento registrado con éxito
573	✅ Duplicidad de evento — ya registrado anteriormente (tratado como éxito)
236	❌ Clave de acceso inválida
491	❌ Manifestación ya registrada — no se puede sobrescribir estado final
596	❌ CNPJ del destinatario difiere del informado
656	❌ Consumo indebido (rate limit)

POST /api/invoice/manifest

Enviar evento de manifestación del destinatario

Encabezados obligatorios

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

Payload

{
  "chave": "35260514200166000187550010000000011000000018",
  "cnpj": "14200166000187",
  "tipo_evento": 210210,
  "justificativa": "Operação reconhecida pelo destinatário"
}

Campos

Campo	Tipo	Obligatorio	Descripción
chave	string	Sí	Clave de acceso de la NF-e — 44 dígitos
cnpj	string	Sí	CNPJ del destinatario (quien manifiesta) — 14 dígitos, sin formato. Debe estar registrado en el sistema
tipo_evento	int	Sí	Código del evento: `210200`, `210210`, `210220` o `210240`
justificativa	string	Condicional	Obligatoria para `210220` y `210240`. Entre 15 y 255 caracteres. Ignorada para `210200` y `210210`

Secuencia (nSeqEvento): calculada automáticamente. Para la misma combinación (cnpj + chave + tipo_evento) se incrementa en cada llamada — así los duplicados devuelven cStat: 573 y se graban sin error.

Respuesta de Éxito

{
  "success": true,
  "message": "data",
  "data": {
    "id": "67341a8f5d4e1f2a3b4c5d6e",
    "chave": "35260514200166000187550010000000011000000018",
    "cnpj": "14200166000187",
    "tipo_evento": 210210,
    "desc_evento": "Ciencia da Operacao",
    "nProt": "135260000123456",
    "cStat": 135,
    "xMotivo": "Evento registrado e vinculado a NF-e",
    "nSeqEvento": 1,
    "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
id	string	ObjectId interno del registro de manifestación (usado en `/get_xml`)
chave	string	Clave de acceso de la NF-e manifestada
cnpj	string	CNPJ del destinatario que manifestó
tipo_evento	int	Código del evento enviado (210200/210210/210220/210240)
desc_evento	string	Descripción textual del evento (texto original SEFAZ)
nProt	string	Número de protocolo SEFAZ — comprobante del evento
cStat	int	Código de estado SEFAZ. `135` = registrado, `573` = duplicidad (también aceptado)
xMotivo	string	Mensaje descriptivo del retorno SEFAZ
nSeqEvento	int	Secuencia del evento asignada automáticamente
xml_url	string	URL pública del XML del procEvento (firmado y protocolizado) almacenado en OSS

Ejemplo — Desconocimiento (210220) con justificación

{
  "chave": "35260514200166000187550010000000011000000018",
  "cnpj": "14200166000187",
  "tipo_evento": 210220,
  "justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
}

POST /api/invoice/manifest/list

Listar manifestaciones enviadas (historial)

Encabezados obligatorios

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

Payload

{
  "cnpj": "14200166000187",
  "chave": "",
  "start_create_time": "01/05/2026",
  "end_create_time": "31/05/2026",
  "page": 1,
  "page_size": 20
}

Campos

Campo	Tipo	Obligatorio	Descripción
cnpj	string	No	Filtrar por CNPJ del destinatario. Si se omite, lista de todos los CNPJ del usuario
chave	string	No	Filtrar por clave NF-e específica (44 dígitos)
start_create_time	string/long	No	Fecha inicial. Acepta: `"dd/MM/yyyy"`, `"yyyy-MM-dd"`, `"dd/MM/yyyy HH:mm:ss"` o Unix timestamp en segundos. Considera 00:00:00 UTC si solo es fecha
end_create_time	string/long	No	Fecha final. Mismo formato. Si solo es fecha, considera 23:59:59.999 UTC
page	int	No	Número de página (por defecto `1`)
page_size	int	No	Items por página (por defecto `20`, máximo `100`)

Respuesta de Éxito

{
  "success": true,
  "message": "成功",
  "data": {
    "total": 2,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "67341a8f5d4e1f2a3b4c5d6e",
        "chave": "35260514200166000187550010000000011000000018",
        "cnpj": "14200166000187",
        "tipo_evento": 210210,
        "desc_evento": "Ciencia da Operacao",
        "justificativa": "Operação reconhecida pelo destinatário",
        "nProt": "135260000123456",
        "nSeqEvento": 1,
        "cStat": 135,
        "xMotivo": "Evento registrado e vinculado a NF-e",
        "xml_url": "https://storage.../...210210_1.xml",
        "create": "2026-05-13 14:25:33"
      }
    ]
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
total	int	Total de registros que cumplen los filtros (sin importar la paginación)
page	int	Página actual devuelta
page_size	int	Tamaño de página devuelto
list[].id	string	ObjectId interno del registro
list[].chave	string	Clave de acceso de la NF-e manifestada
list[].cnpj	string	CNPJ del destinatario que manifestó
list[].tipo_evento	int	Código del evento (210200/210210/210220/210240)
list[].desc_evento	string	Descripción textual del evento
list[].justificativa	string	Justificación enviada (solo para 210220/210240)
list[].nProt	string	Protocolo SEFAZ del evento
list[].nSeqEvento	int	Secuencia del evento
list[].cStat	int	Código de estado SEFAZ
list[].xMotivo	string	Mensaje descriptivo del retorno SEFAZ
list[].xml_url	string	URL pública del XML del procEvento en OSS
list[].create	string	Fecha/hora UTC del registro (formato `yyyy-MM-dd HH:mm:ss`)

Orden: los registros se devuelven del más reciente al más antiguo (por create descendente).

POST /api/invoice/manifest/get_xml

Obtener URL del XML de una manifestación específica

Encabezados obligatorios

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

Payload

{
  "id": "67341a8f5d4e1f2a3b4c5d6e"
}

Campos

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	ObjectId de la manifestación — devuelto por `/manifest` o `/manifest/list`

Respuesta de Éxito

{
  "success": true,
  "message": "data",
  "data": {
    "id": "67341a8f5d4e1f2a3b4c5d6e",
    "chave": "35260514200166000187550010000000011000000018",
    "tipo_evento": 210210,
    "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
  }
}

Errores Comunes

Mensaje	Causa
id inválido	El valor no es un ObjectId válido
manifestação não encontrada	El ObjectId existe pero no pertenece al usuario del token, o fue eliminado

cloud_download Captura DistDFe — NFe Recibidas

Permite consultar y descargar NFe y eventos destinados a su CNPJ vía el servicio NFeDistribuicaoDFe de SEFAZ (Ambiente Nacional). La captura es incremental por NSU (Número Sequencial Único) — cada llamada solo descarga lo que aún no se ha capturado.

Tipos de Documento Retornados

doc_type	Qué es	Contenido
resNFe	Resumen de NFe	Metadatos básicos (clave, valor, emisor, situación). Llega ANTES de enviar Conocimiento — no contiene productos/impuestos
procNFe	NFe completa autorizada	XML completo de la NF-e (con productos, impuestos, transporte, etc.). Solo viene DESPUÉS de que el destinatario envíe Conocimiento (210210) en la clave
resEvento	Resumen de evento	Metadatos del evento (clave, tipo, secuencia, motivo)
procEvento	Evento completo	XML completo del evento (CC-e, cancelación, manifestaciones de otros destinatarios sobre sus notas)

Flujo recomendado:

Llame /received/sync — descarga todos los documentos nuevos
Liste con /received/list filtrando por doc_type: "resNFe" para ver notas sin Conocimiento
Para cada clave de interés, llame /invoice/manifest con tipo_evento: 210210
Llame /received/sync de nuevo — ahora SEFAZ devuelve los procNFe (XML completo) de las claves manifestadas
Use /received/get_xml para obtener la URL del XML y descargar/procesar

Rate limit de SEFAZ: SEFAZ permite como máximo 1 llamada DistDFe por hora por CNPJ. Si se excede, devuelve cStat: 656 (Consumo Indebido). En el entorno de homologación la regla es más permisiva.

Códigos cStat de Retorno de DistDFe

cStat	Significado
137	✅ Ningún documento encontrado (fin normal del loop)
138	✅ Documentos encontrados — el loop continúa
656	❌ Consumo indebido — esperar 1h y reintentar
252	❌ Ambiente diferente del informado (producción vs homologación)
280	❌ Certificado expirado o inválido

POST /api/invoice/received/sync

Sincronizar — descargar NFe/eventos nuevos de SEFAZ vía DistDFe

Encabezados obligatorios

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

Payload

{
  "cnpj": "26638419000167",
  "max_iterations": 50
}

Campos

Campo	Tipo	Obligatorio	Descripción
cnpj	string	Sí	CNPJ de la empresa destinataria — 14 dígitos, sin formato. Debe estar registrado en el sistema vinculado al token
max_iterations	int	No	Número máximo de llamadas SEFAZ por ejecución. Cada llamada descarga hasta 50 documentos. Por defecto `50` (≈2.500 docs), máximo `200`

Cómo funciona:

Lee el último ultNSU persistido para ese (uid + cnpj)
Hace loop llamando a SEFAZ hasta cStat ≠ 138 o alcanzar max_iterations
Descomprime los XML (gzip) devueltos
Persiste cada documento en w_invoice_received con upload del XML en OSS
Actualiza ultNSU y maxNSU en w_invoice_received_sync
Deduplica por (uid + cnpj + nsu) — llamadas repetidas no duplican

Respuesta de Éxito

{
  "success": true,
  "message": "data",
  "data": {
    "cnpj": "26638419000167",
    "uf": "SP",
    "initial_nsu": 0,
    "ult_nsu": 2323,
    "max_nsu": 2323,
    "pending": 0,
    "iterations": 8,
    "last_cstat": 137,
    "last_motivo": "Nenhum documento localizado",
    "stats": {
      "resNFe": 3,
      "procNFe": 4,
      "resEvento": 336,
      "procEvento": 5,
      "skipped": 0
    }
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
cnpj	string	CNPJ destinatario consultado
uf	string	UF del destinatario usada en la consulta
initial_nsu	long	NSU de inicio — el último procesado antes de esta ejecución
ult_nsu	long	Nuevo último NSU tras la sincronización
max_nsu	long	Mayor NSU disponible en SEFAZ AN en el momento de la consulta
pending	long	Documentos aún pendientes (`max_nsu - ult_nsu`). Si > 0, llame `/sync` de nuevo para descargar el resto
iterations	int	Cuántas llamadas SEFAZ se hicieron en esta ejecución
last_cstat	int	Último cStat devuelto por SEFAZ. `137` es fin normal, `656` es rate limit
last_motivo	string	Mensaje descriptivo del último retorno SEFAZ
stats.resNFe	int	Cantidad de resúmenes de NFe descargados en esta ejecución
stats.procNFe	int	Cantidad de NFe completas descargadas
stats.resEvento	int	Cantidad de resúmenes de evento descargados
stats.procEvento	int	Cantidad de eventos completos descargados
stats.skipped	int	Documentos omitidos (duplicados o error de parseo aislado)

Volumen inicial: empresas que nunca han sincronizado pueden tener cientos o miles de documentos históricos. La primera ejecución puede tardar más e interrumpirse por max_iterations. Verifique pending en la respuesta — si > 0, llame de nuevo (respetando el rate limit).

POST /api/invoice/received/list

Listar documentos capturados (NFe y eventos)

Encabezados obligatorios

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

Payload

{
  "cnpj": "26638419000167",
  "doc_type": "resNFe",
  "chave": "",
  "emitente_cnpj": "",
  "start_create_time": "01/05/2026",
  "end_create_time": "31/05/2026",
  "page": 1,
  "page_size": 20
}

Campos

Campo	Tipo	Obligatorio	Descripción
cnpj	string	No	Filtrar por CNPJ destinatario (su CNPJ). Si se omite, lista de todos los del usuario
doc_type	string	No	Filtrar por tipo de documento: `resNFe`, `procNFe`, `resEvento` o `procEvento`
chave	string	No	Filtrar por clave de acceso (44 dígitos)
emitente_cnpj	string	No	Filtrar por CNPJ del emisor de la NF-e (proveedor)
start_create_time	string/long	No	Fecha inicial. Acepta `"dd/MM/yyyy"`, ISO o Unix timestamp
end_create_time	string/long	No	Fecha final. Mismo formato
page	int	No	Número de página (por defecto `1`)
page_size	int	No	Items por página (por defecto `20`, máximo `100`)

Respuesta de Éxito

{
  "success": true,
  "message": "成功",
  "data": {
    "total": 3,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "6a04a70d3201b5a62f3ac2f8",
        "nsu": 2318,
        "doc_type": "resNFe",
        "schema": "resNFe_v1.01.xsd",
        "chave": "35260563845920000120550020000085471156822656",
        "cnpj_destinatario": "26638419000167",
        "emitente_cnpj": "63845920000120",
        "emitente_nome": "MEGA ONLINE LTDA",
        "valor": 1.00,
        "dh_emi": "2026-05-13 14:05:35",
        "serie": 0,
        "number": 0,
        "tp_nf": 1,
        "c_sit_nfe": 3,
        "tp_evento": 0,
        "desc_evento": "",
        "n_seq_evento": 0,
        "dh_evento": null,
        "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
        "create": "2026-05-13 16:30:05"
      }
    ]
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
total	int	Total de registros que cumplen los filtros
page	int	Página actual
page_size	int	Tamaño de página
list[].id	string	ObjectId interno (use en `/received/get_xml`)
list[].nsu	long	NSU asignado por SEFAZ a este documento
list[].doc_type	string	Tipo de documento: `resNFe`, `procNFe`, `resEvento`, `procEvento`
list[].schema	string	Schema del documento (ej. `resNFe_v1.01.xsd`)
list[].chave	string	Clave de acceso de la NF-e (44 dígitos)
list[].cnpj_destinatario	string	CNPJ destinatario (su CNPJ)
list[].emitente_cnpj	string	CNPJ del emisor de la NF-e (proveedor)
list[].emitente_nome	string	Razón social del emisor
list[].valor	decimal	Valor total de la NF-e (`vNF`)
list[].dh_emi	string	Fecha/hora de emisión de la NF-e
list[].serie	int	Serie de la NF-e (solo en `procNFe`)
list[].number	long	Número de la NF-e (solo en `procNFe`)
list[].tp_nf	int	Tipo de operación: `0`=Entrada, `1`=Salida (desde la óptica del emisor)
list[].c_sit_nfe	int	Situación de la NF-e (en `resNFe`): `1`=Autorizada, `2`=Denegada, `3`=Cancelada
list[].tp_evento	int	Código del evento (en `resEvento`/`procEvento`). Ej: `110110`=CC-e, `110111`=Cancelación, `210210`=Conocimiento
list[].desc_evento	string	Descripción textual del evento
list[].n_seq_evento	int	Secuencia del evento
list[].dh_evento	string	Fecha/hora del evento (solo eventos)
list[].xml_url	string	URL pública del XML del documento en OSS
list[].create	string	Fecha/hora UTC de la captura

Orden: los registros se devuelven por NSU descendente (más reciente primero).

POST /api/invoice/received/get_xml

Obtener URL del XML de un documento recibido específico

Encabezados obligatorios

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

Payload

{
  "id": "6a04a70d3201b5a62f3ac2f8"
}

Campos

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	ObjectId del documento — devuelto en `/received/list`

Respuesta de Éxito

{
  "success": true,
  "message": "data",
  "data": {
    "id": "6a04a70d3201b5a62f3ac2f8",
    "nsu": 2318,
    "doc_type": "resNFe",
    "chave": "35260563845920000120550020000085471156822656",
    "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml"
  }
}

Sobre el XML devuelto:

resNFe — El XML es solo el resumen, NO contiene productos/impuestos. Úselo para auditoría/triage antes de enviar Conocimiento
procNFe — XML completo y firmado, equivalente al generado en la emisión. Listo para importar al ERP del cliente
procEvento — XML del evento completo con firma y protocolo

Errores Comunes

Mensaje	Causa
id inválido	El valor no es un ObjectId válido
documento recebido não encontrado	El ObjectId existe pero no pertenece al usuario del token

POST /api/invoice/received/get_sync_status

Consultar estado actual de la sincronización DistDFe (sin llamar a SEFAZ)

Encabezados obligatorios

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

Payload

{
  "cnpj": "26638419000167"
}

Campos

Campo	Tipo	Obligatorio	Descripción
cnpj	string	Sí	CNPJ de la empresa destinataria — 14 dígitos, sin formato

Respuesta — Empresa ya sincronizada

{
  "success": true,
  "message": "成功",
  "data": {
    "cnpj": "26638419000167",
    "uf": "SP",
    "ult_nsu": 2323,
    "max_nsu": 2323,
    "pending": 0,
    "last_sync": "2026-05-13 16:30:05"
  }
}

Respuesta — Empresa nunca sincronizada

{
  "success": true,
  "message": "成功",
  "data": {
    "cnpj": "26638419000167",
    "ult_nsu": 0,
    "max_nsu": 0,
    "pending": 0,
    "last_sync": null
  }
}

Campos de la Respuesta

Campo	Tipo	Descripción
cnpj	string	CNPJ consultado
uf	string	UF del destinatario usada en la última sincronización (ausente si nunca sincronizó)
ult_nsu	long	Último NSU procesado. `0` = nunca sincronizó
max_nsu	long	Mayor NSU disponible en SEFAZ en la última sincronización
pending	long	Documentos pendientes (`max_nsu - ult_nsu`). Si > 0, hay nuevos documentos en SEFAZ
last_sync	string	Fecha/hora UTC de la última sincronización exitosa. `null` si nunca sincronizó

Uso típico: llame a este endpoint antes de /received/sync para decidir si necesita llamar a SEFAZ. Este endpoint no consume el rate limit de SEFAZ — solo lee el estado local de MongoDB.

local_shipping MDF-e — Manifesto Eletrônico de Documentos Fiscais

A API de MDF-e (modelo 58, layout PL-MDFe 3.00) permite emitir, consultar, cancelar e encerrar manifestos de transporte. O MDF-e agrega NF-es e/ou CT-es vinculados a uma operação de transporte, suportando 4 modais: rodoviário, aéreo, aquaviário e ferroviário. Toda informação operacional (condutor, veículo, contratante, CIOT, vale-pedágio, pagamento) vai no corpo do /create — não há eventos de inclusão/alteração após a emissão.

Endpoint	Método	Descrição
`/api/mdfe/create`	POST	Emitir MDF-e
`/api/mdfe/consult`	POST	Consultar situação do MDF-e
`/api/mdfe/cancel`	POST	Cancelar MDF-e (até 24h após autorização)
`/api/mdfe/close`	POST	Cerrar MDF-e (após finalizar viagem)

POST /api/mdfe/create

Emitir MDF-e

Emite um MDF-e a partir do corpo enviado. Os campos serie, nMDF, cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc são calculados automaticamente pelo servidor. O cliente envia apenas os campos de negócio.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body — raiz

Campo	Tipo	Descrição
ide *	object	Identificação do MDF-e
emit *	object	Datos del emisor
infModal *	object	Informações do modal (apenas UM dos quatro: `rodo`, `aereo`, `aquav`, `ferrov`)
infDoc *	object	Documentos fiscales vinculados
tot *	object	Totalizadores de la carga
prodPred	object	Producto predominante de la carga
seg	array	Informações de seguro
lacres	array	Precintos del MDF-e
autXML	array	CNPJs/CPFs autorizados a acceder al XML
infAdic	object	Informações adicionais (fisco e contribuinte)
infRespTec	object	Responsável técnico (CNPJ, contato, email, etc.)

ide — Identificação

Campo	Tipo	Descrição
tpAmb *	int	Ambiente: `1`=produção, `2`=homologação
tpEmit *	int	Tipo do emitente: `1`=transportador, `2`=carga própria, `3`=prestador de serviço de transporte
modal *	string	Modal: `"1"`=rodoviário, `"2"`=aéreo, `"3"`=aquaviário, `"4"`=ferroviário
UFIni *	string	UF de início da viagem (2 letras)
UFFim *	string	UF de fin del viaje
infMunCarrega[] *	array	Municípios de carregamento: `[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	UFs de la ruta: `[{ UFPer }]`
tpTransp	string	Tipo de transportador (rodoviário)
dhIniViagem	string	Data/hora de início da viagem (ISO 8601)
indCanalVerde	string	Indicador de canal verde
indCarregaPosterior	string	Indicador de carga posterior

emit — Emitente

Campo	Tipo	Descrição
CNPJ ⚠	string	CNPJ do emitente (14 dígitos)
CPF ⚠	string	CPF do emitente (11 dígitos)
IE	string	Inscrição Estadual
xNome *	string	Razão social
xFant	string	Nombre comercial
enderEmit	object	Endereço: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — Modal Rodoviário (modal="1")

Campo	Tipo	Descrição
rodo.veicTracao *	object	Veículo de tração: `{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	Condutores: `[{ xNome, CPF }]` — mínimo 1
rodo.veicReboque[]	array	Veículos de reboque (mesma estrutura de veicTracao sem condutor)
rodo.infANTT	object	Informações da ANTT: `{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	Código de agendamento no porto
rodo.lacRodo[]	array	Precintos del modal: `[{ nLacre }]`

infModal — Modal Aéreo (modal="2")

Campo	Tipo	Descrição
aereo.nac *	string	Marca de nacionalidad de la aeronave
aereo.matr *	string	Matrícula da aeronave
aereo.nVoo *	string	Número do voo
aereo.cAerEmb *	string	Código IATA do aeroporto de embarque
aereo.cAerDes *	string	Código IATA do aeroporto de destino
aereo.dVoo *	string	Fecha del vuelo (AAAA-MM-DD)

infModal — Modal Aquaviário (modal="3")

Campo	Tipo	Descrição
aquav.irin *	string	IRIN da embarcação
aquav.tpEmb *	string	Tipo de embarcación (2 dígitos). Use valores ≥ 10 para evitar truncamiento del `byte` interno de Zeus (ej.: `"10"`, `"11"`)
aquav.cEmbar *	string	Código da embarcação
aquav.xEmbar *	string	Nome da embarcação
aquav.nViag *	string	Número del viaje. No puede empezar con cero (validación del schema) — use `"1"`, `"100"`, etc.
aquav.cPrtEmb *	string	Código do porto de embarque
aquav.cPrtDest *	string	Código do porto de destino
aquav.prtTrans	string	Puerto de transbordo
aquav.tpNav	string	Tipo de navegação
aquav.infTermCarreg[]	array	Terminales de carga: `[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	Terminales de descarga
aquav.infEmbComb[]	array	Embarcações de comboio: `[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	Unidades de carga vacÃas
aquav.infUnidTranspVazia[]	array	Unidades de transporte vacÃas

infModal — Modal Ferroviário (modal="4")

Campo	Tipo	Descrição
ferrov.trem *	object	Datos del tren: `{ xPref, dhTrem, xOri, xDest, qVag }`
ferrov.vag[] *	array	Vagones: `[{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }]` — mínimo 1. Restricciones de Zeus/SEFAZ: `serie` debe tener exactamente 3 dígitos (use 100+, ej.: `"100"`); `nVag` solo acepta dígitos (`long` internamente, ej.: `"100001"`); `nSeq` opcional 1-3 dígitos.

infDoc — Documentos vinculados

Campo	Tipo	Descrição
infMunDescarga[] *	array	Municípios de descarga — mínimo 1
infMunDescarga[].cMunDescarga *	string	Código IBGE do município
infMunDescarga[].xMunDescarga *	string	Nome do município
infMunDescarga[].infNFe[]	array	NF-es vinculadas: `[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	CT-es vinculados
infMunDescarga[].infMDFeTransp[]	array	MDF-es de transporte (subcontratação)

prodPred — Produto predominante

Campo	Tipo	Descrição
tpCarga *	string	Tipo de carga: `"01"`=granel sólido, `"02"`=granel líquido, `"03"`=frigorificada, `"04"`=conteinerizada, `"05"`=carga geral, `"06"`=neogranel, `"07"`=perigosa, `"08"`=granel pressurizado
xProd *	string	Descrição do produto predominante
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	Lotação: `{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — Totalizadores

Campo	Tipo	Descrição
vCarga *	decimal	Valor total de la carga (> 0)
cUnid *	string	Código da unidade: `"01"`=KG, `"02"`=TON
qCarga *	decimal	Cantidad total de la carga (> 0)
qCTe	int	Cantidad de CT-es vinculados
qNFe	int	Cantidad de NF-es vinculadas
qMDFe	int	Cantidad de MDF-es vinculados

* Campo obrigatório. ⚠ Pelo menos um de CNPJ ou CPF é obrigatório.

Exemplo simplificado — Modal Rodoviário

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "veicTracao": {
                "placa": "ABC1D23",
                "tara": 8000,
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" }
                ],
                "tpRod": "01",
                "tpCar": "01"
              }
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          }
        }

Exemplo simplificado — Modal Aéreo

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "2",
            "UFIni": "SP",
            "UFFim": "RJ",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA AEREA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV AEROPORTO",
              "nro": "5000",
              "xBairro": "CUMBICA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aereo": {
              "nac": "PT",
              "matr": "ABC1234",
              "nVoo": "AB1234",
              "cAerEmb": "GRU",
              "cAerDes": "GIG",
              "dVoo": "2026-05-21"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3304557",
                "xMunDescarga": "Rio de Janeiro",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 25000.00,
            "cUnid": "01",
            "qCarga": 500.00
          }
        }

Exemplo simplificado — Modal Aquaviário

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "3",
            "UFIni": "SP",
            "UFFim": "PA",
            "infMunCarrega": [
              { "cMunCarrega": "3548500", "xMunCarrega": "SANTOS" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "NAVEGACAO EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV PORTUARIA",
              "nro": "200",
              "xBairro": "PORTO",
              "cMun": "3548500",
              "xMun": "SANTOS",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aquav": {
              "irin": "1234567",
              "tpEmb": "10",
              "cEmbar": "1234",
              "xEmbar": "EMBARCACAO EXEMPLO",
              "nViag": "1",
              "cPrtEmb": "BRSSZ",
              "cPrtDest": "BRBEL"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "1501402",
                "xMunDescarga": "Belém",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "GRAOS DE SOJA"
          },
          "tot": {
            "vCarga": 500000.00,
            "cUnid": "02",
            "qCarga": 50.00
          }
        }

Exemplo simplificado — Modal Ferroviário

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "4",
            "UFIni": "MG",
            "UFFim": "SP",
            "infMunCarrega": [
              { "cMunCarrega": "3106200", "xMunCarrega": "BELO HORIZONTE" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "FERROVIA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV FERROVIARIA",
              "nro": "300",
              "xBairro": "INDUSTRIAL",
              "cMun": "3106200",
              "xMun": "BELO HORIZONTE",
              "UF": "MG"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "ferrov": {
              "trem": {
                "xPref": "F123",
                "dhTrem": "2026-05-21T08:00:00-03:00",
                "xOri": "BELO HORIZONTE",
                "xDest": "SANTOS",
                "qVag": 2
              },
              "vag": [
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "100",
                  "nVag": "100001",
                  "nSeq": "1",
                  "TU": 28.000
                },
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "101",
                  "nVag": "100002",
                  "nSeq": "2",
                  "TU": 28.000
                }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3548500",
                "xMunDescarga": "Santos",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "MINERIO DE FERRO"
          },
          "tot": {
            "vCarga": 800000.00,
            "cUnid": "02",
            "qCarga": 56.00
          }
        }

Exemplo completo (todos os campos) — Modal Rodoviário

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "tpTransp": "1",
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ],
            "dhIniViagem": "2026-05-21T08:00:00-03:00",
            "indCanalVerde": "1",
            "indCarregaPosterior": "0"
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "xFant": "Exemplo Transportes",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "GALPAO A",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP",
              "fone": "1133334444",
              "email": "contato@exemplo.com"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "infANTT": {
                "RNTRC": "12345678",
                "infCIOT": [
                  { "CIOT": "1234567890", "CNPJ": "12345678000199" }
                ],
                "valePed": {
                  "categCombVeic": "01",
                  "disp": [
                    {
                      "CNPJForn": "98765432000111",
                      "CNPJPg": "12345678000199",
                      "nCompra": "VP001",
                      "vValePed": 250.00,
                      "tpValePed": "01"
                    }
                  ]
                },
                "infContratante": [
                  {
                    "xNome": "EMPRESA CONTRATANTE LTDA",
                    "CNPJ": "11222333000144"
                  }
                ],
                "infPag": [
                  {
                    "xNome": "João da Silva",
                    "CPF": "12345678909",
                    "Comp": [
                      { "tpComp": "01", "vComp": 5000.00, "xComp": "Frete contratado" }
                    ],
                    "vContrato": 5000.00,
                    "indAltoDesemp": "1",
                    "indPag": "0",
                    "infBanc": {
                      "codBanco": "001",
                      "codAgencia": "1234",
                      "PIX": "12345678909"
                    }
                  }
                ]
              },
              "veicTracao": {
                "cInt": "VT001",
                "placa": "ABC1D23",
                "RENAVAM": "12345678901",
                "tara": 8000,
                "capKG": 25000,
                "capM3": 80,
                "prop": {
                  "CNPJ": "12345678000199",
                  "RNTRC": "12345678",
                  "xNome": "TRANSPORTADORA EXEMPLO LTDA",
                  "IE": "123456789012",
                  "UF": "SP",
                  "tpProp": "0"
                },
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" },
                  { "xNome": "Maria Souza", "CPF": "98765432100" }
                ],
                "tpRod": "01",
                "tpCar": "01",
                "UF": "SP"
              },
              "veicReboque": [
                {
                  "cInt": "VR001",
                  "placa": "DEF4G56",
                  "RENAVAM": "98765432109",
                  "tara": 3500,
                  "capKG": 30000,
                  "capM3": 90,
                  "tpCar": "02",
                  "UF": "SP"
                }
              ],
              "lacRodo": [
                { "nLacre": "LACRE001" },
                { "nLacre": "LACRE002" }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  {
                    "chNFe": "35260512345678000199550010000000011000000018",
                    "SegCodBarras": "",
                    "indReentrega": "0",
                    "infUnidTransp": [
                      {
                        "tpUnidTransp": "1",
                        "idUnidTransp": "UT001",
                        "qtdRat": 100.000,
                        "lacUnidTransp": [{ "nLacre": "LACRE-UT-001" }],
                        "infUnidCarga": [
                          {
                            "tpUnidCarga": "1",
                            "idUnidCarga": "UC001",
                            "qtdRat": 100.000,
                            "lacUnidCarga": [{ "nLacre": "LACRE-UC-001" }]
                          }
                        ]
                      }
                    ],
                    "peri": []
                  }
                ]
              }
            ]
          },
          "seg": [
            {
              "infResp": {
                "respSeg": "1",
                "CNPJ": "12345678000199"
              },
              "infSeg": {
                "xSeg": "SEGURADORA EXEMPLO SA",
                "CNPJ": "55666777000188"
              },
              "nApol": "APOL-2026-001",
              "nAver": ["AV001", "AV002"]
            }
          ],
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL",
            "cEAN": "7891234567890",
            "NCM": "84713012",
            "infLotacao": {
              "infLocalCarrega": {
                "CEP": "01001000",
                "latitude": "-23.5505",
                "longitude": "-46.6333"
              },
              "infLocalDescarrega": {
                "CEP": "29100000",
                "latitude": "-20.3297",
                "longitude": "-40.2925"
              }
            }
          },
          "tot": {
            "qCTe": 0,
            "qNFe": 1,
            "qMDFe": 0,
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          },
          "lacres": [
            { "nLacre": "LACRE-GERAL-001" }
          ],
          "autXML": [
            { "CNPJ": "11222333000144" }
          ],
          "infAdic": {
            "infAdFisco": "Documento emitido em conformidade com a legislação vigente",
            "infCpl": "Transporte com escolta armada"
          },
          "infRespTec": {
            "CNPJ": "12345678000199",
            "xContato": "Suporte Técnico",
            "email": "suporte@exemplo.com",
            "fone": "1133334444"
          }
        }

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "nMDF": 1,
            "serie": 1,
            "protocolo": "135260000123456",
            "xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
          }
        }

POST /api/mdfe/consult

Consultar situação do MDF-e

Consulta a situação do MDF-e diretamente na SEFAZ a partir da chave de acesso.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descrição
chMDFe *	string	Chave de acesso do MDF-e (44 dígitos)

* Campo obrigatório.

Ejemplo de carga Ãºtil

        {
          "chMDFe": "35260512345678000199580010000000011000000018"
        }

Respuesta

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 100,
            "xMotivo": "Autorizado o uso do MDF-e",
            "protocolo": "135260000123456",
            "dhRecbto": "2026-05-21T10:30:00-03:00",
            "encerrado": false,
            "cancelado": false
          }
        }

POST /api/mdfe/cancel

Cancelar MDF-e

Cancela um MDF-e autorizado. Janela: até 24 horas após a autorização. Não permitido se o MDF-e já tiver sido encerrado.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descrição
chMDFe *	string	Chave de acesso do MDF-e (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência SEFAZ)

* Campo obrigatório.

Ejemplo de carga Ãºtil

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "xJust": "Cancelamento por erro no preenchimento dos dados do veiculo"
        }

Respuesta

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123457",
            "dhRegEvento": "2026-05-21T11:00:00-03:00"
          }
        }

POST /api/mdfe/close

Cerrar MDF-e

Encerra um MDF-e ao final da viagem. Após o encerramento, não é mais possível cancelar. Os campos dtEnc, cUF e cMun são opcionais — quando omitidos, o sistema infere a partir do MDF-e original (data atual, UF e município do emitente).

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descrição
chMDFe *	string	Chave de acesso do MDF-e (44 dígitos)
dtEnc	string	Fecha del cierre (AAAA-MM-DD). Default: fecha actual
cUF	int	Código IBGE da UF onde ocorreu o encerramento. Default: UF do emitente
cMun	string	Código IBGE do município onde ocorreu o encerramento. Default: município do emitente

* Campo obrigatório.

Ejemplo de carga Ãºtil

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "dtEnc": "2026-05-22",
          "cUF": 32,
          "cMun": "3205200"
        }

Respuesta

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123458",
            "dhRegEvento": "2026-05-22T18:00:00-03:00"
          }
        }

vpn_key SSO — Inicio Automático vía Token

Base URL (Producción)

https://api.tffiscal.com

Autenticación

Headers: sign, timestamp, token

Validez del Ticket

60 segundos — uso único

SSO (Single Sign-On) permite que su ERP genere un enlace de acceso directo a TFiscal para el usuario, ya autenticado en la empresa correspondiente y en el idioma deseado, sin que tenga que ingresar credenciales.

Cómo funciona:

El ERP llama a POST /api/sso/create_ticket enviando el token de la empresa.
TFiscal devuelve un redirectUrl con un ticket opaco de uso único.
El ERP redirige el navegador del usuario a esa URL.
La página consume el ticket y el usuario entra al panel de la empresa.

⚠️ Seguridad: el token real de la empresa nunca aparece en la URL. Sólo el ticket efímero (válido por 60 segundos y de uso único) se expone al navegador.

POST /api/sso/create_ticket

Generar enlace de inicio automático

Genera un ticket de uso único válido por 60 segundos para iniciar sesión automáticamente al usuario en el panel de la empresa correspondiente al token.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa (el mismo usado para emitir NF-e)
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Payload

{
  "token": "TOKEN_DA_EMPRESA",
  "language": "br",
  "page": "emitir_nfe"
}

Campos

Campo	Obligatorio	Tipo	Descripción
token	Sí	string	Token de la empresa (`w_company.token`) — el mismo usado en `/api/invoice/create`
language	No	string	Idioma de la interfaz: `br`, `en`, `zh`, `es`, `ja`, `ko`. Default: `br`
page	No	string	Página de destino después del login. Valores aceptados: `emitir_nfe`. Vacío o ausente abre el panel por defecto (`/company/kanban`).

Respuesta de éxito

{
  "success": true,
  "message": "ticket",
  "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
  "redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
  "expiresInSeconds": 60,
  "expiresAt": "2026-04-24T18:34:56.0000000Z"
}

Campos de la respuesta

Campo	Tipo	Descripción
success	boolean	`true` cuando el ticket se generó con éxito
ticket	string	Ticket opaco (aleatorio, 32 bytes base64url)
redirectUrl	string	URL completa a la que el ERP debe redirigir el navegador
expiresInSeconds	number	Validez en segundos (siempre 60)
expiresAt	string	Fecha/hora UTC de expiración (ISO 8601)

Respuestas de error

Mensaje	Causa
`Token es obligatorio`	El campo `token` no fue enviado en el body
`Token inválido`	El token no corresponde a ninguna empresa registrada
`Este token está vinculado a múltiples empresas. Envíe el token de la empresa a la que desea acceder.`	Token de integrador con más de una empresa — envíe el token específico de la empresa
`Rate limit exceeded`	Más de 30 llamadas por minuto para el mismo token

POST /api/sso/consume_ticket

Consumir ticket y recibir el JWT de sesión

Intercambia el ticket generado por /api/sso/create_ticket por el JWT de sesión de TFiscal. Este endpoint es llamado por el frontend (ruta /sso) y no requiere headers sign/timestamp — el propio ticket opaco es la credencial. Cada ticket puede consumirse solo una vez y expira en 60 segundos.

Body

Campo	Tipo	Descripción
ticket *	string	Ticket devuelto por `create_ticket`

* Campo obligatorio.

Ejemplo de payload

        {
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
        }

Respuesta de éxito

        {
          "success": true,
          "message": "Login succeeded",
          "access_token": "eyJhbGciOi...",
          "type": "user",
          "uid": 1234,
          "company_id": 5678,
          "language": "br",
          "page": "emitir_nfe"
        }

Campos de la respuesta

Campo	Tipo	Descripción
access_token	string	JWT de sesión (validez de 365 días). Úselo en el header `Authorization` de las llamadas TFiscal
type	string	Tipo de usuario (`user`, `admin`, etc.)
uid	int	ID interno del usuario
company_id	int	ID de la empresa seleccionada en `create_ticket`
language	string	Idioma elegido en `create_ticket` (siempre normalizado)
page	string	Página de destino (o string vacío si no se define)

Respuestas de error

Mensaje	Causa
`Ticket inválido`	Body sin campo `ticket`
`Ticket inválido ou expirado`	El ticket no existe, ya fue consumido o pasó los 60 segundos
`Rate limit exceeded`	Más de 60 consumos por minuto desde la misma IP
`Sessão inválida`	El usuario vinculado al ticket ya no existe

lock Restricciones y Seguridad

Características del ticket

Característica	Valor
Validez	60 segundos después de generado
Uso	Único — una vez consumido no se puede reutilizar
Rate limit	30 tickets/minuto por token · 60 consumos/minuto por IP
Almacenamiento	MongoDB con TTL automático — tickets expirados se eliminan

Restricciones de navegación

Los usuarios autenticados vía SSO tienen acceso solamente a las pantallas de la empresa correspondiente (/invoice/company/*). Los intentos de acceder a otras áreas (paneles de distribuidor, reportes generales, administración) son redirigidos automáticamente al panel de la empresa.

Sesión después del login

Después de intercambiar el ticket por un JWT, el usuario tiene una sesión normal en TFiscal (JWT válido por 365 días, igual que el login tradicional). Los 60 segundos son sólo la ventana entre generar el ticket y abrir el enlace — después el usuario permanece conectado normalmente hasta cerrar sesión.

⚠️ Importante: el create_ticket debe ser llamado exclusivamente server-side por el ERP. Nunca llame a este endpoint directamente desde el navegador — expondría el token de la empresa en el front-end.

badge Contador (Accountant)

API para consulta de los datos de registro de contadores vinculados a una empresa. Útil para sistemas contables externos que necesitan obtener los datos completos del contador responsable de una empresa determinada.

POST /api/accountant/get_info

Obtener información del contador vinculado a la empresa

Devuelve los datos completos de registro del contador vinculado a la empresa informada. El contador debe estar previamente vinculado a la empresa (mismo CNPJ) y el correo informado debe coincidir con el registro.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa o token B2B del integrador
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body

Campo	Tipo	Descripción
companyId *	int	ID de la empresa vinculada al token
accountantId *	string	ObjectId del contador (24 hex)
email *	string	Correo del contador (debe coincidir con el registro)

* Campo obligatorio.

Ejemplo de payload

      {
        "companyId": 12345,
        "accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
        "email": "contador@oficina.com"
      }

Respuesta de éxito

      {
        "success": true,
        "data": {
          "email": "contador@oficina.com",
          "officeDocumentType": "CNPJ",
          "officeDocument": "12345678000199",
          "officeName": "Oficina Contable LTDA",
          "responsibleName": "Juan Silva",
          "crc": "SP123456/O-7",
          "accountantCpf": "12345678909",
          "workAddress": "Calle Ejemplo, 100 - Centro - São Paulo/SP",
          "site": "https://oficina.com",
          "landline": "1133334444",
          "mobile": "11999998888",
          "assistantName": "María Souza",
          "assistantEmail": "maria@oficina.com",
          "assistantPhone": "11988887777",
          "observations": "Atención de lunes a viernes, 9h a 18h"
        }
      }

Campos de la respuesta

Campo	Tipo	Descripción
email	string	Correo principal del contador
officeDocumentType	string	Tipo de documento de la oficina: "CNPJ" o "CPF"
officeDocument	string	Documento de la oficina (solo dígitos)
officeName	string	Razón social / nombre de la oficina
responsibleName	string	Nombre del contador responsable
crc	string	Número del CRC (Consejo Regional de Contabilidad)
accountantCpf	string	CPF del contador (solo dígitos)
workAddress	string	Dirección comercial
site	string	Sitio web de la oficina
landline	string	Teléfono fijo
mobile	string	Móvil
assistantName	string	Nombre del asistente
assistantEmail	string	Correo del asistente
assistantPhone	string	Teléfono del asistente
observations	string	Observaciones libres del registro

Respuestas de error

Mensaje	Causa
会计师ID参数异常或不存在	`accountantId` ausente o no es un ObjectId válido
该会计师邮箱异常或不存在	`email` inválido o no registrado
发票账号{companyId}异常或不存在	`companyId` no pertenece al usuario del token
该会计师未绑定该发票账号	El contador no está vinculado a la empresa informada

Documentación NFE API

Campos Importantes de la API

Flujo del Proceso de Emisión

1. Crear Empresa

2. Push de Información

3. Emitir Factura

4. Retornar Resultado

5. Generar Archivos

Verificación Fiscal

Éxito

Fallo

Referencia Rápida de Endpoints

Éxito

Error del Cliente

Error del Servidor

NFE API

sync_alt Flujo del Sistema

input Datos de Entrada

settings Procesamiento

download Salida

Endpoints Principales

Headers obligatorios

Body

Ejemplo de carga útil

Respuesta

Headers obligatorios

Body

Ejemplo de carga útil

Respuesta

Headers obligatorios

Body

Ejemplo de carga útil

Respuesta

Headers obligatorios

Query string

Ejemplo de llamada

Respuesta

Headers obligatorios

Ejemplo de llamada

Respuesta

Headers obligatorios

Body — campos de nivel superior

Body — cliente (objeto, obligatorio)

Body — products[] (array, mínimo 1 elemento)

Body — products[].impostos / products[].tax_info

Body — products[].ii (Impuesto de Importación)

Body — products[].import_declarations[]

Body — shipping_address / delivery_address (objetos, opcionales)

Body — transportation (objeto, opcional)

Body — pag_info[] (array, opcional)

Ejemplo simplificado

Ejemplo completo (todos los campos)

Headers obligatorios

Query string

Ejemplo de llamada

Respuesta

Headers obligatorios

Query string

Ejemplo de llamada

Respuesta

Headers obligatorios

Body

Ejemplo de carga útil

Headers obligatorios

Body

Ejemplo de carga útil

Headers obligatorios

Body

Ejemplo de carga útil

Headers obligatorios

Body

Ejemplo de payload

Respuesta

Campos de la respuesta

Respuestas de error

Headers obligatorios

Body

Ejemplo de payload

Respuesta — procesando

Respuesta — concluido

Body — `cliente` (objeto, obligatorio)

Body — `products[]` (array, mínimo 1 elemento)

Body — `products[].impostos` / `products[].tax_info`

Body — `products[].ii` (Impuesto de Importación)

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address` (objetos, opcionales)

Body — `transportation` (objeto, opcional)

Body — `pag_info[]` (array, opcional)

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` y `cofins[]` (misma estructura)

Body — `ibs_cbs[]` (Reforma Tributaria)

Body — `is[]` (Impuesto Selectivo)