Saltar a contenido

Búsqueda por campos

Esta guía documenta la superficie de búsqueda field-scoped de GET /trademarks (en MCP, la misma pregunta se hace con search_trademarks): la lista de parámetros, la semántica AND entre campos, la regla q + campos, la normalización de RUT y el orden configurable con sort=.

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 la semántica de la búsqueda combinada y enlaza a esa referencia — no reformula el esquema. Cuando un campo no está documentado aquí, la referencia es autoritativa.

A lo largo de la guía la URL base es https://api.tarno.cl y cada llamada lleva el encabezado X-API-Key — igual que en primeros pasos y autenticación. Usa el scope brands:read.

Qué cubre esta guía

GET /trademarks es una única ruta que combina libremente:

  • Búsqueda de texto — q rankea por los canales de denominación (exact / fuzzy / fonético / semántico, fusionados por RRF).
  • Filtrado por campos — predicados exactos, de rango y de persona (niceClass, status, applicationNumber, holder, taxId, …) que acotan el resultado.

Todos los parámetros presentes se combinan con AND. La respuesta es una página por keyset — el sobre { results[], limit, next, hasMore, total, meta } de primeros pasos.

¿Ya tienes una lista de números de solicitud? Usa GET /trademarks?applicationNumber=a,b,c (hasta 100, una sola unidad de cuota) en vez de N llamadas al detalle. Las marcas vuelven en el orden de la petición, con meta.notFound = los números que no existen. Los demás filtros se aplican sobre el lote (una marca que existe y no casa simplemente no sale; no está en notFound). El lote no pagina ni ordena: limit, cursor, sort, minScore, q, denomination o facets con applicationNumber son un 400.

Parámetros

Todos opcionales. Un parámetro multi-valor se repite (?niceClass=9&niceClass=25) y hace OR dentro del campo; campos distintos hacen AND entre sí.

Param Tipo Multi-valor Notas
q string no Texto libre (FTS español + fuzzy + fonético + semántico, RRF). Hasta 256 caracteres (más ⇒ validation_error); el mismo tope para similarTo.
denomination string no Texto sobre la denominación, mismo motor que q. Hasta 512 caracteres (q admite 256).
applicationNumber string sí Número de solicitud, match exacto. Cada número, hasta 17 caracteres (12 dígitos, guion y un sufijo de serie de hasta 4).
registrationNumber string no Número de registro, match exacto. Hasta 17 caracteres.
holder string sí Substring sobre el titular, insensible a acentos/mayúsculas. Un valor es un nombre entero, con sus comas («PEPSICO, INC.»); varios, repitiendo el parámetro (ver Nombres de parte). Hasta 20 valores de 2 a 256 caracteres, con al menos una letra o dígito (otra cosa ⇒ validation_error); el mismo tope para representative y taxId.
representative string sí Substring sobre el representante. Mismas reglas que holder: una coma no separa valores.
taxId string sí RUT normalizado (ver RUT); match exacto contra titular y representante. Varios, repitiendo el parámetro: una coma no separa valores.
party string sí Parte por id interno (el id de GET /parties?q=) y papel: <id>:holder o <id>:representative. Varios valores se suman (OR); ver Partes por id. Hasta 20 valores.
includeApplicationNumber string sí Solicitudes que se suman a la cartera (OR con los filtros de parte); los demás filtros se les siguen aplicando. Ver Cartera a mano. Hasta 500.
excludeApplicationNumber string sí Solicitudes que se quitan siempre (AND NOT), aunque casen. Ver Cartera a mano. Hasta 500.
relation enum no current (defecto) · former · all — acota holder/representative/taxId/party a la titularidad actual, anterior o ambas.
niceClass integer sí Clase de Niza, 1–45. Hasta 45 valores.
status string sí Código de estado (catálogo controlado). Casa con el estado publicado, que es el derivado (D11): una marca que INAPI aún llama en_tramite pero que ya tiene número de registro sale con status=registrada, y su literal en statusInapi. Hasta 14 valores (los códigos del catálogo).
signType string sí Código de tipo de signo. Hasta 14 valores (los códigos del catálogo) de hasta 20 caracteres (el más largo, combinacion_de_color).
goodsAndServices string no ⭐ Texto de productos y servicios de las clases de la marca, por palabras, sin acentos ni mayúsculas (calzado encuentra «Calzados»). No es igualdad; basta con que case una clase. 2–200 caracteres. -palabra excluye, pero hace falta al menos una palabra que deba aparecer: sólo palabras vacías (de la) o sólo exclusiones (-calzado) es un 400 validation_error.
filedFrom / filedTo YYYY-MM-DD no Rango de fecha de presentación (filedOn).
milestoneFrom / milestoneTo YYYY-MM-DD no ⭐ Marcas con algún hito en el rango (ver Hitos): sin milestoneKind, cualquiera de los cuatro — vencimiento, cierre de oposición, apertura de la renovación o fin de la gracia. milestoneFrom > milestoneTo es 400 invalid_range.
milestoneKind enum sí Acota el filtro de hitos a esos tipos: expiry, opposition_close, renewal_window_open y/o grace_end. Otro valor —también appeal_close, publicado pero no filtrable— es 400. Exige milestoneFrom y/o milestoneTo (sin rango es 400 validation_error).
renewalStatus enum sí ⭐ Sólo las marcas cuyo renewalStatus (ver Hitos), evaluado en la fecha de la respuesta, es uno de not_due · window_open · grace · lapsed · renewed_expiry_pending. Es el mismo valor que trae cada marca devuelta; las de renewalStatus: null no salen por ninguno. Otro valor es 400.
liveOnly boolean no Sólo marcas vivas: excluye las que están en un estado terminal (rechazada, denegada, desistida, abandonada, anulada, caducado, vencida). Una marca sin estado se conserva. Ausente = sin filtro. Se escribe true o false; cualquier otro valor (yes, 1, vacío) ⇒ 400 validation_error.
sort enum no Orden (ver Orden). relevance (defecto) · filedOn:desc/:asc · denomination:asc/:desc · status:asc/:desc (por el estado publicado, el derivado).
limit integer no Tamaño de página. Defecto 20, máximo 100.
cursor string no Cursor keyset opaco.

Un sort fuera del enum, un parámetro malformado o un valor por encima de su tope (más valores o más caracteres de los indicados) devuelve 400 validation_error — también un booleano que no sea exactamente true o false. Un taxId con forma inválida devuelve 400 invalid_rut (ver RUT).

Titulares y representantes en la lista (holders, representatives)

Cada marca de la respuesta lleva holders (nombres de los titulares) y representatives (nombres de los representantes): string[], [] si no hay, nunca null. representatives sólo incluye la relación vigente (rol representante o ambas); no lleva el id de la parte (para eso, GET /trademarks/{n} con parties). Pensado para exportar sin pedir el expediente fila a fila.

holders también es sólo la relación vigente (antes mezclaba titulares anteriores). Los anteriores se piden con includeFormer=true (parámetro opcional, false por defecto; acepta sólo true o false): cada marca trae entonces formerHolders y formerRepresentatives (string[], [] si no hay), aparte de holders y representatives. Sin el parámetro esas dos claves no viajan. Vale igual en GET /trademarks, POST /trademarks/search y search_trademarks, con o sin q, similitud, ventana de oposición o lote. No cambia qué marcas salen (para filtrar por titulares anteriores está relation). El expediente GET /trademarks/{n} no lo necesita: ya separa parties (vigentes) de formerParties.

Hitos (milestones)

Cada marca de la respuesta —y el expediente GET /trademarks/{n}— trae milestones[]: sus fechas con nombre, [] si no tiene ninguna. Cada hito dice de dónde sale (basis): source (un dato que publica INAPI) o derived (un plazo calculado, que lleva siempre su ancla, su regla y su artículo). Ordenados por fecha. Esta es la lista de tipos (las demás guías enlazan aquí):

kind basis qué es ¿filtra?
expiry source la fecha de vencimiento que publica INAPI (field: "expiresOn") sí
opposition_close derived o estimated el cierre de la ventana de oposición: el 30.º día hábil posterior a la publicación del extracto. legalBasis cita las tres normas: Ley 19.039 art. 5 (term), Ley 19.039 art. 11 (business_days) y Ley 19.880 art. 25 (computation, supletoria). Su date es el deadline de oppositionWindow. Si INAPI dejó sin efecto una publicación y republicó el extracto, el ancla es la última publicación (la que INAPI publica como fecha de publicación de la marca; su «Fin de plazo» cae a 30 días hábiles de ella) sí
renewal_window_open derived la apertura de la ventana de renovación: el vencimiento − 6 meses, de fecha a fecha (31-ago − 6 meses = 28-feb). anchor: {kind: "expiry"}, rule: "6_months_before_expiry", legalBasis Ley 19.039 art. 24 (term), Decreto 82/2022 art. 27 (regulation), Código Civil art. 48 (computation; su aplicación es la pregunta 4 abierta al abogado) y Ley 19.880 art. 25 (computation; la misma cuarta norma de grace_end) sí No se publica en renewed_expiry_pending.
grace_end derived o estimated el fin de la gracia de renovación: el vencimiento + 6 meses, de fecha a fecha, y, si ese día cae en sábado, domingo o feriado, el primer día hábil siguiente (el mismo calendario de feriados que opposition_close). rule: "6_months_after_expiry_next_business_day"; legalBasis las mismas cuatro normas que renewal_window_open, la última Ley 19.880 art. 25 (computation: «Cuando el último día del plazo sea inhábil, éste se entenderá prorrogado al primer día hábil siguiente»; INAPI confirmó por escrito que la renovación presentada ese día hábil se tiene por presentada en plazo). estimated con estimateReasons: ["outside_holiday_calendar"] cuando la fecha cae después de la cobertura declarada del calendario de feriados (hoy hasta el 2030-12-31): se saltan los fines de semana y sólo los feriados conocidos, así que el día real es ése o posterior. Sin reserva sí
appeal_close derived ⭐ (44-14) la fecha límite para apelar un RECHAZO (024) o una ACEPTACIÓN PARCIAL (444): el 15.º día hábil ESTRICTAMENTE posterior a la publicación de esa resolución en el Estado Diario. anchor: {kind: "rejection_notice"}, rule: "15_business_days_after_notification", legalBasis Ley 19.039 art. 17 bis B (term), Ley 19.039 art. 11 (business_days) y Ley 19.880 art. 25 (computation). Sólo cuando el 024 o el 444 es el movimiento resolutivo más reciente (entre los dos, el más reciente; a igual fecha, el 024), en día hábil, dentro del calendario declarado y fuera de Madrid; si no, no sale (nunca estimated) y get_deadlines dice por qué — o, con resoluciones posteriores a un 024 o 444 anterior, da la fecha con su aviso (caveat) sin hito no (400)
opposition_response_close derived o estimated ⭐ (2026-10-10) la fecha límite para contestar el traslado de una oposición: el 30.º día hábil ESTRICTAMENTE posterior a la notificación del traslado; improrrogable. anchor: {kind: "transfer_notice", date, annotationId, sectionCode} — el acto del que sale la fecha: la notificación C1 del Estado Diario o, si falta, la resolución de traslado (458, 647, 1197, 1198)—, rule: "30_business_days_after_notification", legalBasis Ley 19.039 art. 9 (term), Ley 19.039 art. 11 (business_days), Ley 19.880 art. 25 (computation) y Decreto 82/2022 art. 24 (regulation: vencido el plazo, «se haya o no evacuado el traslado», el procedimiento sigue — no contestar no es abandono). derived con notificación y resolución el mismo día; estimated si falta una de las dos (notification_inferred_from_resolution_date o transfer_resolution_not_in_corpus). Manda el traslado más reciente. No sale en designaciones de Madrid, traslados anteriores al 2022-05-09, ancla en día inhábil ni fuera del calendario: get_deadlines y get_filing_context dicen por qué no (400)
grant_fee_close estimated ⭐ (2026-10-10) la fecha límite para acreditar el pago de los derechos de concesión: el 60.º día hábil ESTRICTAMENTE posterior a la notificación de la aceptación (029) o de la certificación de ejecutoria (911, 912); sin pago, la solicitud se tiene por abandonada. anchor: {kind: "acceptance_notice" \| "finality_certificate", date, annotationId, sectionCode}, rule: "60_business_days_after_notification", legalBasis Ley 19.039 art. 18 bis E (term), Ley 19.039 art. 11 (business_days) y Ley 19.880 art. 25 (computation). Siempre estimated (estimateReasons: ["anchor_by_office_practice"]) y con reservation {code, text {es, en, pt}}: la ley cuenta los 60 días desde que la resolución queda ejecutoriada; INAPI, desde su notificación; la fecha sigue lo que INAPI aplica. Mostradla con esa reserva. No sale con una aceptación parcial o un fallo de oposición sin certificar, en Madrid, antes del 2022-05-09, en día inhábil ni fuera del calendario: get_deadlines dice por qué no (400)
resolution derived ⭐ (2026-10-26) la fecha en que INAPI resolvió la solicitud —no es un plazo—: el acto de aceptación o rechazo más reciente. date = anchor.date; anchor: {kind: "acceptance" \| "rejection", date, annotationId, sectionCode}, rule: "latest_acceptance_or_rejection", legalBasis Ley 19.039 art. 13 (notification: la resolución se notifica por el Estado Diario). Aceptación: 029, 444, 484, 485, W146, W151, W152, W147, la sección M4 del Estado Diario y los actos que cumplen un fallo del TDPI que otorga el registro (915, 916, 918, 919, 921, 922, W150, W149); rechazo: 024, 486, W160, W148 y la sección M6. A igual fecha, el código antes que la sección. No sale (nunca null) si la solicitud no llegó a resolverse (428 «tener por no presentada», desistida o abandonada antes de resolver), si después un acto del TDPI la altera sin decir hacia dónde (920, 743, W126) o en un expediente de renovación (W390, 539, 706, 632, 961, 540) no (400)
designation_ceased derived ⭐ (2026-10-28) la fecha en que INAPI dio por cesada la protección de una designación Madrid tras una notificación DEATH de la OMPI —no es un plazo—. date = anchor.date; anchor: {kind: "office_cessation", date, annotationId, sectionCode} con el último cese: 1238 (renuncia a Chile), 1240 (cancelación), 1241 (falta de renovación) o 1242 (dependencia de la marca de base); el 1237 (transferencia parcial) no extingue. rule: "office_cessation_after_wipo_death", legalBasis Protocolo de Madrid arts. 6.3, 6.4 y 9 bis y Reglamento Común reglas 25 y 27 (papel extinction). Sale exactamente cuando la marca publica status: caducado por ese cese (crudo registrada o denegada, cese posterior al último DEATH y al último PROLONG, sin inscripción del registro posterior). ⭐ (2026-11-04) También cuando la cancelación de la OMPI (DEATH) llegó durante el trámite e INAPI concedió después (crudo registrada, DEATH anterior a la concesión y al vencimiento, sin PROLONG, BIRTH, CORRECTION, cese ni serie adicional en su día o después): date = anchor.date = el DEATH, anchor: {kind: "wipo_death", date, annotationId, sectionCode: "MAD01"}, rule: "wipo_death_received_before_grant", la misma legalBasis no (400)

legalBasis es una lista de {norm, article, role}. opposition_close es derived cuando se puede afirmar, y estimated —misma forma, más estimateReasons— cuando no:

  • published_on_non_business_day — publicada en sábado, domingo o feriado (la ley no dice desde qué día se cuenta entonces); se cuenta desde el primer día hábil posterior;
  • outside_holiday_calendar — el tramo publicación → cierre cae fuera de la cobertura declarada del calendario de feriados (meta.coverage de GET /holidays, hoy 2013-2030 — ver Feriados); sólo se descuentan fines de semana y los feriados conocidos, así que el cierre real cae ese día o después.

oppositionWindow lleva la misma legalBasis y, si es estimado, los mismos estimateReasons. Una marca sin fecha de publicación no tiene opposition_close: no hay ancla.

Los dos hitos de renovación sólo existen en las marcas registrada o esperando_renovacion nacionales con vencimiento desde el 2022-05-09 (la regla vigente del art. 24). Con ellos viaja renewalStatus, en cada marca de la respuesta y en el expediente, evaluado en la fecha de la respuesta (hora de Chile):

renewalStatus cuándo (V = vencimiento publicado)
not_due antes de V − 6 meses
window_open de V − 6 meses a V, ambos incluidos
grace después de V y hasta la fecha de grace_end, incluida (V + 6 meses, o el primer día hábil siguiente si ése es inhábil): el registro sigue vigente y aún puede renovarse
lapsed pasada la gracia
renewed_expiry_pending en lugar de window_open, grace o lapsed, antes o después de V: la marca tiene una concesión de renovación (un renewals[] de kind: "grant") fechada desde V − 6 meses y ya llegada — INAPI ya renovó y el vencimiento publicado es el anterior, pendiente de actualizar; la marca no publica renewal_window_open ni grace_end, y vuelve a la regla en cuanto se actualiza el vencimiento
null la regla no se aplica: sin fecha de vencimiento (nunca un estado deducido), ni registrada ni esperando_renovacion, o vía Madrid (número de 9 cifras)

Vencimientos anteriores al 2022-05-09 siguen el art. 24 antiguo: window_open hasta V, grace hasta el 30.º día hábil siguiente, lapsed después, y sin hitos. renewalStatus describe el plazo para pedir la renovación. ⭐ En grace el registro está vigente: caduca por falta de renovación sólo si vence la gracia sin que se pida la renovación (Ley 19.039 art. 24 inc. 2º), lo renovado rige desde el vencimiento sin hueco (Decreto 82/2022, art. 27 inc. 2º) y la caducidad no es retroactiva (Directrices de INAPI, cap. 23). INAPI cita los registros en gracia como obstáculo del art. 20 h igual que los vigentes. ⚠ lapsed no dice que no se pidiera la renovación (una renovación concedida mueve el vencimiento publicado). La regla completa, con sus artículos, está en la descripción de renewalStatus de la referencia OpenAPI en https://api.tarno.cl/docs.

El filtro de hitos se aplica en la colección, la búsqueda, el lote, la similitud, la ventana de oposición y /insights, y lo mismo el filtro renewalStatus. Sin milestoneKind casa cualquiera de los cuatro tipos ([BEH]: hasta el 2026-09-25 no miraba las dos fechas de renovación). Los tipos de renovación casan exactamente la fecha que publica la marca: una del régimen anterior, de Madrid o que no esté registrada ni esperando_renovacion nunca sale por ellos, aunque su vencimiento ± 6 meses caiga en el rango. El filtro por cierre devuelve exactamente las marcas cuyo opposition_close publicado —derivado o estimado— cae en el rango: se traduce a cotas sobre la fecha de publicación (una sola consulta, sin tope de rango).

# «¿Cuáles de esta lista están en gracia?» — UNA llamada; cada marca devuelta trae renewalStatus = "grace".
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1171492,1181941,1198902&renewalStatus=grace" \
  -H "X-API-Key: $TARNO_API_KEY"

# «¿A cuáles se les abre la ventana de renovación el mes que viene?»
curl -sS "https://api.tarno.cl/trademarks?milestoneKind=renewal_window_open&milestoneFrom=2026-10-01&milestoneTo=2026-10-31" \
  -H "X-API-Key: $TARNO_API_KEY"
# → p. ej. 1257468 OXIBLOCK: renewal_window_open 2026-10-30 (vence 2027-04-30), renewalStatus "not_due"
# «¿Qué marcas de esta lista tienen un hito en los próximos 30 días, y cuándo?» — UNA llamada con el lote de 100.
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1672581,1712345,1720001&milestoneFrom=2026-09-24&milestoneTo=2026-10-24" \
  -H "X-API-Key: $TARNO_API_KEY"
# → results[].milestones = [{ "kind": "expiry", "date": "2026-10-10", "basis": "source", "field": "expiresOn" }]
# El cierre de la ventana de oposición de una marca publicada el viernes 2026-08-14 (1648329):
curl -sS "https://api.tarno.cl/trademarks/1648329" -H "X-API-Key: $TARNO_API_KEY"
# → milestones = [{ "kind": "opposition_close", "date": "2026-09-28", "basis": "derived",
#                   "anchor": { "kind": "publication", "date": "2026-08-14" },
#                   "rule": "30_business_days_after_publication",
#                   "legalBasis": [ { "norm": "Ley 19.039", "article": "5",  "role": "term" },
#                                   { "norm": "Ley 19.039", "article": "11", "role": "business_days" },
#                                   { "norm": "Ley 19.880", "article": "25", "role": "computation" } ] }]
# → oppositionWindow.deadline = "2026-09-28", con el mismo legalBasis

# «¿Qué marcas cierran su ventana de oposición la semana que viene?» — UNA llamada.
curl -sS "https://api.tarno.cl/trademarks?milestoneKind=opposition_close&milestoneFrom=2026-09-28&milestoneTo=2026-10-04" \
  -H "X-API-Key: $TARNO_API_KEY"
# → cada marca trae en milestones[] su opposition_close entre el 28-09 y el 04-10

El core publica las fechas; no avisa a nadie. A quién y cuándo avisar (30 días antes, 7, el día) lo decide tu aplicación.

Avisos del expediente (notices)

Algunas marcas traen en la ficha (GET /trademarks/{applicationNumber} ≡ get_trademark) y en su informe una lista notices[]: hechos comprobados a mano en el expediente de INAPI y en el Registro Internacional de la OMPI que las fuentes públicas no traen. Un aviso no decide nada más: status, statusInapi, statusStale y milestones[] los deciden las anotaciones del corpus. La clave se omite (no viaja como [] ni null) en toda marca sin aviso, que son casi todas.

campo qué dice
kind wipo_designation_ended: la OMPI inscribió en el Registro Internacional que Chile ya no está designado · wipo_refused_recording: la OMPI no inscribió la declaración de concesión de protección de INAPI (regla 18ter.1 del Reglamento Común), porque Chile no figura entre las Partes Contratantes designadas
date la fecha del hecho: la del acto de la OMPI, la inscripción o el aviso de rechazo (source.recordedOn)
cause sólo en wipo_designation_ended; lo que inscribió la OMPI: renunciation (renuncia a la designación de Chile), cancellation, dependency (cancelación por dependencia de la marca de base, art. 6.4 del Protocolo de Madrid), non_renewal
label el aviso en es-CL, en y pt-BR
source la fuente principal: la inscripción de la OMPI (kind: "wipo_record"), con reference (RNN/2024/11, CBN/2025/15, o GP-I/2135499301/BB en un aviso de rechazo), recordedOn, internationalRegistrationNumber y madridMonitorUrl (el registro en Madrid Monitor; null si no se anotó el número)
corroboration el respaldo: el documento del expediente de INAPI (kind: "inapi_expediente_document") con documentIndex (su posición en el índice del expediente), label y date; null si no se anotó

Un aviso no decide el status ni los hitos: los deciden las anotaciones del corpus. Una designación Madrid que INAPI concedió después de recibir la cancelación de la OMPI durante el trámite publica caducado con el hito designation_ceased (ver Hitos), y el aviso se queda al lado con su fuente; lo mismo si INAPI dicta el cese. Una marca puede traer los dos avisos, en orden de fecha.

// GET /trademarks/991718309  (extracto)
{
  "status": "caducado",
  "statusInapi": "registrada",
  "statusStale": true,
  "notices": [{
    "kind": "wipo_designation_ended",
    "date": "2024-02-15",
    "cause": "renunciation",
    "label": { "es-CL": "La OMPI inscribió en el Registro Internacional que Chile ya no está designado. …", "en": "…", "pt-BR": "…" },
    "source": {
      "kind": "wipo_record",
      "reference": "RNN/2024/11",
      "recordedOn": "2024-02-15",
      "internationalRegistrationNumber": "1718309",
      "madridMonitorUrl": "https://www3.wipo.int/madrid/monitor/en/showData.jsp?ID=ROM.1718309"
    },
    "corroboration": {
      "kind": "inapi_expediente_document",
      "documentIndex": 11,
      "label": "Madrid OD - Notificación de OMPI tipo DEATH",
      "date": "2024-02-15"
    }
  }]
}

Series de un registro de Madrid

Un registro internacional (Protocolo de Madrid) puede tener más de una serie en Chile. INAPI trata cada serie adicional como una solicitud aparte y la numera con el número de la primera más un sufijo (991652209 y 991652209-2). El contrato hace lo mismo: cada serie es una marca más, con su número de registro, sus clases, sus fechas y su historial, y se pide por su propio número.

campo dónde qué dice
baseApplicationNumber en una serie adicional: colección, búsqueda, similitud, lote, marcas de una parte, informes y ficha el número de solicitud de la serie 1 del mismo registro (991652209)
seriesSuffix igual el sufijo, tal como lo escribe INAPI (2, A). applicationNumber = baseApplicationNumber + - + seriesSuffix
relatedSeries[] en la ficha (GET /trademarks/{applicationNumber} ≡ get_trademark) de cualquier serie de un registro del que el corpus tiene varias las otras series, la serie 1 primero: applicationNumber, seriesSuffix (null en la serie 1), registrationNumber, status, classes y registeredOn

Los tres campos se omiten (no viajan como null) en cualquier otra marca: una marca que no forma parte de un registro con varias series responde exactamente lo mismo que antes.

  • En búsquedas, similitud, lote y cartera la marca sale una vez por serie, cada una con sus clases y su número de registro. Buscar por el número de registro de una serie adicional la encuentra a ella.
  • En el calendario de renovación sale una sola línea por registro: el registro vence una vez y se renueva una vez, así que una serie adicional nunca tiene fila propia. Hoy, además, las marcas de la vía Madrid no publican hitos de renovación (ver arriba).
  • Pedir el número base (991652209) devuelve la serie 1, como siempre (salvo el caso del expediente con letra, más abajo). Pedir 991652209-2 devuelve la serie 2. No quites el sufijo al normalizar un número: atribuirías la serie 2 a la serie 1.
  • Que falte relatedSeries dice que el corpus no tiene otra serie de ese registro, no que INAPI no la tenga: una serie todavía en trámite puede no estar cargada.
  • El sufijo puede ser una letra (991866300-A, -B…): es el expediente que INAPI abre cuando una parte del registro cambia de manos (transferencia parcial). Se sirve igual, como una marca más, con su titular, sus clases y su historial. En la mayoría de los casos la marca viva es la de la letra y el número base queda con su propio estado (a menudo denegada o cesada): antes de dar por perdida una marca de Madrid, mira relatedSeries.
  • Un registro que en Chile sólo tiene el expediente con letra. Algunos registros internacionales nunca designaron a Chile con su número base: en Chile sólo existe el expediente con letra (<base>-A), que es como INAPI lo lista. Esa marca se publica con el número con letra (baseApplicationNumber = el base, seriesSuffix = la letra, sin relatedSeries) y pedir el número base la encuentra igual: GET /trademarks/{applicationNumber} ≡ get_trademark, /deadlines ≡ get_deadlines y /annotations ≡ list_trademark_annotations responden 200 con la marca con letra (mira su applicationNumber), no 404. El lote por número (GET /trademarks?applicationNumber=…), la búsqueda y la vigilancia no reconocen ese número base: usa allí el número con letra. Los actos del Estado Diario que el boletín imprime con el número base quedan en esa marca.
  • Los actos del Estado Diario de una serie adicional aparecen en la serie 1: el boletín imprime sólo el número base. El historial propio de la serie viene de la ficha de expediente de INAPI.
  • Una serie se puede vigilar por separado, con sus propias clases.
curl -sS "https://api.tarno.cl/trademarks/991652209" -H "X-API-Key: $TARNO_API_KEY"
# → "applicationNumber": "991652209", "registrationNumber": "1433511", …
#   "relatedSeries": [{ "applicationNumber": "991652209-2", "seriesSuffix": "2",
#                       "registrationNumber": "1500507", "status": "registrada",
#                       "classes": [35], "registeredOn": "2026-06-23" }]

curl -sS "https://api.tarno.cl/trademarks/991652209-2" -H "X-API-Key: $TARNO_API_KEY"
# → "applicationNumber": "991652209-2", "baseApplicationNumber": "991652209", "seriesSuffix": "2", …
#   "relatedSeries": [{ "applicationNumber": "991652209", "seriesSuffix": null, … }]

Semántica AND

Todos los parámetros presentes se combinan con AND. Cada campo acota más el resultado:

# Marcas en clase 9 O 25 (OR dentro del campo), Y cuyo titular contenga "sonda",
# Y presentadas desde 2020 (AND entre campos).
curl -sS "https://api.tarno.cl/trademarks?niceClass=9&niceClass=25&holder=sonda&filedFrom=2020-01-01" \
  -H "X-API-Key: $TARNO_API_KEY"
  • OR dentro de un campo multi-valor: ?niceClass=9&niceClass=25 = clase 9 o 25.
  • AND entre campos distintos: añadir holder= acota a los que además cumplen ese predicado.

Nombres de parte: una coma no separa

holder, representative y taxId son texto libre, y un nombre de parte lleva comas, puntos, & y comillas («PEPSICO, INC.», «MARS, INCORPORATED», «SARGENT & KRAHN»). Por eso una coma nunca separa valores en estos tres parámetros: el valor viaja entero, con sus signos. Para varios nombres (OR), repite el parámetro; en el cuerpo de POST /trademarks/search y en MCP, un elemento del array por nombre.

# Las marcas de «PEPSICO, INC.» O de «MARS, INCORPORATED» (codifica cada valor: la coma viaja como %2C)
curl -sS -G "https://api.tarno.cl/trademarks" \
  --data-urlencode "holder=PEPSICO, INC." --data-urlencode "holder=MARS, INCORPORATED" \
  -H "X-API-Key: $TARNO_API_KEY"
  • Se recortan los espacios de los extremos y los espacios seguidos cuentan como uno.
  • Un valor vacío o sólo de espacios, uno de menos de 2 caracteres o uno sin letra ni dígito (holder=%) es 400 validation_error — nunca «sin filtro».
  • Codifica cada valor: en un querystring un + sin codificar es un espacio (BAUSCH + LOMB viaja como BAUSCH%20%2B%20LOMB).
  • Para una parte concreta, sin subcadenas, usa su id: Partes por id.
  • Las demás listas (niceClass, status, applicationNumber, party, includeApplicationNumber…) son números, ids o vocabulario cerrado y siguen admitiendo a,b.

q es un conjunto de candidatos, no un predicado

Cada canal de q (exacto, fuzzy, fonético, semántico) devuelve como máximo sus 200 mejores candidatos y el resultado es la fusión de ellos. Con un término común (q=cosme casa más de 200 marcas) la respuesta es, por tanto, una muestra de los mejores candidatos, no todas las marcas que casan.

Los filtros que acotan (filedFrom, niceClass, status, …) se aplican dentro de cada canal, antes del tope de 200: con filtro obtienes los mejores candidatos del filtrado, no los de q sola recortados después. Consecuencias que conviene no suponer:

  • q & filtro no es un subconjunto de q: el filtro puede traer marcas que q sola no devolvía porque quedaban fuera del tope. Medido (2026-10-14): q=cosme ⇒ 553 marcas; q=cosme&filedFrom=2020-01-01 ⇒ 566, 359 de ellas ausentes de la primera.
  • meta.estimatedTotal es el tamaño de ese conjunto de candidatos (cota inferior, nunca el total del corpus que casa). Es exacto respecto a lo que se pagina en esa consulta, pero dos consultas con y sin filtro no son comparables entre sí: un total mayor con filtro no significa que el filtro ampliara la búsqueda.
  • Para contar o recorrer todas las marcas que cumplen un criterio, usa el listado por campos (sin q).

Regla q + campos

q se descarta solo cuando llega junto con un campo competidor de texto/identidad —denomination, applicationNumber o registrationNumber—: entonces manda la búsqueda combinada por campos. Los filtros de acotar (niceClass, status, signType, filedFrom/To, holder, representative, taxId) no descartan q: lo mantienen y solo lo acotan con AND.

  • ?q=cafe ⇒ búsqueda de texto clásica (rankea por relevancia, lleva score).
  • ?q=cafe&niceClass=43 ⇒ q se mantiene; el resultado es «marcas café en clase 43».
  • ?q=cafe&denomination=nescafe ⇒ q se descarta (llegó un campo competidor); manda denomination=.
  • Para buscar por denominación dentro del modo avanzado, usa denomination= (no q=).

Orden y sort=

sort= elige el orden; explícito manda siempre. Sin sort=, con texto es relevance (RRF) y sin texto filedOn desc. Las marcas con filedOn nulo quedan al final. Un sort fuera de la lista devuelve 400 validation_error.

Cada elemento de results[] trae las cuatro fechas por las que se puede ordenar y filtrar: filedOn, publishedOn, registeredOn y expiresOn (YYYY-MM-DD o null), las mismas que la ficha (GET /trademarks/{applicationNumber} ≡ get_trademark). Así se puede mostrar y comprobar el orden recibido sin pedir la ficha de cada marca.

La lista de campos ordenables y su paginación exacta está en la referencia https://api.tarno.cl/docs — no se duplica aquí.

matchedFields[]

Cada elemento de results[] puede incluir matchedFields[], que responde a «¿por qué apareció esta marca?». Cada entrada es { field, kind } (field = campo que matcheó; kind = canal: exact, fuzzy, phonetic, semantic). field es el nombre del filtro que hizo salir la marca: denomination, applicationNumber, registrationNumber, holder, representative o taxId (y highlight.field es denomination). Se omite cuando no hay match de identidad/texto (p. ej. un listado puro por ?niceClass=9). Es aditivo: un cliente que no lo lea sigue funcionando igual.

Parecido y términos genéricos: el canal distinctive

Con similarTo (texto libre), el motor de parecido suma un cuarto canal, distinctive. Busca por el elemento distintivo del texto: lo que queda al quitar los términos genéricos en las clases pedidas y al separar las palabras pegadas. Existe por un caso real: «ALTODESEMPEÑO CONSULTORES» en la clase 35 sólo encontraba marcas con «CONSULTORES» y no veía «MAS DESEMPEÑO».

Qué se trata como genérico:

  • Lista curada neutral, con fuente y fecha de revisión en cada entrada (versión 2026-09-28): conectores (de, la, the…), formas societarias (ltda, s.a., spa sólo al final y nunca en las clases 3 y 44…), gentilicios, dominios, y palabras de comercio (clases 35 y 25) o de servicios profesionales (35 y 42).
  • Frecuencia en la clase: una palabra que llevan al menos max(50, 0,75 %) de las marcas de la clase (p. ej. «cafe» en la 43, «clinica» en la 44).
  • Palabras pegadas: «altodesempeno» ⇒ «alto» + «desempeno», sólo si la palabra entera no es del corpus y las dos partes sí.

El descuento es declarado. Cuando el canal corre, las marcas que trajo llevan distinctive en matchedBy, y meta publica genericTerms (cada término con sus motivos), distinctiveCore (lo que se buscó) y decompounded. signals y score no cambian: siguen midiendo el texto entero.

Cuándo no corre. Si no hay nada que descontar, si sólo quedan términos genéricos o si lo que queda tiene menos de 3 letras (p. ej. «AB CONSULTORES» ⇒ «ab», que se parece a cualquier cosa), el canal no corre: la respuesta es exactamente la de antes y las tres claves no viajan. Tampoco corre si falla (se registra y la búsqueda sigue con los otros canales). La vigilancia de parecidos no lo usa (está desactivado en ella).

Cuánto pesa en el orden. En la fusión, el canal distintivo pesa 2 (los canales semántico y léxico pesan 1, el fonético 2). El peso se calibró el 2026-09-29 con el corpus real: 32 casos medidos en producción. Es el menor peso con el que las 19 marcas que debían salir entran en el grupo del informe de disponibilidad, sin colar marcas ajenas en las 20 primeras de los 13 casos de control. Con 2, «MAS DESEMPEÑO» sale 32.ª para «ALTODESEMPEÑO CONSULTORES» (antes, con 1,5, salía 77.ª).

Latencia. Cuando hay términos genéricos que descontar, el canal añade del orden de 0,7 s a la respuesta (medido en producción el 2026-09-28: ~0,73–0,79 s en caliente y ~1 s la primera vez por clase). Sin términos genéricos no añade nada.

⛔ Que una palabra sea genérica no es un veredicto sobre su registrabilidad: es cómo el motor decide qué buscar, y se dice.

RUT: normalización e invalid_rut

El parámetro taxId matchea exacto contra el RUT de titular y representante. El servidor normaliza el valor antes de comparar, así que acepta los tres formatos:

Entrada Se normaliza a
76.123.456-7 76123456-7
761234567 76123456-7
76123456-7 76123456-7

⭐ Un taxId bien formado cuyo dígito verificador no calcula ya no es error: devuelve un resultado vacío (el corpus guarda personas cuyo RUT no pasa el DV). Un taxId cuya forma no es la de un RUT (letras en el cuerpo, o DV fuera de 0–9/K) devuelve 400 invalid_rut — idéntico en REST y MCP.

⭐ partyRole (desde el 2026-09-28) limita el taxId a un papel: holder (titular) o representative (representante). Sin partyRole, el RUT casa con los dos papeles, como siempre; con relation se combina (p. ej. partyRole=representative&relation=former: las marcas que ese RUT representó). partyRole sin taxId es 400 validation_error, idéntico en REST y MCP.

curl -s "$TARNO_BASE_URL/trademarks?taxId=76.086.428-5&partyRole=representative" -H "X-API-Key: $TARNO_API_KEY"

⭐ RUT de personas naturales. Hoy el RUT de toda parte se publica entero y taxId encuentra a cualquiera. El servicio puede pasar a un modo, que se avisará antes en el changelog, en el que el taxId de una parte cuyo kind no es legal viaja ofuscado (***678-5: los 3 últimos dígitos del cuerpo y el dígito verificador) y el filtro taxId sólo encuentra personas jurídicas (el RUT de una natural da una respuesta vacía, no un error). Ese modo se reconoce por meta.naturalPersonTaxId: "masked" en toda colección; si la clave no está, nada cambia.

Partes por id

party=<id>:<papel> filtra por la identidad de la parte, no por su nombre: no arrastra marcas de partes de nombre parecido y sirve también para partes sin RUT (extranjeras). El id es el de GET /parties?q= ≡ list_parties; el papel, holder (titular) o representative (representante).

  • Varios valores se suman (OR): salen las marcas en las que alguna de esas partes tiene ese papel. party se combina con AND con los demás filtros (niceClass, status, fechas…).
  • El papel significa lo mismo que en GET /parties/{id}/trademarks?role=: una parte inscrita a la vez como titular y representante cuenta para los dos, y relation elige vínculos actuales (defecto), anteriores o todos. party=<id>:representative devuelve las mismas marcas que GET /parties/{id}/trademarks?role=representative, ahora con filtros, orden, facetas y cursor.
  • Repetible o separado por comas, hasta 20 valores. Un valor sin la forma <id>:<papel> o más de 20 es 400 validation_error, idéntico en REST y MCP. Un id que no es de ninguna parte no casa con ninguna marca.
  • Vale también en POST /trademarks/search (con similarTo/similarToTrademark), en /insights/trademarks y en el calendario de renovación; con oppositionWindow es un 400.
curl -s "$TARNO_BASE_URL/trademarks?party=306948:representative&party=1234:holder&niceClass=25" -H "X-API-Key: $TARNO_API_KEY"

Cartera a mano: incluir y excluir solicitudes

Una cartera es lo que dicen sus filtros de parte, más unas solicitudes añadidas a mano, menos otras quitadas a mano; sobre eso se aplican los filtros del listado:

resultado = ((ámbito de cartera ∪ includeApplicationNumber) − excludeApplicationNumber) ∩ demás filtros
  • El ámbito de cartera son los filtros de parte: party, holder, representative y taxId (con partyRole), con su relation. Entre ellos siguen combinándose con AND, como siempre.
  • Todo lo demás es filtro del listado y se aplica después, también a las incluidas: q, denomination, status, niceClass, signType, fechas, hitos, renewalStatus, liveOnly, goodsAndServices y el lote applicationNumber. Una incluida que no los cumple no aparece.
  • La exclusión gana: una solicitud excluida no sale aunque case con el ámbito o esté incluida.
  • Sin ningún filtro de parte, las incluidas son la cartera (sólo ellas, ∩ los filtros del listado); la exclusión resta igual, también sobre el corpus entero.
  • El orden, el cursor, total y meta.facets se calculan sobre el conjunto final.
  • Repetible o separado por comas, hasta 500 números por parámetro, escritos como los escribe INAPI (991652209-2, 990373519-C). Para listas largas, usa comas en el GET (500 números repetidos uno a uno no caben en una URL) o el cuerpo de POST /trademarks/search, que acepta lo mismo. Un número mal formado, una lista vacía o más de 500 es 400 validation_error, igual en REST y MCP. Un número que no existe no suma nada.
  • Vale también en POST /trademarks/search (con similarTo/similarToTrademark), en /insights/trademarks y en el calendario de renovación; con oppositionWindow es un 400.
curl -s "$TARNO_BASE_URL/trademarks?party=306948:representative&includeApplicationNumber=1672581&excludeApplicationNumber=991652209-2&status=registrada" -H "X-API-Key: $TARNO_API_KEY"

El objeto portfolio: lo añadido a mano está siempre

Con los campos planos de arriba, una solicitud incluida a mano sale si no cumple los filtros que refinan la cartera (clase, estado, fechas…). El objeto portfolio separa las dos clases de filtros:

resultado = (((partes ∩ refine) ∪ includeApplicationNumber) − excludeApplicationNumber) ∩ filtros de primer nivel
{
  "portfolio": {
    "party": ["123:holder", "456:representative"],
    "refine": { "niceClass": [9, 42], "status": ["registrada"], "filedFrom": "2015-01-01" },
    "includeApplicationNumber": ["1672581"],
    "excludeApplicationNumber": ["991652209-2"]
  },
  "niceClass": [9]
}
  • portfolio.party: las partes de la cartera, con el mismo valor que party (<id>:<papel>).
  • portfolio.refine: los refinamientos de la cartera. Acepta los mismos filtros de predicado que /trademarks/application-numbers (niceClass, status, fechas, hitos, renewalStatus, liveOnly, holder/taxId, relation, el lote…) y acota sólo las marcas de las partes. Su relation decide también con qué vínculos se leen las partes de portfolio.party. q, denomination, los motores, facets, los filtros de norma y party/includeApplicationNumber/ excludeApplicationNumber dentro de refine son un 400.
  • portfolio.includeApplicationNumber: siempre en la cartera, diga lo que diga refine.
  • portfolio.excludeApplicationNumber: siempre fuera — la exclusión gana.
  • Los filtros de primer nivel son los del listado (lo que el usuario añade al navegar) y se aplican al conjunto entero, también a las incluidas.
  • Sin portfolio.party la cartera son sus incluidas (∩ el listado), nunca el corpus.
  • Dentro de portfolio, cada lista admite hasta 10.000 números.
  • Con portfolio, party, includeApplicationNumber o excludeApplicationNumber de primer nivel son 400 validation_error (una entrada not_combinable por campo): cada cosa va en un solo sitio. Sin portfolio, todo sigue como arriba.
  • Sólo por cuerpo: POST /trademarks/search y POST /trademarks/application-numbers (y en MCP, search_trademarks y list_application_numbers). GET /trademarks sigue plano. Con oppositionWindow es un 400; con similarTo/similarToTrademark el parecido se ordena dentro de la cartera.

El objeto text: búsqueda de texto configurable

text configura la búsqueda de texto con el vocabulario de Algolia. Con todas las opciones por defecto responde exactamente lo mismo que q; q/denomination siguen siendo el atajo de text: { query }, y combinarlos con text es un 400.

{
  "text": {
    "query": "colgate",
    "queryType": "contains",
    "typoTolerance": false,
    "minWordSizefor1Typo": 1,
    "minWordSizefor2Typos": 1,
    "exactOnSingleWordQuery": "word",
    "removeWordsIfNoResults": "allOptional",
    "phonetic": false,
    "semantic": false,
    "getRankingInfo": false
  }
}
opción valores (por defecto primero) qué hace
queryType prefixNone, prefixLast, prefixAll, contains, exact Cómo casa una palabra: entera; la última puede ser el inicio de una palabra; todas pueden serlo; en cualquier punto de la denominación, también dentro de una palabra; la denominación entera, palabra a palabra.
typoTolerance true, false, min, strict Errores de tecleo (Levenshtein) por palabra según su largo; min deja sólo las de menos errores; strict, ésas y las de uno más.
minWordSizefor1Typo · minWordSizefor2Typos 1 · 1 Largo mínimo de palabra para admitir 1 y 2 errores (Algolia usa 4 y 8).
exactOnSingleWordQuery word, attribute, none Qué es «exacta» en el orden con una sola palabra: la denominación la contiene; la denominación es esa palabra; ninguna.
removeWordsIfNoResults allOptional, none, lastWords Qué palabras se exigen: basta una (más palabras ordenan primero); todas; todas o, si ninguna marca las tiene todas, la tira inicial más larga que sí.
phonetic · semantic true · true Añaden las parecidas fonéticas y semánticas después del bloque de palabras clave.
getRankingInfo false Añade rankingInfo a cada acierto: bloque, exacta, prefijo, palabras y errores.

Dos bloques, en este orden. Configurado, primero va el bloque de palabras clave: un conjunto determinista y completo (una marca está o no está por las reglas de arriba, sin tope por canal), ordenado exacta → prefijo (la denominación empieza por la consulta) → más palabras → menos errores → sort → número de solicitud. Después, con phonetic o semantic, las aproximadas, sin borde definido y en orden de relevancia (sort no las reordena). Sin aproximadas, total es el tamaño exacto de la respuesta; con ellas (si corre alguno de esos canales) total no viaja, meta.keywordTotal es el tamaño exacto del bloque de palabras clave y meta.estimatedTotal cuenta los dos bloques (cota inferior). El cursor recorre ese mismo orden y está atado a la petición. Cualquier opción fuera de su valor por defecto (también getRankingInfo: true) elige este motor.

  • query admite como mucho 16 palabras, repetidas incluidas; sin ninguna letra ni dígito es un 400. Una opción que nunca actúa con las demás también es un 400 (typoTolerance: false con tamaños mínimos, exact con removeWordsIfNoResults); exactOnSingleWordQuery y removeWordsIfNoResults, cuyo efecto depende del número de palabras, se admiten con cualquier consulta.
  • Con los tamaños mínimos por defecto (1 y 1) toda palabra admite 2 errores: una palabra corta fuera de una cartera puede dar 422. Para una caja de búsqueda general, minWordSizefor1Typo: 4 y minWordSizefor2Typos: 8 (los de Algolia).

  • En GET /trademarks va aplanado: text=colgate&textQueryType=contains&textTypoTolerance=false&textPhonetic=false&textSemantic=false. Una opción sin text es un 400.

  • En /trademarks/application-numbers y en portfolio.refine.text vale como conjunto: sólo el bloque de palabras clave, así que exige phonetic: false y semantic: false (getRankingInfo no se admite).
  • Con portfolio, un text de primer nivel acota y ordena el conjunto final.
  • text con el lote, registrationNumber, similarTo/similarToTrademark u oppositionWindow es un 400, y minScore con text configurado también. Donde se responde un conjunto, exactOnSingleWordQuery (sólo ordena) también es un 400.
  • Una página de aproximadas cuyos canales no son los de la anterior (uno falló o tardó) es 409 cursor_stale: vuelve a empezar sin cursor. Sin ninguna coincidencia de palabras clave y con todos los canales aproximados caídos, 503: reintenta, no es «no hay marcas».
  • Un bloque de palabras clave con más de 50.000 candidatas es 422 text_set_too_large: acota el filtro, usa palabras más largas o quita la tolerancia a errores.
# La caja de búsqueda de una cartera: literal, total exacto.
curl -s -X POST "$TARNO_BASE_URL/trademarks/search" -H "X-API-Key: $TARNO_API_KEY" -H 'Content-Type: application/json' \
  -d '{"portfolio":{"party":["306948:representative"]},"text":{"query":"colgate","queryType":"contains","typoTolerance":false,"phonetic":false,"semantic":false}}'

Paginación: solo keyset

No hay offset. La paginación es keyset por cursor, para todos los órdenes:

  • Para la página siguiente, reenvía next sin cambios como cursor.
  • next: null significa fin — detente.
  • El cursor es opaco (base64url de las claves de orden); trátalo como caja negra.
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20" -H "X-API-Key: $TARNO_API_KEY"
# página 2: reenvía el `next` de la página 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20&cursor=<next>" -H "X-API-Key: $TARNO_API_KEY"

Todos los números de un filtro, por páginas

GET /trademarks/application-numbers ≡ list_application_numbers (scope brands:read) devuelve sólo los números de solicitud de todas las marcas que casan con el filtro, ordenados por número de solicitud como texto (no numérico: 1000001 va antes que 990373519-C), en páginas de hasta 10.000. El filtro es el de GET /trademarks (lote, partes, cartera a mano, clase, estado, fechas, hitos, renewalStatus, liveOnly, goodsAndServices…) y el conjunto es el mismo que la colección recorrería página a página.

{ "applicationNumbers": ["1161630", "1192677"], "total": 2, "next": null, "cap": 10000,
  "dataAsOf": "2026-10-18T03:12:44.000Z", "coverageThrough": "2026-10-17" }
  • limit (1..10.000, por defecto 10.000 = cap) fija el tamaño de página. next es el cursor opaco de la página siguiente y null en la última: mientras no sea null la lista está incompleta. total es el recuento exacto del conjunto entero y, como dataAsOf, es el mismo en todas las páginas.
  • El cursor se pasa como cursor con el mismo filtro (limit puede cambiar); con otro filtro es 400 validation_error sobre cursor. Dentro de un recorrido ningún número se repite ni se pierde.
  • Si una sincronización del corpus empezó o terminó entre dos páginas, la siguiente responde 409 cursor_stale: vuelve a empezar desde la página uno, sin cursor.
  • Sólo predicados: q, denomination, similarTo, similarToTrademark, allClasses, oppositionWindow, facets y los filtros de norma son 400 validation_error con una entrada por campo (los motores de texto y de parecido ordenan un vecindario, no definen un conjunto). No hay sort ni minScore.
  • Un lote de más de 100 es 422 batch_too_large, como en la colección.
  • POST /trademarks/application-numbers da la misma respuesta con el filtro en el cuerpo JSON (mismo limit, cursor, next, 409 cursor_stale), y es la única forma que acepta el objeto portfolio. El cursor está atado al filtro entero, portfolio incluido.
curl -sS "https://api.tarno.cl/trademarks/application-numbers?party=306948:representative&status=registrada" -H "X-API-Key: $TARNO_API_KEY"
# la página siguiente, con el `next` de la anterior:
curl -sS "https://api.tarno.cl/trademarks/application-numbers?party=306948:representative&status=registrada&cursor=$NEXT" -H "X-API-Key: $TARNO_API_KEY"

Paridad MCP

La herramienta MCP search_trademarks acepta exactamente los mismos parámetros, con idéntica semántica (incluidos sort, la normalización de taxId y el error invalid_rut), y devuelve el mismo JSON que GET /trademarks para la misma pregunta. El lote es search_trademarks con applicationNumber: [a, b, c]. Consulta la guía de MCP.

Hasta el 2026-09-24 esta ruta tenía su propia herramienta gemela de listado; se retiró porque era la misma pregunta que search_trademarks. La ruta REST no cambia.

Tiempo de respuesta

Una búsqueda por texto (q o denomination) consulta cuatro canales a la vez: exacto, aproximado, fonético y por significado. No espera a un canal más de 3 s: pasado ese tiempo, y con al menos un canal que ya haya encontrado coincidencias, responde 200 con los que tiene. Lo normal es que respondan los cuatro en menos de un segundo; el límite sólo actúa cuando uno va lento.

Cómo se ve una respuesta a la que le faltó un canal (igual que cuando un canal falla):

  • las coincidencias de ese canal no están en la página, y su etiqueta (exact, fuzzy, phonetic, semantic) no aparece en matchedBy ni en matchedFields[].kind;
  • si faltó el canal por significado, signals.semantic puede venir null en todos los resultados (null es «no evaluado», nunca un 0);
  • meta.estimatedTotal cuenta lo que encontraron los canales que respondieron;
  • ⭐ meta.degradedChannels nombra los canales que faltaron (p. ej. ["semantic"]), con el mismo vocabulario que matchedBy. Ausente = corrieron todos. semantic sólo cuenta donde hay servicio de significado configurado. Vale igual para similarTo (canales fuzzy, semantic, distinctive) y para text (phonetic, semantic).

Las páginas siguientes de una búsqueda por relevancia con q, denomination o similarTo se arman con los mismos canales que la primera (el cursor los recuerda): si uno que estaba en la primera falla ahora, la respuesta es el 503 reintentable; si uno que faltó en la primera vuelve, se sigue dejando fuera y se declara en meta.degradedChannels, para que el recorrido no repita ni salte marcas. (Con text un cambio de canales entre páginas sigue siendo 409 cursor_stale.) Un minScore explícito que lo descarta todo sigue dando una página vacía, con meta.degradedChannels si faltó algún canal.

La misma búsqueda repetida unos segundos después puede traer más coincidencias y un orden algo distinto. Por eso conviene pedir las páginas de una búsqueda seguidas, sin una espera larga entre una y la siguiente. Nunca se devuelve por esto una página vacía: si a los 3 s ningún canal ha encontrado nada, la búsqueda sigue esperando al primero que encuentre algo o a que terminen todos (una página vacía sigue significando que todos corrieron y ninguno encontró nada); si falta alguno y los demás no encuentran nada, es el 503 de la tabla de abajo.

El objetivo de latencia de la búsqueda (p95 < 3 s) está en el SLA. similarTo no tiene este límite.

Errores

Todos los errores usan el cuerpo RFC 9457 descrito en primeros pasos.

HTTP code Cuándo
400 validation_error Parámetros inválidos (sort fuera del enum, niceClass fuera de 1–45, fecha malformada).
400 invalid_rut Un taxId cuya forma no es la de un RUT — también con similarTo/similarToTrademark y oppositionWindow.
400 invalid_range Un rango con From > To (filedFrom/To, expiresFrom/To, registeredFrom/To, publishedFrom/To, milestoneFrom/To) — también con similitud y ventana de oposición.
400 validation_error ⭐ Un parámetro que la ruta no declara (una entrada de errors[] por clave, field = la clave) — nunca se ignora en silencio.
400 validation_error El lote combinado con limit, cursor, sort, minScore, q, denomination o facets — una entrada de errors[] por campo (field = el campo, code: "not_combinable").
400 validation_error ⭐ Las demás reglas del despacho —lo que la similitud o la ventana de oposición no aplican, similarTo con similarToTrademark, oppositionWindow sin niceClass, partyRole sin taxId, milestoneKind sin rango, los filtros de norma sobre marcas, un goodsAndServices sin nada buscable— también llevan errors[], una entrada por campo: code: "not_combinable" si choca con otro campo de la petición (el detail dice con cuál), "custom" si es otra regla del contrato (el code que la validación de esquemas da a una regla propia), "too_big"/"too_small" si es un tamaño.
422 batch_too_large Un lote (applicationNumber) con más de 100 valores.
422 text_set_too_large El bloque de palabras clave de text tiene más de 50.000 candidatas o es demasiado costoso de verificar.
401 / 403 unauthorized / forbidden Clave ausente/inválida, o falta el scope brands:read.
429 rate_limited / quota_exceeded Límite de ráfaga o cuota mensual.
503 service_unavailable ⭐ Una búsqueda por texto (q, denomination, text o similarTo) a la que le faltó algún canal y los demás no encontraron nada, o en la que fallaron todos. Reintentable. Una página vacía se lee como «ninguna marca coincide», y con un canal caído eso no se sabe: hasta el 2026-10-01 era un 200 vacío con todo caído, y hasta el 2026-11-03 con algún canal caído. Si falla alguno y los demás encuentran algo, responde 200 y lo declara en meta.degradedChannels. También es 503 la página siguiente cuyo canal de la primera está caído ahora, y una página que no se pudo leer entera.

Ver también