<!-- source_url: https://docs.mynexusapi.com/v1/guias/consulta-xml | last_updated: 2026-11-19 -->

# Descargar XML

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](/v1/guias/glosario), en
cambio, es solo su representación impresa en PDF. Con este endpoint puedes
descargar el XML a partir de la [clave de acceso](/v1/guias/glosario) 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](/v1/guias/consulta-operacion) 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](/v1/guias/sandbox);
  cómo viaja la API Key se explica en [Autenticación](/v1/guias/autenticacion).
- [ ] 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](/v1/guias/autenticacion#registra-tu-ip).
- [ ] La `identificacion` del contribuyente emisor, que obtienes con
  [`GET /v1/contexto`](/v1/guias/consulta-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](/v1/guias/consulta-operacion), el webhook o el
  [listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente).

## Parámetros

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `identificacion` (ruta) | string | Sí | Identificación del contribuyente emisor tal como la devuelve [`GET /v1/contexto`](/v1/guias/consulta-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

> [!IMPORTANT]
> 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.

```bash
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
```

```csharp
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)");
```

```python
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")
```

```javascript
// 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
<?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;
}
```

```java
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)");
}
```

```csharp-sdk
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)");
```

```python-sdk
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")
```

```javascript-sdk
// 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-sdk
<?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;
```

```java-sdk
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");
```

```bash-cli
# 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:

```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](/v1/guias/consulta-operacion) 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](/v1/guias/autenticacion). |
| 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`](/v1/guias/consulta-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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Descargar PDF](/v1/guias/consulta-ride): obtén el RIDE para entregarlo a tu cliente.
- [Listado de operaciones](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente): encuentra la clave de acceso de comprobantes anteriores.
