Informe fiscal LHDN

Enviar informe fiscal a la LHDN (Malasia) mediante la API de B2Brouter

Esta guía explica cómo activar y generar un informe fiscal para la Inland Revenue Board of Malaysia (LHDN) a través de la API de B2Brouter.

Entornos de prueba: Usa el sandbox para las pruebas iniciales de la API y la validación de payloads — el sandbox simula las presentaciones a la LHDN para que puedas ejercitar el ciclo de vida completo de la factura sin conectarte a ninguna autoridad real. Para pruebas completas de extremo a extremo contra el endpoint de pruebas propio de la LHDN, usa el entorno de staging (api-staging.b2brouter.net).

Descripción general: proceso de validación

El proceso de reporte fiscal de la LHDN (Lembaga Hasil Dalam Negeri, o Inland Revenue Board of Malaysia) opera como un modelo de validación (clearance). Esto significa que cada factura emitida debe ser reportada y aprobada por la autoridad fiscal.

Al usar B2Brouter, cada informe fiscal enviado a la LHDN será validado automáticamente por esta autoridad. Por tanto, la factura solo puede considerarse legalmente válida tras la validación exitosa por parte de la LHDN.

A continuación se describen los pasos para configurar y gestionar las presentaciones de informes fiscales a la LHDN mediante la API de B2Brouter.

Paso 1: Requisitos de la cuenta para Malasia

Para reportar facturas a la LHDN a través de B2Brouter, tu cuenta de B2Brouter debe estar correctamente configurada como entidad malasia.

Campos obligatorios para cuentas malayas

Al crear tu cuenta mediante la API (POST /accounts), los siguientes campos son requeridos y deben cumplir las restricciones específicas de Malasia:

Campo	Descripción	Notas
country	Código de país ISO	Debe ser my (Malasia)
tin_value	Número de Identificación del Contribuyente	Debe seguir el formato malayo
tin_scheme	Código del esquema TIN	Debe ser 8028 — Nombor Cukai Pendapatan (ITN)
cin_value	Identificador de empresa o persona	Debe ser un Número de Registro Empresarial o un número de documento nacional de identidad
cin_scheme	Código del esquema CIN	Usa 8031 para Business Registration Number (BRN) o 8029 para National Registration Identity Card Number (NRIC)
province	Estado/Región	Debe coincidir con los códigos de estado oficiales de la LHDN
phone	Número de contacto de la empresa	Requerido para la validación fiscal

Referencia completa: API de creación de cuenta

Ejemplo de payload JSON (crear cuenta malaya)

{
  "account": {
    "name": "My Malaysia Business",
    "email": "john.doe@example.com",
    "phone": "60123456789",
    "address": "123 Jalan Ampang",
    "city": "Kuala Lumpur",
    "postalcode": "50088",
    "province": "10",
    "country": "my",
    "tin_value": "ITN123456789",
    "tin_scheme": 8028,
    "cin_value": "BRN123456789",
    "cin_scheme": 8031
  }
}

Paso 2: Registrar B2Brouter como ERP intermediario en el portal MyInvois

Para enviar tus informes fiscales a MyInvois, B2Brouter debe estar registrado como ERP intermediario en el portal MyInvois. Este registro es necesario para autorizarnos a presentar informes fiscales en tu nombre. Puedes encontrar instrucciones detalladas aquí.

Paso 3: Activar el reporte fiscal LHDN en B2Brouter

Debes habilitar la configuración de reporte fiscal LHDN en tu cuenta de B2Brouter para comenzar a reportar facturas a la LHDN.

Endpoint de la API para crear la configuración de informe fiscal para la LHDN:

POST https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings
Content-Type: application/json
X-B2B-API-Key: {YOUR_API_KEY}
X-B2B-API-Version: {YOUR_API_VERSION}

{
  "tax_report_setting": {
    "code": "lhdn",
    "msic": "01111",
    "type_operation": "services",
    "classification_code": "001"
  }
}

Explicación de los campos:

• msic: Código de clasificación empresarial malayo, requerido por la LHDN.
• type_operation: Tipo de operaciones de tu negocio (services o goods). Se usa como valor por defecto si no se especifica en la factura.
• classification_code: Código específico relacionado con la categoría de tu línea de productos. Se usa como valor por defecto si no se especifica en la factura.

Para configurar correctamente el reporte fiscal para Malasia, debes usar los códigos oficiales proporcionados por la LHDN. Puedes encontrarlos aquí: Lista de códigos LHDN

Paso 4: Crear y emitir facturas

Crea una factura en B2Brouter usando nuestra API. Tienes dos opciones:

1. Crear una factura emitida usando un payload JSON

Ejemplo de solicitud:

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'content-type: application/json'

2. Crear una factura emitida importando un formato de archivo compatible

Ejemplo de solicitud:

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices/import?send_after_import=false&transport_type_code_for_contact=email&document_type_code_for_contact=xml.ubl.invoice.pint.billing.my.v1' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'content-type: application/octet-stream' \
  --data 'data:text/xml;name=Invoice-23432234533.xml;base64,{BASE64_RAW_XML}'

Paso 5: Presentar el informe fiscal

Si emitiste automáticamente la factura que acabas de crear (configurando el parámetro send_after_import en la llamada a la API), el informe fiscal correspondiente a la factura se generará automáticamente y se enviará a la Autoridad Fiscal para su validación.

Alternativamente, si quieres más control sobre el proceso de emisión, puedes generar explícitamente el informe fiscal llamando al método de generación de informe fiscal.

Paso 6: Verificar el estado del informe fiscal

El proceso de envío de informes fiscales a la LHDN es asíncrono — generamos y presentamos el informe fiscal en un proceso en segundo plano.

Tendrás que verificar el estado del informe fiscal que enviamos en tu nombre. Puedes:

• Consultar un informe fiscal específico usando su ID.
• Obtener una lista de informes fiscales asociados a un ID de factura llamando al método de listado de informes fiscales.

Debido a la naturaleza asíncrona del proceso de envío del informe fiscal, no hay garantía de que cuando compruebes el estado ya tenga la respuesta de la Autoridad Fiscal. Normalmente tarda unos segundos en completar la transacción. La transacción está completa si el estado es registered o error. Recomendamos implementar una estrategia de retroceso exponencial para los reintentos.