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

# Descargar PDF

Descarga el RIDE, el PDF de un comprobante emitido, a partir de su clave de acceso.

El [RIDE](/v1/guias/glosario) 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](/v1/guias/glosario) 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](/v1/guias/consulta-operacion) 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`](/v1/guias/consulta-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](/v1/guias/consulta-xml) 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](/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 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.

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

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

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

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

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

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

```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_ride("0123456789001", "0710202601012345678900110010010000001231234567811")
with open("ride.pdf", "wb") as destino:
    destino.write(archivo.contenido)
print("RIDE guardado en ride.pdf", len(archivo.contenido), "bytes")
```

```javascript-sdk
// 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-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->descargarRide('0123456789001', '0710202601012345678900110010010000001231234567811');
file_put_contents('ride.pdf', $archivo->contenido);
echo 'RIDE guardado en ride.pdf (' . strlen($archivo->contenido) . ' bytes)' . 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.descargarRide("0123456789001", "0710202601012345678900110010010000001231234567811");
Files.write(Path.of("ride.pdf"), archivo.contenido());
System.out.println("RIDE guardado en ride.pdf (" + archivo.contenido().length + " bytes)");
```

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

```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](/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 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`](/v1/guias/consulta-contexto)) y no tiene RIDE. | Si el contribuyente es de marca blanca, no reintentes: descarga el [XML](/v1/guias/consulta-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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Descargar XML](/v1/guias/consulta-xml): obtén el XML autorizado, que es el documento con validez legal.
- [Perfil del emisor](/v1/guias/perfil-emisor): cambia el logo y los datos de contacto que aparecen en el RIDE.
