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/get_detail`	GET	Consultar empresa
`/api/company/edit`	POST	Modificar empresa
`/api/company/get_list`	GET	Listar empresas
`/api/company/v2/create`	POST	Crear empresa (simplificado)
`/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
`/api/nfce/get_list`	GET	Listar NFC-e (paginado)
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
`/api/nfse/get_list`	GET	Listar NFS-e (paginado)
`/api/nfs/company/create`	POST	Registrar empresa para emisión de NFS-e
receipt_long NF-e — Eventos y Consultas
`/api/invoice/get_danfe`	POST	Obtener DANFE (PDF) de la NF-e
`/api/invoice/consultar_status`	POST	Consultar estado de la NF-e/NFC-e en la SEFAZ
`/api/invoice/validar_cpf_cnpj`	POST	Validar CPF/CNPJ en la base de la Receita Federal
`/api/invoice/cce/send`	POST	Enviar Carta de Corrección (CC-e)
`/api/invoice/cce/get_list`	POST	Listar CC-e de una NF-e
`/api/invoice/cce/download_pdf`	POST	Descargar PDF de la CC-e
`/api/invoice/cce/download_xml`	POST	Descargar XML de la CC-e
mark_email_read NF-e — Manifestación y Notas Recibidas
`/api/invoice/manifest`	POST	Enviar evento de manifestación del destinatario
`/api/invoice/manifest/list`	POST	Listar manifestaciones enviadas
`/api/invoice/manifest/get_xml`	POST	Obtener XML de una manifestación
`/api/invoice/received/sync`	POST	Sincronizar NF-es/eventos recibidos (DistDFe)
`/api/invoice/received/list`	POST	Listar documentos recibidos
`/api/invoice/received/get_xml`	POST	Obtener XML de documento recibido
`/api/invoice/received/get_sync_status`	POST	Consultar estado de la sincronización DistDFe
category NFC-e — Categorías Fiscales
`/api/nfce/category/create`	POST	Crear categoría fiscal NFC-e
`/api/nfce/category/edit`	POST	Editar categoría fiscal NFC-e
`/api/nfce/category/delete`	POST	Eliminar categoría fiscal NFC-e
`/api/nfce/category/get_detail`	GET	Obtener detalles de la categoría NFC-e
`/api/nfce/category/get_list`	GET	Listar categorías fiscales NFC-e
local_shipping MDF-e (Manifiesto Electrónico de Documentos Fiscales)
`/api/mdfe/create`	POST	Emitir MDF-e
`/api/mdfe/consult`	POST	Consultar situación del MDF-e
`/api/mdfe/cancel`	POST	Cancelar MDF-e
`/api/mdfe/close`	POST	Cerrar MDF-e
`/api/mdfe/get_list`	GET	Listar MDF-e (paginado)
inventory_2 DC-e (Declaración de Contenido Electrónica)
`/api/dce/create`	POST	Emitir DC-e
`/api/dce/consult`	POST	Consultar situación de la DC-e
`/api/dce/cancel`	POST	Cancelar DC-e
`/api/dce/pdf`	POST	Obtener DACE (PDF) de la DC-e
`/api/dce/get_list`	GET	Listar DC-e (paginado)
local_shipping CT-e (Conocimiento de Transporte Electrónico)
`/api/cte/create`	POST	Emitir CT-e
`/api/cte/cancel`	POST	Cancelar CT-e
`/api/cte/cce`	POST	Carta de Corrección (CC-e)
`/api/cte/desacordo`	POST	Prestación en Desacuerdo
`/api/cte/consult`	POST	Consultar situación del CT-e
`/api/cte/inutilize`	POST	Inutilizar rango de numeración
`/api/cte/get_list`	GET	Listar CT-e (paginado)
vpn_key SSO (Inicio Automático)
`/api/sso/create_ticket`	POST	Generar enlace de inicio de sesión automático
`/api/sso/consume_ticket`	POST	Consumir ticket y recibir el JWT de sesión
account_balance Contador
`/api/accountant/get_info`	POST	Obtener información del contador vinculado a la empresa

📋 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
Transporte (MDF-e / CT-e / DC-e)
serie_mdfe	int	Serie del MDF-e
number_mdfe	int	Número inicial del MDF-e (donde empieza la numeración)
serie_cte	int	Serie del CT-e
number_cte	int	Número inicial del CT-e (donde empieza la numeración)
serie_dce	int	Serie de la DC-e
number_dce	int	Número inicial de la DC-e (donde empieza 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": "contato@empresa.com",
          "cep": "01001000",
          "address": "Rua Exemplo",
          "house_number": "100",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1,
          "serie_mdfe": 2,
          "number_mdfe": 1,
          "serie_cte": 3,
          "number_cte": 1,
          "serie_dce": 4,
          "number_dce": 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://exemplo.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.

La empresa se crea con la configuración de NF-e (vía /api/company/create). Para habilitar los demás documentos, complete el registro por aquí: este endpoint también acepta los campos de NFC-e, NFS-e, MDF-e, CT-e y DC-e (ver secciones más abajo). Envíe solo los campos del/de los documento(s) que la empresa va a emitir.

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
alias	string	Nombre comercial
telefone	string	Teléfono
complemento	string	Complemento del domicilio
NFC-e
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
NFS-e
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)
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
Transporte (MDF-e / CT-e / DC-e)
serie_mdfe	int	Serie del MDF-e
number_mdfe	int	Número inicial del MDF-e (donde empieza la numeración)
serie_cte	int	Serie del CT-e
number_cte	int	Número inicial del CT-e (donde empieza la numeración)
serie_dce	int	Serie de la DC-e
number_dce	int	Número inicial de la DC-e (donde empieza la numeración)

* Campo obligatorio. Enviar cnpj devuelve error. Todos los demás campos son opcionales — envíe solo los que desea modificar.

Ejemplo de carga útil

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

Ejemplo — habilitar NFC-e y CT-e en la empresa

        {
          "company_id": "comp_789012",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "serie_cte": 1,
          "number_cte": 1
        }

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": "contato@empresa.com",
                "cep": "01001000",
                "address": "Rua Exemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://exemplo.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": "contato@empresa.com",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://exemplo.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/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"
              }
            ]
          }
        }

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: `"Success"` (autorizada), `"Canceled"` (cancelada), `"Voided"` (inutilizada), `"Processing"` (en proceso), `"InvoicingFailed"` (fallo en la emisión), `"Failed"` (falló), `"Contingencia"` (contingencia offline), `"Unknown"` (desconocida)

* Campo obligatorio.

Ejemplo de llamada

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

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Success",
                "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 o por clave de acceso. 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
chave	string	Clave de acceso de la NF-e (44 dígitos)

Informe uuid o chave (al menos uno). Si se envían ambos, uuid tiene prioridad.

Ejemplo de llamada

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

Respuesta

        {
          "success": true,
          "data": {
            "id": "pedido-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Success",
            "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" }],
          "ibs_cbs":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "000", "classificacao_tributaria": "000001" }]
        }

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
        }

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 — la devolución es un clon integral de la NF-e original) o devolución parcial/personalizada (envía chave + los campos completos de la factura en el propio body, misma estructura que /api/invoice/create).

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 (devolución total; obligatorio si `chave` está ausente). Si se envía, la devolución es siempre total — los campos de la devolución parcial se ignoran
chave	string	Clave de 44 dígitos de la NF-e original (obligatoria en la devolución parcial; alternativa a `uuid` en la devolución total)
cfop *	string	CFOP de la devolución (ej.: `"1202"`, `"1411"`, `"2202"`, `"5202"`, `"5411"`, `"6202"`)
natureza_operacao	string	Naturaleza de la operación (ej.: "Devolução de venda"). Alias aceptado: `nature_of_operation`
transaction_type	string	Tipo de operación: `"0"`=entrada, `"1"`=salida (obligatorio en la devolución parcial). La devolución siempre se emite como entrada (`tpNF=0`)
model	string	Modelo del documento: `"55"` (obligatorio en la devolución parcial)
issuance_type	string	Tipo de emisión: `"1"`=normal (obligatorio en la devolución parcial)
ambiente	string	Ambiente: `"1"`=producción, `"2"`=homologación (obligatorio en la devolución parcial)
cliente	object	Datos del destinatario, misma estructura que `/api/invoice/create` (obligatorio en la devolución parcial). Particularidad: el campo del número de dirección es `number` (en inglés), no `numero`. Sin `number`, la dirección sale con nro "S/N"; el código IBGE, la ciudad y la UF se resuelven por el `cep`
products	array	Ítems devueltos, misma estructura que `/api/invoice/create` (obligatorio en la devolución parcial). `codigo` es opcional — si falta, el cProd usa el `name`

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

Automático en la devolución: el pago sale como 90 (Sin Pago) — pag_info se ignora; natureza_operacao vacía usa "Devolução de Mercadoria"; la tributación de los ítems (CST/CSOSN, PIS/COFINS, IPI, IBS/CBS) proviene de la categoría fiscal del category_id, según tipo de persona y escenario.

Ejemplo — devolución total

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolução de venda"
        }

Ejemplo — devolución parcial (campos completos en el body)

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolução 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": "Venda de mercadoria",
          "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": "Rua Exemplo",
            "number": "123",
            "complemento": "Sala 45",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01234567",
            "telefone": "11999999999",
            "email": "contato@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": "YOUR_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1"
            }
          ],
          "transportation": {
            "transport_mode": "0",
            "freight_amount": 30.00,
            "carrier_info": {
              "cnpj": "12345678000188",
              "name": "Transportadora Expressa",
              "endereco": "Rua da 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": "Rua do Remetente",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000"
          },
          "delivery_address": {
            "cnpj": "98765432000111",
            "name": "Destinatário Ltda",
            "endereco": "Rua do Destinatário",
            "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, 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": "YOUR_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": "YOUR_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).

percent Parámetros Tributarios Detallados

scale_balance Parámetros ICMS

Escenario de Tributación

padrao saida_fora_estado saida_dentro_estado entrada_fora_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 saida_fora_estado saida_dentro_estado entrada_fora_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

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://exemplo.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 cadastrada 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": "Loja Centro - Filial 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

Respuesta

        {
          "success": true,
          "message": "Empresa NFC-e atualizada com sucesso"
        }

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": "Loja Centro",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "complemento": "Sala 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://exemplo.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": "Success",
            "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"
          }
        }

GET /api/nfce/get_list

Listar NFC-e (paginado)

Lista las NFC-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: `"Success"` (autorizada), `"Canceled"` (cancelada), `"Processing"` (en proceso), `"Failed"` (falló), `"Unknown"` (desconocida)

* Campo obligatorio.

Ejemplo de llamada

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

Respuesta

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

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_PADRAO",
              "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": "Exemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contato@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Rua Exemplo",
          "house_number": "86",
          "complemento": "Andar 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.exemplo.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": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_dps.xml",
            "nfseXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_nfse.xml"
          }
        }

dpsXml: Enlace (URL en OSS) al XML enviado a la prefectura/ADN. nfseXml: Enlace al XML de retorno con el resultado de la emision. Los XML se suben al OSS en la primera consulta y la URL queda en cache.

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 preço",
          "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": "Corrigir nome do destinatario para 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.

GET /api/nfse/get_list

Listar NFS-e (paginado)

Lista las NFS-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: `"autorizada"`, `"cancelada"`, `"pendente"`, `"rejeitada"`

* Campo obligatorio.

Ejemplo de llamada

GET /api/nfse/get_list?page=1&page_size=20&status=autorizada

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "31250112345678000190000000000012345678901234",
                "codigo_verificacao": "ABCD-1234",
                "serie": 1,
                "number": 1,
                "status": "autorizada",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping MDF-e — Manifiesto Electrónico de Documentos Fiscales

La API de MDF-e (modelo 58, layout PL-MDFe 3.00) permite emitir, consultar, cancelar y cerrar manifiestos de transporte. El MDF-e agrega NF-es y/o CT-es vinculados a una operación de transporte, soportando 4 modales: carretero, aéreo, acuaviario y ferroviario. Toda la información operativa (conductor, vehículo, contratante, CIOT, vale de peaje, pago) va en el cuerpo del /create — no hay eventos de inclusión/modificación después de la emisión.

Endpoint	Método	Descripción
`/api/mdfe/create`	POST	Emitir MDF-e
`/api/mdfe/consult`	POST	Consultar situación del MDF-e
`/api/mdfe/cancel`	POST	Cancelar MDF-e (hasta 24h después de la autorización)
`/api/mdfe/close`	POST	Cerrar MDF-e (después de finalizar el viaje)

POST /api/mdfe/create

Emitir MDF-e

Emite un MDF-e a partir del cuerpo enviado. Los campos cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc son calculados automáticamente por el servidor. El cliente envía únicamente los campos de negocio. Los campos serie y nMDF son opcionales: se asignan automáticamente cuando se omiten (o valen 0), o se respetan cuando se envían en la solicitud (útil para saltar la numeración, por ejemplo tras una duplicidad en la SEFAZ).

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 — raíz

Campo	Tipo	Descripción
ide *	object	Identificación del MDF-e
emit *	object	Datos del emisor
infModal *	object	Información del modal (solo UNO de los cuatro: `rodo`, `aereo`, `aquav`, `ferrov`)
infDoc *	object	Documentos fiscales vinculados
tot *	object	Totalizadores de la carga
prodPred	object	Producto predominante de la carga
seg	array	Información de seguro
lacres	array	Precintos del MDF-e
autXML	array	CNPJs/CPFs autorizados a acceder al XML
infAdic	object	Información adicional (fisco y contribuyente)
infRespTec	object	Responsable técnico (CNPJ, contacto, email, etc.)

ide — Identificación

Campo	Tipo	Descripción
tpAmb *	int	Ambiente: `1`=producción, `2`=homologación
tpEmit *	int	Tipo del emisor: `1`=transportador, `2`=carga propia, `3`=prestador de servicio de transporte
modal *	string	Modal: `"1"`=carretero, `"2"`=aéreo, `"3"`=acuaviario, `"4"`=ferroviario
UFIni *	string	UF de inicio del viaje (2 letras)
UFFim *	string	UF de fin del viaje
infMunCarrega[] *	array	Municipios de carga: `[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	UFs del recorrido: `[{ UFPer }]`
tpTransp	string	Tipo de transportador (carretero)
dhIniViagem	string	Fecha/hora de inicio del viaje (ISO 8601)
indCanalVerde	string	Indicador de canal verde
indCarregaPosterior	string	Indicador de carga posterior
serie	int	Serie del MDF-e (3 dígitos de la clave de acceso). Opcional — autoasignada (serie de MDF-e de la empresa) cuando se omite o vale `0`; respetada cuando se envía
nMDF	int	Número del MDF-e (compone la clave de acceso). Opcional — autoincrementado por el servidor cuando se omite o vale `0`; respetado cuando se envía (útil para saltar la numeración, por ejemplo tras una duplicidad)

emit — Emisor

Campo	Tipo	Descripción
CNPJ ⚠	string	CNPJ del emisor (14 dígitos)
CPF ⚠	string	CPF del emisor (11 dígitos)
IE	string	Inscripción Estadual
xNome *	string	Razón social
xFant	string	Nombre de fantasía
enderEmit	object	Dirección: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — Modal Carretero (modal="1")

Campo	Tipo	Descripción
rodo.veicTracao *	object	Vehículo de tracción: `{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	Conductores: `[{ xNome, CPF }]` — mínimo 1
rodo.veicReboque[]	array	Vehículos de remolque (misma estructura de veicTracao sin conductor)
rodo.infANTT	object	Información de la ANTT: `{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	Código de agendamiento en el puerto
rodo.lacRodo[]	array	Precintos del modal: `[{ nLacre }]`

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

Campo	Tipo	Descripción
aereo.nac *	string	Marca de nacionalidad de la aeronave
aereo.matr *	string	Matrícula de la aeronave
aereo.nVoo *	string	Número del vuelo
aereo.cAerEmb *	string	Código IATA del aeropuerto de embarque
aereo.cAerDes *	string	Código IATA del aeropuerto de destino
aereo.dVoo *	string	Fecha del vuelo (AAAA-MM-DD)

infModal — Modal Acuaviario (modal="3")

Campo	Tipo	Descripción
aquav.irin *	string	IRIN de la embarcación
aquav.tpEmb *	string	Tipo de embarcación (2 dígitos). Use valores ≥ 10 para evitar el truncamiento del `byte` interno del Zeus (ej.: `"10"`, `"11"`)
aquav.cEmbar *	string	Código de la embarcación
aquav.xEmbar *	string	Nombre de la embarcación
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 del puerto de embarque
aquav.cPrtDest *	string	Código del puerto de destino
aquav.prtTrans	string	Puerto de transbordo
aquav.tpNav	string	Tipo de navegación
aquav.infTermCarreg[]	array	Terminales de carga: `[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	Terminales de descarga
aquav.infEmbComb[]	array	Embarcaciones de convoy: `[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	Unidades de carga vacías
aquav.infUnidTranspVazia[]	array	Unidades de transporte vacías

infModal — Modal Ferroviario (modal="4")

Campo	Tipo	Descripción
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 del 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	Descripción
infMunDescarga[] *	array	Municipios de descarga — mínimo 1
infMunDescarga[].cMunDescarga *	string	Código IBGE del municipio
infMunDescarga[].xMunDescarga *	string	Nombre del municipio
infMunDescarga[].infNFe[]	array	NF-es vinculadas: `[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	CT-es vinculados
infMunDescarga[].infMDFeTransp[]	array	MDF-es de transporte (subcontratación)

prodPred — Producto predominante

Campo	Tipo	Descripción
tpCarga *	string	Tipo de carga: `"01"`=granel sólido, `"02"`=granel líquido, `"03"`=refrigerada, `"04"`=contenerizada, `"05"`=carga general, `"06"`=neogranel, `"07"`=peligrosa, `"08"`=granel presurizado
xProd *	string	Descripción del producto predominante
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	Lotación: `{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — Totalizadores

Campo	Tipo	Descripción
vCarga *	decimal	Valor total de la carga (> 0)
cUnid *	string	Código de la unidad: `"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 obligatorio. ⚠ Al menos uno de CNPJ o CPF es obligatorio.

Ejemplo simplificado — Modal Carretero

        {
          "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
          }
        }

Ejemplo 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
          }
        }

Ejemplo simplificado — Modal Acuaviario

        {
          "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
          }
        }

Ejemplo simplificado — Modal Ferroviario

        {
          "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
          }
        }

Ejemplo completo (todos los campos) — Modal Carretero

        {
          "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"
          }
        }

Respuesta de éxito

        {
          "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 situación del MDF-e

Consulta la situación del MDF-e directamente en la SEFAZ a partir de la clave de acceso.

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
chMDFe *	string	Clave de acceso del MDF-e (44 dígitos)

* Campo obligatorio.

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 un MDF-e autorizado. Ventana: hasta 24 horas después de la autorización. No permitido si el MDF-e ya ha sido cerrado.

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
chMDFe *	string	Clave de acceso del MDF-e (44 dígitos)
xJust *	string	Justificación de la cancelación (mínimo 15 caracteres por exigencia SEFAZ)

* Campo obligatorio.

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

Cierra un MDF-e al final del viaje. Después del cierre, ya no es posible cancelar. Los campos dtEnc, cUF y cMun son opcionales — cuando se omiten, el sistema los infiere a partir del MDF-e original (fecha actual, UF y municipio del emisor).

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
chMDFe *	string	Clave de acceso del MDF-e (44 dígitos)
dtEnc	string	Fecha del cierre (AAAA-MM-DD). Default: fecha actual
cUF	int	Código IBGE de la UF donde ocurrió el cierre. Default: UF del emisor
cMun	string	Código IBGE del municipio donde ocurrió el cierre. Default: municipio del emisor

* Campo obligatorio.

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"
          }
        }

GET /api/mdfe/get_list

Listar MDF-e (paginado)

Lista los MDF-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: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Voided"` (cerrado), `"Processing"` (en proceso), `"Failed"` (falló), `"Unknown"` (desconocido)

* Campo obligatorio.

Ejemplo de llamada

GET /api/mdfe/get_list?page=1&page_size=20&status=Success

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190580010000000011000000015",
                "serie": 1,
                "number": 1,
                "modal": "1",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

inventory_2 DC-e — Declaración de Contenido Electrónica

La API de DC-e (modelo 99, layout 1.00) permite emitir, consultar, cancelar y obtener el PDF (DACE) de declaraciones de contenido electrónicas. La DC-e es el documento fiscal que ampara el transporte de bienes o mercancías cuando no existe obligación de emisión de nota fiscal — por ejemplo, envíos que involucran no contribuyentes del ICMS. El emisor es siempre persona jurídica (CNPJ); el destinatario puede ser persona jurídica (CNPJ) o física (CPF). Los datos de negocio van en el cuerpo del /create; los campos técnicos de la clave de acceso (cDC, cDV, cUF, dhEmi, mod) son calculados automáticamente por el servidor.

Endpoint	Método	Descripción
`/api/dce/create`	POST	Emitir DC-e
`/api/dce/consult`	POST	Consultar situación de la DC-e
`/api/dce/cancel`	POST	Cancelar DC-e autorizada
`/api/dce/pdf`	POST	Obtener el DACE (PDF) de la DC-e

La DC-e se enruta al autorizador de la UF del emisor. El campo ide.cUF debe ser coherente con la UF informada en emit.enderEmit.UF — SEFAZ rechaza con cStat=220 cuando divergen; si se omite, el cUF se deriva de esa UF.

POST /api/dce/create

Emitir DC-e

Emite una DC-e a partir del cuerpo enviado. El cliente envía únicamente los datos de negocio; los campos de identificación técnica de la clave de acceso son calculados por el servidor (ver la nota debajo de la tabla ide). El débito de crédito ocurre solo en producción (tpAmb=1) y cuando la DC-e es autorizada.

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 — raíz

Campo	Tipo	Descripción
ide *	object	Identificación de la DC-e
emit *	object	Datos del emisor/remitente (CNPJ; o CPF vía Marketplace — ver abajo)
dest *	object	Datos del destinatario
det *	array	Ítems/bienes declarados — mínimo 1
total *	object	Totalizador de la declaración
transp	object	Datos del transporte
marketplace	object	Datos del marketplace (solo cuando `ide.tpEmit=1`)
fisco	object	Datos del órgano del Fisco (solo cuando `ide.tpEmit=0`)
autXML	array	CNPJ/CPF autorizados a acceder al XML
infAdic	object	Información adicional

Campos obligatorios en la solicitud: ide.tpAmb; emit.CNPJ (14 dígitos) o emit.CPF (11 dígitos, remitente PF vía Marketplace — ver la nota en emit), emit.xNome y emit.enderEmit (xLgr, nro, xBairro, cMun, xMun, CEP con 8 dígitos, UF); dest con CNPJ o CPF, dest.xNome y dest.enderDest (los mismos campos de dirección); al menos 1 ítem en det con xProd, NCM (2 u 8 dígitos), qCom > 0 y vProd > 0; y total.vDC > 0. Todos los demás campos son opcionales.

ide — Identificación

Campo	Tipo	Descripción
tpAmb *	int	Ambiente: `1`=producción, `2`=homologación. Único campo de `ide` realmente obligatorio.
tpEmit	int	Tipo de emisor: `0`=Aplicación del Fisco, `1`=Marketplace, `2`=Emisor propio. Opcional — default: `2`
cUF	int	Código IBGE de la UF del emisor (2 dígitos). Opcional — derivado de `emit.enderEmit.UF` cuando se omite. Si se envía, debe ser coherente con esa UF (SEFAZ rechaza con `cStat=220` en caso de divergencia)
serie	int	Serie del documento fiscal (3 dígitos de la clave de acceso) — identifica el conjunto de numeración de la DC-e. Opcional — default: serie de DC-e registrada en la empresa
nDC	long	Número secuencial de la DC-e (compone la clave de acceso). Opcional — auto-incrementado por el servidor cuando se omite o es `0`
nSiteAutoriz	int	Identificación del sitio autorizador que procesó la DC-e (1 dígito de la clave de acceso). Normalmente `0` (sitio primario). Opcional — default: `0`
tpEmis	int	Forma de emisión: `1`=Normal, `9`=Contingencia. Opcional — default: `1`

Rellenados automáticamente por el servidor — no es necesario enviarlos: mod (fijo en 99) y cDV (dígito verificador de la clave) son siempre definidos por el servidor; cDC (código numérico de 6 dígitos), dhEmi (fecha/hora de emisión) y verProc (versión del proceso) se generan cuando se omiten. Los campos serie, nDC y cUF de la tabla anterior también se rellenan automáticamente cuando se omiten.

emit — Emisor / Remitente

Campo	Tipo	Descripción
CNPJ ⚠	string	CNPJ del emisor (14 dígitos). Rellenado con el CNPJ de la empresa del token cuando se omite
CPF ⚠	string	CPF del remitente persona física (11 dígitos). Solo permitido en la emisión vía Marketplace — ver nota abajo
xNome *	string	Nombre o razón social del emisor/remitente
enderEmit *	object	Dirección del emisor (ver estructura abajo)

Remitente persona física (CPF): por la regla de la SEFAZ, un CPF no puede ser emisor propio (tpEmit=2 exige CNPJ). Para emitir con un CPF como remitente, basta enviar emit.CPF (sin emit.CNPJ): el servidor define automáticamente tpEmit=1 (Marketplace), usa el CNPJ de su empresa (del token) como emisor autorizado en la clave de acceso y rellena el bloque marketplace con los datos de la empresa. El CPF informado aparece como remitente en emit.

dest — Destinatario

Campo	Tipo	Descripción
CNPJ ⚠	string	CNPJ del destinatario (14 dígitos)
CPF ⚠	string	CPF del destinatario (11 dígitos)
xNome *	string	Nombre o razón social del destinatario
enderDest *	object	Dirección del destinatario (ver estructura abajo)

enderEmit / enderDest — Dirección

Campo	Tipo	Descripción
xLgr *	string	Calle
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Barrio
cMun *	long	Código IBGE del municipio (7 dígitos)
xMun *	string	Nombre del municipio
CEP *	string	Código postal (8 dígitos)
UF *	string	Sigla de la UF (2 letras)
cPais	int	Código del país. Default: `1058` (Brasil)
xPais	string	Nombre del país. Default: `BRASIL`
fone	string	Teléfono
email	string	Correo electrónico

det[] — Ítems declarados

Campo	Tipo	Descripción
nItem	int	Número secuencial del ítem
xProd *	string	Descripción del bien/mercancía declarado
NCM *	string	Código NCM (2 u 8 dígitos)
qCom *	decimal	Cantidad (> 0)
vUnCom	decimal	Valor unitario
vProd *	decimal	Valor total del ítem (> 0)
infAdProd	string	Información adicional del ítem

total — Totalizador

Campo	Tipo	Descripción
vDC *	decimal	Valor total declarado (> 0)

transp — Transporte

Campo	Tipo	Descripción
modTrans	int	Modalidad del transporte: `0`=Correos, `1`=propia, `2`=transportista. Default: `2`
CNPJTransp	string	CNPJ del transportista

marketplace — Marketplace (solo `tpEmit=1`)

Campo	Tipo	Descripción
CNPJ	string	CNPJ del marketplace
xNome	string	Nombre del marketplace
Site	string	Sitio del marketplace

fisco — Órgano del Fisco (solo `tpEmit=0`)

Campo	Tipo	Descripción
CNPJ	string	CNPJ del órgano
xOrgao	string	Nombre del órgano
UF	string	UF del órgano

autXML[] — Autorizados al XML

Campo	Tipo	Descripción
CNPJ	string	CNPJ autorizado a consultar/descargar el XML
CPF	string	CPF autorizado a consultar/descargar el XML

infAdic — Información adicional

Campo	Tipo	Descripción
infAdFisco	string	Información de interés del Fisco
infCpl	string	Información complementaria de interés del contribuyente
infAdMarketPlace	string	Información adicional del marketplace

* Campo obligatorio. ⚠ En el emisor y en el destinatario, al menos uno de CNPJ o CPF es obligatorio.

Ejemplo simplificado (campos mínimos)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR"
            }
          },
          "dest": {
            "CPF": "12345678909",
            "xNome": "JOAO DA SILVA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR"
            }
          },
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00
            }
          ],
          "total": {
            "vDC": 150.00
          }
        }

Ejemplo completo (todos los campos)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "cUF": 41,
            "serie": 1,
            "nSiteAutoriz": 0
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "SALA 2",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4133334444",
              "email": "contato@exemplo.com"
            }
          },
          "dest": {
            "CNPJ": "98765432000188",
            "xNome": "DESTINATARIO EXEMPLO LTDA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xCpl": "GALPAO 3",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4333335555",
              "email": "destino@exemplo.com"
            }
          },
          "autXML": [
            { "CNPJ": "11222333000144" },
            { "CPF": "98765432100" }
          ],
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00,
              "infAdProd": "Caixa 1 de 2"
            },
            {
              "nItem": 2,
              "xProd": "MATERIAL DE ESCRITORIO",
              "NCM": "48201000",
              "qCom": 10,
              "vUnCom": 8.00,
              "vProd": 80.00,
              "infAdProd": "Caixa 2 de 2"
            }
          ],
          "total": {
            "vDC": 230.00
          },
          "transp": {
            "modTrans": 2,
            "CNPJTransp": "55666777000188"
          },
          "infAdic": {
            "infAdFisco": "Operacao nao sujeita a emissao de nota fiscal",
            "infCpl": "Remessa de bens entre filiais"
          }
        }

Respuesta de éxito

        {
          "success": true,
          "message": "DC-e autorizada",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Respuesta de rechazo

        {
          "success": false,
          "message": "DC-e rejeitada: Rejeicao: ...",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "225",
            "xMotivo": "Rejeicao: Falha no Schema XML",
            "nProt": "",
            "xml": "",
            "dace": ""
          }
        }

POST /api/dce/consult

Consultar situación de la DC-e

Consulta la situación actual de la DC-e en SEFAZ a partir de la clave de acceso. Cuando la DC-e está cancelada, la respuesta refleja los datos de la cancelación (la base local es la fuente de la verdad sobre la cancelació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
chDCe *	string	Clave de acceso de la DC-e (44 dígitos)

* Campo obligatorio.

Ejemplo de payload

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

Respuesta — DC-e activa

        {
          "success": true,
          "message": "Autorizado o uso do DC-e",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Success",
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Respuesta — DC-e cancelada

        {
          "success": true,
          "message": "DC-e Cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Canceled",
            "cStat": "101",
            "xMotivo": "Cancelamento de DCe homologado",
            "nProt": "141250000123457",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml",
            "dhEventoCancel": "2026-06-11T11:00:00-03:00"
          }
        }

POST /api/dce/cancel

Cancelar DC-e

Cancela una DC-e autorizada (evento 110111). Requiere que la DC-e haya sido autorizada (posea protocolo) y aún no esté cancelada. Cada DC-e admite una única cancelació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
chDCe *	string	Clave de acceso de la DC-e (44 dígitos)
xJust *	string	Justificación de la cancelación (mínimo 15 caracteres por exigencia de SEFAZ)
nProt	string	Protocolo de autorización. Opcional: cuando se omite, usa el protocolo registrado en la emisión

* Campo obligatorio.

Ejemplo de payload

        {
          "chDCe": "41250612345678000199990010000000011201234564",
          "xJust": "Cancelamento por erro no preenchimento dos dados da declaracao"
        }

Respuesta de éxito

        {
          "success": true,
          "message": "DC-e cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a DC-e",
            "nProtCancel": "141250000123457",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml"
          }
        }

En caso de rechazo, la respuesta retorna success=false, el cStat/xMotivo de la negativa y un campo adicional xmlEnviadoDebug con el XML enviado, para diagnóstico.

POST /api/dce/pdf

Obtener DACE (PDF) de la DC-e

Retorna la URL del DACE — la representación en PDF de la DC-e. Cuando el PDF aún no existe en el almacenamiento, se genera bajo demanda y se envía. En caso de que el almacenamiento esté indisponible, el PDF se retorna en base64 en el propio cuerpo de la respuesta.

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
chDCe *	string	Clave de acceso de la DC-e (44 dígitos)

* Campo obligatorio.

Ejemplo de payload

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

Respuesta — URL del PDF

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Respuesta — fallback base64 (almacenamiento indisponible)

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "pdfBase64": "JVBERi0xLjcKJ...",
            "pdfSize": 84213
          }
        }

GET /api/dce/get_list

Listar DC-e (paginado)

Lista las DC-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: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Processing"` (en proceso), `"Failed"` (falló), `"Unknown"` (desconocido)

* Campo obligatorio.

Ejemplo de llamada

GET /api/dce/get_list?page=1&page_size=20&status=Success

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190990010000000011000000013",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping CT-e — Conocimiento de Transporte Electrónico

La API de CT-e (modelo 57, layout 4.00 + NT2025/001) permite emitir, cancelar, corregir (CC-e), registrar prestación en desacuerdo, consultar e inutilizar numeración de Conocimientos de Transporte Electrónicos. El CT-e documenta la prestación de servicio de transporte de cargas. Admite 6 modales (carretero, aéreo, acuaviario, ferroviario, ductoviario, multimodal) y 4 tipos de CT-e (Normal, Complemento, Anulación, Sustituto). Los datos de negocio van en el cuerpo del /create; los campos técnicos de la clave de acceso (cCT, cDV, cUF, dhEmi, mod) son calculados automáticamente por el servidor. Los campos serie y nCT son opcionales: se asignan automáticamente cuando se omiten (o valen 0), o se respetan cuando se envían en la solicitud (útil para saltar la numeración, por ejemplo tras una duplicidad en la SEFAZ).

Endpoint	Método	Descripción
`/api/cte/create`	POST	Emitir CT-e
`/api/cte/cancel`	POST	Cancelar CT-e (evento 110111)
`/api/cte/cce`	POST	Carta de Corrección — CC-e (evento 110110)
`/api/cte/desacordo`	POST	Prestación en Desacuerdo (evento 610110, registrado por el tomador)
`/api/cte/consult`	POST	Consultar situación del CT-e
`/api/cte/inutilize`	POST	Inutilizar rango de numeración

El tomador del servicio (quien paga el flete) se define en ide.toma: 0=Remitente, 1=Expedidor, 2=Recibidor, 3=Destinatario, 4=Otros (en este caso complete ide.toma4).

POST /api/cte/create

Emitir CT-e

Emite un CT-e a partir del cuerpo enviado. El cliente envía únicamente los datos de negocio; los campos de identificación técnica de la clave de acceso son calculados por el servidor (ver la nota debajo de la tabla ide). El débito de crédito ocurre solo en producción (tpAmb=1) y cuando el CT-e es autorizado. Los ejemplos a continuación cubren el caso más común: modal carretero (modal=01) y CT-e Normal (tpCTe=0).

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)

Campos obligatorios en la solicitud: ide (tpAmb, CFOP, natOp, modal, tpCTe, toma, cMunIni, UFIni, cMunFim, UFFim); emit con CNPJ o CPF y xNome; rem con CNPJ o CPF; dest con CNPJ o CPF; vPrest.vTPrest > 0; imp (con una variante de ICMS). Para tpCTe=0 (Normal): infCTeNorm con infCarga (proPred + al menos 1 infQ) e infModal (el modal correspondiente a ide.modal; para modal=01, rodo.RNTRC es obligatorio). Los demás campos son opcionales.

Body — raíz

Campo	Tipo	Descripción
ide *	object	Identificación del CT-e
emit *	object	Datos del emisor (transportista)
rem *	object	Remitente de la carga
dest *	object	Destinatario de la carga
vPrest *	object	Valores de la prestación del servicio
imp *	object	Impuestos (ICMS + tributos)
infCTeNorm *	object	Cuerpo del CT-e Normal — obligatorio cuando `tpCTe=0` (Normal) o `3` (Sustituto)
exped	object	Expedidor (opcional)
receb	object	Recibidor (opcional)
compl	object	Datos complementarios (observaciones, flujo, entrega)
infCteComp	object	Clave del CT-e complementado — obligatorio cuando `tpCTe=1` (Complemento): `{ chCTe }`
infCteAnu	object	Clave del CT-e anulado — obligatorio cuando `tpCTe=2` (Anulación): `{ chCte, dEmi }`
autXML	array	CNPJ/CPF autorizados a acceder al XML: `[{ CNPJ } \| { CPF }]`
infRespTec	object	Responsable técnico — rellenado automáticamente por el servidor según la UF

ide — Identificación

Campo	Tipo	Descripción
tpAmb *	int	Ambiente: `1`=producción, `2`=homologación
CFOP *	int	Código fiscal de la operación (ej.: `5353` dentro del estado, `6353` interestatal)
natOp *	string	Naturaleza de la operación (ej.: `"PRESTACAO DE SERVICO DE TRANSPORTE"`)
modal *	string	Modal: `"01"`=carretero, `"02"`=aéreo, `"03"`=acuaviario, `"04"`=ferroviario, `"05"`=ductoviario, `"06"`=multimodal
tpCTe *	int	Tipo del CT-e: `0`=Normal, `1`=Complemento, `2`=Anulación, `3`=Sustituto
tpServ *	int	Tipo de servicio: `0`=Normal, `1`=Subcontratación, `2`=Reexpedición, `3`=Reexpedición Intermedia, `4`=Servicio Vinculado a Multimodal
toma *	int	Tomador del servicio: `0`=Remitente, `1`=Expedidor, `2`=Recibidor, `3`=Destinatario, `4`=Otros
toma4	object	Datos del tomador — obligatorio cuando `toma=4` (ver tabla abajo)
indIEToma	int	Indicador de IE del tomador: `1`=Contribuyente ICMS, `2`=Exento, `9`=No Contribuyente (cuando `9`, la IE del tomador se omite automáticamente)
cMunIni *	long	Código IBGE del municipio de inicio de la prestación (7 dígitos)
xMunIni	string	Nombre del municipio de inicio
UFIni *	string	UF de inicio (2 letras)
cMunFim *	long	Código IBGE del municipio de fin de la prestación (7 dígitos)
xMunFim	string	Nombre del municipio de fin
UFFim *	string	UF de fin (2 letras)
cMunEnv	long	Código IBGE del municipio de emisión
xMunEnv	string	Nombre del municipio de emisión
UFEnv	string	UF de emisión
retira	int	Retira en el origen: `0`=Sí, `1`=No. Default: `1`
xDetRetira	string	Detalles de la retirada
tpImp	int	Formato del DACTE: `1`=Vertical, `2`=Horizontal. Default: `1`
infPercurso	array	UF del recorrido: `[{ UFPer }]`
dhCont	string	Fecha/hora de entrada en contingencia (ISO 8601)
xJust	string	Justificación de la contingencia
serie	int	Serie del CT-e (3 dígitos de la clave de acceso). Opcional — autoasignada (serie de CT-e de la empresa) cuando se omite o vale `0`; respetada cuando se envía
nCT	long	Número del CT-e (compone la clave de acceso). Opcional — autoincrementado por el servidor cuando se omite o vale `0`; respetado cuando se envía (útil para saltar la numeración, por ejemplo tras una duplicidad)

Rellenados automáticamente por el servidor — no es necesario enviarlos: mod (fijo en 57), cCT (código numérico de 8 dígitos), cDV (dígito verificador), cUF (derivado de la UF del emisor), dhEmi (fecha/hora actual), tpEmis (default 1=Normal), procEmi y verProc.

toma4 — Tomador "Otros" (cuando `ide.toma=4`)

Campo	Tipo	Descripción
CNPJ ⚠ / CPF ⚠	string	Documento del tomador (uno de los dos)
IE	string	Inscripción Estatal
xNome	string	Razón social/nombre
xFant, fone, email	string	Nombre de fantasía, teléfono, correo electrónico
enderToma	object	Dirección: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }`

emit — Emisor (transportista)

Campo	Tipo	Descripción
CNPJ ⚠	string	CNPJ del emisor (14 dígitos)
CPF ⚠	string	CPF del emisor (11 dígitos)
IE	string	Inscripción Estatal
IEST	string	Inscripción Estatal del sustituto tributario
xNome *	string	Razón social
xFant	string	Nombre de fantasía
CRT	int	Código de Régimen Tributario: `1`=Simples Nacional, `2`=SN exceso de sublímite, `3`=Régimen Normal, `4`=MEI. Default: `3`
enderEmit	object	Dirección: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }`

rem — Remitente

Campo	Tipo	Descripción
CNPJ ⚠ / CPF ⚠	string	Documento del remitente (uno de los dos)
IE	string	Inscripción Estatal (o `"ISENTO"`)
xNome	string	Razón social/nombre
xFant, fone, email	string	Nombre de fantasía, teléfono, correo electrónico
enderReme	object	Dirección del remitente (estructura abajo)
locColeta	array	Lugares de recolección (opcional): `[{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]`

dest — Destinatario

Campo	Tipo	Descripción
CNPJ ⚠ / CPF ⚠	string	Documento del destinatario (uno de los dos)
IE	string	Inscripción Estatal (o `"ISENTO"`)
xNome	string	Razón social/nombre
fone, email, ISUF	string	Teléfono, correo electrónico, Inscripción en SUFRAMA
enderDest	object	Dirección del destinatario (estructura abajo)
locEnt	object	Lugar de entrega (opcional): `{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }`

exped / receb — Expedidor / Recibidor (opcionales)

Campo	Tipo	Descripción
CNPJ / CPF	string	Documento (uno de los dos)
IE, xNome, fone, email	string	Inscripción Estatal, nombre, teléfono, correo electrónico
enderExped / enderReceb	object	Dirección (la misma estructura genérica abajo)

Dirección (enderEmit / enderReme / enderExped / enderReceb / enderDest)

Campo	Tipo	Descripción
xLgr	string	Calle/dirección
nro	string	Número
xCpl	string	Complemento
xBairro	string	Barrio
cMun	string	Código IBGE del municipio (7 dígitos)
xMun	string	Nombre del municipio
CEP	string	CEP (8 dígitos) — no usado en `enderEmit`
UF	string	Sigla de la UF (2 letras)
cPais	string	Código del país (opcional, default 1058 Brasil)
xPais	string	Nombre del país (opcional)
fone	string	Teléfono (solo en `enderEmit`)

vPrest — Valores de la Prestación

Campo	Tipo	Descripción
vTPrest *	decimal	Valor total de la prestación del servicio (> 0)
vRec	decimal	Valor a recibir
Comp	array	Componentes del valor: `[{ xNome, vComp }]` — ej.: `"FRETE PESO"`, `"PEDÁGIO"`, `"GRIS"`

imp — Impuestos

Campo	Tipo	Descripción
ICMS *	object	Tributación del ICMS — complete solo una de las variantes (ver abajo)
vTotTrib	decimal	Valor aproximado total de tributos
infAdFisco	string	Información adicional de interés del Fisco
ICMSUFFim	object	DIFAL (reparto interestatal, opcional): `{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }`
infTribFed	object	Tributos federales (opcional): `{ vPIS, vCOFINS, vIR, vINSS, vCSLL }`

ICMS — variantes (completar solo una)

Variante	Cuándo usar	Campos
ICMS00	Tributación normal	`{ vBC, pICMS, vICMS }` (CST 00)
ICMS20	Con reducción de base de cálculo	`{ pRedBC, vBC, pICMS, vICMS }` (CST 20)
ICMS45	Exenta / no tributada / diferida	`{ CST }` — `"40"`=Exenta, `"41"`=No tributada, `"51"`=Diferido
ICMS60	ICMS cobrado por sustitución tributaria	`{ vBCSTRet, vICMSSTRet, pICMSSTRet, vCred }` (CST 60)
ICMS90	Otros (régimen especial)	`{ pRedBC, vBC, pICMS, vICMS, vCred }` (CST 90)
ICMSOutraUF	ICMS debido a otra UF	`{ pRedBCOutraUF, vBCOutraUF, pICMSOutraUF, vICMSOutraUF }`
ICMSSN	Emisor del Simples Nacional	`{ CST: "90", indSN: 1 }`

infCTeNorm — CT-e Normal (obligatorio para `tpCTe=0`/`3`)

Campo	Tipo	Descripción
infCarga *	object	Información de la carga (tabla abajo)
infDoc	object	Documentos transportados (tabla abajo)
infModal *	object	Información del modal (tabla abajo)
docAnt	object	Documentos anteriores (subcontratación/reexpedición): `{ emiDocAnt[]{ CNPJ\|CPF, IE, UF, xNome, idDocAnt[] } }`
seg	array	Seguro de la carga: `[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }]` — `respSeg`: 1=Remitente…6=Tomador
cobr	object	Cobranza/facturas: `{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } }`
veicNovos	array	Vehículos nuevos transportados: `[{ chassi, cCor, xCor, cMod, vUnit, vFrete }]`
infCteSub	object	Sustitución — obligatorio cuando `tpCTe=3`: `{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS }`

infCTeNorm.infCarga — Carga

Campo	Tipo	Descripción
proPred *	string	Producto predominante
vCarga	decimal	Valor total de la carga
xOutCat	string	Otras características de la carga (ej.: FRIA, GRANEL, REFRIGERADA)
vCargaAverb	decimal	Valor de la carga para efecto de averiguación
infQ[] *	array	Cantidades — mínimo 1: `[{ cUnid, tpMed, qCarga }]`
infQ[].cUnid	string	Unidad: `"00"`=M³, `"01"`=KG, `"02"`=TON, `"03"`=UNIDAD, `"04"`=LITROS, `"05"`=MMBTU
infQ[].tpMed	string	Tipo de medida (ej.: `"PESO BRUTO"`, `"PESO DECLARADO"`)
infQ[].qCarga	decimal	Cantidad

infCTeNorm.infDoc — Documentos transportados

Campo	Tipo	Descripción
infNFe	array	NF-e por clave de acceso: `[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }]` — `chave` con 44 dígitos
infNF	array	Notas en papel (legado): `[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }]`
infOutros	array	Otros documentos: `[{ tpDoc, descOutros, nDoc, dEmi, vDocFisc }]` — `tpDoc`: `"00"`=Declaración, `"10"`=Ductoviario, `"99"`=Otros

infCTeNorm.infModal — Modales (completar solo el correspondiente a `ide.modal`)

Modal	Objeto	Campos
01 Carretero	rodo	`{ RNTRC* }` — RNTRC con 8 dígitos o `"ISENTO"`. Opcional: `occ[]` (órdenes de recolección)
02 Aéreo	aereo	`{ nMinu, nOCA, dPrevAereo, natCarga{ xDime, cInfManu[] }, tarifa{ CL, cTar, vTar }, peri[] }` — `dPrevAereo` AAAA-MM-DD
03 Acuaviario	aquav	`{ vPrest, vAFRMM, xNavio, nViag, direc, irin, tpNav, balsa[], detCont[] }` — `direc`: N/L/S/O; `tpNav`: 0=Interior, 1=Cabotaje
04 Ferroviario	ferrov	`{ tpTraf, respFat, ferrEmi, vFrete, chCTeFerroOrigem, ferroEnv[] }` — `tpTraf`: 0=Propio, 1=Mutuo, 2=Rodoferroviario, 3=Carretero
05 Ductoviario	duto	`{ vTar, dIni, dFim }` — fechas AAAA-MM-DD
06 Multimodal	multimodal	`{ COTM, indNegociavel, seg[] }` — `indNegociavel`: 0=No, 1=Sí

Todo el bloque infModal acepta versaoModal (default "4.00").

compl — Datos complementarios (opcional)

Campo	Tipo	Descripción
xCaracAd, xCaracSer, xEmi	string	Característica adicional del transporte / del servicio / nombre del emisor
origCalc, destCalc	string	Municipio de origen / destino para cálculo del flete
xObs	string	Observaciones generales
ObsCont / ObsFisco	array	Observaciones libres del contribuyente / fisco: `[{ xCampo, xTexto }]`
fluxo, Entrega	object	Flujo de carga (origen/paso/destino/ruta) y previsión de entrega

* Campo obligatorio. ⚠ Al menos uno de CNPJ o CPF es obligatorio en el grupo.

Ejemplo simplificado — Modal Carretero, Simples Nacional

        {
          "ide": {
            "CFOP": 5353,
            "natOp": "PRESTACAO DE SERVICO DE TRANSPORTE",
            "tpAmb": 2,
            "tpCTe": 0,
            "modal": "01",
            "tpServ": 0,
            "cMunEnv": 3550308,
            "xMunEnv": "SAO PAULO",
            "UFEnv": "SP",
            "cMunIni": 3550308,
            "xMunIni": "SAO PAULO",
            "UFIni": "SP",
            "cMunFim": 3304557,
            "xMunFim": "RIO DE JANEIRO",
            "UFFim": "RJ",
            "retira": 1,
            "indIEToma": 9,
            "toma": 0
          },
          "emit": {
            "CNPJ": "26638419000167",
            "IE": "141507411110",
            "CRT": 1,
            "xNome": "TF COMERCIO DE PRESENTES LTDA",
            "enderEmit": {
              "xLgr": "RUA QUINTANA",
              "nro": "34",
              "xBairro": "CIDADE MONCOES",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "04571010",
              "UF": "SP",
              "fone": "1133334444"
            }
          },
          "rem": {
            "CNPJ": "11111111000111",
            "IE": "ISENTO",
            "xNome": "EMPRESA REMETENTE LTDA",
            "fone": "1122223333",
            "enderReme": {
              "xLgr": "AV PAULISTA",
              "nro": "1500",
              "xBairro": "BELA VISTA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01310200",
              "UF": "SP"
            }
          },
          "dest": {
            "CNPJ": "22222222000122",
            "IE": "ISENTO",
            "xNome": "EMPRESA DESTINATARIA LTDA",
            "fone": "2133334444",
            "enderDest": {
              "xLgr": "AV RIO BRANCO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3304557",
              "xMun": "RIO DE JANEIRO",
              "CEP": "20040002",
              "UF": "RJ"
            }
          },
          "vPrest": {
            "vTPrest": 1500.00,
            "vRec": 1500.00,
            "Comp": [
              { "xNome": "FRETE PESO", "vComp": 1500.00 }
            ]
          },
          "imp": {
            "ICMS": {
              "ICMSSN": { "CST": "90", "indSN": 1 }
            },
            "vTotTrib": 0
          },
          "infCTeNorm": {
            "infCarga": {
              "vCarga": 10000.00,
              "proPred": "PRODUTOS DIVERSOS",
              "infQ": [
                { "cUnid": "01", "tpMed": "PESO BRUTO", "qCarga": 1000.0000 }
              ]
            },
            "infDoc": {
              "infNFe": [
                { "chave": "35260526638419000167550030000006561341688760" }
              ]
            },
            "infModal": {
              "versaoModal": "4.00",
              "rodo": {
                "RNTRC": "12345678"
              }
            }
          }
        }

Respuesta de éxito

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

Respuesta de rechazo

        {
          "success": false,
          "message": "Rejeicao: ...",
          "data": {
            "cStat": "539",
            "chCTe": "",
            "nProt": "",
            "xml": ""
          }
        }

POST /api/cte/cancel

Cancelar CT-e

Cancela un CT-e autorizado (evento 110111). Requiere que el CT-e haya sido autorizado (posea protocolo) y que aún no esté cancelado.

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
chCTe *	string	Clave de acceso del CT-e (44 dígitos)
xJust *	string	Justificación del cancelamiento (mínimo 15 caracteres por exigencia de SEFAZ)
nProt	string	Protocolo de autorización. Opcional: cuando se omite, usa el protocolo registrado en la emisión

* Campo obligatorio.

Ejemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xJust": "Cancelamento por erro no preenchimento dos dados da prestacao"
        }

Respuesta de éxito

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123457",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/cce

Carta de Corrección (CC-e)

Registra una Carta de Corrección Electrónica (evento 110110) sobre un CT-e autorizado. La CC-e no puede corregir valores que impacten el impuesto, datos registrales que cambien emisor/tomador/remitente/destinatario, ni la fecha de emisión. Cada corrección indica el grupo, campo y nuevo valor.

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
chCTe *	string	Clave de acceso del CT-e (44 dígitos)
infCorrecao[] *	array	Correcciones (mínimo 1, hasta 20)
infCorrecao[].grupoAlterado *	string	Grupo alterado (ej.: `"ide"`, `"rem"`, `"dest"`)
infCorrecao[].campoAlterado *	string	Campo alterado (ej.: `"xNome"`)
infCorrecao[].valorAlterado *	string	Nuevo valor
infCorrecao[].nroItemAlterado	int	Número del ítem alterado (cuando el grupo sea una lista)

* Campo obligatorio. La condición de uso (xCondUso) es rellenada automáticamente por el servidor.

Ejemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "infCorrecao": [
            {
              "grupoAlterado": "compl",
              "campoAlterado": "xObs",
              "valorAlterado": "OBSERVACAO CORRIGIDA"
            }
          ]
        }

Respuesta de éxito

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123458",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/desacordo

Prestación en Desacuerdo

Registra la Prestación de Servicio en Desacuerdo (evento 610110) — utilizada por el tomador del servicio para manifestar que la prestación descrita en el CT-e está en desacuerdo con lo contratado. El CNPJ que registra el evento (el tomador) es el de la empresa del token; no es necesario ser el emisor del CT-e.

Headers obligatorios

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

Body

Campo	Tipo	Descripción
chCTe *	string	Clave de acceso del CT-e (44 dígitos)
xObs *	string	Descripción del desacuerdo (mínimo 15 caracteres)

* Campo obligatorio. El indicador de operación en desacuerdo es siempre 1 (PL-CTe v4.00).

Ejemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xObs": "Valor do frete cobrado diverge do contratado entre as partes"
        }

Respuesta de éxito

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123459"
          }
        }

POST /api/cte/consult

Consultar situación del CT-e

Consulta la situación del CT-e en SEFAZ a partir de la clave de acceso. Cuando el CT-e está cancelado (registro local), la respuesta refleja el cancelamiento.

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
chCTe *	string	Clave de acceso del CT-e (44 dígitos)

* Campo obligatorio.

Ejemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780"
        }

Respuesta

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

POST /api/cte/inutilize

Inutilizar rango de numeración

Inutiliza un rango de numeración de CT-e que no será utilizado (por ejemplo, tras una ruptura de secuencia). La inutilización es definitiva.

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
tpAmb *	int	Ambiente: `1`=producción, `2`=homologación
CNPJ *	string	CNPJ del emisor (14 dígitos)
ano *	int	Año de la numeración (2 dígitos, ej.: `26` para 2026)
serie *	int	Serie de la numeración
nCTIni *	long	Número inicial del rango
nCTFin *	long	Número final del rango (≥ `nCTIni`)
xJust *	string	Justificación (mínimo 15 caracteres)
mod	int	Modelo. Default: `57`

* Campo obligatorio.

Ejemplo de payload

        {
          "tpAmb": 2,
          "CNPJ": "26638419000167",
          "ano": 26,
          "serie": 1,
          "nCTIni": 51,
          "nCTFin": 55,
          "xJust": "Quebra de sequencia na numeracao por falha no sistema emissor"
        }

Respuesta de éxito

        {
          "success": true,
          "message": "Inutilizacao de numero homologado",
          "data": {
            "cStat": "102",
            "chCTe": "",
            "nProt": "135260000123460"
          }
        }

GET /api/cte/get_list

Listar CT-e (paginado)

Lista los CT-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: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Processing"` (en proceso), `"Failed"` (falló), `"Unknown"` (desconocido)

* Campo obligatorio.

Ejemplo de llamada

GET /api/cte/get_list?page=1&page_size=20&status=Success

Respuesta

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190570010000000011000000019",
                "serie": 1,
                "number": 1,
                "modal": "01",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

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@escritorio.com"
        }

Respuesta de éxito

        {
          "success": true,
          "data": {
            "email": "contador@escritorio.com",
            "officeDocumentType": "CNPJ",
            "officeDocument": "12345678000199",
            "officeName": "Escritório Contábil LTDA",
            "responsibleName": "João da Silva",
            "crc": "SP123456/O-7",
            "accountantCpf": "12345678909",
            "workAddress": "Rua Exemplo, 100 - Centro - São Paulo/SP",
            "site": "https://escritorio.com",
            "landline": "1133334444",
            "mobile": "11999998888",
            "assistantName": "Maria Souza",
            "assistantEmail": "maria@escritorio.com",
            "assistantPhone": "11988887777",
            "observations": "Atendimento de segunda a sexta, 9h às 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

verified_user Validación de CPF y CNPJ

API para validar CPF y CNPJ contra la base oficial de la Hacienda Federal de Brasil (Receita Federal). Para CPF, devuelve nombre, situación registral, edad y bloqueo automático de menores de edad (conforme a LGPD). Para CNPJ, devuelve razón social, nombre comercial, dirección, accionistas y situación registral completa. Recomendado para validar registros antes de emitir documentos fiscales e identificar contribuyentes con situación irregular (suspendida, cancelada, dada de baja).

POST /api/invoice/validar_cpf_cnpj

Valida CPF (con fecha de nacimiento) o CNPJ contra la base oficial de la Hacienda Federal de Brasil

Acepta CPF o CNPJ, con o sin formato. El tipo de documento se detecta automáticamente. Para CPF, dataNascimento es obligatorio.

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
cpfCnpj *	string	CPF (11 dígitos) o CNPJ (14 caracteres). Acepta formato.
dataNascimento	string	Fecha de nacimiento — obligatoria solo para CPF. Formatos aceptados: `dd/MM/yyyy`, `dd-MM-yyyy` o `ddMMyyyy`.

* Campo obligatorio.

Ejemplo de payload — CPF

        {
          "cpfCnpj": "407.105.368-28",
          "dataNascimento": "09/01/1997"
        }

Ejemplo de payload — CNPJ

        {
          "cpfCnpj": "03.354.151/0001-36"
        }

Respuesta — CPF encontrado, situación regular

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "nome": "FULANO DE TAL",
            "situacao_codigo": "0",
            "situação_descricao": "REGULAR",
            "menor_de_idade_lgpd": false,
            "idade": 29,
            "data_nascimento": "1997-01-09"
          }
        }

Respuesta — CPF de menor de edad (LGPD)

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "situação_descricao": "Menor de idade",
            "menor_de_idade_lgpd": true
          }
        }

Respuesta — CPF no encontrado

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "Situação": "CPF não encontrado"
          }
        }

Respuesta — Fecha de nacimiento no coincide con el CPF

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "Situação": "Data de nascimento não confere com o CPF"
          }
        }

Respuesta — CNPJ encontrado

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "03354151000136",
            "nome": "EMPRESA EXEMPLO LTDA",
            "situacao_codigo": "2",
            "situação_descricao": "Ativo",
            "nome_empresarial": "EMPRESA EXEMPLO LTDA",
            "nome_fantasia": "EXEMPLO",
            "data_situacao": "20180515",
            "motivo_situacao": ""
          }
        }

Respuesta — CNPJ no encontrado

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "12345678000199",
            "Situação": "Não encontrado"
          }
        }

Códigos de Situación CPF

Código	Descripción
0	REGULAR (activo)
2	SUSPENDIDO
3	TITULAR FALLECIDO
4	PENDIENTE DE REGULARIZACIÓN
5	CANCELADO POR DUPLICIDAD
8	NULO
9	CANCELADO DE OFICIO

Códigos de Situación CNPJ

Código	Descripción
1	Nulo
2	Activo
3	Suspendido
4	Inapto
8	Dado de baja

Respuestas de error

Mensaje	Causa
cpfCnpj é obrigatório	Campo `cpfCnpj` ausente o vacío
CPF inválido, verifique a quantidade de dígitos	El CPF informado no tiene 11 dígitos
CPF inválido	El CPF informado tiene dígitos verificadores inválidos o contiene letras
CNPJ inválido, verifique a quantidade de dígitos	El CNPJ informado no tiene 14 caracteres
CNPJ inválido	El CNPJ informado tiene dígitos verificadores inválidos
é necessário informar a data de nascimento	CPF enviado sin `dataNascimento`
dataNascimento inválida (use dd/MM/yyyy)	El formato de la fecha no coincide con ninguno aceptado

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

Ejemplo — habilitar NFC-e y CT-e en la empresa

Respuesta

Headers obligatorios

Query string

Ejemplo de llamada

Respuesta

Headers obligatorios

Ejemplo de llamada

Respuesta

Headers obligatorios

Query string

Ejemplo de llamada

Respuesta

Headers obligatorios

Ejemplo de llamada

Respuesta

Ejemplo de 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

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)