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
identificaciondel contribuyente emisor, que obtienes conGET /v1/contexto. Es la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos. - La
claveAccesode 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#
- Descargar PDF: obtén el RIDE para entregarlo a tu cliente.
- Listado de operaciones: encuentra la clave de acceso de comprobantes anteriores.