# chemanc/consultarucsunat architecture

> Architecture diagram of the GitHub repository chemanc/consultarucsunat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chemanc/consultarucsunat
- Repository: https://github.com/chemanc/consultarucsunat

## Overview

ConsultaRucSunat is a small Python library for looking up Peruvian taxpayer records from SUNAT. A client calls `consultaRuc`, which maintains a session, obtains SUNAT’s token, retrieves the RUC page, parses its taxpayer fields, requests condition history, and adds the historical record before returning the result. The README documents RUC 10 and RUC 20 parsing and additional structured fields. The source excerpts show the request and parser calls; no separate SUNAT service implementation is included.

Main entry points: [`consultaRuc/consulta.py`](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py) (RUC lookup), [`consultaRuc/clean_consulta.py`](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/clean_consulta.py) (Taxpayer parser), [`consultaRuc/clean_consulta_historica.py`](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/clean_consulta_historica.py) (History parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lookup["Lookup workflow"]
  node_lookup_api["RUC lookup<br/>[consulta.py]"]
  node_session["Session init<br/>[consulta.py]"]
  node_token["Token request<br/>[consulta.py]"]
  node_primary["RUC request<br/>[consulta.py]"]
  node_history["History request<br/>[consulta.py]"]
end

subgraph group_parsing["Response parsing"]
  node_primary_parser["Taxpayer parser<br/>[clean_consulta.py]"]
  node_history_parser["History parser"]
end

node_client(("Client app"))
node_sunat["SUNAT portal"]

node_client -->|"calls"| node_lookup_api
node_lookup_api -->|"starts"| node_session
node_session -->|"GET session"| node_sunat
node_lookup_api -->|"requests token"| node_token
node_token -->|"POST token"| node_sunat
node_lookup_api -->|"requests RUC"| node_primary
node_primary -->|"POST lookup"| node_sunat
node_lookup_api -->|"parses HTML"| node_primary_parser
node_lookup_api -->|"requests history"| node_history
node_history -->|"POST history"| node_sunat
node_lookup_api -->|"parses HTML"| node_history_parser
node_lookup_api -->|"returns data"| node_client

click node_lookup_api "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py"
click node_session "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py"
click node_token "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py"
click node_primary "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py"
click node_history "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py"
click node_primary_parser "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/clean_consulta.py"
click node_history_parser "https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/clean_consulta_historica.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lookup_api,node_session,node_token,node_primary,node_history,node_client toneBlue
class node_primary_parser,node_history_parser toneAmber
class node_sunat toneIndigo
```

## Components

### Lookup workflow

- [RUC lookup](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py): `consultaRuc/consulta.py`
- [Session init](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py): `consultaRuc/consulta.py`
- [Token request](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py): `consultaRuc/consulta.py`
- [RUC request](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py): `consultaRuc/consulta.py`
- [History request](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/consulta.py): `consultaRuc/consulta.py`

### Response parsing

- [Taxpayer parser](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/clean_consulta.py): `consultaRuc/clean_consulta.py`
- [History parser](https://github.com/chemanc/consultarucsunat/blob/main/consultaRuc/clean_consulta_historica.py): `consultaRuc/clean_consulta_historica.py`

### Other components

- **Client app**
- **SUNAT portal**

## Connections

- Client app → RUC lookup: calls (evidence: `README.md`)
- RUC lookup → Session init: starts (evidence: `consultaRuc/consulta.py`)
- Session init → SUNAT portal: GET session (evidence: `consultaRuc/consulta.py`)
- RUC lookup → Token request: requests token (evidence: `consultaRuc/consulta.py`)
- Token request → SUNAT portal: POST token (evidence: `consultaRuc/consulta.py`)
- RUC lookup → RUC request: requests RUC (evidence: `consultaRuc/consulta.py`)
- RUC request → SUNAT portal: POST lookup (evidence: `consultaRuc/consulta.py`)
- RUC lookup → Taxpayer parser: parses HTML (evidence: `consultaRuc/consulta.py`)
- RUC lookup → History request: requests history (evidence: `consultaRuc/consulta.py`)
- History request → SUNAT portal: POST history (evidence: `consultaRuc/consulta.py`)
- RUC lookup → History parser: parses HTML (evidence: `consultaRuc/consulta.py`)
- RUC lookup → Client app: returns data (evidence: `consultaRuc/consulta.py`)
