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

# Padrón de compradores

> Nombre o razón social de un comprador a partir de su CI o NIT, para autocompletar la factura.

## Consultar un documento

`GET /api/v1/padron/{tipo}/{numero}`

Devuelve el nombre (CI) o la razón social (NIT) de un comprador para completar la factura sin que el cajero lo escriba.

* **NIT:** la razón social es la **oficial del Registro Nacional de Contribuyentes del SIN**, escrita tal cual la registra Impuestos (`CUCU S.R.L.`, no `Cucu srl`), junto con su estado (`ACTIVO`, `VIGENTE`...). Si es la primera vez que se consulta ese NIT, la respuesta puede tardar unos segundos; las siguientes son inmediatas.
* **CI:** el nombre más completo conocido para ese documento.

La consulta es solo por número exacto: no hay búsqueda por nombre ni listados. Usa tu misma API Key y cuenta para tu límite de requests por minuto.

> [!WARNING]
>
> **Una consulta por documento, cuando el cajero termina de escribirlo** (al salir del campo o al presionar Enter). No consultes en cada tecla ni hagas polling: el dato no cambia minuto a minuto y superar tu límite devuelve `429`. Si en la misma venta ya lo consultaste, reusá la respuesta.

| Parámetro | Ubicación | Tipo | Req | Descripción |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Sí | Tu API Key |
| `tipo` | Path | integer | Sí | `codigoTipoDocumentoIdentidad` del SIN: `1` CI, `2` CEX, `3` PAS, `4` OD, `5` NIT |
| `numero` | Path | string | Sí | Número de documento |
| `complemento` | Query | string | No | Complemento del CI (ej. `1B`), si tiene |

```bash cURL theme={"system"}
curl https://sandbox.cucu.bo/api/v1/padron/5/591164023 \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript JavaScript theme={"system"}
const response = await fetch('https://sandbox.cucu.bo/api/v1/padron/5/591164023', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const { data } = await response.json();
```

```python Python theme={"system"}
import requests

r = requests.get(
    'https://sandbox.cucu.bo/api/v1/padron/5/591164023',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = r.json()['data']
```

**Respuesta (NIT):**

```json theme={"system"}
{
  "success": true,
  "data": {
    "encontrado": true,
    "tipo": 5,
    "numero": "591164023",
    "complemento": "",
    "nombre": "CUCU S.R.L.",
    "confianza": 95,
    "oficial": true,
    "sin": {
      "registrado": true,
      "estadoContribuyente": "ACTIVO",
      "estadoActividad": "VIGENTE",
      "tipoContribuyente": "PERSONA JURÍDICA"
    },
    "candidatos": []
  }
}
```

### Campos

| Campo | Descripción |
| - | - |
| `encontrado` | `true` si hay un nombre para ese documento |
| `nombre` | Nombre o razón social para la factura (`nombreRazonSocial`) |
| `oficial` | `true` si sale del SIN: usarlo tal cual, sin editar |
| `confianza` | 0–100. Un nombre que no es oficial es el más completo que se conoce, pero conviene que el cajero lo confirme |
| `sin` | Solo NIT: lo que dice el SIN. `registrado: false` = el SIN no tiene ese NIT. `null` si no se pudo consultar en ese momento |
| `candidatos` | Solo CI sin complemento: si hay varias personas con el mismo número (homónimos), la lista para que el cajero elija. Repetir la consulta con `?complemento=` |

> [!NOTE]
>
> Si el SIN no responde, la consulta no falla: devuelve el mejor nombre conocido con `oficial: false` y `sin: null`. Para validar formalmente un NIT antes de emitir, el servicio oficial sigue siendo [Verificar NIT](/api/codes).

### Errores

| HTTP | Código | Cuándo |
| - | - | - |
| 400 | `VALIDATION_ERROR` | Documento con formato imposible o código genérico del SIN (`0`, `99001`, `99002`, `99003`) |
| 401 | — | Sin API Key o API Key inválida |
| 429 | — | Superaste tu límite de requests por minuto |

También disponible como herramienta MCP: [`consultarPadron`](/mcp/herramientas-utilidades#consultarpadron).


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