En esta página
Descargar PDF GET
Descarga el RIDE, el PDF de un comprobante emitido, a partir de su clave de acceso.
El RIDE es la representación impresa del comprobante electrónico, es decir, el PDF que entregas o envías a tu cliente. Con este endpoint puedes descargarlo a partir de la clave de acceso del comprobante, para guardarlo en tu sistema, mostrarlo o adjuntarlo donde lo necesites.
Al terminar esta página sabrás cuándo está disponible el RIDE, cómo descargarlo sin confundir un error con un PDF y qué hacer si todavía no está listo.
GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride
X-Api-Key: <tu API Key>
Cuándo usarlo#
Te recomendamos descargar el RIDE cuando el estado de la operación sea
autorizado, algo que sabes por el
seguimiento o por el webhook
document.authorized. Si vas a mostrarlo o reenviarlo varias veces, guárdalo
en tu sistema en lugar de pedirlo cada vez.
Puedes descargar el RIDE en cuanto la operación tiene claveAcceso, aunque
su estado todavía sea recibido. Mientras la operación no tiene clave de
acceso, la API responde 404 con el codEstado 3013 (no_encontrado). Te entregamos el PDF
aunque el comprobante todavía no esté autorizado, pero solo el RIDE de un
comprobante autorizado tiene validez fiscal. Si lo pides antes y recibes un
404, espera el resultado y vuelve a pedirlo.
Un contribuyente de marca blanca, con marcaBlanca en true en
GET /v1/contexto, no tiene RIDE: la API
responde siempre 404 con el codEstado 3013 (no_encontrado) para sus comprobantes, aunque estén
autorizados. Para esos comprobantes descarga el
XML autorizado y genera tu propia representación
impresa si la necesitas. Revisa marcaBlanca antes de pedir el RIDE para no
reintentar un 404 que no va a cambiar.
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 entonces guarda el
cuerpo; los ejemplos de código lo guardan como ride.pdf y el CLI como
{claveAcceso}.pdf. Si la respuesta es un error, el cuerpo es JSON, así que
los ejemplos lo imprimen en lugar de guardarlo y no terminas con un PDF que no
abre. Reemplaza la clave de ejemplo por la de tu comprobante.
CODIGO=$(curl -s -o ride.pdf -w "%{http_code}" \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride" \
-H "X-Api-Key: $ECUAFACT_API_KEY")
if [ "$CODIGO" = "200" ]; then echo "200 RIDE guardado en ride.pdf"; else echo "$CODIGO $(cat ride.pdf)"; rm ride.pdf; 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/ride");
if ((int)respuesta.StatusCode == 200)
{
byte[] pdf = await respuesta.Content.ReadAsByteArrayAsync();
await File.WriteAllBytesAsync("ride.pdf", pdf);
Console.WriteLine($"200 RIDE guardado en ride.pdf ({pdf.Length} bytes)");
}
else
{
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
}
import os
import requests
r = requests.get(
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride",
headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
timeout=60,
)
if r.status_code == 200:
with open("ride.pdf", "wb") as archivo:
archivo.write(r.content)
print(200, "RIDE guardado en ride.pdf", len(r.content), "bytes")
else:
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como ride.mjs y ejecuta: node ride.mjs
import { writeFile } from 'node:fs/promises';
const res = await fetch(
'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride',
{ headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY } });
if (res.status === 200) {
const pdf = Buffer.from(await res.arrayBuffer());
await writeFile('ride.pdf', pdf);
console.log(200, `RIDE guardado en ride.pdf (${pdf.length} bytes)`);
} else {
console.log(res.status, await res.text());
}
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/comprobantes/0710202601012345678900110010010000001231234567811/ride');
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) {
file_put_contents('ride.pdf', $cuerpo);
echo '200 RIDE guardado en ride.pdf (' . strlen($cuerpo) . ' bytes)' . PHP_EOL;
} else {
echo $estado . ' ' . $cuerpo . 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/ride"))
.header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
.GET()
.build();
HttpResponse<byte[]> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofByteArray());
if (respuesta.statusCode() == 200) {
Files.write(Path.of("ride.pdf"), respuesta.body());
System.out.println("200 RIDE guardado en ride.pdf (" + respuesta.body().length + " bytes)");
} else {
System.out.println(respuesta.statusCode() + " " + new String(respuesta.body(), StandardCharsets.UTF_8));
}
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 ride = await client.DescargarRideAsync("0123456789001", "0710202601012345678900110010010000001231234567811");
await File.WriteAllBytesAsync("ride.pdf", ride.Contenido);
Console.WriteLine($"RIDE guardado en ride.pdf ({ride.Contenido.Length} bytes, {ride.ContentType})");
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_ride("0123456789001", "0710202601012345678900110010010000001231234567811")
with open("ride.pdf", "wb") as destino:
destino.write(archivo.contenido)
print("RIDE guardado en ride.pdf", len(archivo.contenido), "bytes")
// Node.js 18 o superior. Guarda como ride-sdk.mjs y ejecuta: node ride-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.descargarRide('0123456789001', '0710202601012345678900110010010000001231234567811');
await writeFile('ride.pdf', archivo.contenido);
console.log(`RIDE guardado en ride.pdf (${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->descargarRide('0123456789001', '0710202601012345678900110010010000001231234567811');
file_put_contents('ride.pdf', $archivo->contenido);
echo 'RIDE guardado en ride.pdf (' . strlen($archivo->contenido) . ' bytes)' . 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.descargarRide("0123456789001", "0710202601012345678900110010010000001231234567811");
Files.write(Path.of("ride.pdf"), archivo.contenido());
System.out.println("RIDE guardado en ride.pdf (" + archivo.contenido().length + " bytes)");
# Resultado esperado: el RIDE descargado como 0710202601012345678900110010010000001231234567811.pdf en la carpeta actual.
ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride --entorno sandbox
Sabrás que funcionó si el archivo que guardó el ejemplo abre en un lector de PDF y muestra el comprobante.
Respuesta#
La API responde 200 OK con el PDF como cuerpo binario:
| Elemento | Valor |
|---|---|
| Estado HTTP | 200 |
Content-Type |
application/pdf |
| Cuerpo | Bytes del PDF. No es JSON ni texto, así que guárdalo como archivo binario y no lo imprimas en consola ni lo conviertas a texto. |
La respuesta no trae un nombre de archivo. Te sugerimos guardarlo como
{claveAcceso}.pdf para encontrarlo después.
Si la respuesta no es 200, el cuerpo es un error JSON:
{
"estado": "rechazado",
"codEstado": 3013,
"msgError": "Recurso no encontrado.",
"errores": []
}
Estados de este endpoint#
codEstado |
HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | El cuerpo trae el PDF del RIDE. | Guárdalo como archivo binario. |
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 un comprobante emitido con esa clave para ese contribuyente y ambiente, el PDF todavía no está disponible o el contribuyente es de marca blanca (marcaBlanca en true en /v1/contexto) y no tiene RIDE. |
Si el contribuyente es de marca blanca, no reintentes: descarga el XML. Si acabas de emitir, espera a que el estado de la operación sea autorizado y reintenta. Si persiste, revisa la clave y el ambiente, de pruebas o de producción. |
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 genera el PDF 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 genera el PDF. | 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 XML: obtén el XML autorizado, que es el documento con validez legal.
- Perfil del emisor: cambia el logo y los datos de contacto que aparecen en el RIDE.