Documentación

Todo lo que necesitas para integrar nuestras APIs en tu sistema.

Autenticación

Cada llamada lleva tu API Key en la cabecera x-api-key. Una key habilita un solo servicio: si consumes consultas y facturación, necesitas dos.

curl https://api.seia.pe/v1/ruc/20100070970 \
  -H "x-api-key: sk_live_..."

Formato de respuesta

Todas las respuestas tienen la misma forma, tanto en éxito como en error. Ramifica siempre por status, no por el código HTTP.

{
  "status": 1,
  "message": ["Consulta exitosa"],
  "data": { "ruc": "20100070970", "estado": "ACTIVO" },
  "errors": [],
  "request_id": "req_8fc6061c"
}

Límites

Cada respuesta incluye cabeceras con tu situación:

• X-RateLimit-Limit y X-RateLimit-Remaining — velocidad: peticiones por minuto.
• X-Consultas-Limite y X-Consultas-Restantes — volumen: el saldo de tu ciclo actual.

Si agotas el saldo del ciclo recibes un 403 con un mensaje claro. Se repone solo en la siguiente renovación; si lo necesitas antes, sube de plan desde tu panel y se aplica al momento. Sigues con la misma key: ni las renovaciones ni los cambios de plan la tocan.

Pagos pendientes

Si un ciclo se renueva y su recibo queda sin pagar, la API no te corta de golpe: durante unos días sigue respondiendo con normalidad y te avisa en cada respuesta.

• X-Pago-Pendiente, X-Pago-Monto y X-Pago-Dias-Restantes — cuánto se debe y cuántos días quedan antes de la suspensión.

Agotado ese plazo, las peticiones devuelven 402 Payment Required hasta que se valide el pago. Es 402 y no 403 a propósito: el permiso lo tienes, lo que falta es el pago, y así tu integración puede distinguir un caso del otro y avisar a quien corresponda en tu empresa.

Trazabilidad

Toda respuesta trae un request_id. Guárdalo en tus logs: si algo falla, con ese identificador localizamos la petición exacta.