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
validoesfalse, 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
tipote dice si el número es una cédula, un RUC o un pasaporte, y con eso llenastipoIdentificacionComprador:05para cédula,04para RUC y06para 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.