Desarrolladores

Primeros pasos

De cero a la primera respuesta de la API en cinco pasos.

¿Quieres conectar ChatGPT, Claude u otro asistente sin programar? Empieza por Conecta tu IA.

1. Requisito: acceso activado

El acceso a la API lo activa BMC para cada empresa. Mientras no esté activo, el área de cliente no muestra la sección Desarrolladores. Si no la ves, escribe a plataforma@bm.consulting indicando la empresa.

Crear, editar, rotar y revocar tokens lo pueden hacer el titular (OWNER) o un administrador (ADMIN) de la empresa. El resto de usuarios ve la lista, pero no puede cambiarla.

2. Crea un token

  1. Entra en el área de cliente en https://app.bm.consulting/login con tu correo. Te llega un enlace de acceso de un solo uso: ábrelo en el mismo navegador.
  2. Abre Desarrolladores › API y MCP (https://app.bm.consulting/portal/desarrolladores), pestaña Credenciales, y pulsa Crear API token.
  3. Información básica. En Descripción (obligatoria, hasta 64 caracteres) pon para qué es, por ejemplo «Informe mensual de tesorería». En Para qué se usa (opcional) anota qué integración lo usa y quién responde de ella.
  4. Permisos. Elige un nivel por área o, dentro de cada área, por recurso: Ninguno, Leer, Escribir o Full. Con Avanzado eliges acción a acción. Empieza por Leer y añade solo lo que la integración necesite (más sobre permisos).
  5. Despliega Uso del token y completa:
    • Empresas y grupos: de qué empresas verá datos el token. Aparecen las que administras y tienen el acceso a la API activado. Puedes elegir empresas sueltas o Todo el grupo (incluye filiales futuras). Un grupo solo entra si lo eliges: elegir una empresa no añade el resto de su grupo.
    • Cuenta principal (cuota y límites): una de las empresas elegidas, o una del grupo elegido. El token gasta la cuota mensual y los límites por minuto de esa cuenta. No se puede cambiar después; para otra, crea un token nuevo.
    • Caducidad: una fecha. Vacía, el token no caduca.
    • Límites por minuto (Lectura y Escritura): vacíos, 1.200 y 300 (Límites de uso).
    • Cuota mensual propia: tope de llamadas al mes de este token, dentro de la cuota de la cuenta. Vacía, solo cuenta la de la cuenta.
    • IPs permitidas: una IP o rango CIDR por línea. Vacía, vale cualquier IP. Si vas a usar el token con el servidor MCP, déjala vacía.
    • Puede ver datos personales: sin marcar, NIF, IBAN, teléfono, fecha de nacimiento y domicilio salen enmascarados (Autenticación).
  6. Pulsa Crear token y copia el valor, con la forma bmc_live_…: solo se muestra una vez. Confirma con Ya lo he guardado.

Guarda el token en un gestor de secretos o en una variable de entorno. No lo escribas en el código ni lo subas a un repositorio. El mismo token vale para la API REST y para el servidor MCP.

En la lista de Credenciales, cada token tiene un interruptor para desactivarlo y volver a activarlo, y las acciones Editar, Rotar (cambia el secreto al momento; el anterior deja de valer) y Revocar (definitivo). El consumo del mes está en la pestaña Uso de la API.

3. Haz la primera llamada

Esta llamada lista tus contactos. Exige el permiso contacts:contacts.read, así que el token debe tener al menos el nivel Leer en el recurso Contactos.

Variable de entorno
export BMC_TOKEN="bmc_live_…"
curl 
curl -X GET "https://app.bm.consulting/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer $BMC_TOKEN"
TypeScript (fetch) 
const res = await fetch("https://app.bm.consulting/api/v1/contacts?limit=50", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BMC_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Python (requests) 
import os
import requests

res = requests.get(
    "https://app.bm.consulting/api/v1/contacts?limit=50",
    headers={"Authorization": f"Bearer {os.environ['BMC_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()

4. Lee la respuesta

Una respuesta correcta devuelve 200 y un JSON. En esta ruta, la lista viene en contacts junto con los campos de paginación. Si el token no puede ver datos personales, el NIF, el teléfono y el resto de datos personales salen enmascarados.

Respuesta de ejemplo de GET /contacts
{
  "contacts": [
    {
      "id": "…",
      "firstName": "Ana",
      "lastName": "García",
      "fullName": "Ana García",
      "email": "ana@example.com",
      "nif": "A******21",
      "isActive": true
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "pages": 1
}

Si recibes 401, el token no es válido, ha caducado o se ha revocado. Si recibes 403, el token no tiene el permiso de la ruta o la llamada sale de una IP no permitida. Consulta Errores.

5. Identifica tus empresas

Las rutas de contabilidad llevan la empresa en la ruta (/books/{companyId}/…). El companyId es el identificador de la empresa en BMC. Para saber cuáles alcanza tu token, llama a GET /auth/whoami, que no exige ningún permiso: 

curl "https://app.bm.consulting/api/v1/auth/whoami" \
  -H "Authorization: Bearer $BMC_TOKEN"
Respuesta de ejemplo
{
  "token": { "id": "…", "prefix": "bmc_live_…", "name": "Informe mensual de tesorería", "kind": "API" },
  "accountId": "cm…a1",
  "accountIds": ["cm…a1", "cm…b2", "cm…c3"],
  "audience": "client",
  "scopes": ["…"],
  "permissions": ["…"],
  "piiAccess": false,
  "expiresAt": null,
  "groupIds": ["cm…b2"]
}
  • accountId: la cuenta principal del token (cuota y límites).
  • accountIds: todas las empresas que alcanza hoy, la principal primero, con las filiales de los grupos ya incluidas. Cualquiera de ellas vale como companyId.
  • groupIds: los grupos elegidos enteros.

Un companyId fuera de esa lista recibe 403 o 404, sin datos de otra empresa.

Siguientes pasos

URL base: https://app.bm.consulting/api/v1

Email
Contacto