# Consultar Cédula Profesional

> Valida Cédulas Profesionales (SEP) en milisegundos. Ideal para RRHH, clínicas y plataformas web.

API publicada en idoo.dev por Jonathan Fonseca (categoría: Utilidades).
Página: https://idoo.dev/apis/consultar-cedula-profesional

## Cómo llamar a la API

- **URL:** `https://idoo.dev/v1/consultar-cedula-profesional/{ruta}` — cualquier método HTTP; query, body y `Content-Type` llegan intactos a la API.
- **Autenticación:** header `Authorization: Bearer {api_key}` (o `X-API-KEY: {api_key}`). Una sola key de idoo.dev sirve para todas las APIs a las que estés suscrito.
- **Ambiente según la key:** `idoo_sk_test_...` → sandbox (gratis, no descuenta cuota); `idoo_sk_live_...` → producción.
- **Seguridad:** guarda la key en una variable de entorno (p. ej. `IDOO_API_KEY`) y llama a la API solo desde el servidor; nunca la expongas en el frontend ni la subas al repositorio.
- **Obtener acceso:** inicia sesión en https://idoo.dev/login, suscríbete a la API en https://idoo.dev/apis/consultar-cedula-profesional y crea tu key en https://idoo.dev/panel/apikeys.

## Respuestas

La respuesta de la API se devuelve **tal cual** (status, headers y body del proveedor). Solo los errores del propio gateway usan este sobre JSON:

```json
{"valid": false, "status": 402, "message": "…", "data": null, "timestamp": "2026-01-01 12:00:00"}
```

| Status | Causa | Qué hacer |
|---|---|---|
| 401 | No se envió la key | Agrega el header `Authorization: Bearer {api_key}` |
| 403 | Key inválida o revocada, o sin suscripción activa a la API | Revisa la key y la suscripción en el panel |
| 402 | Cuota mensual agotada (`data.periodo_reinicia` indica cuándo se renueva) | Mejora el plan o compra un paquete; no reintentes |
| 404 | La API no existe o no está publicada | Revisa el slug de la URL |
| 429 | Rate limit por minuto excedido | Espera los segundos del header `Retry-After` y reintenta |
| 502 | La API no respondió o no tiene URL para tu ambiente | Reintenta con backoff; si persiste, contacta al creador |

Headers útiles en cada respuesta: `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-Idoo-Cuota-Restante` (si el plan tiene cuota).
Solo descuentan cuota las llamadas de producción que la API responde con 2xx/3xx; los errores no se cobran.

## Planes

| Plan | Precio (MXN) | Llamadas/mes | Peticiones/min |
|---|---|---|---|
| Gratis | Gratis | 100 | 30 |
| Pro | $499.00/mes | 5,000 | 60 |
| Ultra | $1,499.00/mes | Ilimitadas | 120 |

## Documentación

## Cédulas Profesionales — API

API para la verificación e inspección en tiempo real de Cédulas Profesionales mexicanas directamente desde el Registro Nacional de Profesionistas (SEP). Publicada a través del gateway de **idoo.dev**: la autenticación, cuotas, planes y control de tasa (rate limiting) se gestionan de forma centralizada.

> **Facturación Deducible (CFDI 4.0):** Todos los consumos contratados a través de idoo.dev cuentan con comprobante fiscal local para empresas en México.

---

### Autenticación

Todas las solicitudes deben autenticarse enviando tu **API key de idoo.dev** en el encabezado HTTP `Authorization`:

```http
Authorization: Bearer {tu_api_key}
```

Las peticiones se dirigen a la URL base asignada por el gateway:

```http
POST https://api.idoo.dev/v1/consultar-cedula-profesional/
```

> 🔒 **Buenas prácticas de seguridad:** Mantén siempre tu API key resguardada en variables de entorno en el servidor (`.env`). Nunca realices peticiones directas desde el navegador o aplicaciones móviles (frontend) que puedan exponer tu clave.

---

### Endpoints

#### Consultar por número de cédula

Consulta el registro oficial de la SEP para validar la legitimidad de un profesional y extraer sus datos académicos.

`POST /`

##### Encabezados obligatorios (Headers)

| Header | Valor | Descripción |
| :--- | :--- | :--- |
| `Authorization` | `Bearer {tu_api_key}` | Token de acceso asignado en tu panel de idoo.dev. |
| `Content-Type` | `application/json` | Formato del cuerpo de la petición. |

##### Cuerpo de la Petición (Request Body)

La API requiere un objeto JSON en el cuerpo de la solicitud HTTP (especificado mediante `-d` o `--data` en llamadas cURL):

```json
{
  "cedula": "7739476"
}
```

##### Esquema del JSON (Body Schema)

| Campo | Tipo | Requerido | Formato / Reglas | Descripción |
| :--- | :--- | :--- | :--- | :--- |
| `cedula` | `string` | **Sí** | `7` u `8` dígitos numéricos | Número único de cédula profesional. No debe contener espacios, guiones ni letras (Ejemplo: `"7739476"`). |

---

### Ejemplos de integración

Copiar y pegar directamente en tu entorno de desarrollo:

#### cURL (Terminal / Bash)

```bash
curl -X POST "https://api.idoo.dev/v1/consultar-cedula-profesional/" \
  -H "Authorization: Bearer {tu_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "cedula": "7739476"
  }'
```

#### Python (Requests)

```python
import requests

url = "https://api.idoo.dev/v1/consultar-cedula-profesional/"
headers = {
    "Authorization": "Bearer {tu_api_key}",
    "Content-Type": "application/json"
}
payload = {
    "cedula": "7739476"
}

try:
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    data = response.json()
    
    if response.status_code == 200 and data.get("valid"):
        profesionista = data["data"]["items"][0]
        print(f"Nombre: {profesionista['nombre']} {profesionista['paterno']} {profesionista['materno']}")
        print(f"Carrera: {profesionista['titulo']}")
        print(f"Institución: {profesionista['desseccion']}")
    else:
        print(f"Error ({data.get('status')}): {data.get('message')}")

except requests.exceptions.RequestException as e:
    print(f"Error de red o conexión: {e}")
```

#### JavaScript / Node.js (Fetch API)

```javascript
const API_KEY = 'tu_api_key';
const URL = 'https://api.idoo.dev/v1/consultar-cedula-profesional/';

async function consultarCedula(cedula) {
  try {
    const response = await fetch(URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ cedula })
    });

    const result = await response.json();

    if (response.ok && result.valid) {
      console.log('Información oficial:', result.data.items[0]);
    } else {
      console.error(`Error (${result.status}):`, result.message);
    }
  } catch (error) {
    console.error('Error de red:', error);
  }
}

consultarCedula('7739476');
```

#### PHP (cURL nativo)

```php
<?php

$apiKey = 'tu_api_key';
$url = 'https://api.idoo.dev/v1/consultar-cedula-profesional/';

$payload = json_encode([
    'cedula' => '7739476'
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_TIMEOUT        => 10
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($httpCode === 200 && isset($data['valid']) && $data['valid']) {
    $profesionista = $data['data']['items'][0];
    echo "Profesionista: " . $profesionista['nombre'] . " " . $profesionista['paterno'] . "\n";
    echo "Título: " . $profesionista['titulo'] . "\n";
} else {
    echo "Error " . $httpCode . ": " . ($data['message'] ?? 'Falló la consulta');
}
```

---

### Respuestas

La API devuelve un envoltorio JSON estandarizado para facilitar la validación en código.

#### Respuesta exitosa (200 OK)

Se retorna cuando la cédula existe en la base de datos oficial.

```json
{
  "valid": true,
  "status": 200,
  "message": "Consulta exitosa",
  "data": {
    "items": [
      {
        "idProfesionista": "7739476",
        "nombre": "JUAN",
        "paterno": "PEREZ",
        "materno": "GARCIA",
        "titulo": "LICENCIATURA EN DERECHO",
        "desseccion": "UNIVERSIDAD NACIONAL AUTÓNOMA DE MÉXICO",
        "anio": "2012"
      }
    ]
  },
  "timestamp": "2026-07-26T22:30:00.000Z"
}
```

#### Respuesta cuando no se encuentra registro (404 Not Found)

Se retorna cuando el número digitado no tiene un registro asociado en el Registro Nacional de Profesionistas.

```json
{
  "valid": false,
  "status": 404,
  "message": "La cédula consultada no se encuentra registrada en la SEP",
  "data": null,
  "timestamp": "2026-07-26T22:30:00.000Z"
}
```

---

### Códigos de error

Códigos de respuesta estándar emitidos por la API o por el gateway de idoo.dev:

| Código HTTP | Mensaje / Razón | Causa Probable | Solución |
| :--- | :--- | :--- | :--- |
| `400 Bad Request` | Parámetro `cedula` faltante o mal formado. | El body enviado no es un JSON válido o la clave `"cedula"` no existe. | Verifica que el cuerpo lleve `{"cedula": "NUMBER"}` en un JSON estricto. |
| `401 Unauthorized` | API Key no válida o revocada. | El encabezado `Authorization` falta o contiene una clave incorrecta. | Confirma tu API key en tu panel de control de idoo.dev. |
| `404 Not Found` | Cédula no encontrada. | El número ingresado no existe en el registro de la SEP. | Valida que la cédula ingresada contenga únicamente números. |
| `429 Too Many Requests` | Cuota o Rate Limit superado. | Alcanzaste el límite de consultas permitidas por tu plan actual. | Revisa tus métricas en idoo.dev o actualiza a un plan de mayor capacidad. |
| `500 Internal Error` | Error interno del servidor. | Fallo temporal al conectar con la fuente de datos. | Reintenta la solicitud. El servicio cuenta con reintentos automáticos. |