Documentación axoruc

API HTTP de consulta RUC orientada a producción: contratos simples, DX moderna y latencias extremadamente bajas.

Base URL

https://api.axoruc.com

Auth

Authorization: Bearer <api-key>

GET /api/v1/taxpayer/{ruc}

Devuelve información oficial del contribuyente identificado por su RUC.

Request

curl --request GET \
 --url  'https://api.axoruc.com/api/v1/taxpayer/20100017491' \
 --header 'Authorization: Bearer <api-key>'

200 OK

▾

Body

{
  "ruc": "20131312955",
  "name": "SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA - SUNAT",
  "status": "ACTIVO",
  "condition": "HABIDO",
  "address": "AV. GARCILASO DE LA VEGA 1472",
  "ubigeo_code": "150101",
  "department": "LIMA",
  "province":    "LIMA", 
  "district": "LIMA",
  "is_retention_agent": false,
  "is_perception_agent": false,
  "is_fuel_perception_agent": false,
  "is_good_taxpayer": false
}

Campo	Tipo	Requerido	Descripción
ruc	string	Sí	Número de RUC.
name	string	Sí	Razón social.
status	string	Sí	Estado SUNAT (ej. ACTIVO).
condition	string	Sí	Condición (ej. HABIDO).
address	string	Opcional	Dirección fiscal principal.
ubigeo_code	string	Opcional	Código ubigeo.
is_retention_agent	boolean	Opcional	Agente de retención.
is_perception_agent	boolean	Opcional	Agente de percepción.
is_fuel_perception_agent	boolean	Opcional	Percepción combustibles.
is_good_taxpayer	boolean	Opcional	Buen contribuyente.

GET /api/v1/taxpayer/{ruc}/establishment

Devuelve la lista de establecimientos asociados a un contribuyente identificado por su RUC.

Request

curl --request GET \
 --url  'https://api.axoruc.com/api/v1/taxpayer/20100017491/establishment' \
 --header 'Authorization: Bearer <api-key>'

200 OK

▾

Body

[
  {
    "address": "CAL. MANUEL SEOANE 84",
    "ubigeo_code": "140112",
    "department": "LAMBAYEQUE",
    "province": "CHICLAYO",
    "district": "PIMENTEL"
  },
  {
    "address": "CAR. PANAMERICANA SUR KM 1336",
    "ubigeo_code": "230101",
    "department": "TACNA",
    "province": "TACNA",
    "district": "TACNA"
  },
  {
    "address": "AV. TUPAC AMARU 139",
    "ubigeo_code": "150801",
    "department": "LIMA",
    "province": "HUAURA",
    "district": "HUACHO"
  }
]

Campo	Tipo	Requerido	Descripción
address	string	Sí	Dirección del establecimiento.
ubigeo_code	string	Opcional	Código ubigeo.
department	string	Opcional	Departamento.
province	string	Opcional	Provincia.
district	string	Opcional	Distrito.

GET /api/v1/taxpayer/search

Permite buscar contribuyentes por razón social o nombre, devolviendo coincidencias registradas en SUNAT.

Request

curl --request GET \
 --url  'https://api.axoruc.com/api/v1/taxpayer/search?query=superintendencia' \
 --header 'Authorization: Bearer <api-key>'

200 OK

▾

Body

[
  {
    "ruc": "20131312955",
    "name": "SUPERINTENDENCIA NACIONAL DE ADUANAS Y DE ADMINISTRACION TRIBUTARIA - SUNAT",
    "status": "ACTIVO",
    "condition": "HABIDO",
    "address": "AV. GARCILASO DE LA VEGA 1472",
    "ubigeo_code": "150101",
    "department": "LIMA",
    "province": "LIMA",
    "district": "LIMA",
    "is_retention_agent": false,
    "is_perception_agent": false,
    "is_fuel_perception_agent": false,
    "is_good_taxpayer": false
  }
]

Campo	Tipo	Requerido	Descripción
ruc	string	Sí	Número de RUC.
name	string	Sí	Razón social.
status	string	Sí	Estado SUNAT.
condition	string	Sí	Condición SUNAT.

Errores

Códigos de error comunes. La semántica exacta puede variar por endpoint.

Código	Motivo	Descripción
401	Unauthorized	Credenciales inválidas, token inválido o API Key inválida.
403	Forbidden	API Key inactiva o suscripción inactiva.
404	Not Found	Recurso inexistente.
409	Conflict	El usuario ya existe.
429	Too Many Requests	Límite de solicitudes excedido.
500	Internal Server Error	Error interno no esperado (login, registro u otro fallo).