{"openapi":"3.1.0","info":{"title":"Winkstec Perú API","version":"1.0.0","description":"Consulta de RUC con el padrón reducido de SUNAT, actualizado cada día.\n\nPlanes: Gratis (1,000 consultas), Micro (5,000 consultas), Básico (60,000 consultas), Pro (150,000 consultas), Empresa (350,000 consultas)."},"servers":[{"url":"https://api.peru.winkstec.com"}],"security":[{"clave":[]}],"components":{"securitySchemes":{"clave":{"type":"http","scheme":"bearer","description":"Tu clave `wk_live_…` o `wk_test_…` del panel."}},"schemas":{"Ruc":{"type":"object","properties":{"ruc":{"type":"string","example":"20131312955"},"razonSocial":{"type":"string","example":"SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA - SUNAT"},"estado":{"type":["string","null"],"example":"ACTIVO"},"condicion":{"type":["string","null"],"example":"HABIDO"},"direccion":{"type":["string","null"],"example":"AV. GARCILASO DE LA VEGA NRO. 1472"},"ubigeo":{"type":["string","null"],"example":"150101"},"departamento":{"type":["string","null"],"example":"LIMA"},"provincia":{"type":["string","null"],"example":"LIMA"},"distrito":{"type":["string","null"],"example":"LIMA"},"tipo":{"type":"string","enum":["persona_natural","persona_juridica","otro"]},"fechaPadron":{"type":["string","null"],"format":"date","description":"Fecha del archivo de SUNAT con que se respondió."}}},"Error":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}},"paths":{"/v1/ruc/{ruc}":{"get":{"summary":"Consultar un RUC","description":"Cobra 1 consulta sólo si el RUC existe en el padrón.","parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{11}$"},"example":"20131312955"}],"responses":{"200":{"description":"Encontrado","headers":{"X-RateLimit-Limit":{"description":"Peticiones por minuto de tu plan.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Peticiones que te quedan en este minuto.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Segundos para que empiece el próximo minuto.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Consultas incluidas en tu periodo.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas que te quedan en el periodo.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Fin del periodo (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-Credits-Remaining":{"description":"Créditos de paquetes que te quedan.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ruc"}}}},"400":{"description":"`ruc_invalido`, `lote_invalido`, `ubigeo_invalido`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"401":{"description":"`clave_faltante`, `clave_invalida`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"403":{"description":"`lote_no_permitido`, `ip_no_permitida`, `cuenta_suspendida`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"404":{"description":"`no_encontrado`, `ruta_no_existe`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"429":{"description":"`limite_por_segundo`, `limite_por_minuto`, `cuota_agotada`, `demasiados_intentos`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}}}}},"/v1/ruc/lote":{"post":{"summary":"Consultar varios RUC","description":"Planes Pro (50) y Empresa (100). Cobra una consulta por cada RUC encontrado.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rucs"],"properties":{"rucs":{"type":"array","items":{"type":"string"},"maxItems":100}}},"example":{"rucs":["20131312955","20100047218"]}}}},"responses":{"200":{"description":"Resultados en el mismo orden","headers":{"X-RateLimit-Limit":{"description":"Peticiones por minuto de tu plan.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Peticiones que te quedan en este minuto.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Segundos para que empiece el próximo minuto.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Consultas incluidas en tu periodo.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas que te quedan en el periodo.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Fin del periodo (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-Credits-Remaining":{"description":"Créditos de paquetes que te quedan.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"consultasCobradas":{"type":"integer"},"resultados":{"type":"array","items":{"type":"object","properties":{"ruc":{"type":"string"},"encontrado":{"type":"boolean"},"datos":{"$ref":"#/components/schemas/Ruc"},"error":{"type":"string"}}}}}}}}},"400":{"description":"`ruc_invalido`, `lote_invalido`, `ubigeo_invalido`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"401":{"description":"`clave_faltante`, `clave_invalida`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"403":{"description":"`lote_no_permitido`, `ip_no_permitida`, `cuenta_suspendida`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"429":{"description":"`limite_por_segundo`, `limite_por_minuto`, `cuota_agotada`, `demasiados_intentos`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}}}}},"/v1/ubigeo/{codigo}":{"get":{"summary":"Traducir un ubigeo","description":"No gasta consultas.","parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{6}$"},"example":"150101"}],"responses":{"200":{"description":"Lugar","content":{"application/json":{"schema":{"type":"object","properties":{"ubigeo":{"type":"string"},"departamento":{"type":"string"},"provincia":{"type":"string"},"distrito":{"type":"string"}}}}}},"400":{"description":"`ruc_invalido`, `lote_invalido`, `ubigeo_invalido`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"401":{"description":"`clave_faltante`, `clave_invalida`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"404":{"description":"`no_encontrado`, `ruta_no_existe`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"429":{"description":"`limite_por_segundo`, `limite_por_minuto`, `cuota_agotada`, `demasiados_intentos`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}}}}},"/v1/uso":{"get":{"summary":"Tu consumo","description":"Plan, periodo, consultas usadas y créditos. No gasta consultas.","responses":{"200":{"description":"Consumo","headers":{"X-RateLimit-Limit":{"description":"Peticiones por minuto de tu plan.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Peticiones que te quedan en este minuto.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Segundos para que empiece el próximo minuto.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Consultas incluidas en tu periodo.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas que te quedan en el periodo.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Fin del periodo (ISO 8601).","schema":{"type":"string","format":"date-time"}},"X-Credits-Remaining":{"description":"Créditos de paquetes que te quedan.","schema":{"type":"integer"}}}},"401":{"description":"`clave_faltante`, `clave_invalida`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}},"429":{"description":"`limite_por_segundo`, `limite_por_minuto`, `cuota_agotada`, `demasiados_intentos`","content":{"application/json":{"schema":{"type":"object","required":["error","mensaje"],"properties":{"error":{"type":"string","enum":["ruc_invalido","lote_invalido","lote_no_permitido","ubigeo_invalido","no_encontrado","clave_faltante","clave_invalida","ip_no_permitida","cuenta_suspendida","limite_por_segundo","limite_por_minuto","cuota_agotada","demasiados_intentos","ruta_no_existe","error_interno","padron_no_disponible"]},"mensaje":{"type":"string"}}}}}}}}},"/v1/estado":{"get":{"summary":"Estado del padrón","description":"Público, sin clave. Fecha del padrón y número de RUC.","security":[],"responses":{"200":{"description":"Estado","content":{"application/json":{"schema":{"type":"object","properties":{"disponible":{"type":"boolean"},"fechaPadron":{"type":["string","null"]},"filas":{"type":"integer"},"cargadoEn":{"type":["string","null"]},"actualizado":{"type":"boolean"}}}}}}}}}}}