La API de codecs sirve la biblioteca de codecs y tus propios codecs a personas, scripts y routers con licencia. Úsala para mantener los codecs en control de versiones, para publicarlos desde un pipeline o para probar payloads desde tus propias herramientas.
Las rutas de abajo siguen la forma habitual https://<your host>/tenant/<tenantId>/api/…. Envía una clave de API como Authorization: Bearer <API key>. Consulta REST API basics.
Rutas
| Método y ruta | Permiso | Respuesta |
|---|---|---|
GET /api/iot/lorawan/codecs | Opcional (ver más abajo) | El índice de codecs: { version, scope, codecs: [...], sig: null } |
GET /api/iot/lorawan/codecs/<codecId> | Opcional | Un codec: { id, rev, sha256, scope, document, outputSet } |
GET /api/iot/lorawan/codecs/bundle | Opcional | Todos los codecs con su documento, comprimidos: { version, codecs: [{ id, rev, sha256, scope, document }] } |
GET /api/iot/lorawan/codec-library | Ver codecs | La lista que muestra el panel de codecs (paginada, ordenable, de ambas fuentes) |
POST /api/iot/lorawan/codecs | Gestionar codecs | Publicar un codec nuevo (201) |
PATCH /api/iot/lorawan/codecs/<codecId> | Gestionar codecs | Publicar una nueva revisión de tu codec |
DELETE /api/iot/lorawan/codecs/<codecId> | Gestionar codecs | Eliminar tu codec |
POST /api/iot/lorawan/codecs/<codecId>/test | Ver codecs | Decodificar una trama con un codec guardado |
POST /api/iot/lorawan/codecs/test | Ver codecs | Comprobar un documento de codec y, opcionalmente, decodificar una trama; no se guarda nada |
GET /api/iot/lorawan/codecs/<codecId>/revisions | Ver codecs | Las revisiones del codec |
«Ver codecs» es el permiso para ver los codecs de LoRaWAN y usar el banco de pruebas (por defecto, usuarios). «Gestionar codecs» es el permiso para añadir, modificar y eliminar tus propios codecs (por defecto, administradores).
Quién ve qué en las tres rutas de lectura
| Credencial enviada | Respuesta |
|---|---|
| Ninguna | Solo la biblioteca pública. En caché durante 5 minutos (Cache-Control: public, max-age=300). |
| Una sesión válida o una clave de API con el permiso de ver | La biblioteca más los codecs de tu organización. Sin caché (private, no-store). |
| La solicitud firmada de un router con licencia | La biblioteca más los codecs de la organización del router. |
| Una credencial presente pero incorrecta (cabecera incorrecta, sesión caducada, clave desconocida) | 401 con invalid_credentials, signature_expired o certificate_revoked. Nunca la lista pública. |
| Una credencial válida sin el permiso | 403 |
Filtros y caché
El índice acepta q (búsqueda), vendor, model, oui, fport y scope. Cada respuesta incluye un ETag igual a la versión del índice; envíalo de vuelta en If-None-Match para obtener 304 Not Modified cuando nada haya cambiado.
GET …/codecs/<codecId>?sha256=<fingerprint> solicita una revisión exacta. Un codec retirado responde 410 (codec_withdrawn).
Publicar un codec
POST /tenant/<tenantId>/api/iot/lorawan/codecs
Content-Type: application/json
{ "document": { "id": "t.room-sensor", "title": "…", "vendor": "…", "kind": "layout", "frames": [ … ], "tests": [ … ] } }O copia un codec de la biblioteca:
{ "copyOf": "<library codec id>", "id": "t.my-copy" }La respuesta es 201 { codec, indexVersion }. Los codecs de la biblioteca no se pueden modificar ni eliminar mediante estas rutas: 403 codec_read_only.
Probar una trama
POST /tenant/<tenantId>/api/iot/lorawan/codecs/t.room-sensor/test
Content-Type: application/json
{ "fport": 2, "hex": "0BC4010A32" }fport va de 1 a 255 y hex tiene como máximo 255 bytes. Una trama no válida responde Introduce el FPort (1-255) y el payload como dígitos hexadecimales (como máximo 255 bytes).
Límites de frecuencia
| Solicitante | Límite |
|---|---|
| Sin credencial: índice y codec individual | 60 solicitudes por minuto por dirección |
| Sin credencial: bundle | 6 por hora por dirección |
| Usuarios conectados y claves de API | 240 por minuto; bundle, 30 por hora |
| Routers con licencia | 120 por minuto por certificado de dispositivo |
Al superar un límite, la API responde 429 (Demasiadas solicitudes. Inténtalo más tarde.).
Códigos de error
| Estado | details.reason | Significado |
|---|---|---|
| 404 | — | Codec no encontrado. |
| 409 | codec_exists | Ya existe un codec con este id. Elige otro id. |
| 410 | codec_withdrawn | Esta revisión del codec fue retirada. |
| 403 | codec_read_only | Los codecs de la biblioteca no se editan aquí: guarda una copia y modifica la copia. |
| 422 | codec_format_not_supported | Se envió un decodificador de JavaScript. |
| 422 | codec_tests_failed | Las pruebas de vectores fallaron; se listan los vectores que fallan. |
| 422 | codec_incompatible | La nueva revisión elimina claves o cambia unidades. |
| 422 | codec_model_claimed | Otro de tus codecs cubre este modelo. |
| 422 | codec_choice_unknown | (Cuando un dispositivo o perfil elige un codec) el codec no existe o fue retirado. |
| 401 | invalid_credentials | Las credenciales enviadas con esta solicitud no son válidas. |
Para la API completa de LoRaWAN (gateways, dispositivos, claves, emparejamiento, tramas), consulta la API de LoRaWAN.