# BusinessLink > BusinessLink es el servicio de facturación electrónica (e-CF) de República Dominicana: emite, firma y envía comprobantes fiscales electrónicos a la DGII, asigna los e-NCF (secuenciador), recibe las facturas electrónicas de los proveedores, consulta RNC y tasas de cambio, y avisa por webhook. Se usa desde un portal web, una API REST, un conector para Odoo (14 a 18) y un servidor MCP para asistentes de IA. / BusinessLink is the Dominican Republic e-invoicing (e-CF, DGII) backend: issuing, signing and filing electronic fiscal documents, e-NCF sequence numbering, receiving suppliers' e-invoices, RNC lookup, BCRD exchange rates and webhooks, via web portal, REST API, Odoo connector and an MCP server for AI assistants. Operado por Tejada Tech Group EIRL (TTG), Santo Domingo. Notas para asistentes de IA: las claves `bl_test_` son sandbox (nada llega a la DGII); `bl_live_` emite comprobantes reales. La API se llama solo desde servidores, nunca desde el navegador. Tipos de e-CF: 31 crédito fiscal, 32 consumo (NO es nota de crédito), 33 nota de débito, 34 nota de crédito, 41 compras, 43 gastos menores, 44 regímenes especiales, 45 gubernamental, 46 exportaciones, 47 pagos al exterior. API base: https://api.businesslink.do ## Producto - [Funcionalidades](https://www.businesslink.do/funcionalidades): emisión, secuenciador de e-NCF, comprobantes recibidos, validación con la DGII, webhooks, RNC, sandbox. - [Integraciones](https://www.businesslink.do/integraciones): Odoo 14 a 18, otros ERP y POS por API, asistentes de IA. - [Solicitar una demo](https://www.businesslink.do/contacto) - [Portal de clientes (claves de API, certificado, documentos)](https://ui.businesslink.do) ## Documentación y API - [Qué es BusinessLink y qué ofrece](https://www.businesslink.do/docs/que-es-businesslink.md) - [Inicio rápido (sandbox)](https://www.businesslink.do/docs/inicio-rapido.md) - [Emitir e-CF](https://www.businesslink.do/docs/emitir-facturas.md): factura simple `POST /v1/facturas` o JSON completo de la DGII `POST /v1/ecf`, notas de crédito, moneda extranjera. - [Comprobantes recibidos de proveedores](https://www.businesslink.do/docs/comprobantes-recibidos.md): listar, documento completo, XML/PDF, sincronización incremental. - [Secuenciador de e-NCF](https://www.businesslink.do/docs/secuencias-encf.md): rangos autorizados por la DGII, numeración atómica. - [Webhooks firmados](https://www.businesslink.do/docs/webhooks.md) - [Errores e idempotencia](https://www.businesslink.do/docs/errores-e-idempotencia.md) - [Integrar un ERP o sistema propio](https://www.businesslink.do/docs/integracion-erp.md) - [Especificación OpenAPI 3](https://api.businesslink.do/v1/openapi.json) ## Asistentes de IA (MCP) - [Servidor MCP de BusinessLink](https://www.businesslink.do/docs/mcp.md): herramientas, seguridad y cómo conectarlo (`https://api.businesslink.do/mcp`). - [Ficha del servidor MCP](https://www.businesslink.do/.well-known/mcp/server-card.json) ## Todo el contenido - [Documentación completa en un solo archivo](https://www.businesslink.do/llms-full.txt) ## Optional - [Blog](https://www.businesslink.do/blog): artículos sobre facturación electrónica en República Dominicana. - [Catálogo de APIs (RFC 9727)](https://api.businesslink.do/.well-known/api-catalog) - [DGII: comprobantes fiscales electrónicos](https://dgii.gov.do/cicloContribuyente/facturacion/comprobantesFiscalesElectronicos/Paginas/default.aspx): normativa y especificaciones oficiales. --- # Qué es BusinessLink BusinessLink es el servicio de **facturación electrónica (e-CF) para República Dominicana** de Tejada Tech Group EIRL (TTG). Es el motor que firma, valida y envía los comprobantes fiscales electrónicos a la DGII, recibe los que mandan los proveedores, y se puede usar de tres formas: 1. **Portal web** (https://ui.businesslink.do): empresas que facturan, consultan documentos, suben su certificado y administran sus claves de API. 2. **API REST `/v1`** (https://api.businesslink.do/v1): para cualquier app o sistema propio, incluidas las creadas con Lovable, Base44, Replit, Bolt, v0 o Claude Code. Especificación OpenAPI pública: https://api.businesslink.do/v1/openapi.json 3. **Conector para Odoo** (`l10n_do_ecf_businesslink`, Odoo 14 a 18): los ERP envían sus facturas a BusinessLink y reciben el resultado de la DGII. También hay un **servidor MCP** (https://api.businesslink.do/mcp) para usar BusinessLink desde Claude, ChatGPT, Cursor y otros asistentes de IA. Ver [mcp.md](https://www.businesslink.do/docs/mcp.md). ## Qué ofrece | Capacidad | Qué hace | |---|---| | **Emisión de e-CF** | Tipos 31 (crédito fiscal), 32 (consumo), 33 (nota de débito), 34 (nota de crédito), 41 (compras), 43 (gastos menores), 44 (regímenes especiales), 45 (gubernamental), 46 (exportaciones), 47 (pagos al exterior). Dos formas de enviar: factura simple (BusinessLink calcula totales e ITBIS) o documento completo de la DGII (para ERP). | | **Secuenciador de e-NCF** | BusinessLink puede asignar el número del e-NCF a partir de los rangos que la DGII autorizó a la empresa, con reserva atómica (sin duplicados aunque haya varias llamadas a la vez). Aviso cuando quedan pocos números. | | **Comprobantes recibidos** | Recibe los e-CF que le envían los proveedores (servicios de recepción y aprobación comercial de la DGII), verifica la firma y los deja consultables por API: listado, documento completo con líneas e impuestos, XML firmado y PDF. | | **Validación con la DGII** | Estado en tiempo real (en proceso, Aceptado, Aceptado Condicional, Rechazado), estado y ventanas de mantenimiento de los servicios de la DGII. | | **Webhooks firmados** | Aviso al sistema del cliente cuando la DGII acepta, acepta condicionalmente o rechaza un comprobante; reintentos por unos 2 días. | | **Directorio de RNC** | Consulta por RNC/cédula y búsqueda por nombre, con el estado del contribuyente según los archivos públicos de la DGII. | | **Tasas de cambio** | Dólar y euro según el Banco Central. | | **Sandbox gratuito** | Claves `bl_test_` que nunca llegan a la DGII, con PDF marcado "sin validez fiscal". | | **Certificación con la DGII** | Herramientas y acompañamiento para las pruebas técnicas que exige la DGII antes de emitir en producción. | | **PDF y XML** | Representación impresa con código QR y XML firmado de cada comprobante. | ## Para quién es - Empresas dominicanas que necesitan emitir e-CF (desde pequeñas hasta con ERP propio). - Desarrolladores y agencias que construyen sistemas de facturación, punto de venta o apps para clientes dominicanos y no quieren implementar firma, XSD, secuencias ni comunicación con la DGII. - Contadores y equipos que procesan las facturas electrónicas de sus proveedores. ## BusinessLink como backend completo de facturación electrónica Una app solo necesita guardar una clave de API. BusinessLink se encarga de: numerar (secuenciador), calcular impuestos, firmar con el certificado de la empresa, enviar a la DGII, seguir el estado, recibir facturas de proveedores, generar PDF/XML y avisar por webhook. ## Cómo empezar - Guía de 5 minutos: [inicio-rapido.md](https://www.businesslink.do/docs/inicio-rapido.md). - Para pedir acceso o una demo: https://www.businesslink.do (formulario "Solicita una demo"). - Soporte: Tejada Tech Group EIRL, Santo Domingo, República Dominicana. --- # Inicio rápido (5 minutos, sandbox) Todo se hace **desde un servidor** (backend, función serverless o API route). `/v1` rechaza llamadas con cabecera `Origin` (error `llamada_desde_navegador`) para que la clave nunca viva en el navegador. ## 1. Consiga una clave de prueba En el portal (https://ui.businesslink.do) entre a **Mi Empresa → Claves de API** y cree una clave de prueba. Empieza con `bl_test_`. Se muestra una sola vez: guárdela como secreto (variable de entorno). Las claves `bl_live_` (producción) solo se pueden crear cuando la empresa terminó la certificación con la DGII. ## 2. Pruebe la conexión ```bash curl https://api.businesslink.do/v1/me -H "Authorization: Bearer $BL_API_KEY" ``` Devuelve la empresa, el modo (`test` o `live`) y los permisos de la clave. ## 3. Emita una factura de prueba ```bash curl -X POST https://api.businesslink.do/v1/facturas \ -H "Authorization: Bearer $BL_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "tipo_ecf": "31", "comprador": {"rnc": "101000228", "razon_social": "Cliente Ejemplo SRL"}, "lineas": [{"descripcion": "Consultoria", "cantidad": 2, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"}], "tipo_pago": "contado" }' ``` Respuesta: `encf`, `estado`, `totales`, `codigo_seguridad`, `url_consulta_qr` y `consultar` (la ruta para ver el estado). ## 4. Consulte el estado, el PDF y el XML ```bash curl https://api.businesslink.do/v1/facturas/E310000000001 -H "Authorization: Bearer $BL_API_KEY" curl -o factura.pdf https://api.businesslink.do/v1/facturas/E310000000001/pdf -H "Authorization: Bearer $BL_API_KEY" curl -o factura.xml https://api.businesslink.do/v1/facturas/E310000000001/xml -H "Authorization: Bearer $BL_API_KEY" ``` ## 5. Reciba el resultado por webhook (en vez de consultar) Registre `POST /v1/webhooks` con la URL https de su backend. Ver [webhooks.md](https://www.businesslink.do/docs/webhooks.md). ## Pasar a producción 1. La empresa completa la certificación con la DGII (el equipo de BusinessLink acompaña el proceso). 2. Registre los rangos de e-NCF que la DGII autorizó (si BusinessLink numera): [secuencias-encf.md](https://www.businesslink.do/docs/secuencias-encf.md). 3. Cree una clave `bl_live_`. Con ella los comprobantes son reales y se reportan a la DGII. ## Recursos - OpenAPI: https://api.businesslink.do/v1/openapi.json - Errores e idempotencia: [errores-e-idempotencia.md](https://www.businesslink.do/docs/errores-e-idempotencia.md) - Uso desde asistentes de IA (MCP): [mcp.md](https://www.businesslink.do/docs/mcp.md) --- # Emitir comprobantes fiscales electrónicos (e-CF) Permiso de la clave: `facturas:emitir`. Consultar: `facturas:leer`. ## Dos formas de emitir | Endpoint | Cuándo usarlo | |---|---| | `POST /v1/facturas` | **Factura simple.** Usted envía líneas (descripción, cantidad, precio, tasa de ITBIS); BusinessLink calcula totales e impuestos y, si la empresa usa numeración de BusinessLink, asigna el e-NCF. Ideal para apps nuevas. | | `POST /v1/ecf` | **Documento completo de la DGII** (`Encabezado`, `DetallesItems`, ...). Para ERP que ya calculan todo y ya numeran (como el conector de Odoo). BusinessLink no recalcula: firma, valida contra el XSD y envía. | Ambos exigen la cabecera `Idempotency-Key`. ## Tipos de e-CF | Tipo | Uso | |---|---| | 31 | Crédito fiscal: el comprador tiene RNC y puede usarlo como gasto. | | 32 | Consumo (consumidor final). **No es una nota de crédito.** RNC del comprador obligatorio desde RD$250,000. | | 33 | Nota de débito (lleva `referencia`). | | 34 | Nota de crédito (siempre con `referencia` al e-NCF que modifica; no puede devolver más de lo facturado). | | 41 | Compras a proveedor informal (`proveedor` y `retencion` por línea). | | 43 | Gastos menores (sin comprador, líneas exentas). | | 44 | Regímenes especiales (exento). | | 45 | Gubernamental. | | 46 | Exportaciones (ITBIS tasa 0; comprador extranjero con `id_extranjero` y `pais`). | | 47 | Pagos al exterior (proveedor extranjero, exento, ISR retenido en cada línea). | ## Ejemplo de factura simple ```json { "tipo_ecf": "31", "comprador": {"rnc": "101000228", "razon_social": "Cliente Ejemplo SRL", "correo": "compras@cliente.do"}, "lineas": [ {"descripcion": "Consultoria", "cantidad": 2, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"}, {"descripcion": "Libro", "cantidad": 1, "precio_unitario": 800, "itbis": "exento", "tipo": "bien", "descuento": {"porcentaje": 10}} ], "tipo_pago": "credito", "fecha_limite_pago": "2026-11-30" } ``` - `itbis` por línea: `"18"`, `"16"`, `"0"` o `"exento"`. - `precios_incluyen_itbis: true` si el precio ya trae el impuesto. - Otra moneda: `moneda: "USD"` y precios en dólares; `tipo_cambio` es opcional con USD (por defecto, venta del Banco Central del cierre anterior; ver `GET /v1/tasas`). - Si omite `razon_social` y el RNC está en el directorio de la DGII, se completa sola. ## Nota de crédito (E34) ```json { "tipo_ecf": "34", "comprador": {"rnc": "101000228"}, "lineas": [{"descripcion": "Devolución consultoría", "cantidad": 1, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"}], "referencia": {"encf": "E310000000123", "fecha": "2026-11-02", "codigo_modificacion": "3"} } ``` `codigo_modificacion`: 1 anula, 2 corrige texto, 3 corrige montos, 4 reemplazo por contingencia, 5 referencia a consumo. ## Estados del comprobante `en_proceso` (enviado, esperando a la DGII) → `Aceptado`, `Aceptado Condicional` o `Rechazado`. Con clave `bl_test_` el resultado se simula al instante; use `numero_factura_interna: "SIMULAR-RECHAZO"` o `"SIMULAR-CONDICIONAL"` para probar esos casos. - `GET /v1/facturas/{encf}` estado de uno. - `POST /v1/ecf/estados` con `{"encfs": [...]}` estado de hasta 500. - `GET /v1/facturas/{encf}/pdf` y `/xml` representación impresa (con QR) y XML firmado. En sandbox el PDF lleva el sello "SIN VALIDEZ FISCAL". - Webhooks: ver [webhooks.md](https://www.businesslink.do/docs/webhooks.md). ## Numeración (e-NCF) Cada empresa numera de una de dos maneras (nunca las dos a la vez): **su ERP** (el e-NCF viene en el documento) o **BusinessLink** (el secuenciador lo asigna). Detalles en [secuencias-encf.md](https://www.businesslink.do/docs/secuencias-encf.md). ## Reglas de seguridad - Con `bl_live_` el comprobante es real y se reporta a la DGII; no se puede deshacer desde la API. - Una clave `bl_test_` solo ve comprobantes de prueba y una `bl_live_` solo los reales. - Siempre repita el **mismo** `Idempotency-Key` al reintentar una factura tras un timeout. Si el documento cambia, use otra clave. --- # Comprobantes recibidos de proveedores (facturas de compra) Permiso de la clave: `recibidos:leer`. BusinessLink recibe los e-CF que los proveedores de la empresa le envían (a través de los servicios de recepción y aprobación comercial de la DGII). Cada comprobante queda disponible por API con su XML firmado, su PDF y el documento completo ya leído, listo para convertirse en una factura de compra en un ERP o en un sistema contable. ## Listar `GET /v1/recibidos`: del más reciente al más antiguo. | Parámetro | Para qué | |---|---| | `desde`, `hasta` | Rango por fecha de emisión (AAAA-MM-DD). | | `recibido_desde` | Momento de llegada a BusinessLink (ISO 8601, p. ej. `2026-10-10T14:00:00-04:00`). Úselo para **sincronizar solo lo nuevo** guardando la última hora consultada. | | `emisor_rnc` | Un proveedor. | | `tipo_ecf` | Un tipo de comprobante. | | `limite` (máx. 200), `offset` | Paginación; `siguiente_offset` es `null` en la última página. | ## Un comprobante completo `GET /v1/recibidos/{emisor_rnc}/{encf}` devuelve el resumen y `documento`: la factura leída del XML firmado con líneas (códigos, cantidad, precio, descuento, ITBIS por línea, impuestos adicionales), descuentos o recargos globales, totales por tasa, moneda y referencias (orden de compra, NCF modificado). `documento.cuadre` indica si líneas + impuestos suman el total y si los montos de las líneas incluyen el ITBIS (muchos emisores lo declaran mal): revíselo antes de contabilizar. ## Descargar - `GET /v1/recibidos/{emisor_rnc}/{encf}/xml`: XML firmado original del proveedor. - `GET /v1/recibidos/{emisor_rnc}/{encf}/pdf`: representación impresa. ## Leer un XML que usted ya tiene `POST /v1/recibidos/leer` con `{"xml": ""}`: devuelve el mismo `documento`, indica si el comprador es su empresa (`para_su_empresa`) y si la firma digital es válida (`firma`). No guarda nada. Sirve para facturas que llegaron por correo o que un usuario arrastra a su sistema. ## Flujo típico para un sistema contable o ERP 1. Cada X minutos, `GET /v1/recibidos?recibido_desde=<última consulta>`. 2. Para cada nuevo, `GET /v1/recibidos/{emisor_rnc}/{encf}` y crear la factura de compra con `documento`. 3. Guardar el XML (`/xml`) como respaldo fiscal del documento. 4. Validar al proveedor con `GET /v1/rnc/{rnc}` (estado en el directorio de la DGII). El conector de Odoo (`l10n_do_ecf_businesslink`) hace exactamente este flujo y crea las facturas de proveedor completas (líneas, impuestos, retenciones aprendidas del hábito del contable). Las claves `bl_test_` ven lo recibido en los ambientes de prueba de la DGII. --- # Secuenciador de e-NCF Permisos de la clave: `secuencias:leer` y `secuencias:gestionar` (este último **no** viene en los permisos por defecto de una clave nueva). ## Qué es La DGII autoriza a cada empresa uno o más **rangos** de e-NCF por tipo de comprobante (por ejemplo E31 del 1 al 500, con fecha de vencimiento). El secuenciador de BusinessLink guarda esos rangos y entrega el siguiente número disponible cada vez que se emite un comprobante, de forma atómica: aunque lleguen varias llamadas a la vez, nunca se entrega el mismo número dos veces. Así una app no necesita llevar su propia numeración: BusinessLink es el backend de numeración y de emisión. ## Quién numera: `erp` o `businesslink` Cada empresa tiene una fuente de numeración, y es una sola (la DGII da un rango consecutivo por tipo): - `erp`: el e-NCF viene en el documento (todas las empresas con ERP existente, como Odoo). - `businesslink`: BusinessLink asigna el e-NCF en `POST /v1/facturas`. El cambio lo hace el equipo de BusinessLink. Antes de cambiar a `businesslink` se rechazan rangos que empiecen en o antes del último e-NCF que el ERP ya emitió de ese tipo, para evitar duplicados. ## Endpoints | Endpoint | Qué hace | |---|---| | `GET /v1/secuencias?tipo_ecf=31` | Rangos registrados, cuántos números quedan y vencimientos. | | `POST /v1/secuencias` | Registra un rango autorizado por la DGII (OFV): `tipo_ecf`, `desde`, `hasta`, `fecha_vencimiento`, y opcionalmente `siguiente` (si parte del rango ya se usó) y `aviso_umbral` (avisar cuando queden N o menos; por defecto 50). | | `POST /v1/secuencias/{id}/anular` con `{"confirmar": true}` | El rango deja de entregar números. No envía nada a la DGII: los números sin usar se anulan aparte (ANECF). | Una clave `bl_test_` solo ve y registra rangos de prueba; una `bl_live_`, los reales. ## Números quemados Un número se reutiliza solo si es seguro que la DGII nunca lo recibió (falló la validación o la firma antes de enviar). Si hubo timeout o resultado desconocido, **nunca** se reutiliza: se consulta el estado y, si la DGII no lo tiene, se anula con ANECF. ## Avisos BusinessLink avisa por correo cuando a un rango le quedan pocos números o está por vencer. --- # Webhooks Permiso de la clave: `webhooks:gestionar`. En vez de consultar el estado de cada comprobante, registre una URL https de su backend y BusinessLink le avisa cuando la DGII responde. ## Registrar `POST /v1/webhooks` ```json {"url": "https://miapp.com/api/webhooks/businesslink", "eventos": ["ecf.aceptado", "ecf.rechazado"], "descripcion": "Produccion"} ``` La respuesta incluye el `secreto`, que **solo se muestra esa vez**. Guárdelo para verificar la firma. ## Eventos | Evento | Significado | |---|---| | `ecf.aceptado` | La DGII aceptó el comprobante. | | `ecf.aceptado_condicional` | Aceptado con observaciones. | | `ecf.rechazado` | La DGII lo rechazó. | | `webhook.prueba` | Evento de prueba (`POST /v1/webhooks/{id}/probar`). | Use `"*"` para todos. El cuerpo trae `datos.encf`, `datos.estado` y `datos.mensajes`. Una clave `bl_test_` recibe los eventos del sandbox. ## Verificar la firma Cabecera `BL-Signature: t=,v1=` donde `v1 = HMAC-SHA256(secreto, t + "." + cuerpo_crudo)`. Rechace firmas de más de 5 minutos. Responda 2xx en menos de 10 segundos. ## Reintentos Si su servidor falla, BusinessLink reintenta con esperas crecientes (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h): unos 2 días en total. El mismo evento (`id`) puede llegar más de una vez: ignore los repetidos. ## Administrar - `GET /v1/webhooks`: lista (sin el secreto). - `DELETE /v1/webhooks/{id}`: borra el webhook y su historial. - `GET /v1/webhooks/{id}/entregas`: historial de entregas de 30 días. --- # Errores e idempotencia ## Formato de error (siempre el mismo) ```json {"error": {"codigo": "documento_invalido", "mensaje": "Una factura de credito fiscal (E31) requiere el RNC o cedula del comprador.", "sugerencia": "Si el cliente no tiene RNC, use tipo_ecf 32 (consumo).", "campo": "comprador.rnc", "detalles": [], "request_id": "..."}} ``` Los mensajes están en español y son accionables: lea `sugerencia`, corrija y reintente. Los agentes de IA pueden autocorregirse con ellos. Cite `request_id` al pedir soporte. ## Códigos frecuentes | Código | HTTP | Qué hacer | |---|---|---| | `clave_revocada`, clave inválida | 401 | Cree una clave nueva en el portal. | | `permiso_insuficiente` | 403 | La clave no tiene ese permiso; cree otra con el permiso. | | `llamada_desde_navegador` | 403 | Llame desde un servidor, no desde el navegador. | | `documento_invalido` | 422 | Falta o sobra un campo; vea `campo` y `sugerencia`. | | `filtro_invalido` | 422 | Un parámetro de consulta es incorrecto. | | `rnc_invalido` | 422 | Un RNC tiene 9 dígitos y una cédula 11. | | `rnc_no_encontrado` | 404 | El número no está en el directorio de la DGII. | | `factura_no_encontrada` | 404 | Revise el e-NCF y el modo (`test` vs `live`). | | `recibido_no_encontrado` | 404 | Revise el RNC del proveedor y el e-NCF. | | `nota_excede_original` | 422 | Una nota de crédito no puede devolver más de lo facturado. | | `confirmacion_requerida` | 400 | Envíe `confirmar: true`. | | `servicio_no_disponible` | 503 | Reintente con el mismo `Idempotency-Key`. | ## Idempotencia `POST /v1/facturas` y `POST /v1/ecf` exigen `Idempotency-Key` (un valor único por factura, por ejemplo un UUID). - Mismo valor y mismo documento: recibe la misma respuesta (cabecera `Idempotent-Replayed: true`) y **nunca** se emiten dos comprobantes. - Mismo valor y documento distinto: error de conflicto; use otra clave. - Un timeout no significa que falló: reintente con el **mismo** valor. --- # Integrar un ERP o sistema propio con BusinessLink ## Odoo El módulo `l10n_do_ecf_businesslink` (Odoo 14 a 18) envía cada factura posteada a BusinessLink, actualiza el estado con la respuesta de la DGII y trae los comprobantes recibidos de proveedores como facturas de compra. Se instala con la URL y la clave de API de la empresa. Módulos complementarios (autocompletar contactos desde el directorio de RNC de la DGII sin IAP, tasas diarias del Banco Central) viven en `businesslink-odoo-addons`. ## Otro ERP, POS o sistema propio | Necesita | Use | |---|---| | Enviar una factura ya calculada y numerada | `POST /v1/ecf` (JSON completo de la DGII, con `Idempotency-Key`). | | Que BusinessLink calcule impuestos y numere | `POST /v1/facturas` ([emitir-facturas.md](https://www.businesslink.do/docs/emitir-facturas.md)). | | Saber cuándo la DGII responde | Webhooks ([webhooks.md](https://www.businesslink.do/docs/webhooks.md)) o `POST /v1/ecf/estados`. | | Traer las compras (facturas de proveedores) | `GET /v1/recibidos?recibido_desde=...` ([comprobantes-recibidos.md](https://www.businesslink.do/docs/comprobantes-recibidos.md)). | | Numeración de e-NCF | Secuenciador ([secuencias-encf.md](https://www.businesslink.do/docs/secuencias-encf.md)). | | Validar clientes y proveedores | `GET /v1/rnc/{rnc}` y `GET /v1/rnc?q=`. | | Tasa de cambio oficial | `GET /v1/tasas?moneda=USD`. | ## Autenticación Una clave de API por app, con permisos mínimos (`facturas:emitir`, `facturas:leer`, `recibidos:leer`, `rnc:leer`, `secuencias:leer`, `secuencias:gestionar`, `webhooks:gestionar`) y modo `test` o `live`. Se crean y revocan en el portal, Mi Empresa → Claves de API. Los ERP existentes que usan la API anterior (`/fe/*` con usuario y contraseña) siguen funcionando; migran a `/v1` con una clave de API sin cambiar el formato del documento. --- # BusinessLink en asistentes de IA (servidor MCP) BusinessLink tiene un servidor **MCP** (Model Context Protocol) para que Claude, ChatGPT, Cursor, Claude Code y otros asistentes puedan consultar RNC, emitir comprobantes en sandbox, revisar las facturas recibidas de proveedores y administrar el secuenciador de e-NCF, hablando en lenguaje natural. - URL del servidor (HTTP, Streamable HTTP): `https://api.businesslink.do/mcp` - Autenticación: su clave de API de BusinessLink en la cabecera `Authorization: Bearer bl_test_...` - Empiece siempre con una clave **`bl_test_`** (sandbox: nada llega a la DGII). - Código y guía de instalación local: carpeta `mcp_server/` del repositorio de BusinessLink. ## Herramientas | Herramienta | Qué hace | Escribe | |---|---|---| | `mi_empresa` | Empresa, modo (test/live) y permisos de la clave | no | | `consultar_rnc`, `buscar_rnc` | Directorio de RNC de la DGII (por número o por nombre) | no | | `tasa_cambio` | Dólar y euro, Banco Central | no | | `estado_dgii` | Estado y mantenimiento de los servicios de la DGII | no | | `emitir_factura` | Emite un e-CF (factura simple; BusinessLink calcula e ITBIS y numera) | sí | | `emitir_ecf_completo` | Emite el JSON completo de la DGII (ERP) | sí | | `consultar_factura`, `consultar_facturas` | Estado de uno o varios comprobantes emitidos | no | | `descargar_factura` | XML firmado o PDF de un comprobante emitido | no | | `listar_recibidos` | Facturas de proveedores (compras), con filtros y sincronización incremental | no | | `consultar_recibido` | Documento completo de una compra: líneas, impuestos, totales | no | | `descargar_recibido` | XML firmado o PDF del proveedor | no | | `leer_ecf_xml` | Lee un XML de e-CF suelto y valida su firma | no | | `listar_secuencias` | Rangos de e-NCF y números disponibles | no | | `registrar_secuencia` | Registra un rango autorizado por la DGII | sí | | `anular_secuencia` | Deja de usar un rango | sí | | `listar_webhooks`, `registrar_webhook` | Webhooks firmados para el resultado de la DGII | sí (registrar) | | `buscar_documentacion` | Busca en estas guías (no necesita clave) | no | ## Seguridad - Las herramientas que escriben con una clave `bl_live_` (producción) exigen `confirmar_produccion=true`, que el asistente solo debe enviar después de la confirmación explícita de la persona. - Emitir exige `idempotency_key`: reintentar con el mismo valor nunca emite dos comprobantes. - Cree claves con los permisos mínimos. Para solo consultar, `rnc:leer`, `facturas:leer` y `recibidos:leer` bastan. - El servidor no guarda la clave: la reenvía a `https://api.businesslink.do/v1` en cada llamada. ## Cómo conectarlo ### Claude Code ```bash claude mcp add --transport http businesslink https://api.businesslink.do/mcp \ --header "Authorization: Bearer $BL_API_KEY" ``` ### Cursor / otros clientes con cabeceras (`mcp.json`) ```json { "mcpServers": { "businesslink": { "url": "https://api.businesslink.do/mcp", "headers": {"Authorization": "Bearer bl_test_XXXXXXXX"} } } } ``` ### Claude Desktop (local, stdio) ```json { "mcpServers": { "businesslink": { "command": "python", "args": ["-m", "businesslink_mcp", "--stdio"], "env": {"BL_API_KEY": "bl_test_XXXXXXXX"} } } } ``` (Instale antes el paquete: `pip install ./mcp_server`.) ### Claude.ai y ChatGPT (conectores web) Los conectores personalizados de Claude.ai y ChatGPT piden inicio de sesión OAuth y no permiten una cabecera fija. El inicio de sesión OAuth de BusinessLink está en desarrollo; mientras tanto use Claude Code, Cursor, Claude Desktop u otro cliente con cabeceras, o llame a la API REST directamente (ver [inicio-rapido.md](https://www.businesslink.do/docs/inicio-rapido.md)). ## Ejemplos de lo que se le puede pedir - "Busca el RNC de Ferretería Americana y dime si está activo." - "Emite una factura de prueba E31 a 101000228 por 2 horas de consultoría a RD$1,500 más ITBIS." - "Lista las facturas que me enviaron los proveedores esta semana y dime cuáles no cuadran." - "¿Cuántos e-NCF E31 me quedan disponibles y cuándo vence el rango?" - "Hazme una nota de crédito por devolución de la factura E310000000123." ---