GCContable · API SUNAT

1. Autenticación

Incluye tu API Key en el header de cada petición:

X-API-Key: tu_api_key_aqui

Si no tienes una API Key, contacta a gccontable.es.

2. Ejemplo rápido — Consultar un RUC

curl -X GET "https://gccontable.es/contribuyente/ruc/20603408161" \
     -H "X-API-Key: tu_api_key"

Respuesta exitosa

{
  "success": true,
  "data": {
    "ruc": "20603408161",
    "razonSocial": "EMPRESA EJEMPLO S.A.C.",
    "estado": "ACTIVO",
    "condicion": "HABIDO",
    "direccion": "AV. EJEMPLO 123, LIMA"
  }
}

Respuesta con error

{
  "success": false,
  "error": "Credenciales SUNAT inválidas o expiradas.",
  "sunat": {
    "codigo": "invalid_client",
    "mensaje": "El client_id no existe o la clave es incorrecta."
  }
}

3. Endpoints disponibles

Consulta RUC

Método	Ruta	Descripción
GET	/contribuyente/ruc/{ruc}	Datos básicos de un RUC
GET	/contribuyente/ruc/{ruc}/full	Datos completos (actividad económica, tipo, etc.)
POST	/contribuyente/ruc/lote	Consultar hasta 20 RUCs en paralelo

Tipo de Cambio

Método	Ruta	Descripción
GET	/contribuyente/tipo-cambio/sunat	Tipo de cambio USD/PEN (SUNAT). Param: ?fecha=YYYY-MM-DD
GET	/contribuyente/tipo-cambio/sbs	Tipo de cambio promedio SBS. Param: ?moneda=USD&fecha=YYYY-MM-DD

Validar Comprobante (requiere credenciales SUNAT)

Método	Ruta	Descripción
POST	/contribuyente/{ruc}/validarcomprobante	Valida si un comprobante de pago es válido en SUNAT

SIRE — Registro de Ventas (requiere credenciales SUNAT)

Método	Ruta	Descripción
GET	/contribuyente/sire/periodos?ruc=	Listar periodos disponibles
GET	/contribuyente/sire/ventas?ruc=&periodo=YYYYMM	Registro de Ventas por periodo
GET	/contribuyente/sire/rvie?ruc=&periodo=YYYYMM	RVIE por periodo

GRE — Guía de Remisión Electrónica (requiere credenciales SOL)

Método	Ruta	Descripción
POST	/contribuyente/gre/emitir	Emitir una guía de remisión electrónica
GET	/contribuyente/gre/consultar?serie=&numero=	Consultar estado de una guía
POST	/contribuyente/gre/confirmar	Confirmar recepción de una guía

SSPP — Receptor XML (requiere credenciales SOL)

Método	Ruta	Descripción
POST	/contribuyente/sspp/enviar	Enviar comprobante XML (ZIP en Base64)
GET	/contribuyente/sspp/{identificador}/estado	Consultar estado/CDR de un comprobante enviado

Control Aduanero (requiere credenciales SOL)

Método	Ruta	Descripción
POST	/aduanero/documentossustentatorios	Transmitir documentos digitalizados (PDF en Base64)

Mi Cuenta

Método	Ruta	Descripción
GET	/mi-cuenta/perfil	Ver tu plan, estado y credenciales configuradas
GET	/mi-cuenta/uso	Ver tu consumo de hoy y total por endpoint
PUT	/mi-cuenta/credenciales	Actualizar tus credenciales SUNAT

4. Ejemplos de body

POST /contribuyente/ruc/lote

{ "rucs": ["20603408161", "20478963719", "10456789012"] }

POST /contribuyente/{ruc}/validarcomprobante

{
  "numRuc": "20603408161",
  "codComp": "01",
  "numeroSerie": "F001",
  "numero": "1234",
  "fechaEmision": "2024-01-15",
  "monto": 1180.00
}

POST /contribuyente/sspp/enviar

{
  "ruc": "20603408161",
  "nombreArchivo": "20603408161-01-F001-1234.zip",
  "archivo": "UEsDBAoAAAAAAGR..."
}

5. Códigos de error HTTP

Código	Significado
400	Parámetros inválidos o faltantes
401	API Key inválida o credenciales SUNAT incorrectas
403	Sin permisos para el servicio (RUC no habilitado en SOL)
404	RUC, comprobante o periodo no encontrado
422	Formato de datos incorrecto
429	Límite diario de requests alcanzado
503	SUNAT temporalmente no disponible
504	SUNAT tardó demasiado en responder

6. Documentación interactiva

Prueba todos los endpoints directamente desde el navegador:

→ Swagger UI (/docs)   |   → ReDoc (/redoc)