MSeller LogoECF MSeller
🔍
Integración

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-ecf

Donde {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/json

Cuerpo 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: 4 que 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: 32 para 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

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 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/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.

Estados de los documentos

Los documentos enviados a la plataforma pueden tener los siguientes estados:

EstadoDescripción
RECIBIDOEl documento ha sido recibido pero aún no ha sido procesado
PROCESANDOEl documento está siendo procesado y validado
ACEPTADOEl documento ha sido validado y aceptado correctamente
RECHAZADOEl documento ha sido rechazado por errores en su formato o contenido
ERRORHa 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:

  1. Recepción del documento JSON - MSeller recibe el documento
  2. Transformación a XML - Conversión automática al formato requerido por la DGII
  3. Aplicación de firma electrónica - Utilizando tu certificado digital
  4. Almacenamiento del documento XML - Guardado seguro de la versión firmada
  5. Respuesta inmediata - Devolución de códigos de seguridad y enlace QR
  6. Procesamiento en cola - El documento se coloca en cola para envío a la DGII
  7. 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 HTTPDescripciónSolución
400JSON mal formateadoVerifica que el JSON cumpla con la estructura definida
401Error de autenticaciónVerifica tu token de acceso
403API Key inválidaVerifica tu API Key
429Límite de solicitudes excedidoReduce la frecuencia de solicitudes según tu plan
500Error del servidorContacta al soporte técnico

Buenas prácticas

  1. Validación previa: Valida los documentos JSON antes de enviarlos para evitar rechazos.
  2. Manejo de errores: Implementa un sistema robusto para manejar los diferentes tipos de errores.
  3. Reintentos: Implementa una estrategia de reintentos para casos de fallos temporales.
  4. Almacenamiento local: Mantén una copia local de los documentos enviados para referencia futura.
  5. Consulta periódica: Implementa consultas periódicas para actualizar el estado de los documentos enviados.
  6. Tiempo de espera: Programa consultas con un tiempo de espera adecuado entre el envío del documento y la consulta de su estado.
  7. 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

ArchivoDescripciónÚltima modificaciónTamaño
Formato Comprobante Fiscal Electrónico (e-CF) V 1.0Especificaciones para la elaboración de un e-CF18/09/20242,1MB
Formato Acuse de Recibo v1.0Especificaciones para recibir y dar constancia de recibo de un e-CF23/07/2020193,2KB
Formato Aprobación Comercial V1.0Especificaciones para recibir y dar respuesta de la conformidad de un e-CF10/01/2020212,2KB
Formato Anulación de e-CF V1.0Especificaciones para la Anulación de un e-CF20/06/2022494,4KB
Formato Resumen Factura Consumo Electrónico v1.0Especificaciones para la remisión del resumen de factura de consumo electrónica menor a DOP250 mil19/08/2020275KB

Documentación Técnica (XSD)

ArchivoDescripciónÚltima modificaciónTamaño
e-CF 31 v.1.0Factura de Crédito Fiscal Electrónica13/02/2025120,1KB
e-CF 32 v.1.0Factura de Consumo Electrónica13/02/2025120,1KB
e-CF 33 v.1.0Nota de Débito Electrónica13/02/2025121,5KB
e-CF 34 v.1.0Nota de Crédito Electrónica13/02/2025119,1KB
e-CF 41 v.1.0Comprobante de Compras Electrónico13/02/2025108,5KB
e-CF 43 v.1.0Comprobante de Gastos Menores Electrónico13/02/202593,8KB
e-CF 44 v.1.0Comprobante de Regímenes Especiales Electrónico13/02/2025111,6KB
e-CF 45 v.1.0Comprobante Gubernamental Electrónico13/02/2025118,9KB
e-CF 46 v.1.0Comprobante para Pagos al Exterior Electrónico13/02/2025113,2KB
e-CF 47 v.1.0Comprobante de Ingresos Electrónico13/02/202598,9KB
RFCE 32 v1.0Representación Fiscal de Comprobante Electrónico20/06/202315KB
ARECF v1.0Acuse de Recibo de e-CF20/06/20232,8KB
ANECF v.1.0Acuse Negativo de Recibo de e-CF20/06/20235KB
ACECF v.1.0Acuse Comercial de e-CF21/12/20223,5KB
Semilla v.1.0Definición de semilla para firma12/11/2020487B

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

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:

  1. Envía tus documentos al endpoint TesteCF como se describe en la sección de Envío de documentos
  2. Utiliza secuencias de prueba para los eNCF (como se indica en la nota sobre secuencias aleatorias)
  3. 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