Informe fiscal LHDN

Enviar un informe fiscal a LHDN (Malàisia) amb l’API de B2Brouter

Aquesta guia explica com activar i generar un informe fiscal per a l’Inland Revenue Board of Malaysia (LHDN) mitjançant l’API de B2Brouter.

Entorns de prova: feu servir sandbox per a les primeres proves d’API i validació de payloads. Sandbox simula els enviaments a LHDN. Per a proves end-to-end completes contra l’endpoint de test de LHDN, utilitzeu l’entorn staging (api-staging.b2brouter.net).

Visió general: procés de clearance

El procés d’informes fiscals de LHDN funciona amb un model de clearance. Això vol dir que cada factura emesa s’ha d’informar i aprovar per l’autoritat fiscal.

Quan utilitzeu B2Brouter, cada informe fiscal enviat a LHDN es valida automàticament a través d’aquesta autoritat. Per tant, la factura només es pot considerar legalment vàlida després del clearance correcte per part de LHDN.

Pas 1: requisits del compte per a Malàisia

Per reportar factures a LHDN via B2Brouter, el vostre compte ha d’estar configurat correctament com a entitat malaia.

Camps obligatoris per a comptes malais

Camp	Descripció	Notes
`country`	Codi ISO del país	Ha de ser `my`
`tin_value`	Taxpayer Identification Number	Ha de seguir el format malai
`tin_scheme`	Codi de l’esquema TIN	Ha de ser `8028`
`cin_value`	Identificador d’empresa o persona	BRN o NRIC
`cin_scheme`	Codi CIN	`8031` per BRN o `8029` per NRIC
`province`	Estat o regió	Ha de coincidir amb els codis oficials LHDN
`phone`	Telèfon de contacte	Obligatori per a la validació fiscal

Exemple JSON per crear un compte malai

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

Pas 2: registrar B2Brouter com a ERP intermediari a MyInvois

Per enviar informes fiscals a MyInvois, B2Brouter ha d’estar registrat com a ERP intermediari al portal MyInvois. Aquest registre és necessari per autoritzar-nos a enviar els informes fiscals en nom vostre.

Podeu trobar les instruccions detallades aquí.

Pas 3: activar la configuració fiscal de LHDN a B2Brouter

Heu d’habilitar la configuració d’informes fiscals LHDN al vostre compte de B2Brouter.

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ó dels camps:

msic: codi de classificació empresarial malai requerit per LHDN
type_operation: tipus d’operacions de negoci, serveis o béns
classification_code: codi específic relacionat amb la categoria de la línia de producte

Per configurar correctament l’informe fiscal de Malàisia, heu d’utilitzar els codis oficials proporcionats per LHDN: LHDN Code List

Pas 4: crear i emetre factures

Creeu una factura a B2Brouter amb l’API. Teniu dues opcions:

1. Crear una factura emesa amb payload JSON

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 emesa important un fitxer compatible

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

Pas 5: enviar l’informe fiscal

Si heu emès automàticament la factura creada, amb send_after_import, l’informe fiscal corresponent es generarà i s’enviarà automàticament a l’autoritat fiscal per a la seva validació.

Si voleu més control, també podeu generar explícitament l’informe fiscal cridant el mètode generate tax report.

Pas 6: comprovar l’estat de l’informe fiscal

L’enviament d’informes fiscals a LHDN és asíncron. Haureu de consultar l’estat de l’informe fiscal enviat en nom vostre.

Podeu:

Consultar un informe fiscal concret amb el seu ID
Obtenir la llista d’informes fiscals associats a una factura amb list tax reports

Com que l’enviament és asíncron, no hi ha garantia que la resposta de l’autoritat fiscal estigui disponible immediatament. Habitualment, el procés triga uns segons. La transacció es considera completada quan l’estat és registered o error. Recomanem implementar una estratègia d’exponential backoff.