Primeros pasos
Tarno expone un contrato de lectura neutral sobre el corpus de marcas de INAPI: una API REST (sin prefijo de versión) más un servidor MCP, ambos respaldados por la misma capa de consultas y los mismos datos. Esta guía te lleva desde cero hasta una primera llamada autenticada contra la API REST.
El esquema completo y siempre actualizado por campo vive en la referencia OpenAPI interactiva en
https://api.tarno.cl/docs(Scalar). Esta guía explica cómo hacer la puesta en marcha y enlaza a esa referencia — no reformula el esquema. Cuando un campo no está documentado aquí,https://api.tarno.cl/docses autoritativo.
1. URL base
La API REST se sirve en https://api.tarno.cl sobre HTTPS. El contrato ya no usa prefijo de versión:
cada recurso vive directamente en la raíz, p. ej. https://api.tarno.cl/trademarks. La referencia
interactiva (Scalar) está en https://api.tarno.cl/docs.
Un puñado de rutas son intencionalmente públicas (no requieren clave):
| Path | Propósito |
|---|---|
/health |
Sonda de liveness / readiness (200 ok / 503 degradado) |
/docs |
Referencia OpenAPI (Scalar) interactiva — https://api.tarno.cl/docs |
/metrics |
Métricas de Prometheus (solo red interna) |
Todas las demás rutas de negocio (p. ej. /trademarks) están protegidas y requieren una clave de API (ver
más abajo y la guía de autenticación).
2. Obtén una clave de API
Las claves de API las emite el operador, fuera de banda, desde el portal de operador. No hay endpoint de registro de autoservicio — tú no creas tu propia clave. Pídele a tu operador una clave de lectura; te entregará una cadena de clave opaca y te dirá qué scopes lleva (la lista completa está en la tabla de scopes). Consulta la guía de autenticación para los scopes, el ciclo de vida (rotar / revocar / expiración) y la semántica exacta de errores.
Guarda la clave como una variable de entorno y nunca la subas al control de versiones:
export TARNO_API_KEY="<API_KEY>" # la clave opaca que te entregó tu operador
Todos los ejemplos de este portal usan el marcador de posición obvio
<API_KEY>. Reemplázalo por tu clave real en tiempo de ejecución; nunca escribas una clave de forma fija en un archivo versionado.
3. Tu primera llamada autenticada: GET /trademarks
Envía la clave en el encabezado de solicitud X-API-Key. GET /trademarks busca o lista resúmenes
de marcas.
curl
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=5" \
-H "X-API-Key: $TARNO_API_KEY"
TypeScript (fetch)
const baseUrl = "https://api.tarno.cl";
const apiKey = process.env.TARNO_API_KEY!; // "<API_KEY>"
const res = await fetch(`${baseUrl}/trademarks?q=cafe&limit=5`, {
headers: {
"X-API-Key": apiKey,
"X-Correlation-ID": "<tu-id-de-correlación>", // opcional; se devuelve en toda respuesta
},
});
if (!res.ok) {
// application/problem+json (RFC 9457)
const problem = await res.json();
throw new Error(`${problem.status} ${problem.code}: ${problem.detail} (requestId=${problem.requestId})`);
}
const page = await res.json(); // { results: Trademark[], limit, next, hasMore, total, meta }
console.log(page.results.length, "results; next =", page.next);
Una respuesta exitosa es una página por keyset:
{
"results": [
{
"applicationNumber": "123456",
"registrationNumber": null,
"denomination": "CAFE EXAMPLE",
"status": "en_tramite",
"statusInapi": null,
"statusStale": false,
"signType": "mixta",
"filedOn": "2023-01-15",
"expiresOn": null,
"publishedOn": "2023-02-01",
"registeredOn": null,
"renewalStatus": null,
"milestones": [],
"score": 0.87
}
],
"limit": 20,
"next": "eyJvIjoyMH0",
"hasMore": true,
"meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" }
}
score es una confianza absoluta de 0 a 1 (la mayor de las señales por canal, no el valor RRF interno, que sólo ordena la lista; por eso puede no bajar de forma monótona) y está presente solo en la ruta de búsqueda
de texto libre (q=); se omite en un listado filtrado simple. ⭐ La búsqueda por texto omite
total: la clave sólo viaja en el lote (applicationNumber=), en la lista sin filtros y en las
listas filtradas con cuenta ≤ 10.000. status y signType son cadenas
con el código (p. ej. "en_tramite", "mixta"), o null. statusInapi y statusStale viajan siempre:
statusInapi es el estado crudo de INAPI sólo cuando difiere de status (si no, null), y statusStale es
true exactamente cuando difieren («INAPI aún no lo ha virado»). Para el conjunto exacto de campos de la marca, consulta la referencia en
https://api.tarno.cl/docs.
4. Filtrado y paginación por keyset
GET /trademarks acepta estos parámetros de consulta:
| Param | Type | Notas |
|---|---|---|
q |
string | Búsqueda de texto libre (full-text + fuzzy). Cuando está presente, los resultados se rankean y llevan score. Omítelo para un listado filtrado simple. |
niceClass |
integer[] | Filtro de clase de Niza, 1–45; admite varias. |
status |
string[] | Códigos de estado (catálogo controlado); admite varios. |
signType |
string[] | Códigos de tipo de signo (catálogo controlado); admite varios. |
filedFrom |
YYYY-MM-DD |
Límite inferior de la fecha de presentación (filedOn >=). |
filedTo |
YYYY-MM-DD |
Límite superior de la fecha de presentación (filedOn <=). |
limit |
integer | Tamaño de página. Por defecto 20, máximo 100. |
cursor |
string | Cursor de keyset opaco (ver más abajo). Trátalo como una caja negra. |
Búsqueda por campos (field-scoped).
GET /trademarksacepta además una superficie combinada por campos —denomination/holder/representative/taxId/applicationNumber/registrationNumber, multi-valor, semánticaAND,matchedFields[]y orden configurable consort=. La documenta la guía de búsqueda por campos.
La paginación se basa en keyset, no en offset. Cada respuesta lleva un cursor opaco next:
- Para obtener la página siguiente, pásalo de vuelta sin cambios como el parámetro de consulta
cursor. next: nullsignifica fin de los resultados — detente.- Una excepción:
GET /watch/hitses un feed y devuelvenextsiempre; ahí el fin eshasMore: false(Vigilancia de parecidos).
# page 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20" -H "X-API-Key: $TARNO_API_KEY"
# page 2 — pass the `next` cursor from page 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20&cursor=<next>" -H "X-API-Key: $TARNO_API_KEY"
Para obtener una marca con sus secciones completas (parties + annotations + encumbrances + classes + norms),
llama a GET /trademarks/{applicationNumber}?expand=parties,annotations,encumbrances,classes,norms
(norms exige además el permiso legal:read; sin él, quítalo de expand):
curl -sS "https://api.tarno.cl/trademarks/123456?expand=parties,annotations,encumbrances,classes,norms" \
-H "X-API-Key: $TARNO_API_KEY"
Un número de solicitud desconocido devuelve 404 not_found.
La familia insights:read (GET /system/freshness, GET /system/sync-runs) está documentada en la
guía de autenticación y en la referencia https://api.tarno.cl/docs.
5. Errores (RFC 9457)
Cada error — validación, autenticación, no encontrado, límite de tasa y errores inesperados del servidor — se
devuelve con el cuerpo application/problem+json de la RFC 9457, con la misma forma en REST y en el MCP:
{
"type": "https://api.tarno.cl/problems/validation_error",
"title": "Request validation failed",
"status": 400,
"detail": "`offset` was withdrawn from the contract: paginate with `limit` + `cursor`",
"code": "validation_error",
"requestId": "74c953c7-24fc-492d-80ed-c6e1b18327fe",
"errors": [ { "field": "offset", "code": "unrecognized_keys", "detail": "…" } ]
}
code— un token estable y neutral sobre el que puedes ramificar (ver la tabla siguiente). Es el contrato.title/detail— descripciones legibles para un humano; su redacción puede cambiar sin ser una rotura. Las respuestas5xxusan un texto genérico y nunca filtran detalles internos.requestId— correlaciona tu reporte con el log del servidor. Es el mismo valor que viaja en el encabezadoX-Correlation-ID; puedes suministrar el tuyo propio con ese mismo encabezado de solicitud.errors[]— en un400, detalla qué campo falló y por qué. ⭐ Un parámetro que la ruta no declara es también un400 validation_error, con una entrada por clave (field= la clave,code: "unrecognized_keys"): la API nunca ignora en silencio lo que no entiende.
| HTTP | code |
Cuándo |
|---|---|---|
| 400 | validation_error |
Consulta / parámetros inválidos (falló la validación de esquemas). |
| 401 | unauthorized |
Clave de API ausente, malformada, desconocida o revocada. |
| 403 | forbidden |
Clave válida, pero le falta el scope que la ruta requiere. |
| 404 | not_found |
Número de solicitud de marca desconocido, o una ruta desconocida. |
| 409 | ambiguous_selector |
La referencia (a un documento de INAPI o a una norma) casa con más de un recurso. |
| 409 | cursor_stale |
El cursor de GET /trademarks/application-numbers es de un corpus anterior (una sincronización empezó o terminó entre páginas): vuelve a empezar sin cursor. |
| 405 | method_not_allowed |
Método HTTP no admitido (el MCP sólo acepta POST). |
| 413 | payload_too_large |
El cuerpo de la petición supera el tamaño admitido. |
| 422 | regla de negocio (p. ej. out_of_coverage) |
La petición es válida y aun así no se puede atender: p. ej. un tramo que el calendario de feriados no afirma cubrir. Nunca se responde con una lista vacía o parcial — ver Calendario de feriados. |
| 429 | rate_limited |
Se excedió el límite de ráfaga de corto plazo (ver más abajo). |
| 422 | application_terminal · watch_limit_reached |
Vigilancia: la solicitud está en estado terminal, o tu organización llegó al tope de su plan — ver Vigilancia. |
| 429 | quota_exceeded |
Cuota mensual agotada (ver más abajo). Lleva Retry-After. |
| 429 | watch_daily_limit_reached |
Tope diario de altas de vigilancia. Lleva limit y resetsAt; sin Retry-After: espera hasta resetsAt. |
| 500 | internal_error |
Error no previsto del servicio; texto genérico, sin detalles internos. |
| 502 | logo_analysis_invalid_output |
El modelo que describe un logo devolvió una salida no válida. |
| 503 | service_unavailable |
Una dependencia no está disponible ahora (la base sin recursos, el almacén de vigilancias, el canal de significado de un semantic, la búsqueda de marcas con todos sus canales caídos…); reintentable. |
| 503 | coverage_not_declared |
El calendario de feriados no declara ningún año cubierto; reintentable. |
| 504 | query_timeout |
Timeout de la consulta/upstream; reintentable. Como todo 5xx, no filtra detalles internos. |
⭐ Un code tiene un solo status, el mismo por REST y por MCP (desde el 2026-09-30, ERR-1). La tabla
vive en el código del servicio y los dos transportes la leen. Hasta esa fecha, un error
de recursos de la base (disco, memoria) era 500 internal_error por REST; ahora es 503 service_unavailable.
6. Límites de tasa y cuota
Dos límites independientes protegen el contrato de lectura:
- Límites de ráfaga de corto plazo — dos topes de tasa, ambos con HTTP 429
code: "rate_limited"yRetry-After: uno por clave (por defecto 300 solicitudes cada 60 s, idéntico en REST y en el MCP) y otro por IP de cliente (por defecto 100 solicitudes / minuto en REST y 30 por segundo en el MCP). Detalle en la guía de autenticación. - Cuota mensual — un presupuesto mensual de solicitudes por clave. Cuando lo agotas, la API devuelve
HTTP 429 con
code: "quota_exceeded"y un encabezadoRetry-After(segundos hasta que la ventana de cuota se reinicia al final del mes). Esta misma cuota aplica de forma idéntica en REST y en el MCP — consulta la guía de MCP.
En toda respuesta autenticada servida viajan los encabezados estándar RateLimit-Limit,
RateLimit-Remaining y RateLimit-Reset, que describen la cuota mensual de la clave (Reset = segundos
hasta el reinicio de fin de mes; una clave sin límite sólo lleva RateLimit-Limit: unlimited). Los 429 de ráfaga y de cuota llevan
Retry-After (el de vigilancia, watch_daily_limit_reached, lleva resetsAt en el cuerpo):
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1209600
{ "type": "https://api.tarno.cl/problems/quota_exceeded", "title": "Rate limit exceeded", "status": 429,
"detail": "Monthly quota exceeded", "code": "quota_exceeded", "requestId": "…" }
Respeta Retry-After: espera el número indicado de segundos antes de reintentar.
Próximos pasos
- Autenticación y scopes —
X-API-Key, la tabla de scopes, ciclo de vida de la clave y la semántica completa de401/403/429. - Conecta tu agente de IA (MCP) — el endpoint
mcp.tarno.cly las herramientassearch_trademarks/get_trademark. - Ejemplos de código — clientes REST y MCP listos para copiar y pegar.
- La referencia OpenAPI en vivo en
https://api.tarno.cl/docs— el esquema autoritativo por campo.