Organización
La organización se obtiene de la API key, no de un parámetro del cliente. REST exige Starter o Pro activo.
| Método y ruta | Scope | Rol del creador de la clave | Éxito |
|---|---|---|---|
GET /api/v1/organization |
organization:read |
No exige administrador actual | 200 {"data": organización} |
PATCH /api/v1/organization |
organization:write |
Debe seguir siendo administrador actualmente | 200 {"data": organización} |
organization:write también concede lectura. Un scope no sustituye la comprobación de rol en PATCH. No hay PUT, POST ni DELETE para organización.
Parámetros
GET no necesita parámetros. El contrato de lectura común permite id opcional (ID positivo que debe ser el de la organización), include=monthly_hours y from/to (ISO juntos, ordenados, ≤3660 días); no añaden cálculos a esta entidad, por lo que conviene omitirlos.
| Campo JSON de PATCH | Tipo | Requerido | Regla |
|---|---|---|---|
name |
string | No | Nombre no vacío |
default_annual_convention_hours |
entero 1–2500 o null | No | Convenio anual por defecto; null lo deja sin configurar |
Omitir un campo lo conserva; {} conserva ambos. REST también admite attrs (objeto) en lugar de campos planos, sin duplicarlos. No admite slug, plan, facturación, organization_id ni propietario como atributos.
Ejemplos y respuesta
GET /api/v1/organization
Authorization: Bearer <API_KEY>
PATCH /api/v1/organization
Authorization: Bearer <API_KEY>
Content-Type: application/json
{"name":"Equipo Atlas","default_annual_convention_hours":1800}
Respuesta de ejemplo para ambos:
{"data":{"id":1,"name":"Equipo Atlas","slug":"equipo-atlas","default_annual_convention_hours":1800}}
id entero, name y slug strings, convenio entero o null. No incluye datos de suscripción ni facturación. La configuración por defecto interviene en cálculos que no disponen de convenio contractual propio; revisa informes tras cambiarla.
Errores y MCP
400 invalid_params por atributos desconocidos/duplicados o query inválida; 403 forbidden por scope o rol actual insuficiente; 404 not_found para ID de otra organización; 422 validation_error por nombre vacío o convenio fuera de rango. Envelope errors con code, detail y errores de campo si existen. También autenticación/suscripción.
MCP Pro: kordia_get con {"entity":"organization"} sin id; kordia_update_organization con atributos planos. El esquema MCP exige número para convenio y no admite null; usa entero para cumplir la validación del dominio. Miembros e invitaciones tienen scopes separados.