NUEVO 🚀 API REST v2 - Primeros Pasos

Descripción general

La API REST de relBase le permite integrar su sistema de gestión con aplicaciones externas de forma segura y eficiente. Con ella puede crear documentos tributarios electrónicos (DTEs), gestionar productos, clientes, inventario, cotizaciones, compras y mucho más, todo de manera programática.

La documentación completa de cada endpoint está disponible en https://apidocs.relbase.cl/

Importante: La API v1 será deprecada durante este año. Le recomendamos utilizar la API v2 para todas las nuevas integraciones.

Antes de comenzar

Para utilizar la API v2, asegúrese de contar con lo siguiente:

• Una cuenta activa en relBase con un plan que incluya acceso a la API.
• Una aplicación OAuth creada en su cuenta de relBase (consulte la sección siguiente).
• Conocimientos básicos de HTTP y herramientas como curl, Postman o similares.

Crear una aplicación OAuth

Para conectar una aplicación externa con relBase, primero debe crear una aplicación OAuth desde su cuenta:

1. Ingrese a relBase y vaya a Configuración > Más opciones > API v2.
2. Haga clic en Crear aplicación.
3. Complete los campos requeridos:
   • Nombre: un nombre descriptivo para identificar la integración (ejemplo: "Mi ERP", "Tienda Online").
   • URL de redirección (Redirect URI): la URL de su aplicación donde se recibirá el código de autorización.
   • Scopes: los permisos que necesita la aplicación (consulte la tabla de scopes más adelante).
4. Al confirmar, se generarán su Client ID y Client Secret.

Importante: El Client Secret se muestra una sola vez al momento de la creación. Guárdelo en un lugar seguro. Si lo pierde, deberá rotar las credenciales.

Se recomienda crear una aplicación OAuth separada por cada integración que conecte, en lugar de compartir credenciales entre varias aplicaciones.

Autenticación

La API v2 utiliza OAuth 2.0 con el flujo Authorization Code. Este flujo permite que su aplicación obtenga acceso a los datos de relBase en nombre de un usuario autorizado.

 

Paso 1: Redirija al usuario a la pantalla de autorización

Dirija al usuario a la siguiente URL para que autorice el acceso:

GET https://api.relbase.cl/oauth/authorize
  ?client_id=SU_CLIENT_ID
  &redirect_uri=https://su-app.com/callback
  &response_type=code
  &scope=products:read products:write customers:read
  &state=STATE_ALEATORIO

Parámetro	Requerido	Descripción
client_id	Sí	ID de su aplicación OAuth
redirect_uri	Sí	URL registrada donde se recibirá el código. Debe coincidir exactamente con la URL configurada al crear la aplicación
response_type	Sí	Siempre "code"
scope	Sí	Permisos solicitados, separados por espacio
state	Recomendado	Cadena aleatoria para protección contra CSRF. Se devuelve tal cual en el callback

El usuario verá una pantalla de autorización en relBase donde podrá aceptar o rechazar el acceso. Tras autorizar, será redirigido a su redirect_uri con un parámetro code:

https://su-app.com/callback?code=CODIGO_DE_AUTORIZACION&state=STATE_ALEATORIO

Verifique que el valor de state coincida con el que envió en el paso anterior antes de continuar.

Paso 2: Intercambie el código por tokens

curl -X POST "https://api.relbase.cl/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=SU_CLIENT_ID" \
  -d "client_secret=SU_CLIENT_SECRET" \
  -d "code=CODIGO_DE_AUTORIZACION" \
  -d "redirect_uri=https://su-app.com/callback"

Respuesta exitosa:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "abc123def456...",
  "scope": "products:read products:write customers:read",
  "created_at": 1712300000
}

El access_token expira en 15 minutos (900 segundos). Utilice el refresh_token para obtener uno nuevo sin requerir intervención del usuario.

PKCE (opcional, recomendado)

Para mayor seguridad, puede implementar PKCE (Proof Key for Code Exchange) en su flujo de autorización. Esto es especialmente recomendado para aplicaciones móviles o aplicaciones donde el client_secret no puede almacenarse de forma segura.

Genere el Code Verifier y el Code Challenge:

CODE_VERIFIER=$(openssl rand -base64 48 | tr -dc 'a-zA-Z0-9-._~' | head -c 64)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')

Agregue estos parámetros a la URL de autorización (Paso 1):

Parámetro	Descripción
code_challenge	Challenge generado a partir del code_verifier
code_challenge_method	Siempre "S256"

Y agregue el code_verifier al intercambio de tokens (Paso 2):

curl -X POST "https://api.relbase.cl/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=SU_CLIENT_ID" \
  -d "client_secret=SU_CLIENT_SECRET" \
  -d "code=CODIGO_DE_AUTORIZACION" \
  -d "redirect_uri=https://su-app.com/callback" \
  -d "code_verifier=SU_CODE_VERIFIER"

Renovar el Access Token

Cuando el access_token expire, utilice el refresh_token para obtener uno nuevo:

curl -X POST "https://api.relbase.cl/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=SU_CLIENT_ID" \
  -d "client_secret=SU_CLIENT_SECRET" \
  -d "refresh_token=SU_REFRESH_TOKEN"

Importante:

• Cada renovación genera un nuevo par de access_token + refresh_token.
• El refresh_token anterior queda revocado automáticamente.
• Guarde siempre el nuevo refresh_token recibido en la respuesta.

Revocar un Token

Para invalidar un token de forma explícita (por ejemplo, al desconectar la integración):

curl -X POST "https://api.relbase.cl/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=SU_CLIENT_ID" \
  -d "client_secret=SU_CLIENT_SECRET" \
  -d "token=TOKEN_A_REVOCAR"

Realizar su primera solicitud

Una vez que tenga su access_token, inclúyalo en el header Authorization de cada solicitud:

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

Respuesta exitosa:

{
  "data": {
    "resources": [
      {
        "id": 1234,
        "name": "Producto de ejemplo",
        "sku": "SKU-001",
        "price": 15000
      }
    ]
  },
  "meta": {
    "code": 200,
    "message": "success",
    "current_page": 1,
    "next_page": 2,
    "prev_page": -1,
    "total_pages": 10,
    "total_count": 120
  }
}

Scopes y permisos

Los scopes determinan qué operaciones puede realizar su aplicación. Al crear la aplicación OAuth, seleccione únicamente los scopes que necesita.

Scope	Permite
users:read	Consultar usuarios
users:write	Crear y modificar usuarios
products:read	Consultar productos
products:write	Crear, modificar y eliminar productos
customers:read	Consultar clientes
customers:write	Crear, modificar y eliminar clientes
providers:read	Consultar proveedores
providers:write	Modificar y eliminar proveedores
documents:read	Consultar DTEs, cotizaciones y compras
documents:write	Crear DTEs, cotizaciones y compras
inventory:read	Consultar ajustes de inventario
inventory:write	Crear ajustes de inventario (recepción, consumo, toma)
warehouses:read	Consultar bodegas
admin:read	Consultar información administrativa
webhooks:read	Consultar webhooks configurados
webhooks:write	Crear, modificar y eliminar webhooks

Buena práctica: Aplique el principio de mínimo privilegio. Si su aplicación solo necesita consultar productos, solicite únicamente products:read.

Formato de respuestas

Todas las respuestas de la API siguen una estructura estándar con dos campos principales: data y meta.

Recurso individual:

{
  "data": {
    "id": 5678,
    "name": "Cliente S.A.",
    "rut": "76.000.000-K"
  },
  "meta": {
    "code": 200,
    "message": "success"
  }
}

Lista con paginación:

{
  "data": {
    "resources": [ ... ]
  },
  "meta": {
    "code": 200,
    "message": "success",
    "current_page": 1,
    "next_page": 2,
    "prev_page": -1,
    "total_pages": 5,
    "total_count": 50
  }
}

Error:

{
  "data": null,
  "meta": {
    "code": 401,
    "message": "not_authenticated",
    "debug_info": "OAuth token missing, invalid, expired or revoked"
  }
}

Códigos de estado HTTP

Código	Significado	Acción sugerida
200	Solicitud exitosa	—
201	Recurso creado correctamente	—
400	Parámetros inválidos	Revise los parámetros enviados
401	No autenticado	Renueve su access token
403	Permiso insuficiente	Verifique los scopes de su token
404	Recurso no encontrado	Verifique el ID del recurso
422	Error de validación	Revise las reglas de negocio del recurso
429	Límite de solicitudes excedido	Espere según el header Retry-After

Paginación

Las respuestas de listado incluyen metadatos de paginación dentro del campo meta.

Parámetro	Tipo	Descripción
page	Integer	Número de página (por defecto: 1)
per_page	Integer	Cantidad de resultados por página

Ejemplo:

curl -X GET "https://api.relbase.cl/api/v2/productos?page=3&per_page=25" \
  -H "Authorization: Bearer SU_ACCESS_TOKEN"

Campo en meta	Descripción
current_page	Página actual
next_page	Siguiente página disponible (-1 si no hay más)
prev_page	Página anterior (-1 si es la primera)
total_pages	Número total de páginas
total_count	Número total de registros

Para recorrer todos los registros, incremente el parámetro page hasta que next_page sea -1.

Rate Limiting

La API implementa límites de solicitudes para garantizar la estabilidad del servicio.

Tipo	Por segundo	Por minuto
Con token de empresa	5 solicitudes	300 solicitudes
Sin token (por IP)	3 solicitudes	60 solicitudes

Cada respuesta incluye headers informativos sobre el estado del rate limit:

Header	Descripción
X-RateLimit-Limit	Límite de solicitudes del periodo actual
X-RateLimit-Remaining	Solicitudes restantes en el periodo
Retry-After	Segundos de espera (solo cuando se excede el límite)

Si excede el límite, la API responde con código 429. Espere la cantidad de segundos indicada en el header Retry-After antes de reintentar. Se recomienda implementar una estrategia de backoff exponencial: esperar 1 segundo, luego 2, luego 4, luego 8, etc.

Idempotencia

La API soporta solicitudes idempotentes mediante el header Idempotency-Key. Esto evita que una misma operación se ejecute dos veces en caso de errores de red o reintentos.

1. Envíe un header Idempotency-Key con un valor único (por ejemplo, un UUID) en su solicitud POST o PATCH.
2. Si la misma clave se envía nuevamente dentro de 24 horas, la API retorna la respuesta original sin ejecutar la operación de nuevo.

Ejemplo:

curl -X POST "https://api.relbase.cl/api/v2/inventario/recepcion" \
  -H "Authorization: Bearer SU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "warehouse_id": 1, "products": [...] }'

Endpoints que requieren Idempotency-Key:

• POST /api/v2/inventario/recepcion
• POST /api/v2/inventario/consumo
• POST /api/v2/inventario/toma-inventario

En el resto de endpoints el uso es opcional pero recomendado para operaciones de escritura.

Webhooks

Puede registrar webhooks para recibir notificaciones en tiempo real cuando ocurren eventos en relBase, sin necesidad de consultar la API periódicamente (polling).

Consulte los topics disponibles:

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

Registre un webhook:

curl -X POST "https://api.relbase.cl/api/v2/webhooks" \
  -H "Authorization: Bearer SU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://su-app.com/webhooks/relbase",
    "topic": "documents/created"
  }'

Acción	Método	Endpoint
Listar webhooks	GET	/api/v2/webhooks
Crear webhook	POST	/api/v2/webhooks
Actualizar webhook	PATCH	/api/v2/webhooks/:id
Eliminar webhook	DELETE	/api/v2/webhooks/:id

Requiere los scopes webhooks:read y webhooks:write.

Resolución de problemas

Error 401: "not_authenticated"

Causa: El access token es inválido, ha expirado o fue revocado.

Solución:

1. Verifique que el header sea Authorization: Bearer SU_TOKEN (con "Bearer" antes del token).
2. Si el token expiró, utilice el refresh_token para obtener uno nuevo.
3. Si el refresh token también falla, inicie el flujo de autorización nuevamente.

Error 403: "missing_scope"

Causa: Su token no tiene el scope necesario para la operación solicitada.

Solución: Verifique los scopes configurados en su aplicación OAuth e inicie un nuevo flujo de autorización solicitando los scopes correctos.

Error 429: "Too many requests"

Causa: Ha excedido el límite de solicitudes por segundo o por minuto.

Solución:

1. Lea el header Retry-After para saber cuántos segundos esperar.
2. Implemente backoff exponencial en su lógica de reintentos.
3. Reduzca la frecuencia de solicitudes.

Error 422: "validation_failed"

Causa: Los datos enviados no cumplen las reglas de validación del recurso.

Solución: Revise el campo debug_info en la respuesta para identificar qué campo presenta el error.

El token se invalida constantemente

Causa: Cada vez que utiliza un refresh_token, se genera uno nuevo y el anterior se revoca.

Solución: Asegúrese de guardar siempre el nuevo refresh_token que recibe en cada renovación. Si utiliza el token antiguo, la solicitud fallará.

¿Necesita ayuda adicional?

Si después de seguir esta guía tiene dudas o dificultades, contacte a nuestro equipo en contacto@relbase.cl indicando:

• El endpoint al que intenta acceder
• El código de error y el contenido del campo debug_info
• El client_id de su aplicación OAuth (nunca comparta el client_secret)