MSeller LogoECF MSeller
🔍
Integración

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

CampoDescripción
fileNameNombre del archivo XML generado
updateAtTimestamp de la última actualización
customerReceivedAtFecha y hora en que el cliente recibió el documento
documentTypeTipo de documento (ej: "Factura de Crédito Fiscal Electrónico")
customerResponseRespuesta completa en formato XML (transformada a JSON para la API)
statusEstado del documento ("Aceptado", "Rechazado", etc.)
dgiiResponseRespuestas recibidas de la DGII
createdAtTimestamp de creación del documento
securityCodeCódigo de seguridad para la representación impresa
signedXmlRuta al documento XML firmado
ncfNúmero de Comprobante Fiscal
internalTrackIdID de seguimiento interno
customerReceivedIndicador de recepción por el cliente
qr_urlURL del código QR para consulta
customerIdID 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/batch

Lí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/json

Cuerpo 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

CampoDescripción
totalCantidad total de documentos consultados
resultsArray con los resultados de cada documento consultado

Campos de cada resultado

CampoDescripción
ecfNúmero de comprobante electrónico consultado
statusEstado actual del documento ("Aceptado", "Rechazado", "Aceptado Condicional", etc.)
foundIndica si el documento fue encontrado en el sistema (true/false)
dataObjeto con los detalles completos del documento (solo si found = true). Ver tabla de campos a continuación

Campos del objeto data

CampoDescripción
buyerRncRNC del comprador
createdAtTimestamp de creación del documento
customerReceivedIndicador de recepción por el cliente (opcional)
customerReceivedAtFecha y hora en que el cliente recibió el documento (opcional)
customerResponseRespuesta completa en formato XML del comprador (opcional)
dgiiResponseArray con las respuestas recibidas de la DGII
documentTypeTipo de documento (ej: "Factura de Crédito Fiscal Electrónico")
fileNameNombre del archivo XML generado
internalTrackIdID de seguimiento interno
invoiceTotalMonto total de la factura
ncfNúmero de Comprobante Fiscal
qr_urlURL del código QR para consulta
secretIdID secreto asociado al documento
securityCodeCódigo de seguridad para la representación impresa
signedXmlRuta al documento XML firmado
summarySignedXmlRuta al resumen XML firmado (solo para e-CF tipo 32)
statusEstado del documento
updateAtTimestamp de la última actualización
customerIdID del cliente (RNC)

Ventajas de la consulta en batch

  1. Optimización de rendimiento: Reduce significativamente el número de llamadas HTTP necesarias.
  2. Eficiencia de recursos: Menor consumo de ancho de banda y mejor gestión de rate limits.
  3. Sincronización masiva: Ideal para sincronizar estados de múltiples documentos de forma periódica.
  4. 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.