Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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, 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.

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; 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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.