Saltar al contenido
Español - México
Ir a relbase.pe
  • No hay sugerencias porque el campo de búsqueda está vacío.

relBase API Rest - Primeros pasos

Versión de la API

La plataforma opera actualmente con API v2. Esta versión reemplaza la autenticación por tokens fijos de la v1 por el estándar OAuth 2.0, e incorpora control de acceso por permisos (scopes), respuestas con estructura uniforme e idempotencia en las operaciones de escritura.

La documentación detallada de cada endpoint está disponible en:

https://apidocs.relbase.cl

edited

Autenticación

La API v2 utiliza OAuth 2.0. Ya no se emplean los encabezados company y authorization con tokens fijos que usaba la v1.

Cada integración debe registrar una Aplicación OAuth dentro de la cuenta de la empresa. Esa aplicación entrega las credenciales (client_id y client_secret) con las que se solicitan los tokens de acceso.

PASO 1: Crear la Aplicación OAuth

Ingrese a relBase y diríjase a Mis Aplicaciones para crear una nueva aplicación. Deberá definir:

  • client_id — se genera automáticamente.
  • client_secret — se genera automáticamente y se muestra una sola vez. Guárdelo en un lugar seguro; si lo pierde, deberá regenerarlo.
  • redirect_uri — la URL exacta a la que relBase devolverá al usuario tras autorizar. Puede registrar varias, una por línea.
  • Scopes — los permisos que su integración necesita.
Importante

La redirect_uri se valida de forma estricta. No se admiten comodines ni coincidencias parciales. Diferencias que causan rechazo: una barra final de más (/callback/ vs /callback), el protocolo (http:// vs https://), parámetros adicionales en la URL o puertos explícitos (:443). En producción debe usar https://.

PASO 2: Solicitar la autorización del usuario

Redirija al usuario a la pantalla de autorización de relBase:

GET https://api.relbase.cl/oauth/authorize     ?client_id=SU_CLIENT_ID     &redirect_uri=https://su-app.cl/callback     &response_type=code     &scope=products:read documents:write     &state=valor_aleatorio     &code_challenge=SU_CODE_CHALLENGE     &code_challenge_method=S256
Parámetro Obligatorio Descripción
client_id Sí UID de su Aplicación OAuth.
redirect_uri Sí Debe coincidir exactamente con la registrada.
response_type Sí Siempre code.
scope Sí Scopes separados por espacio.
state Recomendado Valor aleatorio para prevenir ataques CSRF.
code_challenge Recomendado Challenge PKCE generado con SHA-256.
code_challenge_method Recomendado S256. Obligatorio si envía code_challenge.

El usuario inicia sesión, autoriza la aplicación y relBase lo redirige a su redirect_uri con los parámetros code y state.

PASO 3: Intercambiar el código por tokens

curl -X POST "https://api.relbase.cl/oauth/token" \   -d "grant_type=authorization_code" \   -d "client_id=SU_CLIENT_ID" \   -d "client_secret=SU_CLIENT_SECRET" \   -d "redirect_uri=https://su-app.cl/callback" \   -d "code=EL_CODIGO_RECIBIDO" \   -d "code_verifier=SU_CODE_VERIFIER"

Respuesta exitosa (200):

{   "access_token": "...",   "token_type": "Bearer",   "expires_in": 900,   "refresh_token": "...",   "scope": "products:read documents:write",   "created_at": 1711800000 }

PASO 4: Consumir los endpoints

Envíe el token en el encabezado Authorization de cada solicitud:

curl -H "Authorization: Bearer SU_ACCESS_TOKEN" \      -X GET "https://api.relbase.cl/api/v2/productos"

Encabezados disponibles:

Encabezado Uso
Authorization: Bearer Obligatorio en todos los endpoints de negocio.
X-Request-Id Opcional. Permite trazar una solicitud de extremo a extremo ante soporte.
Idempotency-Key Requerido en escrituras de inventario; soportado en webhooks y proveedores. 
PKCE (recomendado)

Se recomienda usar PKCE (Proof Key for Code Exchange) en todas las solicitudes de autorización. El método soportado es S256.

  1. Genere un code_verifier aleatorio de entre 43 y 128 caracteres URL-safe.
  2. Calcule code_challenge = BASE64URL(SHA256(code_verifier)).
  3. Envíe code_challenge y code_challenge_method=S256 en el Paso 2.
  4. Envíe el code_verifier original en el Paso 3.

Si envía code_challenge en la autorización, el code_verifier pasa a ser obligatorio al intercambiar el código.

Vigencia y renovación de tokens
Token Vigencia
access_token 15 minutos (expires_in: 900).
refresh_token No expira por tiempo. Permanece válido hasta ser revocado o rotado.

Para renovar el acceso antes de que expire:

curl -X POST "https://api.relbase.cl/oauth/token" \   -d "grant_type=refresh_token" \   -d "client_id=SU_CLIENT_ID" \   -d "client_secret=SU_CLIENT_SECRET" \   -d "refresh_token=SU_REFRESH_TOKEN_ACTUAL"Rotación obligatoria

Cada renovación devuelve un par nuevo de access_token + refresh_token, y el refresh_token anterior queda revocado de inmediato. Su integración debe guardar siempre el último par recibido. Reutilizar un refresh token ya canjeado producirá un error de autenticación.

Como el refresh_token no caduca por inactividad, no es necesario volver a pedirle autorización al usuario mientras la integración siga activa.

Revocar tokens

Para desconectar la integración o cerrar sesión:

curl -X POST "https://api.relbase.cl/oauth/revoke" \   -d "token=SU_ACCESS_TOKEN_O_REFRESH_TOKEN" \   -d "client_id=SU_CLIENT_ID" \   -d "client_secret=SU_CLIENT_SECRET"

La revocación es idempotente: repetirla no genera error. También puede desactivar la aplicación completa desde Mis Aplicaciones.

Flujos soportados

  • authorization_code (con PKCE recomendado) — para aplicaciones web y clientes públicos que actúan en nombre de un usuario.
  • client_credentials — para integraciones servidor a servidor, sin contexto de usuario.
Permisos disponibles (scopes)

Solicite únicamente los scopes que su integración necesite.

Scope Permiso
users:read / users:write Usuarios: lectura / escritura
products:read / products:write Productos: lectura / escritura
customers:read / customers:write Clientes: lectura / escritura
providers:read / providers:write Proveedores: lectura / escritura
documents:read / documents:write Documentos: lectura / escritura
inventory:read / inventory:write Inventario: lectura / escritura
warehouses:read Bodegas: lectura
deliveries:read / deliveries:write Entregas: lectura / escritura
webhooks:read / webhooks:write Webhooks: lectura / escritura
admin:read Administración: lectura

Si un endpoint requiere un scope que su token no incluye, la respuesta será un error missing_scope.

Empresa activa

En las Aplicaciones OAuth creadas desde relBase, el token ya queda asociado a la empresa correspondiente. En el flujo normal de integración no es necesario realizar ningún paso adicional para seleccionar empresa.

Si necesita consultar los datos de configuración o el detalle de la empresa activa, utilice:

GET /api/v2/profileEstructura de las respuestas

Todas las respuestas JSON de la v2 utilizan un envoltorio uniforme:

{   "data": { },   "meta": {     "code": 200,     "message": "success"   } }
Campo Contenido
data El recurso o la colección solicitada.
meta.code Código lógico o HTTP principal.
meta.message Mensaje resumido del resultado.
meta.debug_info Detalle técnico, útil para soporte e integraciones.

Ante un error de validación, revise meta.message y meta.debug_info: ahí encontrará el motivo específico del rechazo.

Paginación

Los endpoints de listado se paginan y devuelven la información de navegación dentro de meta:

{   "data": [ ],   "meta": {     "code": 200,     "message": "success",     "current_page": 1,     "next_page": 2,     "prev_page": -1,     "total_pages": 8,     "total_count": 94   } }

Los campos next_page y prev_page devuelven -1 cuando no existe página siguiente o anterior respectivamente. Para avanzar, use el parámetro page:

GET /api/v2/productos?page=2Idempotencia

Los endpoints de escritura marcados como idempotentes aceptan el encabezado Idempotency-Key. Repetir una solicitud con la misma clave devuelve la misma respuesta emitida originalmente, en lugar de ejecutar la operación dos veces.

  • La clave se aísla por empresa, usuario y Aplicación OAuth.
  • En inventario es requerida para las escrituras.
  • En webhooks y proveedores es soportada, para integraciones que necesiten reintentos seguros.

Este mecanismo evita duplicados cuando una solicitud falla por timeout o corte de red y su sistema la reintenta.

Límite de solicitudes

La API aplica dos controles independientes: uno de velocidad, por minuto, y una cuota diaria que depende del plan contratado. Ambos responden 429 Too Many Requests al excederse.

1. Velocidad (ventana de 60 segundos)

Situación Límite
Con token OAuth asociado a empresa 300 solicitudes por empresa cada 60 segundos.
Sin token OAuth con empresa resuelta 60 solicitudes por IP cada 60 segundos.

Este control protege la plataforma de ráfagas puntuales. Implemente reintentos con espera progresiva (backoff exponencial) en lugar de reintentar de inmediato.

2. Cuota diaria según su plan

Adicionalmente, cada plan de relBase incluye una cantidad distinta de solicitudes diarias. No es un valor único para todos los clientes: depende del plan que su empresa tenga contratado.

  • El contador se reinicia todos los días a las 00:00 UTC.
  • Al alcanzar el tope, la empresa recibe una notificación por correo y las solicitudes siguientes del día son rechazadas.
  • Los planes Enterprise o personalizados pueden no tener tope diario.

Puede consultar el cupo exacto de su plan y su consumo actual desde relBase, en Mi Cuenta → Consumo de API. Ahí encontrará:

  • El uso del mes en curso y las solicitudes realizadas hoy, con indicador de cuánto le queda disponible.
  • El detalle por categoría (lecturas, escrituras, emisión de DTE, autenticación y configuración de webhooks).
  • La comparativa de planes, desde donde puede contratar o cambiar de plan si necesita más capacidad.

Cómo monitorear su consumo

Cada respuesta de la API incluye encabezados con el estado de su cuota diaria. Léalos en lugar de esperar el error: le permiten ajustar el ritmo de su integración antes de quedarse sin cupo.

Encabezado Contenido
X-RateLimit-Daily-Limit Cupo diario total de su plan.
X-RateLimit-Daily-Remaining Solicitudes que le quedan disponibles hoy.
Retry-After Segundos que faltan para el reinicio del contador (medianoche UTC).

Respuesta al agotar la cuota diaria:

{   "data": null,   "meta": {     "code": 429,     "message": "Cuota diaria de requests de tu plan alcanzada (10000). Sube de plan para más capacidad."   } }

No consulte en bucle: use webhooks

Por lo anterior, no se recomienda el polling — es decir, consultar repetidamente un endpoint para detectar si algo cambió. Una integración que revisa cada pocos segundos si hay documentos nuevos consume la cuota diaria completa sin obtener información nueva la mayor parte del tiempo, y termina agotando el cupo del plan antes del final del día.

En su lugar, utilice webhooks: relBase le notifica a su sistema en el momento exacto en que ocurre el evento, sin que usted deba preguntar.

Polling Webhooks
Consumo de cuota Alto y constante, aunque no pase nada. Mínimo: sólo cuando hay un evento real.
Latencia Depende del intervalo de consulta. Inmediata.
Complejidad Requiere controlar frecuencia y estado. Requiere exponer una URL que reciba el aviso.

Configure sus webhooks con los scopes webhooks:read y webhooks:write. Los eventos disponibles y el formato de cada notificación están documentados en apidocs.relbase.cl.

Cuándo sí consultar

El polling sigue siendo válido para cargas puntuales —una sincronización inicial de catálogo o un reporte diario— no para detectar cambios en tiempo real.

Errores frecuentes
Código Significado Cómo resolverlo
missing_scope El token no incluye el scope que exige el endpoint. Agregue el scope a la Aplicación OAuth y vuelva a autorizar.
company_required El token no resuelve una empresa activa. Verifique que la Aplicación OAuth esté asociada a una empresa.
validation_failed El payload es sintácticamente válido pero falla una regla de negocio. Revise meta.debug_info.
resource_not_found El recurso no existe o no pertenece al contexto actual. Verifique el identificador y la empresa del token.
idempotency_key_missing El endpoint exige Idempotency-Key y no fue enviada. Agregue el encabezado a la solicitud.
feature_not_available_in_country La funcionalidad no está disponible para el país de la empresa. Consulte con soporte la disponibilidad en su país. 
Recomendaciones de seguridad
  • Nunca exponga el client_secret en aplicaciones móviles, código JavaScript del navegador ni repositorios públicos. Para clientes públicos, use authorization_code con PKCE.
  • Utilice siempre el parámetro state y valídelo al recibir el callback.
  • Solicite el mínimo conjunto de scopes necesario.
  • Almacene los tokens cifrados y revoque de inmediato los de integraciones que deje de usar.

Para dudas sobre la integración o apoyo en la migración desde la v1 —recuerde que se deprecará el 31 de diciembre de 2026— escríbanos a contacto@relbase.pe