Consulta de Documentos
Cómo consultar el estado de documentos electrónicos enviados a través de MSeller ECF
Consulta de Documentos
Esta sección explica cómo consultar el estado de documentos electrónicos enviados previamente a través de la API de MSeller ECF.
Consulta individual
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 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.
Envío de Documentos
Cómo enviar documentos electrónicos en MSeller ECF
Certificación DGII Facturación Electrónica — Guía Paso a Paso
Guía completa paso a paso para certificar tu empresa ante la DGII y emitir Comprobantes Fiscales Electrónicos (e-CF) en República Dominicana usando MSeller ECF. Incluye video tutorial, capturas de pantalla y asistente interactivo.