Dominican Republic Invoices (DGII e-CF facturacion electronica)

Official4 toolsLive

by junter1989k-ai · JavaScript

Dominican Republic DGII e-CF: AI agents authenticate and submit electronic invoices, stateless BYO.

Topics

ai-agentclaudedgidgiidominican-republicinvoicemcpmcp-servervatwishpool

Captured live from the server via tools/list.

get_seed

Step 1 of DGII authentication: fetch a fresh "semilla" (seed) XML from the DGII Autenticacion service — GET /Autenticacion/api/Autenticacion/Semilla. No credentials, no fiscal effect. Returns { seed_xml, valor, fecha }: a short-lived XML document you must SIGN with your DGII-recognized digital certificate (Digifirma or another approved CA), then pass to get_token. This server only fetches the seed — the signing happens on YOUR side. Environment header (set once in your MCP client, per-request): x-dgii-env: test (default = TesteCF certificacion, open, NO fiscal effect) | prod (eCF produccion, real fiscal effect). There is NO static API key — DGII authentication is certificate-based: you sign the semilla and each e-CF with your own DGII-recognized digital certificate (Digifirma or another approved CA). This server never signs and never stores a token or certificate. Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

get_token

Step 2 of DGII authentication: exchange your SIGNED semilla for a session token — POST /Autenticacion/api/Autenticacion/ValidarSemilla (multipart field "xml"). You take the seed from get_seed, sign it with your DGII-recognized digital certificate merchant-side, and pass it here as base64 (signed_seed_xml). Returns { token, expira, expedido } — a Bearer token valid ~1 hour; use it for submit_invoice and query_status. If the seed is not correctly signed DGII returns HTTP 400 (e.g. "Archivo no valido." when the file is missing/not XML). This server forwards the signed bytes untouched and never stores the token. Environment header (set once in your MCP client, per-request): x-dgii-env: test (default = TesteCF certificacion, open, NO fiscal effect) | prod (eCF produccion, real fiscal effect). There is NO static API key — DGII authentication is certificate-based: you sign the semilla and each e-CF with your own DGII-recognized digital certificate (Digifirma or another approved CA). This server never signs and never stores a token or certificate. Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Parameters1

signed_seed_xml

string

required

The semilla XML from get_seed, SIGNED with your DGII-recognized digital certificate, base64-encoded (raw signed XML text is also accepted). Signing stays merchant-side; this server forwards the bytes untouched.

Raw schema

{
  "type": "object",
  "properties": {
    "signed_seed_xml": {
      "type": "string",
      "description": "The semilla XML from get_seed, SIGNED with your DGII-recognized digital certificate, base64-encoded (raw signed XML text is also accepted). Signing stays merchant-side; this server forwards the bytes untouched."
    }
  },
  "required": [
    "signed_seed_xml"
  ]
}

submit_invoice

Step 3: submit an ALREADY-SIGNED e-CF (comprobante fiscal electronico) to DGII for validation — POST /Recepcion/api/FacturasElectronicas (multipart field "xml", Bearer token). Your billing software BUILDS the e-CF XML (e-NCF, RNC emisor/comprador, Totales, ITBIS) and SIGNS it with your DGII-recognized certificate; this server does NOT generate or sign the XML — it forwards the signed bytes with your token. DGII replies { trackId, mensaje, error }: a trackId is your acuse de recibo (receipt) — the document was RECEIVED for asynchronous validation, NOT yet accepted. Poll query_status with the trackId until estado is "Aceptado" (fiscally valid) / "Aceptado Condicional" / "Rechazado" (rejected — read mensajes, fix, resubmit with a new e-NCF). An "error" with no trackId means DGII rejected the submission outright. Environment header (set once in your MCP client, per-request): x-dgii-env: test (default = TesteCF certificacion, open, NO fiscal effect) | prod (eCF produccion, real fiscal effect). There is NO static API key — DGII authentication is certificate-based: you sign the semilla and each e-CF with your own DGII-recognized digital certificate (Digifirma or another approved CA). This server never signs and never stores a token or certificate. Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Parameters2

signed_ecf_xml	string	required	The FULL signed e-CF XML, base64-encoded (raw signed XML text is also accepted). You build and sign it with your DGII certificate merchant-side; this server forwards the bytes untouched.
token	string	optional	The DGII session token from get_token (Bearer). Required. Can also be supplied via the x-dgii-token header.

Raw schema

{
  "type": "object",
  "properties": {
    "signed_ecf_xml": {
      "type": "string",
      "description": "The FULL signed e-CF XML, base64-encoded (raw signed XML text is also accepted). You build and sign it with your DGII certificate merchant-side; this server forwards the bytes untouched."
    },
    "token": {
      "type": "string",
      "description": "The DGII session token from get_token (Bearer). Required. Can also be supplied via the x-dgii-token header."
    }
  },
  "required": [
    "signed_ecf_xml"
  ]
}

query_status

Step 4: query the validation status of a submitted e-CF by its trackId — GET /ConsultaResultado/api/Consultas/Estado?TrackId={id} (Bearer token). Returns { trackId, estado, codigo, rnc, encf, secuenciaUtilizada, fechaRecepcion, mensajes[] }. estado enum: "En Proceso" (still validating — poll again) / "Aceptado" (ACCEPTED, fiscally valid) / "Aceptado Condicional" (accepted with observations in mensajes) / "Rechazado" (REJECTED — read mensajes for the reason, fix and resubmit with a new e-NCF). Poll this after submit_invoice until estado is no longer "En Proceso". Environment header (set once in your MCP client, per-request): x-dgii-env: test (default = TesteCF certificacion, open, NO fiscal effect) | prod (eCF produccion, real fiscal effect). There is NO static API key — DGII authentication is certificate-based: you sign the semilla and each e-CF with your own DGII-recognized digital certificate (Digifirma or another approved CA). This server never signs and never stores a token or certificate. Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Parameters2

trackId	string	required	The trackId returned by submit_invoice (DGII acuse de recibo).
token	string	optional	The DGII session token from get_token (Bearer). Required. Can also be supplied via the x-dgii-token header.

Raw schema

{
  "type": "object",
  "properties": {
    "trackId": {
      "type": "string",
      "description": "The trackId returned by submit_invoice (DGII acuse de recibo)."
    },
    "token": {
      "type": "string",
      "description": "The DGII session token from get_token (Bearer). Required. Can also be supplied via the x-dgii-token header."
    }
  },
  "required": [
    "trackId"
  ]
}

README.md6 KBView on GitHub

Dominican Republic Invoice MCP 🇩🇴

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "dominican-invoice": {
      "type": "http",
      "url": "https://inv-do.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/dominican-republic-invoice-mcp && cd dominican-republic-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent authenticate to and submit Dominican Republic electronic invoices (e-CF, comprobante fiscal electrónico / factura electrónica) through the DGII (Dirección General de Impuestos Internos) national gateway.

Endpoint: https://inv-do.wishpool.app/mcp (MCP Streamable HTTP, stateless JSON mode)
Stateless / BYO: no database, no accounts. DGII authentication is certificate-based — you sign the semilla and every e-CF with your own DGII-recognized digital certificate (Digifirma or another approved CA). This server only forwards already-signed bytes; it never signs, never generates the e-CF XML, and never stores anything.

Honest scope

This server is a thin, stateless translation layer over the four DGII e-CF web services. It does not:

generate or build the e-CF XML (your billing software does that, with the e-NCF, RNC, Totales, ITBIS);
sign anything (the XAdES signature and the DGII certificate stay merchant-side);
store credentials, tokens, invoices, or customer data.

It does map the DGII flow to four weak-model-friendly tools and pass DGII's native responses straight through.

The 4-step DGII e-CF flow

Step	Tool	DGII web service	You provide	You get back
1	`get_seed`	`GET /Autenticacion/api/Autenticacion/Semilla`	—	`{ seed_xml, valor, fecha }`
2	`get_token`	`POST /Autenticacion/api/Autenticacion/ValidarSemilla` (multipart `xml`)	the signed semilla (base64)	`{ token, expira, expedido }`
3	`submit_invoice`	`POST /Recepcion/api/FacturasElectronicas` (multipart `xml`, Bearer)	the signed e-CF (base64) + `token`	`{ trackId, mensaje, error }`
4	`query_status`	`GET /ConsultaResultado/api/Consultas/Estado?TrackId=` (Bearer)	`trackId` + `token`	`{ estado, codigo, rnc, encf, mensajes[] }`

estado enum: En Proceso → Aceptado (fiscally valid) / Aceptado Condicional (accepted with observations) / Rechazado (fix and resubmit with a new e-NCF).

Where do the credentials come from?

There is no static API key. To use production you need a DGII-recognized digital certificate issued by an approved Certification Authority (e.g. Digifirma), registered as a taxpayer certificate with the DGII. You sign the semilla with it to obtain a ~1-hour session token, and sign each e-CF the same way. For free testing, the DGII TesteCF (certificación) environment is open, requires no registration, and has no fiscal effect.

Headers

Header	Required	Meaning
`x-dgii-env`	optional	`test` (default, TesteCF certificación, no fiscal effect) or `prod` (eCF production, real fiscal effect)
`x-dgii-token`	optional	alternative to passing the `get_token` token as the `token` argument on `submit_invoice`/`query_status`
`x-agentpay-max-amount`	optional	hard cap on the grand total (`MontoTotal`, incl. ITBIS, in DOP) — owner-set; the agent cannot relax it
`x-agentpay-approval-above`	optional	above this the invoice is not submitted; returns an unsubmitted draft for human review
`x-agentpay-allowed-tools`	optional	comma-separated tool allow-list

json

{
  "mcpServers": {
    "dominican-republic-invoice": {
      "type": "http",
      "url": "https://inv-do.wishpool.app/mcp",
      "headers": { "x-dgii-env": "prod" }
    }
  }
}

Mandate

Electronic invoicing (facturación electrónica / e-CF) is mandatory in the Dominican Republic under Law 32-23, phased in by taxpayer size: large national taxpayers first, medium/small/micro phased through 2026. Every taxpayer must issue e-CF and report it to the DGII via these web services.

Develop & test

bash

npm run dev    # local server on http://localhost:3246 (simulates /mcp routing)
npm test       # full e2e: protocol + validation + policy + LIVE DGII TesteCF probes

The e2e suite includes live probes against the open DGII TesteCF environment: GET Semilla asserts 200 + <valor>, and a fake POST ValidarSemilla asserts the native 400 "Archivo no válido." — no certificate required.

Sister servers

Invoices: Costa Rica Hacienda (inv-cr), Saudi ZATCA (inv-sa), Mexico CFDI 4.0 (inv-mx), Poland KSeF (inv-pl), Chile DTE (inv-cl), Brazil NF-e (inv-br), Peru CPE (inv-pe), India GST (inv-in). Local payments in 81 countries and logistics, one family, same stateless pattern — see mcp.wishpool.app · logi.wishpool.app.

License

MIT

Install

Tools (4)

get_seedget_tokensubmit_invoicequery_status

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-do.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "dominican-republic-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-do.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.