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

# Decodificar clave de acceso

Comprueba que una clave de acceso esté bien formada y devuelve sus partes: fecha, tipo de comprobante, RUC, ambiente, serie y secuencial.

La [clave de acceso](/v1/guias/glosario) es el identificador único de 49
dígitos de un comprobante electrónico. Cada grupo de dígitos tiene un
significado fijo, así que de la clave puedes leer la fecha de emisión, el
tipo de comprobante, el RUC del emisor, el ambiente y el número del
comprobante. Este endpoint revisa su largo y su dígito verificador y te
devuelve esas partes ya separadas.

Al terminar esta página sabrás cómo está formada una clave de acceso, cómo se
calcula su dígito verificador y cómo usar sus partes, por ejemplo, para
referenciar el documento que modifica una nota de crédito.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas,
> y la decodificación se comporta igual en ambos ambientes.

## Endpoint

```
GET /v1/consultas/comprobantes/decodificar/{claveAcceso}
X-Api-Key: <tu API Key>
```

| Cabecera | Obligatoria | Descripción |
|---|---|---|
| `X-Api-Key` | Sí | Tu [API Key](/v1/guias/glosario). |
| `X-Api-Version` | No | Versión del contrato. Si la omites, se usa la vigente. |

La respuesta es un objeto JSON con los campos en el primer nivel. Esta consulta **no
consume cupo** de documentos, pero sí cuenta para el límite de solicitudes por
minuto de tu API Key, que se explica en [Límites](/v1/guias/limites).

> [!NOTE]
> Decodificar **no prueba que el comprobante esté autorizado** ni que exista en
> el [SRI](/v1/guias/glosario), porque solo revisa la estructura y el dígito
> verificador. Para conocer el estado de un comprobante que emitiste, usa el
> [seguimiento](/v1/guias/consulta-operacion).

## Cuándo usarlo

Cuando emites, te asignamos la clave de acceso y la recibes en el seguimiento
o en el webhook. También la encuentras impresa en el RIDE de los comprobantes
que te entregan tus proveedores. Puedes decodificarla en casos como estos:

- **Validar una clave capturada a mano** antes de usarla, por ejemplo la clave
  del comprobante de sustento de una retención (`numAutDocSustento`). Así
  detectas aquí un dígito mal copiado, en lugar de recibir un rechazo del SRI.
- **Obtener los datos del documento modificado** al emitir una nota de crédito o
  de débito. Con `establecimiento`, `puntoEmision` y `secuencial` armas
  `numDocModificado`, por ejemplo `001-001-000000123`, y con `fechaEmision`
  llenas `fechaEmisionDocSustento`, convirtiendo `yyyy-MM-dd` a `dd/MM/yyyy`.
- **Clasificar las claves** que llegan a tu sistema por tipo de comprobante,
  emisor o ambiente, sin hacer otra consulta.

## Estructura de la clave de acceso

La clave tiene 49 dígitos en posiciones fijas. Este es un ejemplo ficticio, con
el dígito verificador correcto: `0710202601012345678900110010010000001231234567811`.

| Posición | Largo | Contenido | Valor del ejemplo | Campo de la respuesta |
|---|---|---|---|---|
| 1-8 | 8 | Fecha de emisión, `ddMMyyyy` | `07102026` (07/10/2026) | `fechaEmision` (`2026-10-07`) |
| 9-10 | 2 | Tipo de comprobante (`tipoDocumento`) | `01` (factura) | `tipo` |
| 11-23 | 13 | RUC del emisor | `0123456789001` | `rucEmisor` |
| 24 | 1 | Ambiente: `1` pruebas, `2` producción | `1` | `ambiente` |
| 25-27 | 3 | Establecimiento (`estab`) | `001` | `establecimiento` |
| 28-30 | 3 | Punto de emisión (`ptoEmi`) | `001` | `puntoEmision` |
| 31-39 | 9 | Secuencial | `000000123` | `secuencial` |
| 40-47 | 8 | Código numérico, que genera quien emite | `12345678` | `codigoNumerico` |
| 48 | 1 | Tipo de emisión: `1` normal | `1` | `tipoEmision` |
| 49 | 1 | Dígito verificador módulo 11 | `1` | `digitoVerificador` |

Los establecimientos, puntos de emisión y secuenciales se explican en el
[Glosario](/v1/guias/glosario).

| Tipo de comprobante (posiciones 9-10) | Documento |
|---|---|
| `01` | Factura |
| `03` | Liquidación de compra |
| `04` | Nota de crédito |
| `05` | Nota de débito |
| `06` | Guía de remisión |
| `07` | Comprobante de retención |

### Dígito verificador módulo 11

El dígito 49 se calcula sobre los primeros 48, siguiendo estos pasos:

1. Recorre los 48 dígitos **de derecha a izquierda** y multiplica cada uno por
   un factor que empieza en 2, sube hasta 7 y vuelve a 2, es decir, 2, 3, 4,
   5, 6, 7, 2, 3 y así sucesivamente.
2. Suma los productos.
3. Calcula `11 - (suma mod 11)`.
4. Si el resultado es 11, el dígito es 0, y si es 10, el dígito es 1. En
   cualquier otro caso, el dígito es el resultado.

En el ejemplo, la suma es 527, y como `527 mod 11 = 10`, el cálculo da
`11 - 10 = 1`. Por eso el dígito verificador es 1.

## 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).

## Parámetros

| Nombre | Dónde | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
| `claveAcceso` | ruta | string | Sí | Clave de acceso de 49 dígitos, sin espacios ni guiones. |

## Ejemplo

```bash
curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811" \
  -H "X-Api-Key: $ECUAFACT_API_KEY"
```

```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/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
```

```python
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=30,
)
print(r.status_code, r.text)
```

```javascript
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log(res.status, await res.text());
```

```php
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811');
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);
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;

// 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/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .GET()
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
```

```csharp-sdk
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;

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

ClaveAccesoDecodificada clave = await client.DecodificarClaveAccesoAsync(
    "0710202601012345678900110010010000001231234567811");
Console.WriteLine($"{clave.Valido} {clave.Tipo} {clave.Establecimiento}-{clave.PuntoEmision}-{clave.Secuencial}");
```

```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"],
))

clave = client.decodificar_clave_acceso("0710202601012345678900110010010000001231234567811")
print(clave.valido, clave.tipo, f"{clave.establecimiento}-{clave.punto_emision}-{clave.secuencial}")
```

```javascript-sdk
// Node.js 18 o superior. Guarda como ejemplo.mjs y ejecuta: node ejemplo.mjs
import { EcuafactClient } from "@ecuafact/sdk";

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

const clave = await client.decodificarClaveAcceso("0710202601012345678900110010010000001231234567811");
console.log(clave.valido, clave.tipo, `${clave.establecimiento}-${clave.puntoEmision}-${clave.secuencial}`);
```

```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'),
));

$clave = $client->decodificarClaveAcceso('0710202601012345678900110010010000001231234567811');
echo ($clave->valido ? 'true' : 'false') . ' ' . $clave->tipo . ' '
    . $clave->establecimiento . '-' . $clave->puntoEmision . '-' . $clave->secuencial . PHP_EOL;
```

```java-sdk
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.ClaveAccesoDecodificada;

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

ClaveAccesoDecodificada clave = client.decodificarClaveAcceso("0710202601012345678900110010010000001231234567811");
System.out.println(clave.valido() + " " + clave.tipo() + " "
    + clave.establecimiento() + "-" + clave.puntoEmision() + "-" + clave.secuencial());
```

```bash-cli
# Resultado esperado: la fecha, el tipo, el RUC, el ambiente, la serie y el secuencial de la clave.
ecuafact clave decodificar 0710202601012345678900110010010000001231234567811 --entorno sandbox
```

El resultado esperado es un 200 con `valido` en `true` y las partes que
aparecen en la tabla de estructura. Si cambias cualquier dígito de la clave, el
dígito verificador deja de coincidir y la respuesta es un 400 con el `codEstado` 3003 (`solicitud_invalida`).

## Respuesta

La API responde `200 OK` para la clave del ejemplo. El texto de `mensaje` es
ilustrativo.

```json
{
  "entrada": "0710202601012345678900110010010000001231234567811",
  "normalizada": "0710202601012345678900110010010000001231234567811",
  "valido": true,
  "longitud": 49,
  "fechaEmision": "2026-10-07",
  "tipo": "Factura",
  "rucEmisor": "0123456789001",
  "ambiente": "Pruebas",
  "establecimiento": "001",
  "puntoEmision": "001",
  "secuencial": "000000123",
  "codigoNumerico": "12345678",
  "tipoEmision": "1",
  "tipoEmisionDescripcion": "Normal",
  "digitoVerificador": "1",
  "mensaje": "Clave de acceso decodificada correctamente."
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `entrada` | string | Clave tal como la enviaste. |
| `normalizada` | string | Clave sin espacios ni separadores. |
| `valido` | boolean | `true` si la clave tiene 49 dígitos y el dígito verificador es correcto. Usa los demás campos solo si es `true`. |
| `longitud` | integer | Cantidad de dígitos, que en una clave correcta es 49. |
| `fechaEmision` | string | Fecha de emisión en formato `yyyy-MM-dd`, tomada de las posiciones 1 a 8. En la Estructura del comprobante las fechas van como `dd/MM/yyyy`, así que conviértela antes de usarla. |
| `tipo` | string | Nombre del tipo de comprobante de las posiciones 9 y 10, por ejemplo `Factura`. |
| `rucEmisor` | string | RUC de 13 dígitos de quien emitió el comprobante, tomado de las posiciones 11 a 23. |
| `ambiente` | string | `Pruebas` si el dígito es 1 o `Produccion` si es 2. Un comprobante de `Pruebas` no tiene validez fiscal. |
| `establecimiento` | string | Código del establecimiento, de 3 dígitos. |
| `puntoEmision` | string | Código del punto de emisión, de 3 dígitos. |
| `secuencial` | string | Secuencial de 9 dígitos, con ceros a la izquierda. |
| `codigoNumerico` | string | Código numérico de 8 dígitos. No tiene significado fiscal. |
| `tipoEmision` | string | Dígito del tipo de emisión, por ejemplo `1`. |
| `tipoEmisionDescripcion` | string | Descripción del tipo de emisión, por ejemplo `Normal`. |
| `digitoVerificador` | string | Dígito verificador de la posición 49, como texto. |
| `mensaje` | string | Explicación del resultado en lenguaje natural. No la uses para programar. |

Cualquier campo puede venir `null` si la clave no se pudo descomponer.

## Estados de este endpoint

Una clave con un largo o un dígito verificador incorrecto responde 400 con el
`codEstado` 3003 (`solicitud_invalida`). Cuando recibas un 200, confirma además que `valido` es `true`
antes de usar las partes, porque ese campo es el que decide y no el código
HTTP.

```json
{
  "estado": "rechazado",
  "codEstado": 3003,
  "msgError": "La solicitud no es válida.",
  "errores": [
    "La solicitud de consulta tiene un formato invalido."
  ]
}
```

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| - | 200 | La clave se descompuso. | Revisa `valido` antes de usar los datos. |
| 3003 (`solicitud_invalida`) | 400 | La clave no tiene 49 dígitos, contiene otros caracteres o el dígito verificador no coincide. | Corrige la clave, que suele tener un dígito mal copiado. |
| 3007 (`version_no_soportada`) | 400 | Enviaste `X-Api-Version` con una versión no admitida. | Quita la cabecera o envía la versión vigente. |
| 3009 (`credenciales_invalidas`) | 401 | Falta la API Key o es inválida. | Revisa `X-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 revisa los proxies o balanceadores entre tu servidor y la API. |
| 3011 (`acceso_denegado`) | 403 | Tu API Key está limitada y no incluye el scope `sri:consultar`. | Crea una API Key con ese scope en **Cuenta > API Keys**. |
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes de tu API Key o la consulta se limitó temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. |
| 5001 (`error_interno`) | 500 | Ocurrió un error interno. | Reintenta con una espera y, si persiste, reporta el valor de `X-Correlation-Id`. |
| 5003 (`error_dependencia`) | 502 | La consulta no pudo completarse por un error temporal del servicio. | Reintenta con una espera. |
| 5002 (`servicio_no_disponible`) | 503 | El servicio de consultas no está disponible temporalmente. | Espera los segundos que indica `Retry-After` y reintenta. |
| 5004 (`tiempo_agotado`) | 504 | La consulta no respondió a tiempo. | Reintenta con una espera. |

El catálogo completo de `codEstado` está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta si un comprobante que emitiste está autorizado.
- [Nota de crédito](/v1/guias/emision-04): usa las partes de la clave para referenciar el documento modificado.
- [Comprobante de retención](/v1/guias/emision-07): valida la clave del comprobante de sustento antes de emitir.
- [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno.
