--- title: SDK Verifactu para Node y TypeScript (@beel_es/sdk) | BeeL. description: SDK Verifactu de BeeL. para Node y TypeScript: emite, remite a la AEAT y verifica webhooks con tipos del contrato OpenAPI. Sandbox gratis, sin tarjeta. image: https://beel.es/api/og/card?title=SDK%20Verifactu%20para%20Node%20y%20TypeScript%20(%40beel_es%2Fsdk)&domain=beel.es --- SDK # SDK Verifactu: uno de Node y un contrato REST para todo lo demás. @beel\_es/sdk emite la factura Verifactu, la remite a la AEAT y devuelve el QR y el hash, con los tipos generados del contrato, reintentos, Idempotency-Key en cada POST y verificador de webhooks. Si tu stack no es Node, el mismo contrato OpenAPI 3.0 genera tu cliente tipado. Verifactu es obligatorio desde el 1 de enero de 2027 para sociedades y el 1 de julio de 2027 para el resto (RDL 15/2025). [Crear cuenta gratis](https://app.beel.es/signup?ref=sdks)[Ver documentación↗](https://docs.beel.es) Qué trae ## No es un envoltorio fino sobre fetch. Las cinco piezas que un equipo espera de una API que va a producción vienen dentro del paquete. Ninguna se monta aparte. Lo que trae @beel\_es/sdk Node.js / TypeScript PiezaQué te ahorra Tipos desde el contratoAutocompletado y errores en compilación Reintentos con backoffSolo en 429 y 5xx; un 400 nunca se reintenta Idempotency-Key en cada POSTUn reintento devuelve la factura que ya existía Verificación de webhooksHMAC-SHA256 con comparación en tiempo constante Descarga del PDFBuffer y nombre de fichero, sin pelearse con las cabeceras Si tu stack no es Node, el contrato OpenAPI 3.0 es público y genera un cliente tipado en el lenguaje que uses. El paquete Nombre @beel\_es/sdk Registro npm Clase BeeL Tipos Incluidos Origen OpenAPI 3.0 Los modelos salen del mismo contrato que sirve la API, así que el día que cambia un campo lo dice el compilador, no producción. Del install a la factura ## Dos llamadas: una deja el borrador, la otra lo emite. La segunda asigna el número de tu serie, genera el registro Verifactu con su huella y lo remite a la AEAT. El PDF con el QR se genera detrás. No hay un tercer paso escondido. invoice.ts 1. 1 2. 2 3. 3 4. 4 5. 5 6. 6 7. 7 8. 8 9. 9 10. 10 11. 11 12. 12 ``` import { BeeL } from '@beel_es/sdk'; const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY }); const draft = await beel.invoices.create({ type: 'STANDARD', recipient: { legal_name: 'Comercial Martínez SL', nif: 'B87654323' }, lines: [{ description: 'Sprint de mayo', quantity: 1, unit_price: 40.50 }], }); const issued = await beel.invoices.issue(draft.id); console.log(issued.number); ``` Número asignado ``` "F-2026-0042" ``` npmpnpmyarnCopiar: npmnpm install @beel\_es/sdk $`npm install @beel_es/sdk` Node 18 o superior. La clave de pruebas lleva el prefijo beel\_sk\_test\_ y remite al entorno de pruebas de la AEAT, sin efecto fiscal. Verifactu ## Lo que el SDK Verifactu resuelve por ti. Registro de facturación del RD 1007/2023, huella encadenada, remisión a la AEAT, QR en el PDF y los webhooks que lo cuentan. Tu código llama a issue() y lee la respuesta. [Qué exige Verifactu](/guia/verifactu) ### issue() remite a la AEAT Al emitir, la API genera el registro con la huella SHA-256 del anterior y lo remite a la AEAT. El estado vuelve tipado en verifactu.submission\_status y cambia por webhook. invoices.issueverifactu\_registration\_id ### QR y hash en la respuesta La factura emitida trae qr\_url, qr\_base64 e invoice\_hash con sus tipos. El PDF sale con el QR de cotejo de Hacienda; tu cliente lo escanea y comprueba la factura ante la AEAT. qr\_urlinvoice\_hash ### Webhooks verificados en una línea WebhookVerifier comprueba la firma HMAC-SHA256 de BeeL-Signature en tiempo constante y rechaza repeticiones de más de 5 minutos. Seis eventos, de invoice.issued a verifactu.status.updated. WebhookVerifierBeeL-Signature ### Sandbox gratis, misma API Cambias la clave por una beel\_sk\_test\_ y el SDK habla con el sandbox: mismos endpoints, remisión al entorno de pruebas de la AEAT y sin efecto fiscal. Gratis, sin tarjeta y sin caducidad. [Ver el sandbox](/sandbox) ### Idempotencia y errores tipados Cada POST lleva su Idempotency-Key: un reintento devuelve la factura original, no una nueva. Los errores llegan como clases (BeeLValidationError, BeeLRateLimitError, BeeLConflictError) y el SDK reintenta con backoff en 429 y 5xx. Idempotency-KeyBeeLRateLimitError ### Un NIF o cientos, el mismo cliente Las rutas por empresa (/v1/companies) están tipadas en el SDK: cada NIF con sus series, su numeración y su cadena Verifactu. Cómo se monta para gestorías y plataformas, en multi-NIF. [Ver multi-NIF](/api-verifactu/multi-nif) Otros lenguajes ## Sin SDK propio no te quedas fuera. El contrato OpenAPI 3.0 es público y es el mismo del que sale el SDK de Node. Genera tu cliente y tendrás los tipos y los errores del día en que lo generes. Generar tu cliente del contrato VíaCuándo Cliente generado del specTipos y errores en tu lenguaje, desde el mismo contrato REST directoUn Bearer y JSON; sin dependencias que mantener openapi-generatorcurlCopiar: openapi-generatoropenapi-generator generate -i https://docs.beel.es/openapi.yaml -g python $`openapi-generator generate -i https://docs.beel.es/openapi.yaml -g python` El contrato Formato OpenAPI 3.0 Operaciones Más de 200 Auth Bearer · OAuth 2.1 Base /api/v1 Publicamos cabeceras de Deprecation y Sunset con changelog antes de retirar una ruta. La suite ## El SDK es una de las cuatro puertas. SDK, CLI, servidor MCP y plugin de Claude Code salen del mismo contrato de la API, así que ninguna se queda atrás cuando la API cambia. ### Servidor MCP Conecta Claude, Cursor o ChatGPT a tu facturación y emite hablando. Hosteado, con OAuth 2.1. Servidor MCPCopiar: Servidor MCPhttps://mcp.beel.es/mcp `https://mcp.beel.es/mcp` [Ver el MCP](/agentes) ### CLI Opera y automatiza desde la terminal o desde tu CI. Salida JSON y sandbox por defecto. TerminalCopiar: Terminalnpx @beel\_es/cli invoices create $`npx @beel_es/cli invoices create` [Ver la CLI](/api-verifactu/cli) ### Plugin de Claude Code Claude monta la integración contra la spec en vivo y la verifica en sandbox antes de tocar producción. Claude CodeCopiar: Claude Code/plugin install beel-api@beel ›`/plugin install beel-api@beel` [Ver el plugin](/api-verifactu/claude-code) El SDK no tiene precio aparte: pagas la API por NIF, con facturas incluidas cada mes, y el sandbox es gratis. [Ver precios](/precios)[Ver el sandbox](/sandbox) Preguntas frecuentes ## Lo que se pregunta del SDK Verifactu. ### ¿Qué SDKs de Verifactu hay? Uno oficial: @beel\_es/sdk para Node y TypeScript, generado del contrato OpenAPI 3.0 de la API. Cada factura que emite lleva su registro Verifactu remitido a la AEAT. Para cualquier otro lenguaje el contrato es público y genera un cliente tipado; y además están la CLI, el servidor MCP y el plugin de Claude Code. ### ¿Hay SDK de Python o de Java? Hoy no. El único SDK publicado es el de Node y TypeScript, @beel\_es/sdk. Para cualquier otro lenguaje, el contrato OpenAPI 3.0 es público y genera un cliente tipado con las herramientas estándar, que es lo que usamos nosotros para generar el de Node. ### ¿Cómo emito una factura Verifactu con el SDK? Dos llamadas: invoices.create deja el borrador e invoices.issue lo emite. La segunda asigna el número de la serie, genera el registro de facturación con su huella SHA-256, lo remite a la AEAT y devuelve la factura con qr\_url, qr\_base64 e invoice\_hash. El PDF con el QR se genera detrás, o esperas a que esté con wait\_for\_pdf. ### ¿El SDK se queda atrás cuando cambia la API? Los modelos se generan del mismo contrato que sirve la API, así que un campo nuevo aparece con la versión siguiente y un campo que cambia lo canta el compilador. Y publicamos cabeceras de Deprecation y Sunset con changelog público antes de retirar nada. ### ¿Qué pasa si mi servidor reintenta una llamada? El SDK manda una Idempotency-Key en cada POST. Si repites la misma llamada durante 24 horas, la API devuelve la respuesta original en lugar de emitir otra factura. Una factura duplicada con número legal no se borra: se corrige con una rectificativa. ### ¿Cómo verifico los webhooks? El SDK trae WebhookVerifier: firma HMAC-SHA256 en la cabecera BeeL-Signature, comparación en tiempo constante y ventana antirreplay de 5 minutos. Los eventos son invoice.issued, invoice.email.sent, invoice.voided, recurring\_invoice.paused, verifactu.status.updated y account.claimed. ### ¿Hay sandbox gratis? Sí, y es la misma URL base. Cambias la clave por una con prefijo beel\_sk\_test\_ y la remisión va al entorno de pruebas de la AEAT, sin efecto fiscal. El sandbox es gratis, ilimitado, sin tarjeta y no caduca. ### ¿El SDK tiene precio aparte? No. El SDK y el contrato OpenAPI no cuestan nada: el precio es el de la API, por NIF, con facturas incluidas cada mes, y el sandbox es gratis. El precio está en la página de precios. ### ¿Cuáles son los límites de la API? 300 peticiones por minuto y por credencial, más límites propios en unos pocos endpoints: validación de NIF 100 por hora con clave de API, importación CSV 3 por hora, hasta 50 facturas por petición masiva y hasta 10 webhooks activos por cuenta. ```json {"@context":"https://schema.org","@type":"Organization","@id":"https://beel.es/#organization","name":"BeeL.","alternateName":["BeeL","BeeL.es","Beel"],"legalName":"Honey Solutions, S.L.","url":"https://beel.es","logo":{"@type":"ImageObject","@id":"https://beel.es/#logo","url":"https://beel.es/brand/logos/beel-logo-blue.png","contentUrl":"https://beel.es/brand/logos/beel-logo-blue.png","width":2118,"height":487,"caption":"Logo de BeeL."},"image":"https://beel.es/brand/logos/beel-logo-blue.png","description":"Software de facturación para España listo para Verifactu, con API para desarrolladores e integración nativa con Stripe.","email":"hola@beel.es","telephone":"+34 711 21 23 00","contactPoint":[{"@type":"ContactPoint","contactType":"customer support","email":"hola@beel.es","telephone":"+34711212300","url":"https://beel.es/contacto","availableLanguage":["es","ca","en"],"areaServed":"ES"},{"@type":"ContactPoint","contactType":"sales","email":"hola@beel.es","telephone":"+34711212300","url":"https://beel.es/ventas","availableLanguage":["es","ca","en"],"areaServed":"ES"}],"foundingDate":"2026","address":{"@type":"PostalAddress","addressLocality":"Vila-seca","addressRegion":"Tarragona","addressCountry":"ES"},"sameAs":["https://www.linkedin.com/company/beel-es","https://www.instagram.com/beel.es","https://www.tiktok.com/@app.beel.es","https://www.youtube.com/@beel_es","https://x.com/beel_es","https://github.com/beel-es"],"subjectOf":{"@type":"WebPage","url":"https://beel.es/logo","name":"Logo de BeeL."}} {"@context":"https://schema.org","@type":"Service","@id":"https://beel.es/#service","name":"Facturación Verifactu completa por API — BeeL.","serviceType":"Facturación electrónica y Verifactu (AEAT) por API y por integración con Stripe","description":"Emite facturas legales en España desde tu producto o desde tus cobros de Stripe: numeración, PDF, envío, rectificativas, varios NIFs y el registro en la AEAT, sin escribir código fiscal.","provider":{"@id":"https://beel.es/#organization"},"areaServed":{"@type":"Country","name":"España"},"audience":{"@type":"BusinessAudience","audienceType":"SaaS, marketplaces, gestorías y negocios que cobran con Stripe"},"availableChannel":[{"@type":"ServiceChannel","serviceUrl":"https://app.beel.es/api/v1","name":"API REST"},{"@type":"ServiceChannel","serviceUrl":"https://mcp.beel.es/mcp","name":"Servidor MCP"},{"@type":"ServiceChannel","serviceUrl":"https://beel.es/integraciones/stripe-verifactu","name":"Stripe Connect"}],"termsOfService":"https://beel.es/terminos","offers":{"@id":"https://beel.es/precios#api"},"url":"https://beel.es/api-verifactu"} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://beel.es/api-verifactu/sdks#faq","name":"SDK Verifactu de BeeL. para Node.js y TypeScript","url":"https://beel.es/api-verifactu/sdks","mainEntity":[{"@type":"Question","name":"¿Qué SDKs de Verifactu hay?","acceptedAnswer":{"@type":"Answer","text":"Uno oficial: @beel_es/sdk para Node y TypeScript, generado del contrato OpenAPI 3.0 de la API. Cada factura que emite lleva su registro Verifactu remitido a la AEAT. Para cualquier otro lenguaje el contrato es público y genera un cliente tipado; y además están la CLI, el servidor MCP y el plugin de Claude Code."}},{"@type":"Question","name":"¿Hay SDK de Python o de Java?","acceptedAnswer":{"@type":"Answer","text":"Hoy no. El único SDK publicado es el de Node y TypeScript, @beel_es/sdk. Para cualquier otro lenguaje, el contrato OpenAPI 3.0 es público y genera un cliente tipado con las herramientas estándar, que es lo que usamos nosotros para generar el de Node."}},{"@type":"Question","name":"¿Cómo emito una factura Verifactu con el SDK?","acceptedAnswer":{"@type":"Answer","text":"Dos llamadas: invoices.create deja el borrador e invoices.issue lo emite. La segunda asigna el número de la serie, genera el registro de facturación con su huella SHA-256, lo remite a la AEAT y devuelve la factura con qr_url, qr_base64 e invoice_hash. El PDF con el QR se genera detrás, o esperas a que esté con wait_for_pdf."}},{"@type":"Question","name":"¿El SDK se queda atrás cuando cambia la API?","acceptedAnswer":{"@type":"Answer","text":"Los modelos se generan del mismo contrato que sirve la API, así que un campo nuevo aparece con la versión siguiente y un campo que cambia lo canta el compilador. Y publicamos cabeceras de Deprecation y Sunset con changelog público antes de retirar nada."}},{"@type":"Question","name":"¿Qué pasa si mi servidor reintenta una llamada?","acceptedAnswer":{"@type":"Answer","text":"El SDK manda una Idempotency-Key en cada POST. Si repites la misma llamada durante 24 horas, la API devuelve la respuesta original en lugar de emitir otra factura. Una factura duplicada con número legal no se borra: se corrige con una rectificativa."}},{"@type":"Question","name":"¿Cómo verifico los webhooks?","acceptedAnswer":{"@type":"Answer","text":"El SDK trae WebhookVerifier: firma HMAC-SHA256 en la cabecera BeeL-Signature, comparación en tiempo constante y ventana antirreplay de 5 minutos. Los eventos son invoice.issued, invoice.email.sent, invoice.voided, recurring_invoice.paused, verifactu.status.updated y account.claimed."}},{"@type":"Question","name":"¿Hay sandbox gratis?","acceptedAnswer":{"@type":"Answer","text":"Sí, y es la misma URL base. Cambias la clave por una con prefijo beel_sk_test_ y la remisión va al entorno de pruebas de la AEAT, sin efecto fiscal. El sandbox es gratis, ilimitado, sin tarjeta y no caduca."}},{"@type":"Question","name":"¿El SDK tiene precio aparte?","acceptedAnswer":{"@type":"Answer","text":"No. El SDK y el contrato OpenAPI no cuestan nada: el precio es el de la API, por NIF, con facturas incluidas cada mes, y el sandbox es gratis. El precio está en la página de precios."}},{"@type":"Question","name":"¿Cuáles son los límites de la API?","acceptedAnswer":{"@type":"Answer","text":"300 peticiones por minuto y por credencial, más límites propios en unos pocos endpoints: validación de NIF 100 por hora con clave de API, importación CSV 3 por hora, hasta 50 facturas por petición masiva y hasta 10 webhooks activos por cuenta."}}]} ```