Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Validar identificación GET

Comprueba el formato y el dígito verificador de una cédula, un RUC o un pasaporte, sin consultar al SRI.

Antes de emitir un comprobante, puedes comprobar que la identificación del comprador esté bien escrita. Este endpoint revisa el formato del número y su dígito verificador, te dice si es una cédula, un RUC o un pasaporte y te devuelve el valor normalizado. Como no consulta al SRI, te responde rápido.

Ten en cuenta que la API responde 200 tanto si el número es válido como si no lo es; lo que decide es el campo valido de la respuesta. Al terminar esta página sabrás qué reglas se comprueban y cómo usar el resultado para llenar el tipo de identificación del comprador.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan la URL de pruebas, y la validación se comporta igual en ambos ambientes.

Endpoint#

GET /v1/consultas/identificacion/validar/{numero}
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

Esta validación es solo de formato y no confirma que la persona o empresa exista en el SRI. Para confirmar que existe, usa Contribuyente por identificación.

Cuándo usarlo#

  • Validar la cédula o el RUC del comprador antes de emitir. Llama a esta consulta cuando tu usuario captura el número en el formulario de facturación. Si valido es false, pídele que lo corrija antes de enviar el comprobante, y así evitas un rechazo del SRI por una identificación mal escrita.
  • Elegir el tipo de identificación del comprador. El campo tipo te dice si el número es una cédula, un RUC o un pasaporte, y con eso llenas tipoIdentificacionComprador: 05 para cédula, 04 para RUC y 06 para pasaporte. Los códigos están en Catálogos.
  • Limpiar los datos de tu ERP en lote, sin depender de la disponibilidad del SRI.

Qué se valida#

Tipo Regla que se comprueba
Cédula Tiene 10 dígitos y su dígito verificador cumple el módulo 10.
RUC de persona natural Tiene 13 dígitos: una cédula válida seguida de un código de establecimiento, por ejemplo 001. La respuesta trae la cédula en cedulaBaseDelRuc.
RUC de sociedad privada o pública Tiene 13 dígitos con la estructura de RUC de sociedad. No se exige el dígito verificador módulo 11.
Pasaporte Es alfanumérico, de 5 a 20 caracteres.

La cédula de prueba de esta documentación, 0123456789, y el RUC de prueba 0123456789001 no pasan el módulo 10, así que con ellos la respuesta trae valido en false. Para ver una respuesta con valido en true, prueba con tu propia cédula o con el RUC de tu empresa.

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
numero ruta string Sí Cédula, RUC o pasaporte a validar. La API elimina los espacios al inicio y al final, y normalizado muestra el valor sin separadores.

Ejemplo#

curl -s "https://api-sandbox.mynexusapi.com/v1/consultas/identificacion/validar/0123456789001" \
  -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/identificacion/validar/0123456789001");
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/consultas/identificacion/validar/0123456789001",
    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/identificacion/validar/0123456789001', {
  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/identificacion/validar/0123456789001');
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/identificacion/validar/0123456789001"))
    .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")!
});

ValidacionIdentificacion resultado = await client.ValidarIdentificacionAsync("0123456789001");
if (resultado.Valido == true)
{
    Console.WriteLine("Formato valido: " + resultado.Tipo);
}
else
{
    Console.WriteLine("Corrige el numero: " + resultado.Mensaje);
}
import os
from ecuafact import EcuafactClient, EcuafactClientOptions

client = EcuafactClient(EcuafactClientOptions(
    base_address="https://api-sandbox.mynexusapi.com/",
    api_key=os.environ["ECUAFACT_API_KEY"],
))

resultado = client.validar_identificacion("0123456789001")
if resultado.valido:
    print("Formato valido:", resultado.tipo)
else:
    print("Corrige el numero:", resultado.mensaje)
// 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 resultado = await client.validarIdentificacion("0123456789001");
if (resultado.valido === true) {
  console.log("Formato valido:", resultado.tipo);
} else {
  console.log("Corrige el numero:", resultado.mensaje);
}
<?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'),
));

$resultado = $client->validarIdentificacion('0123456789001');
if ($resultado->valido === true) {
    echo 'Formato valido: ' . $resultado->tipo . PHP_EOL;
} else {
    echo 'Corrige el numero: ' . $resultado->mensaje . PHP_EOL;
}
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EcuafactClientOptions;
import com.ecuafact.sdk.contracts.ValidacionIdentificacion;

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

ValidacionIdentificacion resultado = client.validarIdentificacion("0123456789001");
if (Boolean.TRUE.equals(resultado.valido())) {
    System.out.println("Formato valido: " + resultado.tipo());
} else {
    System.out.println("Corrige el numero: " + resultado.mensaje());
}
# Resultado esperado con 0123456789001: valido en false, porque la cédula de prueba no cumple el módulo 10.
ecuafact identificacion validar 0123456789001 --entorno sandbox

Con 0123456789001, el resultado esperado es un 200 con valido en false, porque la cédula base de prueba no cumple el módulo 10. Con un número real bien escrito recibes un 200 con valido en true.

Respuesta#

La API responde 200 OK. Esta es la respuesta con un RUC de persona natural válido; en lugar de 0123456789001 verás el RUC real que validaste, y los textos de mensaje son ilustrativos.

{
  "entrada": "0123456789001",
  "normalizado": "0123456789001",
  "valido": true,
  "tipo": "RucPersonaNatural",
  "longitud": 13,
  "esSoloDigitos": true,
  "cedulaBaseDelRuc": "0123456789",
  "mensaje": "Formato de RUC de persona natural aceptado; confirme su registro en el SRI."
}

Y esta es la respuesta con un número inválido, que también llega con un 200:

{
  "entrada": "0123456789",
  "normalizado": "0123456789",
  "valido": false,
  "tipo": "Cedula",
  "longitud": 10,
  "esSoloDigitos": true,
  "cedulaBaseDelRuc": null,
  "mensaje": "El digito verificador de la cedula no es valido."
}
Campo Tipo Descripción
entrada string Número tal como lo enviaste.
normalizado string Número sin espacios ni separadores. Guarda este valor en tu sistema.
valido boolean true si el formato y el dígito verificador son correctos. Es el campo que decide, así que no uses el código HTTP para saber si el número es válido.
tipo string Tipo detectado. Sus valores están en la tabla siguiente.
longitud integer Cantidad de caracteres de normalizado.
esSoloDigitos boolean true si el número contiene solo dígitos; es false en los pasaportes alfanuméricos.
cedulaBaseDelRuc string Cédula contenida en un RUC de persona natural, es decir, sus primeros 10 dígitos. Vale null en los demás tipos.
mensaje string Explicación del resultado en lenguaje natural. Puedes mostrarla a tu usuario, pero no la uses para programar.
tipo Significado tipoIdentificacionComprador
Cedula Cédula de identidad, de 10 dígitos. 05
RucPersonaNatural RUC de una persona natural, formado por la cédula y el establecimiento. 04
RucSociedadPrivada RUC de una sociedad privada. 04
RucSociedadPublica RUC de una entidad pública. 04
Pasaporte Pasaporte alfanumérico, de 5 a 20 caracteres. 06
Desconocido El número no coincide con ningún tipo. Trátalo como inválido. -

Estados de este endpoint#

codEstado HTTP Cuándo ocurre Qué hacer
- 200 La validación se realizó, con valido en true o en false. Revisa valido. Si es false, pide al usuario que corrija el número.
3003 (solicitud_invalida) 400 El número tiene caracteres que no se pueden validar. Corrige el número.
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. Valida cuando el usuario sale del campo, no en cada tecla.
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#

  • Contribuyente por identificación: confirma que el número existe y obtiene la razón social.
  • Factura: usa la identificación validada en identificacionComprador.
  • Catálogos: códigos de tipo de identificación y demás tablas del SRI.
  • Errores: catálogo completo de códigos y qué hacer ante cada uno.
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.