Envío y Consulta de Documentos
Cómo enviar y consultar documentos electrónicos en MSeller ECF
Envío y Consulta de Documentos
Esta sección explica cómo enviar y consultar documentos electrónicos utilizando la API de MSeller ECF.
Envío de documentos
Para enviar un documento electrónico a la plataforma, debes realizar una solicitud POST al endpoint correspondiente:
POST /{entorno}/documentos-ecfDonde {entorno} puede ser:
TesteCF(para pruebas)CertCF(para certificación)eCF(para producción)
Encabezados requeridos
Authorization: Bearer {tu_token}
X-API-KEY: {tu_api_key}
Content-Type: application/jsonCuerpo de la solicitud
El cuerpo de la solicitud debe contener el documento en formato JSON estructurado según las especificaciones detalladas en Formato de Documentos.
Ejemplos de documentos JSON
Ejemplo 1: Factura de Crédito Fiscal con descuento simple
{
"ECF": {
"Encabezado": {
"Version": "1.0",
"IdDoc": {
"TipoeCF": "31",
"eNCF": "E310571508136",
"FechaVencimientoSecuencia": "31-12-2026",
"IndicadorEnvioDiferido": "1",
"IndicadorMontoGravado": "0",
"TipoIngresos": "05",
"TipoPago": "2",
"FechaLimitePago": "07-08-2026",
"TotalPaginas": 1
},
"Emisor": {
"RNCEmisor": "102320705",
"RazonSocialEmisor": "Comercial Ejemplo SRL",
"DireccionEmisor": "Calle Principal No. 123",
"FechaEmision": "29-06-2025"
},
"Comprador": {
"RNCComprador": "101023122",
"RazonSocialComprador": "Cliente Prueba SRL"
},
"Totales": {
"MontoGravadoTotal": 540.0,
"MontoGravadoI1": 540.0,
"MontoExento": 0,
"ITBIS1": 18,
"TotalITBIS": 97.2,
"TotalITBIS1": 97.2,
"MontoTotal": 637.2,
"MontoNoFacturable": 0
}
},
"DetallesItems": {
"Item": [
{
"NumeroLinea": "1",
"IndicadorFacturacion": "1",
"NombreItem": "Producto Ejemplo",
"IndicadorBienoServicio": "1",
"CantidadItem": 24,
"UnidadMedida": "43",
"PrecioUnitarioItem": 25.0,
"DescuentoMonto": 60.0,
"TablaSubDescuento": {
"SubDescuento": [
{
"TipoSubDescuento": "%",
"SubDescuentoPorcentaje": 10.0,
"MontoSubDescuento": 60.0
}
]
},
"MontoItem": 540.0
}
]
},
"Paginacion": {
"Pagina": [
{
"PaginaNo": 1,
"NoLineaDesde": 1,
"NoLineaHasta": 1,
"SubtotalMontoGravadoPagina": 540.0,
"SubtotalMontoGravado1Pagina": 540.0,
"SubtotalExentoPagina": 0,
"SubtotalItbisPagina": 97.2,
"SubtotalItbis1Pagina": 97.2,
"MontoSubtotalPagina": 637.2,
"SubtotalMontoNoFacturablePagina": 0
}
]
},
"FechaHoraFirma": ""
}
}Ejemplo 2: Factura de Consumo con múltiples ITBIS y producto exento
Este ejemplo muestra una factura de consumo (tipo 32) con múltiples productos que incluyen diferentes tasas de ITBIS (18% y 16%) y un producto exento de impuestos.
{
"ECF": {
"Encabezado": {
"Version": "1.0",
"IdDoc": {
"TipoeCF": 32,
"eNCF": "E320004380890",
"IndicadorEnvioDiferido": 1,
"IndicadorMontoGravado": 0,
"TipoIngresos": "01",
"TipoPago": 1
},
"Emisor": {
"RNCEmisor": "000000000",
"RazonSocialEmisor": "Empresa Ejemplo SRL",
"NombreComercial": "Tienda Ejemplo",
"Sucursal": "SUCURSAL PRINCIPAL",
"DireccionEmisor": "Calle Principal #100",
"Municipio": "010100",
"Provincia": "010000",
"WebSite": "www.ejemplo.com.do",
"CodigoVendedor": "VEND001",
"FechaEmision": "04-11-2025"
},
"Comprador": {
"RNCComprador": "40211111111",
"RazonSocialComprador": "Juan Pérez",
"DireccionComprador": "C/ Ejemplo #123",
"FechaEntrega": "04-11-2025"
},
"Totales": {
"MontoGravadoTotal": 1139.5,
"MontoGravadoI1": 807.02,
"MontoGravadoI2": 332.48,
"MontoExento": 96,
"ITBIS1": 18,
"ITBIS2": 16,
"TotalITBIS": 194.11,
"TotalITBIS1": 140.91,
"TotalITBIS2": 53.2,
"MontoTotal": 1405.39,
"MontoNoFacturable": 0
}
},
"DetallesItems": {
"Item": [
{
"NumeroLinea": 1,
"IndicadorFacturacion": 4,
"NombreItem": "AGUA FONTINA",
"IndicadorBienoServicio": 1,
"DescripcionItem": "AGUA FONTINA",
"CantidadItem": 1,
"UnidadMedida": 43,
"PrecioUnitarioItem": 96,
"MontoItem": 96
},
{
"NumeroLinea": 2,
"IndicadorFacturacion": 1,
"NombreItem": "MALTA INDIA 12/1",
"IndicadorBienoServicio": 1,
"DescripcionItem": "MALTA INDIA 12/1",
"CantidadItem": 1,
"UnidadMedida": 43,
"PrecioUnitarioItem": 807.02,
"DescuentoMonto": 24.21,
"TablaSubDescuento": {
"SubDescuento": [
{
"TipoSubDescuento": "%",
"SubDescuentoPorcentaje": 3,
"MontoSubDescuento": 24.21
}
]
},
"MontoItem": 807.02
},
{
"NumeroLinea": 3,
"IndicadorFacturacion": 2,
"NombreItem": "CAFE BUSTELO CAPSULA 1.7 OZ.",
"IndicadorBienoServicio": 1,
"DescripcionItem": "CAFE BUSTELO CAPSULA 1.7 OZ.",
"CantidadItem": 1,
"UnidadMedida": 43,
"PrecioUnitarioItem": 332.48,
"MontoItem": 332.48
}
]
},
"FechaHoraFirma": "03-11-2025 19:26:35"
}
}Características destacadas de este ejemplo:
- Producto exento (Item 1): El agua tiene
IndicadorFacturacion: 4que indica que está exenta de ITBIS - Múltiples tasas de ITBIS: Item 2 con ITBIS1 (18%) e Item 3 con ITBIS2 (16%)
- Descuento aplicado: El Item 2 incluye un descuento del 3%
- Factura de consumo:
TipoeCF: 32para ventas al consumidor final - Información completa del emisor: Incluye sucursal, municipio, provincia y código de vendedor
Nota importante: Para facturas de consumo (tipo 32), puedes omitir el RNC del comprador si es una venta a persona física sin RNC, pero es recomendable incluirlo cuando esté disponible.
Ejemplo de envío
curl -X POST \
https://ecf.api.mseller.app/TesteCF/documentos-ecf \
-H 'Authorization: Bearer eyJraWQiOiJ1dE...' \
-H 'X-API-KEY: tu_api_key' \
-H 'Content-Type: application/json' \
-d '{
"ECF": {
"Encabezado": {
"Version": "1.0",
"IdDoc": {
"TipoeCF": "31",
"eNCF": "E310571508136",
"FechaVencimientoSecuencia": "31-12-2026",
"IndicadorEnvioDiferido": "1",
"IndicadorMontoGravado": "0",
"TipoIngresos": "05",
"TipoPago": "2",
"FechaLimitePago": "07-08-2026",
"TotalPaginas": 1
},
"Emisor": {
"RNCEmisor": "Tu RNC",
"RazonSocialEmisor": "Tu Negocio",
"DireccionEmisor": "DireccionEmisor1",
"FechaEmision": "29-06-2025"
},
"Comprador": {
"RNCComprador": "101023122",
"RazonSocialComprador": "Cliente Prueba SRL"
},
"Totales": {
"MontoGravadoTotal": 540.0,
"MontoGravadoI1": 540.0,
"MontoExento": 0,
"ITBIS1": 18,
"TotalITBIS": 97.2,
"TotalITBIS1": 97.2,
"MontoTotal": 637.2,
"MontoNoFacturable": 0
}
}
}
}'async function enviarDocumento() {
const documento = {
ECF: {
Encabezado: {
Version: "1.0",
IdDoc: {
TipoeCF: "31",
eNCF: "E310571508136",
FechaVencimientoSecuencia: "31-12-2026",
IndicadorEnvioDiferido: "1",
IndicadorMontoGravado: "0",
TipoIngresos: "05",
TipoPago: "2",
FechaLimitePago: "07-08-2026",
TotalPaginas: 1,
},
Emisor: {
RNCEmisor: "Tu RNC",
RazonSocialEmisor: "Tu Negocio",
DireccionEmisor: "DireccionEmisor1",
FechaEmision: "29-06-2025",
},
Comprador: {
RNCComprador: "101023122",
RazonSocialComprador: "Cliente Prueba SRL",
},
Totales: {
MontoGravadoTotal: 540.0,
MontoGravadoI1: 540.0,
MontoExento: 0,
ITBIS1: 18,
TotalITBIS: 97.2,
TotalITBIS1: 97.2,
MontoTotal: 637.2,
MontoNoFacturable: 0,
},
},
DetallesItems: {
Item: [
{
NumeroLinea: "1",
IndicadorFacturacion: "1",
NombreItem: "Producto 1",
IndicadorBienoServicio: "1",
CantidadItem: 24,
UnidadMedida: "43",
PrecioUnitarioItem: 25.0,
DescuentoMonto: 60.0,
TablaSubDescuento: {
SubDescuento: [
{
TipoSubDescuento: "%",
SubDescuentoPorcentaje: 10.0,
MontoSubDescuento: 60.0,
},
],
},
MontoItem: 540.0,
},
],
},
Paginacion: {
Pagina: [
{
PaginaNo: 1,
NoLineaDesde: 1,
NoLineaHasta: 1,
SubtotalMontoGravadoPagina: 540.0,
SubtotalMontoGravado1Pagina: 540.0,
SubtotalExentoPagina: 0,
SubtotalItbisPagina: 97.2,
SubtotalItbis1Pagina: 97.2,
MontoSubtotalPagina: 637.2,
SubtotalMontoNoFacturablePagina: 0,
},
],
},
FechaHoraFirma: "",
},
};
const idToken = localStorage.getItem("idToken");
try {
const response = await fetch(
"https://ecf.api.mseller.app/TesteCF/documentos-ecf",
{
method: "POST",
headers: {
Authorization: `Bearer ${idToken}`,
"X-API-KEY": "tu_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify(documento),
}
);
const resultado = await response.json();
console.log("Documento enviado:", resultado);
return resultado;
} catch (error) {
console.error("Error al enviar documento:", error);
throw error;
}
}using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
public class MSellercfClient
{
private readonly HttpClient _client = new HttpClient();
private readonly string _idToken;
private readonly string _apiKey;
public MSellercfClient(string idToken, string apiKey)
{
_idToken = idToken;
_apiKey = apiKey;
}
public async Task<JObject> EnviarDocumento()
{
// Crear el objeto documento
var documento = new JObject();
var ecf = new JObject();
var encabezado = new JObject();
encabezado["Version"] = "1.0";
var idDoc = new JObject();
idDoc["TipoeCF"] = "31";
idDoc["eNCF"] = "E310571508136";
idDoc["FechaVencimientoSecuencia"] = "31-12-2026";
idDoc["IndicadorEnvioDiferido"] = "1";
idDoc["IndicadorMontoGravado"] = "0";
idDoc["TipoIngresos"] = "05";
idDoc["TipoPago"] = "2";
idDoc["FechaLimitePago"] = "07-08-2026";
idDoc["TotalPaginas"] = 1;
var emisor = new JObject();
emisor["RNCEmisor"] = "Tu RNC";
emisor["RazonSocialEmisor"] = "Tu Negocio";
emisor["DireccionEmisor"] = "DireccionEmisor1";
emisor["FechaEmision"] = "29-06-2025";
var comprador = new JObject();
comprador["RNCComprador"] = "101023122";
comprador["RazonSocialComprador"] = "Cliente Prueba SRL";
var totales = new JObject();
totales["MontoGravadoTotal"] = 540.0;
totales["MontoGravadoI1"] = 540.0;
totales["MontoExento"] = 0;
totales["ITBIS1"] = 18;
totales["TotalITBIS"] = 97.2;
totales["TotalITBIS1"] = 97.2;
totales["MontoTotal"] = 637.2;
totales["MontoNoFacturable"] = 0;
// Estructura completa del documento (ejemplo simplificado)
encabezado["IdDoc"] = idDoc;
encabezado["Emisor"] = emisor;
encabezado["Comprador"] = comprador;
encabezado["Totales"] = totales;
// Agregar más detalles conforme a la estructura completa
// ...
ecf["Encabezado"] = encabezado;
documento["ECF"] = ecf;
// Configurar la solicitud HTTP
_client.DefaultRequestHeaders.Clear();
_client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_idToken}");
_client.DefaultRequestHeaders.Add("X-API-KEY", _apiKey);
var content = new StringContent(
documento.ToString(),
Encoding.UTF8,
"application/json");
var response = await _client.PostAsync(
"https://ecf.api.mseller.app/TesteCF/documentos-ecf",
content);
var responseJson = await response.Content.ReadAsStringAsync();
return JObject.Parse(responseJson);
}
}<?php
function enviarDocumento($idToken, $apiKey) {
$url = 'https://ecf.api.mseller.app/TesteCF/documentos-ecf';
// Documento en formato JSON
$documento = [
'ECF' => [
'Encabezado' => [
'Version' => '1.0',
'IdDoc' => [
'TipoeCF' => '31',
'eNCF' => 'E310571508136',
'FechaVencimientoSecuencia' => '31-12-2026',
'IndicadorEnvioDiferido' => '1',
'IndicadorMontoGravado' => '0',
'TipoIngresos' => '05',
'TipoPago' => '2',
'FechaLimitePago' => '07-08-2026',
'TotalPaginas' => 1
],
'Emisor' => [
'RNCEmisor' => 'Tu RNC',
'RazonSocialEmisor' => 'Tu Negocio',
'DireccionEmisor' => 'DireccionEmisor1',
'FechaEmision' => '29-06-2025'
],
'Comprador' => [
'RNCComprador' => '101023122',
'RazonSocialComprador' => 'Cliente Prueba SRL'
],
'Totales' => [
'MontoGravadoTotal' => 540.0,
'MontoGravadoI1' => 540.0,
'MontoExento' => 0,
'ITBIS1' => 18,
'TotalITBIS' => 97.2,
'TotalITBIS1' => 97.2,
'MontoTotal' => 637.2,
'MontoNoFacturable' => 0
]
],
'DetallesItems' => [
'Item' => [
[
'NumeroLinea' => '1',
'IndicadorFacturacion' => '1',
'NombreItem' => 'Producto 1',
'IndicadorBienoServicio' => '1',
'CantidadItem' => 24,
'UnidadMedida' => '43',
'PrecioUnitarioItem' => 25.0,
'DescuentoMonto' => 60.0,
'TablaSubDescuento' => [
'SubDescuento' => [
[
'TipoSubDescuento' => '%',
'SubDescuentoPorcentaje' => 10.0,
'MontoSubDescuento' => 60.0
]
]
],
'MontoItem' => 540.0
]
]
]
// Agregar Paginación y otros elementos según necesidad
]
];
$options = [
'http' => [
'method' => 'POST',
'header' =>
"Authorization: Bearer " . $idToken . "\r\n" .
"X-API-KEY: " . $apiKey . "\r\n" .
"Content-Type: application/json\r\n",
'content' => json_encode($documento)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === false) {
// Manejar error
return null;
}
return json_decode($result, true);
}
// Uso
$idToken = $_SESSION['idToken']; // Obtenido del proceso de autenticación
$apiKey = 'tu_api_key';
$resultado = enviarDocumento($idToken, $apiKey);
print_r($resultado);
?>Nota: En el ambiente de prueba debes buscar una secuencia aleatoria que no haya sido utilizada, debes tratar con diferentes secuencias
Respuesta exitosa
{
"rnc": "102320705",
"ecf": "E310000009175",
"internalTrackId": "58f1bdd7-f4be-4a2e-a1e6-570c95b8d477",
"securityCode": "fWCZCV",
"qr_url": "https://ecf.dgii.gov.do/testecf/consultatimbre?rncemisor=102320705&RncComprador=101023122&encf=E310000009175&FechaEmision=14-05-2025&montototal=637.2&FechaFirma=14-05-2025%2002:57:33&codigoseguridad=fWCZCV",
"signedDate": "14-05-2025 02:57:33"
}Consulta de documentos
Para consultar el estado de un documento enviado previamente, debes realizar una solicitud GET al endpoint de consulta:
GET /{entorno}/documentos-ecf?ecf={No. comprobante electrónico}Encabezados requeridos
Authorization: Bearer {tu_token}
X-API-KEY: {tu_api_key}Ejemplo de consulta
curl -X GET \
https://ecf.api.mseller.app/TesteCF/documentos-ecf?ecf=E123456789 \
-H 'Authorization: Bearer eyJraWQiOiJ1dE...' \
-H 'X-API-KEY: tu_api_key'Ejemplo de consulta
async function consultarDocumento(ecf) {
const idToken = localStorage.getItem("idToken");
try {
const response = await fetch(
`https://ecf.api.mseller.app/TesteCF/documentos-ecf?ecf=${ecf}`,
{
method: "GET",
headers: {
Authorization: `Bearer ${idToken}`,
"X-API-KEY": "tu_api_key",
},
}
);
const resultado = await response.json();
console.log("Estado del documento:", resultado);
return resultado;
} catch (error) {
console.error("Error al consultar documento:", error);
throw error;
}
}Ejemplo de consulta
using System;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;
public class MSellercfClient
{
private readonly HttpClient _client = new HttpClient();
private readonly string _idToken;
private readonly string _apiKey;
public MSellercfClient(string idToken, string apiKey)
{
_idToken = idToken;
_apiKey = apiKey;
}
public async Task<JObject> ConsultarDocumento(string ecf)
{
_client.DefaultRequestHeaders.Clear();
_client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_idToken}");
_client.DefaultRequestHeaders.Add("X-API-KEY", _apiKey);
var response = await _client.GetAsync(
$"https://ecf.api.mseller.app/TesteCF/documentos-ecf?ecf={ecf}");
var responseJson = await response.Content.ReadAsStringAsync();
return JObject.Parse(responseJson);
}
}Ejemplo de consulta
<?php
function consultarDocumento($ecf, $idToken, $apiKey) {
$url = 'https://ecf.api.mseller.app/TesteCF/documentos-ecf?ecf=' . urlencode($ecf);
$options = [
'http' => [
'method' => 'GET',
'header' =>
"Authorization: Bearer " . $idToken . "\r\n" .
"X-API-KEY: " . $apiKey . "\r\n"
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === false) {
// Manejar error
return null;
}
return json_decode($result, true);
}
// Uso
$idToken = $_SESSION['idToken']; // Obtenido del proceso de autenticación
$apiKey = 'tu_api_key';
$ecf = 'E123456789';
$resultado = consultarDocumento($ecf, $idToken, $apiKey);
print_r($resultado);
?>Respuesta exitosa
{
"fileName": "102320705E310000009179.xml",
"updateAt": 1747250783965,
"customerReceivedAt": "14-05-2025 15:26:21",
"documentType": "Factura de Crédito Fiscal Electrónico",
"customerResponse": "{\"_declaration\":{\"_attributes\":{\"version\":\"1.0\",\"encoding\":\"utf-8\"}},\"ARECF\":{...}}",
"status": "Aceptado",
"dgiiResponse": [
"{\"trackId\":\"0cc42712-4a99-48be-b66d-346b33e36d7f\",\"error\":null,\"mensaje\":null}",
"{\"trackId\":\"0cc42712-4a99-48be-b66d-346b33e36d7f\",\"codigo\":\"1\",\"estado\":\"Aceptado\",\"rnc\":\"102320705\",\"encf\":\"E310000009179\",\"secuenciaUtilizada\":true,\"fechaRecepcion\":\"5/14/2025 3:26:21 PM\",\"mensajes\":[{\"valor\":\"\",\"codigo\":0}]}"
],
"createdAt": 1747250778433,
"securityCode": "hhABiM",
"signedXml": "102320705/documents/TesteCF/102320705E310000009179.xml",
"ncf": "E310000009179",
"internalTrackId": "a118ea44-ac12-466a-b071-c4b650bb5a4f",
"customerReceived": "0",
"qr_url": "https://ecf.dgii.gov.do/testecf/consultatimbre?rncemisor=102320705&RncComprador=101023122&encf=E310000009179&FechaEmision=14-05-2025&montototal=637.2&FechaFirma=14-05-2025%2003:26:18&codigoseguridad=hhABiM",
"customerId": "102320705"
}Campos de la respuesta de consulta
| Campo | Descripción |
|---|---|
| fileName | Nombre del archivo XML generado |
| updateAt | Timestamp de la última actualización |
| customerReceivedAt | Fecha y hora en que el cliente recibió el documento |
| documentType | Tipo de documento (ej: "Factura de Crédito Fiscal Electrónico") |
| customerResponse | Respuesta completa en formato XML (transformada a JSON para la API) |
| status | Estado del documento ("Aceptado", "Rechazado", etc.) |
| dgiiResponse | Respuestas recibidas de la DGII |
| createdAt | Timestamp de creación del documento |
| securityCode | Código de seguridad para la representación impresa |
| signedXml | Ruta al documento XML firmado |
| ncf | Número de Comprobante Fiscal |
| internalTrackId | ID de seguimiento interno |
| customerReceived | Indicador de recepción por el cliente |
| qr_url | URL del código QR para consulta |
| customerId | ID del cliente (RNC) |
Consulta de documentos en batch
Para consultar el estado de múltiples documentos en una sola solicitud, puedes utilizar el endpoint de consulta en batch. Este método es especialmente útil cuando necesitas verificar el estado de varios documentos simultáneamente, optimizando el rendimiento y reduciendo el número de llamadas a la API.
POST /{entorno}/documentos-ecf/status/batchLímites
- Máximo de documentos por consulta: 100 e-CF por solicitud
Encabezados requeridos
Authorization: Bearer {tu_token}
X-API-KEY: {tu_api_key}
Content-Type: application/jsonCuerpo de la solicitud
El cuerpo de la solicitud debe contener un array con los números de comprobantes electrónicos (e-CF) que deseas consultar:
{
"ecfs": ["E320004380895", "E310000510917", "E310000510916", "E310000510915"]
}Ejemplo de consulta en batch
curl -X POST \
https://ecf.api.mseller.app/TesteCF/documentos-ecf/status/batch \
-H 'Authorization: Bearer eyJraWQiOiJ1dE...' \
-H 'X-API-KEY: tu_api_key' \
-H 'Content-Type: application/json' \
-d '{
"ecfs": ["E320004380895", "E310000510917", "E310000510916", "E310000510915"]
}'Ejemplo de consulta en batch
async function consultarDocumentosBatch(ecfs) {
const idToken = localStorage.getItem("idToken");
try {
const response = await fetch(
`https://ecf.api.mseller.app/TesteCF/documentos-ecf/status/batch`,
{
method: "POST",
headers: {
Authorization: `Bearer ${idToken}`,
"X-API-KEY": "tu_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({ ecfs }),
}
);
const resultado = await response.json();
console.log("Estado de documentos:", resultado);
return resultado;
} catch (error) {
console.error("Error al consultar documentos en batch:", error);
throw error;
}
}
// Uso
const ecfs = [
"E320004380895",
"E310000510917",
"E310000510916",
"E310000510915",
];
consultarDocumentosBatch(ecfs);Ejemplo de consulta en batch
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
public class MSellercfClient
{
private readonly HttpClient _client = new HttpClient();
private readonly string _idToken;
private readonly string _apiKey;
public MSellercfClient(string idToken, string apiKey)
{
_idToken = idToken;
_apiKey = apiKey;
}
public async Task<JObject> ConsultarDocumentosBatch(List<string> ecfs)
{
_client.DefaultRequestHeaders.Clear();
_client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_idToken}");
_client.DefaultRequestHeaders.Add("X-API-KEY", _apiKey);
var payload = new JObject
{
["ecfs"] = JArray.FromObject(ecfs)
};
var content = new StringContent(
payload.ToString(),
Encoding.UTF8,
"application/json");
var response = await _client.PostAsync(
"https://ecf.api.mseller.app/TesteCF/documentos-ecf/status/batch",
content);
var responseJson = await response.Content.ReadAsStringAsync();
return JObject.Parse(responseJson);
}
}
// Uso
var ecfs = new List<string>
{
"E320004380895",
"E310000510917",
"E310000510916",
"E310000510915"
};
var resultado = await client.ConsultarDocumentosBatch(ecfs);Ejemplo de consulta en batch
<?php
function consultarDocumentosBatch($ecfs, $idToken, $apiKey) {
$url = 'https://ecf.api.mseller.app/TesteCF/documentos-ecf/status/batch';
$payload = json_encode([
'ecfs' => $ecfs
]);
$options = [
'http' => [
'method' => 'POST',
'header' =>
"Authorization: Bearer " . $idToken . "\r\n" .
"X-API-KEY: " . $apiKey . "\r\n" .
"Content-Type: application/json\r\n",
'content' => $payload
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === false) {
// Manejar error
return null;
}
return json_decode($result, true);
}
// Uso
$idToken = $_SESSION['idToken']; // Obtenido del proceso de autenticación
$apiKey = 'tu_api_key';
$ecfs = [
'E320004380895',
'E310000510917',
'E310000510916',
'E310000510915'
];
$resultado = consultarDocumentosBatch($ecfs, $idToken, $apiKey);
print_r($resultado);
?>Respuesta exitosa
La respuesta incluye el total de documentos consultados y un array con los resultados de cada documento:
{
"total": 4,
"results": [
{
"ecf": "E320004380895",
"status": "Aceptado",
"found": true,
"data": {
"buyerRnc": "00115275869",
"createdAt": 1762217966021,
"dgiiResponse": [
"{\"codigo\":1,\"estado\":\"Aceptado\",\"mensajes\":null,\"encf\":\"E320004380895\",\"secuenciaUtilizada\":true}"
],
"documentType": "Factura de Consumo Electrónica",
"fileName": "102320705E320004380895.xml",
"internalTrackId": "aada68a0-42c6-4a0a-804a-db9c042e1dc6",
"invoiceTotal": 385.68,
"ncf": "E320004380895",
"qr_url": "https://fc.dgii.gov.do/testecf/consultatimbrefc?rncemisor=102320705&encf=E320004380895&montototal=385.68&codigoseguridad=A7HXQC",
"secretId": "b14ac74e-ab14-4230-8894-ec19929ed7bc",
"securityCode": "A7HXQC",
"signedXml": "102320705/documents/TesteCF/102320705E320004380895.xml",
"status": "Aceptado",
"summarySignedXml": "102320705/summaries/TesteCF/102320705E320004380895.xml",
"updateAt": 1762217969008,
"customerId": "102320705"
}
},
{
"ecf": "E310000510917",
"status": "Aceptado",
"found": true,
"data": {
"buyerRnc": "00115275869",
"createdAt": 1762215883006,
"documentType": "Factura de Crédito Fiscal Electrónico",
"invoiceTotal": 952.28,
"ncf": "E310000510917",
"qr_url": "https://ecf.dgii.gov.do/testecf/consultatimbre?rncemisor=102320705&RncComprador=00115275869&encf=E310000510917&fechaemision=04-11-2025&montototal=952.28&fechafirma=03-11-2025%2008%3A24%3A42&codigoseguridad=wKL28p",
"securityCode": "wKL28p",
"status": "Aceptado",
"updateAt": 1762215889088,
"customerId": "102320705"
}
},
{
"ecf": "E310000510916",
"status": "Rechazado",
"found": true,
"data": {
"buyerRnc": "00300717659",
"createdAt": 1762215563667,
"dgiiResponse": [
"{\"trackId\":\"32c4f7e0-dbbe-40cc-a1d4-e4cc0ff82c13\",\"codigo\":\"2\",\"estado\":\"Rechazado\",\"rnc\":\"102320705\",\"encf\":\"E310000510916\",\"secuenciaUtilizada\":true,\"fechaRecepcion\":\"11/3/2025 8:19:30 PM\",\"mensajes\":[{\"valor\":\"El campo MontoGravadoTotal del área Totales de la sección Encabezado\",\"codigo\":1920}]}"
],
"documentType": "Factura de Crédito Fiscal Electrónico",
"invoiceTotal": 952.28,
"ncf": "E310000510916",
"status": "Rechazado",
"updateAt": 1762215575268,
"customerId": "102320705"
}
},
{
"ecf": "E310000510915",
"status": "Aceptado Condicional",
"found": true,
"data": {
"buyerRnc": "00115275869",
"createdAt": 1762215210792,
"dgiiResponse": [
"{\"trackId\":\"45309489-f05b-425b-bb67-6706d0a77225\",\"codigo\":\"4\",\"estado\":\"Aceptado Condicional\",\"rnc\":\"102320705\",\"encf\":\"E310000510915\",\"secuenciaUtilizada\":true,\"fechaRecepcion\":\"11/3/2025 8:13:37 PM\",\"mensajes\":[{\"valor\":\"El campo MontoGravadoTotal del área Totales de la sección Encabezado no corresponde con la sumatoria de los items de su factura ya que excede la tolerancia de 100.\",\"codigo\":1924},{\"valor\":\"El campo MontoTotal del área Totales de la sección Encabezado no es válido.El elemento MontoTotal no es correcto\",\"codigo\":11105}]}"
],
"documentType": "Factura de Crédito Fiscal Electrónico",
"invoiceTotal": 952.28,
"ncf": "E310000510915",
"status": "Aceptado Condicional",
"updateAt": 1762215220782,
"customerId": "102320705"
}
}
]
}Campos de la respuesta batch
| Campo | Descripción |
|---|---|
| total | Cantidad total de documentos consultados |
| results | Array con los resultados de cada documento consultado |
Campos de cada resultado
| Campo | Descripción |
|---|---|
| ecf | Número de comprobante electrónico consultado |
| status | Estado actual del documento ("Aceptado", "Rechazado", "Aceptado Condicional", etc.) |
| found | Indica si el documento fue encontrado en el sistema (true/false) |
| data | Objeto con los detalles completos del documento (solo si found = true). Ver tabla de campos a continuación |
Campos del objeto data
| Campo | Descripción |
|---|---|
| buyerRnc | RNC del comprador |
| createdAt | Timestamp de creación del documento |
| customerReceived | Indicador de recepción por el cliente (opcional) |
| customerReceivedAt | Fecha y hora en que el cliente recibió el documento (opcional) |
| customerResponse | Respuesta completa en formato XML del comprador (opcional) |
| dgiiResponse | Array con las respuestas recibidas de la DGII |
| documentType | Tipo de documento (ej: "Factura de Crédito Fiscal Electrónico") |
| fileName | Nombre del archivo XML generado |
| internalTrackId | ID de seguimiento interno |
| invoiceTotal | Monto total de la factura |
| ncf | Número de Comprobante Fiscal |
| qr_url | URL del código QR para consulta |
| secretId | ID secreto asociado al documento |
| securityCode | Código de seguridad para la representación impresa |
| signedXml | Ruta al documento XML firmado |
| summarySignedXml | Ruta al resumen XML firmado (solo para e-CF tipo 32) |
| status | Estado del documento |
| updateAt | Timestamp de la última actualización |
| customerId | ID del cliente (RNC) |
Ventajas de la consulta en batch
- Optimización de rendimiento: Reduce significativamente el número de llamadas HTTP necesarias.
- Eficiencia de recursos: Menor consumo de ancho de banda y mejor gestión de rate limits.
- Sincronización masiva: Ideal para sincronizar estados de múltiples documentos de forma periódica.
- Mejor experiencia de usuario: Respuestas más rápidas al consultar múltiples documentos simultáneamente.
Recomendaciones de uso
- Agrupación inteligente: Agrupa documentos por período o proceso para optimizar las consultas.
- Límite recomendado: Aunque el máximo es 100, considera usar grupos de 50 documentos para mejor rendimiento.
- Consultas programadas: Implementa consultas batch programadas para actualizar estados de forma eficiente.
- Manejo de errores: Procesa individualmente los documentos que no fueron encontrados (found = false).
- Cache local: Almacena localmente los resultados para evitar consultas repetidas innecesarias.
Estados de los documentos
Los documentos enviados a la plataforma pueden tener los siguientes estados:
| Estado | Descripción |
|---|---|
| RECIBIDO | El documento ha sido recibido pero aún no ha sido procesado |
| PROCESANDO | El documento está siendo procesado y validado |
| ACEPTADO | El documento ha sido validado y aceptado correctamente |
| RECHAZADO | El documento ha sido rechazado por errores en su formato o contenido |
| ERROR | Ha ocurrido un error durante el procesamiento del documento |
Flujo de procesamiento asíncrono
Es importante entender que MSeller ECF utiliza un procesamiento asíncrono para optimizar el rendimiento y manejar grandes volúmenes de documentos. El proceso completo incluye:
- Recepción del documento JSON - MSeller recibe el documento
- Transformación a XML - Conversión automática al formato requerido por la DGII
- Aplicación de firma electrónica - Utilizando tu certificado digital
- Almacenamiento del documento XML - Guardado seguro de la versión firmada
- Respuesta inmediata - Devolución de códigos de seguridad y enlace QR
- Procesamiento en cola - El documento se coloca en cola para envío a la DGII
- Actualización de estado - El estado del documento se actualiza tras la respuesta de la DGII
IMPORTANTE: Debido a este proceso asíncrono, debes esperar unos segundos antes de consultar el estado final del documento para verificar si fue aceptado o rechazado por la DGII.
Manejo de errores
Errores comunes en el envío
| Código HTTP | Descripción | Solución |
|---|---|---|
| 400 | JSON mal formateado | Verifica que el JSON cumpla con la estructura definida |
| 401 | Error de autenticación | Verifica tu token de acceso |
| 403 | API Key inválida | Verifica tu API Key |
| 429 | Límite de solicitudes excedido | Reduce la frecuencia de solicitudes según tu plan |
| 500 | Error del servidor | Contacta al soporte técnico |
Buenas prácticas
- Validación previa: Valida los documentos JSON antes de enviarlos para evitar rechazos.
- Manejo de errores: Implementa un sistema robusto para manejar los diferentes tipos de errores.
- Reintentos: Implementa una estrategia de reintentos para casos de fallos temporales.
- Almacenamiento local: Mantén una copia local de los documentos enviados para referencia futura.
- Consulta periódica: Implementa consultas periódicas para actualizar el estado de los documentos enviados.
- Tiempo de espera: Programa consultas con un tiempo de espera adecuado entre el envío del documento y la consulta de su estado.
- Gestión de códigos de seguridad: Almacena y gestiona correctamente los códigos de seguridad y URLs de QR para la representación impresa de las facturas.
Recursos y herramientas para la adaptación de documentos
Para asegurar que tu integración con MSeller ECF funcione correctamente, es fundamental comprender la estructura y los requisitos específicos de los documentos electrónicos. La Dirección General de Impuestos Internos (DGII) ofrece recursos oficiales que te ayudarán en este proceso.
Documentación y archivos XSD oficiales
La DGII proporciona documentación detallada y archivos XSD (XML Schema Definition) que contienen la definición completa de la estructura de los documentos electrónicos. Estos recursos son esenciales para comprender los campos requeridos y las validaciones que se aplican a cada tipo de documento.
Formatos XML
| Archivo | Descripción | Última modificación | Tamaño |
|---|---|---|---|
| Formato Comprobante Fiscal Electrónico (e-CF) V 1.0 | Especificaciones para la elaboración de un e-CF | 18/09/2024 | 2,1MB |
| Formato Acuse de Recibo v1.0 | Especificaciones para recibir y dar constancia de recibo de un e-CF | 23/07/2020 | 193,2KB |
| Formato Aprobación Comercial V1.0 | Especificaciones para recibir y dar respuesta de la conformidad de un e-CF | 10/01/2020 | 212,2KB |
| Formato Anulación de e-CF V1.0 | Especificaciones para la Anulación de un e-CF | 20/06/2022 | 494,4KB |
| Formato Resumen Factura Consumo Electrónico v1.0 | Especificaciones para la remisión del resumen de factura de consumo electrónica menor a DOP250 mil | 19/08/2020 | 275KB |
Documentación Técnica (XSD)
| Archivo | Descripción | Última modificación | Tamaño |
|---|---|---|---|
| e-CF 31 v.1.0 | Factura de Crédito Fiscal Electrónica | 13/02/2025 | 120,1KB |
| e-CF 32 v.1.0 | Factura de Consumo Electrónica | 13/02/2025 | 120,1KB |
| e-CF 33 v.1.0 | Nota de Débito Electrónica | 13/02/2025 | 121,5KB |
| e-CF 34 v.1.0 | Nota de Crédito Electrónica | 13/02/2025 | 119,1KB |
| e-CF 41 v.1.0 | Comprobante de Compras Electrónico | 13/02/2025 | 108,5KB |
| e-CF 43 v.1.0 | Comprobante de Gastos Menores Electrónico | 13/02/2025 | 93,8KB |
| e-CF 44 v.1.0 | Comprobante de Regímenes Especiales Electrónico | 13/02/2025 | 111,6KB |
| e-CF 45 v.1.0 | Comprobante Gubernamental Electrónico | 13/02/2025 | 118,9KB |
| e-CF 46 v.1.0 | Comprobante para Pagos al Exterior Electrónico | 13/02/2025 | 113,2KB |
| e-CF 47 v.1.0 | Comprobante de Ingresos Electrónico | 13/02/2025 | 98,9KB |
| RFCE 32 v1.0 | Representación Fiscal de Comprobante Electrónico | 20/06/2023 | 15KB |
| ARECF v1.0 | Acuse de Recibo de e-CF | 20/06/2023 | 2,8KB |
| ANECF v.1.0 | Acuse Negativo de Recibo de e-CF | 20/06/2023 | 5KB |
| ACECF v.1.0 | Acuse Comercial de e-CF | 21/12/2022 | 3,5KB |
| Semilla v.1.0 | Definición de semilla para firma | 12/11/2020 | 487B |
Nota: Los archivos XSD se pueden abrir con Visual Studio en Windows para visualizar la estructura completa de los esquemas XML.
Herramientas para validación y depuración
Para facilitar la adaptación de tus sistemas a los requisitos de documentos electrónicos, puedes utilizar las siguientes herramientas:
Convertidores y validadores online
-
JSON a XML: Para comprobar la conversión correcta entre el formato JSON que utilizas en las solicitudes y el formato XML que se utiliza internamente.
-
Validadores XSD: Para verificar que tus documentos XML cumplen con los esquemas definidos por la DGII.
Simuladores de entorno
MSeller ECF ofrece un ambiente de prueba (TesteCF) que te permite validar tus documentos antes de usarlos en producción. Este entorno simula completamente el proceso de envío y recepción de documentos electrónicos.
Para usar el simulador:
- Envía tus documentos al endpoint
TesteCFcomo se describe en la sección de Envío de documentos - Utiliza secuencias de prueba para los eNCF (como se indica en la nota sobre secuencias aleatorias)
- Verifica las respuestas y corrija cualquier error antes de pasar a producción
Soporte y asesoría
Si encuentras dificultades durante la implementación o adaptación de tus documentos, puedes recurrir a:
- Soporte técnico de MSeller: A través del portal de soporte
- Documentación extendida: Disponible en el Centro de Ayuda de MSeller
- Asesoría especializada: MSeller ofrece servicios de consultoría para casos complejos de integración