En esta página
Decodificar clave de acceso GET
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 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.
Importante
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. |
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.
Nota
Decodificar no prueba que el comprobante esté autorizado ni que exista en el SRI, porque solo revisa la estructura y el dígito verificador. Para conocer el estado de un comprobante que emitiste, usa el seguimiento.
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,puntoEmisionysecuencialarmasnumDocModificado, por ejemplo001-001-000000123, y confechaEmisionllenasfechaEmisionDocSustento, convirtiendoyyyy-MM-ddadd/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.
| 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:
- 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.
- Suma los productos.
- Calcula
11 - (suma mod 11). - 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; 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.
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#
curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/comprobantes/decodificar/0710202601012345678900110010010000001231234567811" \
-H "X-Api-Key: $ECUAFACT_API_KEY"
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()}");
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)
// 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
$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;
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());
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}");
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}")
// 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
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;
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());
# 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.
{
"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.
{
"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. |
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.
Siguientes pasos#
- Seguimiento de una operación: consulta si un comprobante que emitiste está autorizado.
- Nota de crédito: usa las partes de la clave para referenciar el documento modificado.
- Comprobante de retención: valida la clave del comprobante de sustento antes de emitir.
- Errores: catálogo completo de códigos y qué hacer ante cada uno.