SDK oficial de FiscalAPI para Node.js, la API de facturación CFDI y otros servicios fiscales en México. Simplifica la integración con los servicios de facturación electrónica, eliminando las complejidades del SAT y facilitando la generación de facturas, notas de crédito, complementos de pago, nómina, carta porte, y más. ¡Factura sin dolor!
Compatible con múltiples versiones de Node.js ( Node.js 12.0.0 o superior)
npm:
npm install fiscalapi
yarn:
yarn add fiscalapi
Puedes usar el SDK tanto en aplicaciones Node.js tradicionales como en frameworks modernos (Express, NestJS, Next.js, etc.). A continuación se describen ambas formas:
Crea tu objeto de configuración con tus credenciales:
// CommonJS
const { FiscalapiClient } = require('fiscalapi');
// o ESM
import { FiscalapiClient } from 'fiscalapi';
const settings = {
apiUrl: "https://test.fiscalapi.com", // https://live.fiscalapi.com (producción)
apiKey: "<tu_api_key>",
tenant: "<tenant>"
};
Crea la instancia del cliente:
const fiscalApi = FiscalapiClient.create(settings);
Para ejemplos completos, consulta ejemplos Express, ejemplos NestJs o más ejemplos en NodeJs.
Agrega la configuración en tu archivo de variables de entorno (.env):
FISCALAPI_API_KEY=<api_key>
FISCALAPI_TENANT=<tenant>
FISCALAPI_API_URL=https://test.fiscalapi.com
Crea y registra el cliente (por ejemplo, en un servicio o módulo):
// services/fiscalapi.service.ts
import { FiscalapiClient } from 'fiscalapi'
import config from '../config/config';
export const createFiscalApiClient = () => {
return FiscalapiClient.create({
apiUrl: config.fiscalapiSettings.apiUrl,
apiKey: config.fiscalapiSettings.apiKey,
tenant: config.fiscalapiSettings.tenant
});
};
En Express:
// En tu controlador o router
import { createFiscalApiClient } from '../services/fiscalapi.service';
const fiscalapi = createFiscalApiClient();
app.post('/invoices', async (req, res) => {
try {
const response = await fiscalapi.invoices.create(req.body);
res.json(response);
} catch (error) {
res.status(500).json({ error: error.message });
}
});
Para más ejemplos, revisa ejemplos Express, ejemplos NestJs o más ejemplos en NodeJs.
FiscalAPI admite dos modos de operación:
Por Referencias: Envía solo IDs de objetos previamente creados en el dashboard de FiscalAPI.
Ideal para integraciones ligeras.
Por Valores: Envía todos los campos requeridos en cada petición, con mayor control sobre los datos.
No se requiere configuración previa en el dashboard.
A continuación se muestran algunos ejemplos básicos para ilustrar cómo utilizar el SDK. Puedes encontrar más ejemplos en la documentación oficial.
const fiscalApi = FiscalApiClient.create(settings);
const request = {
legalName: "Persona de Prueba",
email: "someone@somewhere.com",
password: "YourStrongPassword123!",
};
try {
const apiResponse = await fiscalApi.persons.create(request);
console.log(apiResponse.data);
} catch (error) {
console.error(error);
}
Descarga certificados de prueba
const fiscalApi = FiscalApiClient.create(settings);
const certificadoCsd = {
personId: "984708c4-fcc0-43bd-9d30-ec017815c20e",
base64File: "MIIFsDCCA5igAwIBAgI...==", // Certificado .cer codificado en Base64
fileType: "CertificateCsd",
password: "12345678a",
tin: "EKU9003173C9"
};
const clavePrivadaCsd = {
personId: "984708c4-fcc0-43bd-9d30-ec017815c20e",
base64File: "MIIFDjBABgkqhkiG9w0BBQ0...==", // Llave privada .key codificada en Base64
fileType: "PrivateKeyCsd",
password: "12345678a",
tin: "EKU9003173C9"
};
try {
const apiResponseCer = await fiscalApi.taxFiles.create(certificadoCsd);
const apiResponseKey = await fiscalApi.taxFiles.create(clavePrivadaCsd);
console.log(apiResponseCer.data, apiResponseKey.data);
} catch (error) {
console.error(error);
}
const fiscalApi = FiscalApiClient.create(settings);
const request = {
description: "Servicios contables",
unitPrice: 100,
satUnitMeasurementId: "E48",
satTaxObjectId: "02",
satProductCodeId: "84111500"
};
try {
const apiResponse = await fiscalApi.products.create(request);
console.log(apiResponse.data);
} catch (error) {
console.error(error);
}
const fiscalApi = FiscalApiClient.create(settings);
const request = {
id: "310301b3-1ae9-441b-b463-51a8f9ca8ba2",
description: "Servicios contables",
unitPrice: 100,
satUnitMeasurementId: "E48",
satTaxObjectId: "02",
satProductCodeId: "84111500",
productTaxes: [
{ rate: 0.16, taxId: "002", taxFlagId: "T", taxTypeId: "Tasa" }, // IVA 16%
{ rate: 0.10, taxId: "001", taxFlagId: "R", taxTypeId: "Tasa" }, // ISR 10%
{ rate: 0.10666666666, taxId: "002", taxFlagId: "R", taxTypeId: "Tasa" } // IVA 2/3 partes
]
};
try {
const apiResponse = await fiscalApi.products.update(request.id, request);
console.log(apiResponse.data);
} catch (error) {
console.error(error);
}
const fiscalApi = FiscalApiClient.create(settings);
const invoice = {
versionCode: "4.0",
series: "SDK-F",
date: new Date(),
paymentFormCode: "01",
currencyCode: "MXN",
typeCode: "I",
expeditionZipCode: "42501",
issuer: {
id: "<id-emisor-en-fiscalapi>"
},
recipient: {
id: "<id-receptor-en-fiscalapi>"
},
items: [
{
id: "<id-producto-en-fiscalapi>",
quantity: 1,
discount: 10.85
}
],
paymentMethodCode: "PUE",
};
try {
const apiResponse = await fiscalApi.invoices.create(invoice);
console.log(apiResponse.data);
} catch (error) {
console.error(error);
}
const fiscalApi = FiscalApiClient.create(settings);
// Agregar sellos CSD, Emisor, Receptor, Items, etc.
const invoice = {
versionCode: "4.0",
series: "SDK-F",
date: new Date(),
paymentFormCode: "01",
currencyCode: "MXN",
typeCode: "I",
expeditionZipCode: "42501",
issuer: {
tin: "EKU9003173C9",
legalName: "ESCUELA KEMPER URGATE",
taxRegimeCode: "601",
taxCredentials: [
{
base64File: "certificate_base64...",
fileType: "CertificateCsd",
password: "12345678a"
},
{
base64File: "private_key_base64...",
fileType: "PrivateKeyCsd",
password: "12345678a"
}
]
},
recipient: {
tin: "EKU9003173C9",
legalName: "ESCUELA KEMPER URGATE",
zipCode: "42501",
taxRegimeCode: "601",
cfdiUseCode: "G01",
email: "someone@somewhere.com"
},
items: [
{
itemCode: "01010101",
quantity: 9.5,
unitOfMeasurementCode: "E48",
description: "Invoicing software as a service",
unitPrice: 3587.75,
taxObjectCode: "02",
discount: 255.85,
itemTaxes: [
{
taxCode: "002", // IVA
taxTypeCode: "Tasa",
taxRate: 0.16,
taxFlagCode: "T"
}
]
}
],
paymentMethodCode: "PUE",
};
try {
const apiResponse = await fiscalApi.invoices.create(invoice);
console.log(apiResponse.data);
} catch (error) {
console.error(error);
}
try {
// Busca los registros que contengan 'inter' en el catalogo 'SatUnitMeasurements' (pagina 1, tamaño pagina 10)
const apiResponse = await fiscalApi.catalogs.searchCatalog("SatUnitMeasurements", "inter", 1, 10);
if (apiResponse.succeeded) {
apiResponse.data.items.forEach(item => {
console.log(`Unidad: ${item.description}`);
});
} else {
console.log(apiResponse.message);
}
} catch (error) {
console.error(error);
}
git checkout -b feature/AmazingFeature.git commit -m 'Add some AmazingFeature'.git push origin feature/AmazingFeature.Este proyecto está licenciado bajo la Licencia MPL-2.0. Consulta el archivo LICENSE para más detalles.
Desarrollado con ❤️ por Fiscalapi
FAQs
SDK de Node.js para Fiscalapi
The npm package fiscalapi receives a total of 173 weekly downloads. As such, fiscalapi popularity was classified as not popular.
We found that fiscalapi demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.