> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conexiones

> Cómo Croma inicia sesión en fuentes que solo responden a una persona autenticada: registra tu propia cuenta una vez y cada consulta corre con ella, con rotación automática y credenciales que nunca se devuelven.

Algunas fuentes solo responden a una persona con sesión iniciada.
[SUNARP](/es/guides/peru/sunarp), por ejemplo, necesita un DNI peruano. Para
esas fuentes registras **tu propia cuenta** una vez como **conexión**, y cada
consulta de esa fuente corre con ella.

<Note>
  Lo haces una sola vez por cuenta. Después consultas la fuente como cualquier
  otro endpoint: nada extra en la solicitud.
</Note>

## Cómo encaja

```mermaid theme={"dark"}
flowchart TB
  A["Tu app o agente"] -->|"1. registra una vez"| B["API de Croma"]
  B -->|"cifrada al llegar"| V[("Bóveda de conexiones")]
  A -->|"2. consulta como siempre"| B
  B --> S["Servicio aislado de inicio de sesión"]
  V -.->|"solo se abre aquí"| S
  S -->|"con sesión de tu cuenta"| R["Fuente"]
```

La API que recibe tus credenciales puede guardarlas pero no leerlas. Solo el
servicio aislado que inicia sesión en la fuente puede abrirlas, y solo para la
consulta que las necesita.

## 1. Registra una conexión

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant App as Tu app
  participant API as API de Croma
  participant Src as Fuente
  App->>API: POST /pe/sunarp/connections/v1<br/>campos de la cuenta + authorized: true
  API->>API: cifra, ligada a tu organización
  API->>Src: inicia sesión una vez para verificarla
  alt la fuente la acepta
    API-->>App: 201 { id: "conn_…", display_name: "J*** P*** G***" }
  else la fuente la rechaza
    API-->>App: 422 connection_rejected (no se guarda nada)
  end
```

`authorized: true` deja constancia de que eres titular de la cuenta o tienes
autorización de su titular. La respuesta nunca incluye las credenciales, solo un
nombre enmascarado.

## 2. Consulta

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant App as Tu app
  participant API as API de Croma
  participant Src as Fuente
  App->>API: POST /pe/sunarp/registry-search/v1
  alt consultada en los últimos 30 días
    API-->>App: 200 desde Croma, sin ir a la fuente
  else pregunta nueva
    API->>API: elige una de tus conexiones
    API->>Src: consulta con la sesión de esa cuenta
    Src-->>API: respuesta
    API-->>App: 200 { data }
  end
```

* **Elección.** Croma prefiere la conexión cuya sesión ya está abierta y luego la
  que tiene más cupo. Envía `connection_id` para usar una en particular.
* **Una consulta por cuenta a la vez.** Las consultas en cuentas distintas corren
  en paralelo; las de una misma cuenta esperan su turno, así nunca inician sesión
  una sobre otra.
* **Rotación.** Cuando una cuenta llega a su cupo diario, la misma consulta pasa a
  tu siguiente conexión. Registra más de una para tener más capacidad.

## Estados de una conexión

```mermaid theme={"dark"}
stateDiagram-v2
  [*] --> active: registrada y verificada
  active --> exhausted: cupo diario usado
  exhausted --> active: el cupo se reinicia
  active --> invalid: la fuente ya no la acepta
  invalid --> [*]: elimínala y regístrala de nuevo
  active --> [*]: DELETE
```

`GET /pe/sunarp/connections/v1` muestra el estado de cada conexión, los inicios
de sesión usados hoy y cuándo se reinicia.

| Estado | Código | Cuándo |
| - | - | - |
| 409 | `connection_required` | Tu organización aún no tiene una conexión para la fuente. |
| 422 | `connection_rejected` | La fuente ya no acepta la cuenta. |
| 429 | `connections_exhausted` | Todas las conexiones usaron su cupo diario. `Retry-After` indica cuándo vuelve una. |

## Seguridad

* Las credenciales se cifran en cuanto llegan a Croma y quedan ligadas a tu
  organización: nadie más puede usarlas.
* Solo el servicio aislado que inicia sesión en la fuente puede abrirlas.
* La API nunca las devuelve ni se muestran a nadie, y nunca se escriben en logs.
* Eliminar una conexión la destruye de forma permanente.

## Desde un agente (MCP)

Los mismos verbos son herramientas del [servidor MCP](/es/mcp-server):
`sunarp_connect`, `sunarp_list_connections` y `sunarp_delete_connection`. Un
agente puede conectar la cuenta del usuario en la conversación, con su
consentimiento, y luego consultar.

<Card title="SUNARP" icon="building-columns" href="/es/guides/peru/sunarp">
  La primera fuente que usa conexiones, con sus campos y ejemplos.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.