NF-e

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

Body — campos de nivel superior

Body — cliente (objeto, obligatorio)

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

Body — products[].impostos

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "2" }
}

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "1",
            "difal_desconta_icms_inter": true,
            "difal_base_por_dentro": true }
}

{
  "icms": { "aliquota": "4", "aliquota_fcp": "1", "v_bc_uf_dest": "122.29" }
}

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)

* Campo obligatorio.

Campos de la respuesta (data)

Respuesta — rechazo / error

        {
          "success": false,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Failed",
            "motivo": "Rejeição 226: Código da UF do Emitente diverge da UF autorizadora / 拒绝 226: 发件人所在州代码与授权州不一致",
            "nfe": 100,
            "serie": 1,
            "chave": "",
            "modelo": "nfe",
            "epec": false,
            "xml": ""
          }
        }

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

Query string

* Campo obligatorio.

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

Query string

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

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

Headers obligatorios

Body

* Campo obligatorio.

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

Headers obligatorios

Body

* Campo obligatorio.

Campos de la respuesta (data)

Respuesta — error

        {
          "success": false,
          "message": "Rejeição: NF-e já está cancelada na base de dados da autoridad fiscal"
        }

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 la autoridad fiscal y es irreversible.

Headers obligatorios

Body

* Campo obligatorio.

Campos de la respuesta (data)

Respuesta — error

        {
          "success": false,
          "message": "Rejeição: Faixa de numeração já inutilizada"
        }

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

Body

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

Campos de la respuesta

Respuestas de error

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

Body

* Campo obligatorio.

Campos de la respuesta

Respuestas de error

Consulta el estado actual de una NF-e o NFC-e directamente en la autoridad fiscal 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

Body

* Campo obligatorio.

Campos de la respuesta

Mapeo de estados

Respuestas de error

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

Body — campos siempre leídos de la raíz

Body — campos dentro de return_detail

Todos los campos siguientes van dentro del objeto return_detail. Colocarlos en la raíz de la petición no funciona: el endpoint devuelve error en lugar de caer silenciosamente en la devolución total.

* 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, o se envía en línea por ítem mediante impostos — uno u otro.

Headers obligatorios

Headers obligatorios

El cuerpo de la solicitud y la validación son idénticos a /api/invoice/create. La diferencia es que no espera a la autoridad fiscal: tras la validación la solicitud entra en cola y se devuelve de inmediato el número de recepción task_id; la emisión se completa en segundo plano. Obtenga el resultado consultando /api/invoice/v2/task/get o recíbalo en la dirección de webhook configurada en el portal (vea “Webhook” abajo).

Cabeceras obligatorias

Body

Reglas de procesamiento

Campos de la respuesta

Respuesta — rechazada

{ "success": false, "message": "Rate limit exceeded for this CNPJ, please slow down" }

Consulta estado y resultado por task_id. La ruta oficial es /api/invoice/v2/task/get; la ruta antigua /api/invoice/task/get sigue disponible con comportamiento y cobro idénticos. Solo se pueden consultar tareas de la propia cuenta; de lo contrario Task not found. Consulte cada 1–2 segundos; las tareas suelen terminar en segundos.

Cabeceras obligatorias

Body

status

Envía una CC-e (evento 110110) a la autoridad fiscal 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

Body

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

Las facturas emitidas en otro proveedor también admiten carta de corrección: la carta es un evento independiente de la factura original y basta con que el número de identificación fiscal del emisor contenido en la clave de acceso pertenezca a una empresa de este token. Para estas facturas la plataforma no conserva el registro original, por lo que el número de secuencia no puede calcularse y se asume 1. Si la autoridad fiscal informa que ya existe un evento con ese número, reenvíe con un n_seq_evento mayor. Para estas facturas no se genera el PDF de la carta de corrección, solo el XML del evento.

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

Body

Al menos uno entre uuid y chave es obligatorio.

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

Body

* Campo obligatorio.

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

Headers obligatorios

Body

* Campo obligatorio.