Saltar a contenido

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/docs es 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 /trademarks acepta además una superficie combinada por campos — denomination/holder/representative/taxId/applicationNumber/registrationNumber, multi-valor, semántica AND, matchedFields[] y orden configurable con sort=. 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: null significa fin de los resultados — detente.
  • Una excepción: GET /watch/hits es un feed y devuelve next siempre; ahí el fin es hasMore: 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 respuestas 5xx usan 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 encabezado X-Correlation-ID; puedes suministrar el tuyo propio con ese mismo encabezado de solicitud.
  • errors[] — en un 400, detalla qué campo falló y por qué. ⭐ Un parámetro que la ruta no declara es también un 400 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:

  1. Límites de ráfaga de corto plazo — dos topes de tasa, ambos con HTTP 429 code: "rate_limited" y Retry-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.
  2. Cuota mensual — un presupuesto mensual de solicitudes por clave. Cuando lo agotas, la API devuelve HTTP 429 con code: "quota_exceeded" y un encabezado Retry-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