Inicio rápido

El Client API es la superficie estable de EdTools para integraciones server-to-server: un SIS que sincroniza estudiantes, una tesorería que empuja pagos, un CRM que lee admisiones.

Base: https://app.edtools.co/api/client/v1 · 41 operaciones en 8 recursos · OpenAPI 3.1 en /api/client/openapi.json

Requisitos

El Client API está encendido en el entorno

EDTOOLS_CLIENT_API_ENABLED=1. Para webhooks, además EDTOOLS_CLIENT_WEBHOOKS_ENABLED=1.

La institución tiene el módulo de integraciones

platform_integrations activo, más el módulo funcional del recurso que vas a tocar. Sin esto los endpoints responden 403 MODULE_DISABLED.

Tienes una API key

Se crea en Ajustes → API e integraciones → API Keys. Necesitas el permiso settings.api.manage.

Tu primera llamada

curl https://app.edtools.co/api/client/v1/me \
  -H "Authorization: Bearer $EDTOOLS_API_KEY"

{
  "data": {
    "tenant": { "id": "...", "slug": "colegio-abc", "name": "Colegio ABC" },
    "apiKey": {
      "id": "...",
      "name": "SIS producción",
      "scopes": ["students:read", "students:write"],
      "masterDomains": ["students"],
      "rateLimit": { "requestsPerMinute": 120 }
    },
    "productAccess": {
      "enabledModules": ["platform_integrations", "staff_students"],
      "sorByDomain": { "students": "external_master", "grades": "edtools_master" }
    }
  }
}

/me es la llamada de diagnóstico. Antes de depurar un 403, mira qué te responde: casi siempre la respuesta está ahí — falta un scope, falta un módulo, o el dominio no es tuyo.

Qué puedes tocar

Recurso	Operaciones	Scopes
Students	5	`students:read`, `students:write`
Admissions	9	`admissions:read`, `admissions:write`
Payments	5	`payments:read`, `payments:write`
Vault	15	`vault:read`, `vault:write`
Programs	2	`programs:read`
Courses	2	`courses:read`
Forms	2	`forms:read`
Client API	1	— (`/me`)

Las convenciones que se repiten

Todo viene envuelto en data

Las respuestas de éxito llevan la carga en data. Los errores llevan error con code, message y requestId.

Los listados se paginan con page y limit

Y aceptan updatedSince para sincronización incremental. Pide solo lo que cambió desde tu última corrida.

Los POST exigen Idempotency-Key

Reintentar sin ella duplica recursos. Ver Idempotencia.

Los PUT /external/{externalId} son upserts

Si tu sistema ya tiene un identificador estable, úsalo: sincronizas sin crear duplicados y sin llevar cuenta de los ids de EdTools.

Las escrituras respetan el Source of Record

Un 403 SOR_WRITE_FORBIDDEN no es un problema de permisos del token, es que ese dominio de datos tiene otro dueño. Ver Multi-tenancy.

Con el SDK, en tres líneas

import { EdToolsClient } from '@edtools/client';

const edtools = new EdToolsClient({
  baseUrl: 'https://app.edtools.co',
  apiKey: process.env.EDTOOLS_API_KEY!,
});

const estudiantes = await edtools.students.list({ limit: 20 });

Sigue por Autenticación si vas a configurar el token con cuidado, o por el SDK si trabajas en TypeScript.

Empezar

La plataforma

Client API

Requisitos

Tu primera llamada

Qué puedes tocar

Las convenciones que se repiten

Con el SDK, en tres líneas

​Requisitos

​Tu primera llamada

​Qué puedes tocar

​Las convenciones que se repiten

​Con el SDK, en tres líneas

Requisitos

Tu primera llamada

Qué puedes tocar

Las convenciones que se repiten

Con el SDK, en tres líneas