relBase API Rest - Primeros pasos

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

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 1Crear 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.

PASO 2Solicitar 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 3Intercambiar 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 4Consumir 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"

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

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

GET /api/v2/profile

Estructura 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=2

Idempotencia

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

	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.

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.