Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Descargar XML GET

Descarga el XML autorizado de un comprobante emitido a partir de su clave de acceso.

El XML es el comprobante electrónico en sí: el documento que el SRI valida y el que debes conservar en tu archivo contable. El RIDE, en cambio, es solo su representación impresa en PDF. Con este endpoint puedes descargar el XML a partir de la clave de acceso del comprobante.

Al terminar esta página sabrás cuándo está disponible el XML y cómo descargarlo sin volver a emitir el comprobante.

GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml
X-Api-Key: <tu API Key>

Cuándo usarlo#

Te recomendamos descargar el XML cuando el estado de la operación sea autorizado, algo que sabes por el seguimiento o por el webhook document.authorized, y guardarlo junto con la clave de acceso.

La API responde 200 cuando el comprobante está autorizado y su XML está disponible. Mientras falta la autorización o el archivo, responde HTTP 404 con el codEstado 3013 (no_encontrado). Espera y repite esta consulta; no vuelvas a emitir. Si persiste, revisa la clave, el contribuyente y el ambiente.

Antes de empezar#

  • Una API Key de pruebas guardada en la variable de entorno ECUAFACT_API_KEY. Si todavía no tienes una, crea un sandbox; cómo viaja la API Key se explica en Autenticación.
  • Solo en producción, la IP pública de salida de tu servidor registrada para tu integración. El sandbox acepta cualquier IP. Si no sabes cómo hacerlo, sigue Registra tu IP.
  • La identificacion del contribuyente emisor, que obtienes con GET /v1/contexto. Es la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos.
  • La claveAcceso de 49 dígitos del comprobante, que te dan el seguimiento, el webhook o el listado de operaciones.

Parámetros#

Nombre Tipo Obligatorio Descripción
identificacion (ruta) string Sí Identificación del contribuyente emisor tal como la devuelve GET /v1/contexto en identificacion; es la identificación completa del contribuyente, la misma de infoTributaria.ruc.
claveAcceso (ruta) string Sí Clave de acceso de 49 dígitos del comprobante, tal como la devuelven el seguimiento o el webhook. Debe tener su dígito verificador correcto.
X-Api-Key (cabecera) string Sí Tu API Key.

Ejemplo#

Importante

Ambiente de pruebas: sin validez fiscal.

Cada ejemplo comprueba que la respuesta sea 200 y solo guarda el XML; los ejemplos de código lo guardan como comprobante.xml y el CLI como {claveAcceso}.xml. Si la respuesta es un error, los ejemplos imprimen el JSON del error en lugar de guardarlo. Reemplaza la clave de ejemplo por la de tu comprobante.

CODIGO=$(curl -s -o comprobante.xml -w "%{http_code}" \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml" \
  -H "X-Api-Key: $ECUAFACT_API_KEY")
if [ "$CODIGO" != "200" ]; then echo "$CODIGO $(cat comprobante.xml)"; rm comprobante.xml
else echo "200 XML guardado en comprobante.xml"; fi
using System.Net.Http;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using HttpResponseMessage respuesta = await http.GetAsync(
    "/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml");
if ((int)respuesta.StatusCode != 200)
{
    Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
    return;
}
byte[] xml = await respuesta.Content.ReadAsByteArrayAsync();
await File.WriteAllBytesAsync("comprobante.xml", xml);
Console.WriteLine($"200 XML guardado en comprobante.xml ({xml.Length} bytes)");
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=60,
)
if r.status_code != 200:
    print(r.status_code, r.text)
else:
    with open("comprobante.xml", "wb") as archivo:
        archivo.write(r.content)
    print(200, "XML guardado en comprobante.xml", len(r.content), "bytes")
// Node.js 18 o superior. Guarda como xml.mjs y ejecuta: node xml.mjs
import { writeFile } from 'node:fs/promises';

const res = await fetch(
  'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml',
  { headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } });
if (res.status !== 200) {
  console.log(res.status, await res.text());
} else {
  const xml = Buffer.from(await res.arrayBuffer());
  await writeFile('comprobante.xml', xml);
  console.log(200, `XML guardado en comprobante.xml (${xml.length} bytes)`);
}
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($estado !== 200) {
    echo $estado . ' ' . $cuerpo . PHP_EOL;
} else {
    file_put_contents('comprobante.xml', $cuerpo);
    echo '200 XML guardado en comprobante.xml (' . strlen($cuerpo) . ' bytes)' . PHP_EOL;
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/xml"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
HttpResponse<byte[]> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray());
if (respuesta.statusCode() != 200) {
    System.out.println(respuesta.statusCode() + " " + new String(respuesta.body(), StandardCharsets.UTF_8));
} else {
    Files.write(Path.of("comprobante.xml"), respuesta.body());
    System.out.println("200 XML guardado en comprobante.xml (" + respuesta.body().length + " bytes)");
}
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

using var client = EcuafactClient.Create(new EcuafactClientOptions
{
    BaseAddress = new Uri("https://api-sandbox.mynexusapi.com/"),
    ApiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!
});

// Si la API responde un error, el SDK lanza EcuafactApiException.
ArchivoComprobante xml = await client.DescargarXmlAsync("0123456789001", "0710202601012345678900110010010000001231234567811");
await File.WriteAllBytesAsync("comprobante.xml", xml.Contenido);
Console.WriteLine($"XML guardado en comprobante.xml ({xml.Contenido.Length} bytes)");
import os
from ecuafact import EcuafactClient, EcuafactClientOptions

client = EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
))

# Si la API responde un error, el SDK lanza EcuafactApiException.
archivo = client.descargar_xml("0123456789001", "0710202601012345678900110010010000001231234567811")
with open("comprobante.xml", "wb") as destino:
    destino.write(archivo.contenido)
print("XML guardado en comprobante.xml", len(archivo.contenido), "bytes")
// Node.js 18 o superior. Guarda como xml-sdk.mjs y ejecuta: node xml-sdk.mjs
import { writeFile } from 'node:fs/promises';
import { EcuafactClient } from '@ecuafact/sdk';

const client = new EcuafactClient({
  baseAddress: 'https://api-sandbox.mynexusapi.com/',
  apiKey: process.env.ECUAFACT_API_KEY
});

// Si la API responde un error, el SDK lanza EcuafactApiException.
const archivo = await client.descargarXml('0123456789001', '0710202601012345678900110010010000001231234567811');
await writeFile('comprobante.xml', archivo.contenido);
console.log(`XML guardado en comprobante.xml (${archivo.contenido.length} bytes)`);
<?php
require 'vendor/autoload.php';

use Ecuafact\Sdk\EcuafactClient;
use Ecuafact\Sdk\EcuafactClientOptions;

$client = new EcuafactClient(new EcuafactClientOptions(
    baseAddress: 'https://api-sandbox.mynexusapi.com/',
    apiKey: getenv('ECUAFACT_API_KEY'),
));

// Si la API responde un error, el SDK lanza EcuafactApiException.
$archivo = $client->descargarXml('0123456789001', '0710202601012345678900110010010000001231234567811');
file_put_contents('comprobante.xml', $archivo->contenido);
echo 'XML guardado en comprobante.xml' . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.ArchivoComprobante;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
EcuafactClient client = new EcuafactClient(
    EcuafactClientOptions.create("https://api-sandbox.mynexusapi.com/", System.getenv("ECUAFACT_API_KEY")));

// Si la API responde un error, el SDK lanza EcuafactApiException.
ArchivoComprobante archivo = client.descargarXml("0123456789001", "0710202601012345678900110010010000001231234567811");
Files.write(Path.of("comprobante.xml"), archivo.contenido());
System.out.println("XML guardado en comprobante.xml");
# Resultado esperado: el XML descargado como 0710202601012345678900110010010000001231234567811.xml.
# Si el XML aun no esta disponible, la API devuelve HTTP 404; reintenta la descarga mas tarde.
ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo xml --entorno sandbox

Sabrás que funcionó si el archivo que guardó el ejemplo se abre como XML y contiene la clave de acceso que pediste.

Respuesta#

La API responde 200 OK con el XML como cuerpo:

Elemento Valor
Estado HTTP 200
Content-Type application/xml
Content-Disposition attachment, con el nombre de archivo {claveAcceso}.xml.
Cuerpo El XML del comprobante. Guárdalo tal cual, sin reformatearlo ni cambiar su codificación, porque cualquier cambio invalida la firma electrónica.

Si la respuesta no es 200, el cuerpo es un error JSON:

{
  "estado": "rechazado",
  "codEstado": 3013,
  "msgError": "Recurso no encontrado.",
  "errores": []
}

XML todavía no disponible#

El XML se entrega únicamente cuando el comprobante está autorizado. Mientras el archivo autorizado no esté disponible, la API responde 404 con el codEstado 3013 (no_encontrado). Cuando eso ocurra, consulta el seguimiento de la operación y vuelve a pedir el XML cuando el estado sea autorizado.

Estados de este endpoint#

codEstado HTTP Cuándo ocurre Qué hacer
- 200 El cuerpo trae el XML autorizado. Guarda el archivo sin modificarlo.
3003 (solicitud_invalida) 400 La claveAcceso no tiene 49 dígitos, tiene un dígito verificador incorrecto o es solo ceros. El campo errores trae el detalle. Copia la clave del seguimiento o del webhook.
3009 (credenciales_invalidas) 401 Falta la API Key o es inválida. Revisa la API Key, como se explica en Autenticación.
3010 (ip_no_autorizada) 403 En producción, la IP de la que sale la llamada no está registrada o no se pudo identificar. El sandbox no lo devuelve. Registra tu IP en Cuenta > IP permitidas o llama sin proxies que oculten el origen.
3011 (acceso_denegado) 403 El contribuyente no está habilitado para tu API Key en este ambiente, o tu API Key está limitada y no incluye el scope comprobantes:leer. Usa la identificacion que devuelve /v1/contexto.
3013 (no_encontrado) 404 No existe el comprobante para ese contribuyente y ambiente, o falta su autorización o el archivo. Consulta la operación y reintenta la descarga. No vuelvas a emitir. Si persiste, revisa la clave y el ambiente.
5005 (limite_solicitudes) 429 Superaste el límite de solicitudes. Espera lo que indica Retry-After y reintenta.
5003 (error_dependencia) 502 Nuestro servicio que entrega el XML devolvió un error. Reintenta en unos minutos con una espera creciente.
5001 (error_interno) 500 Ocurrió un error inesperado, por ejemplo una falla de comunicación con nuestro servicio que entrega el XML. Reintenta en unos minutos y, si persiste, contacta a soporte con el valor de la cabecera X-Correlation-Id.

El catálogo completo de codEstado está en Errores.

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.