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

# Validar identificación

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](/v1/guias/glosario),
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.

> [!IMPORTANT]
> 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](/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]
> 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](/v1/guias/consulta-contribuyente).

## 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](/v1/guias/catalogos).
- **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](/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 |
|---|---|---|---|---|
| `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

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

```python
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)
```

```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/identificacion/validar/0123456789001', {
  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/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;
```

```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/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());
```

```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")!
});

ValidacionIdentificacion resultado = await client.ValidarIdentificacionAsync("0123456789001");
if (resultado.Valido == true)
{
    Console.WriteLine("Formato valido: " + resultado.Tipo);
}
else
{
    Console.WriteLine("Corrige el numero: " + resultado.Mensaje);
}
```

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

resultado = client.validar_identificacion("0123456789001")
if resultado.valido:
    print("Formato valido:", resultado.tipo)
else:
    print("Corrige el numero:", resultado.mensaje)
```

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

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

$resultado = $client->validarIdentificacion('0123456789001');
if ($resultado->valido === true) {
    echo 'Formato valido: ' . $resultado->tipo . PHP_EOL;
} else {
    echo 'Corrige el numero: ' . $resultado->mensaje . PHP_EOL;
}
```

```java-sdk
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());
}
```

```bash-cli
# 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.

```json
{
  "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:

```json
{
  "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](/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. 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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Contribuyente por identificación](/v1/guias/consulta-contribuyente): confirma que el número existe y obtiene la razón social.
- [Factura](/v1/guias/emision-01): usa la identificación validada en `identificacionComprador`.
- [Catálogos](/v1/guias/catalogos): códigos de tipo de identificación y demás tablas del SRI.
- [Errores](/v1/guias/errores): catálogo completo de códigos y qué hacer ante cada uno.
