> ## 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.

# Conexões

> Como a Croma faz login em fontes que só respondem a uma pessoa autenticada: registre sua própria conta uma vez e cada consulta roda com ela, com rodízio automático e credenciais que nunca são devolvidas.

Algumas fontes só respondem a uma pessoa com sessão iniciada. A
[SUNARP](/pt/guides/peru/sunarp), por exemplo, exige um DNI peruano. Para essas
fontes você registra **sua própria conta** uma vez como **conexão**, e cada
consulta dessa fonte roda com ela.

<Note>
  Você faz isso uma vez por conta. Depois consulta a fonte como qualquer outro
  endpoint: nada a mais na solicitação.
</Note>

## Como se encaixa

```mermaid theme={"dark"}
flowchart TB
  A["Seu app ou agente"] -->|"1. registre uma vez"| B["API da Croma"]
  B -->|"criptografada ao chegar"| V[("Cofre de conexões")]
  A -->|"2. consulte como sempre"| B
  B --> S["Serviço isolado de login"]
  V -.->|"aberta só aqui"| S
  S -->|"com a sessão da sua conta"| R["Fonte"]
```

A API que recebe suas credenciais pode guardá-las, mas não lê-las. Só o serviço
isolado que faz login na fonte pode abri-las, e só para a consulta que precisa
delas.

## 1. Registre uma conexão

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant App as Seu app
  participant API as API da Croma
  participant Src as Fonte
  App->>API: POST /pe/sunarp/connections/v1<br/>campos da conta + authorized: true
  API->>API: criptografa, vinculada à sua organização
  API->>Src: faz login uma vez para verificá-la
  alt a fonte aceita
    API-->>App: 201 { id: "conn_…", display_name: "J*** P*** G***" }
  else a fonte recusa
    API-->>App: 422 connection_rejected (nada é guardado)
  end
```

`authorized: true` registra que você é o titular da conta ou tem a autorização
do titular. A resposta nunca inclui as credenciais, só um nome mascarado.

## 2. Consulte

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant App as Seu app
  participant API as API da Croma
  participant Src as Fonte
  App->>API: POST /pe/sunarp/registry-search/v1
  alt consultada nos últimos 30 dias
    API-->>App: 200 a partir da Croma, sem ir à fonte
  else pergunta nova
    API->>API: escolhe uma das suas conexões
    API->>Src: consulta com a sessão dessa conta
    Src-->>API: resposta
    API-->>App: 200 { data }
  end
```

* **Escolha.** A Croma prefere a conexão cuja sessão já está aberta e depois a
  que tem mais cota. Envie `connection_id` para usar uma específica.
* **Uma consulta por conta de cada vez.** Consultas em contas diferentes rodam em
  paralelo; as de uma mesma conta esperam a vez, então nunca fazem login uma
  sobre a outra.
* **Rodízio.** Quando uma conta atinge sua cota diária, a mesma consulta passa
  para a sua próxima conexão. Registre mais de uma para ter mais capacidade.

## Estados de uma conexão

```mermaid theme={"dark"}
stateDiagram-v2
  [*] --> active: registrada e verificada
  active --> exhausted: cota diária usada
  exhausted --> active: a cota reinicia
  active --> invalid: a fonte não a aceita mais
  invalid --> [*]: exclua e registre de novo
  active --> [*]: DELETE
```

`GET /pe/sunarp/connections/v1` mostra o estado de cada conexão, os logins
usados hoje e quando reinicia.

| Status | Código | Quando |
| - | - | - |
| 409 | `connection_required` | Sua organização ainda não tem uma conexão para a fonte. |
| 422 | `connection_rejected` | A fonte não aceita mais a conta. |
| 429 | `connections_exhausted` | Todas as conexões usaram sua cota diária. `Retry-After` indica quando uma volta. |

## Segurança

* As credenciais são criptografadas assim que chegam à Croma e ficam vinculadas
  à sua organização: ninguém mais pode usá-las.
* Só o serviço isolado que faz login na fonte pode abri-las.
* A API nunca as devolve nem as mostra a ninguém, e elas nunca são gravadas em
  logs.
* Excluir uma conexão a destrói permanentemente.

## A partir de um agente (MCP)

Os mesmos verbos são ferramentas do [servidor MCP](/pt/mcp-server):
`sunarp_connect`, `sunarp_list_connections` e `sunarp_delete_connection`. Um
agente pode conectar a conta do usuário na conversa, com o consentimento dele, e
depois consultar.

<Card title="SUNARP" icon="building-columns" href="/pt/guides/peru/sunarp">
  A primeira fonte que usa conexões, com seus campos e exemplos.
</Card>


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