Padrón de compradores

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.

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

curl https://sandbox.cucu.bo/api/v1/padron/5/591164023 \
  -H "X-API-Key: YOUR_API_KEY"

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();

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):

{
  "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=`

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.

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.

Información General

Endpoints Disponibles

Documentos Sector

Utilidades y Soporte

Padrón de compradores

Consultar un documento

Campos

Errores

​Consultar un documento

​Campos

​Errores

Consultar un documento

Campos

Errores