Referencia de la API

Acceso programático a las declaraciones de aduana de Uruguay. URL base https://uytrades.com/api/v1. Las respuestas son application/json; las fechas siguen ISO 8601.

Autenticación

Enviá un token de acceso personal en el header Authorization: Bearer <token>. Los tokens se crean en /account. El valor en texto plano se devuelve una sola vez, al crearlo, y no se puede recuperar después.

curl -H "Authorization: Bearer uytr_a1b2c3d4_xxxxxxxxxxxx" \
     "https://uytrades.com/api/v1/me"

El token hereda el plan de la cuenta que lo creó. Si la suscripción vence, los endpoints Pro devuelven 402 para ese token; no hace falta revocarlo.

También se acepta autenticación por cookie de sesión, de modo que los endpoints se pueden abrir en un navegador con sesión iniciada. Para clientes no interactivos, usá un token.

Límites de uso

Los límites se aplican por cuenta, sumando todos sus tokens. Crear tokens adicionales no los aumenta.

Las dos ventanas se aplican en simultáneo. Los dos grupos de endpoints se miden por separado: agotar uno no afecta al otro.

Las respuestas de estos endpoints incluyen:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1755792000
X-RateLimit-Limit-Minute: 20
X-RateLimit-Remaining-Minute: 19

Superar cualquiera de las dos ventanas devuelve 429. Retry-After indica los segundos que faltan para que esa ventana se reinicie.

HTTP/1.1 429 Too Many Requests
Retry-After: 412

{
  "error": {
    "code": "rate_limited",
    "message": "60 requests/hour exceeded.",
    "limit": 60,
    "window": "hour",
    "reset": 1755792000
  }
}

Endpoints

curl -H "Authorization: Bearer $TOKEN" "https://uytrades.com/api/v1/me"

{"id": 42, "email": "you@example.com", "tier": "pro",
 "is_pro": true, "pro_until": "2027-01-14T00:00:00+00:00"}

curl "https://uytrades.com/api/v1/dua/meta"

{"row_limit_max": 10000, "default_limit": 100,
 "regimens": ["ALL", "EXPORT", "IMPORT", "TRANSIT"],
 "columns": ["anio", "fecha_dua", "aduana_ing_egr", ...],
 "requires_pro": true, "is_pro": false}

curl -H "Authorization: Bearer $TOKEN" \
  "https://uytrades.com/api/v1/dua?year=2026&regimen=IMPORT&limit=100"

{"data": [{"anio": 2026, "fecha_dua": "2026-03-04", "nombre": "ACME SA", ...}],
 "pagination": {"limit": 100, "offset": 0, "returned": 100, "has_more": true},
 "query": {"year": 2026, "aduana": null, "regimen": "IMPORT", "search": null},
 "meta": {"elapsed_ms": 84.2}}

curl -H "Authorization: Bearer $TOKEN" \
  "https://uytrades.com/api/v1/dua/summary?year=2026&regimen=IMPORT"

{"row_count": 148230, "total_usd": 2841993022.14,
 "by_aduana": [{"aduana": "001", "rows": 91204, "usd": 1922841003.5}],
 "by_regimen": [{"regimen_tipo": "I", "rows": 148230}],
 "query": {"year": 2026, "aduana": null, "regimen": "IMPORT", "search": null}}

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "nightly-etl"}' \
  "https://uytrades.com/api/v1/keys"

{"id": 7, "name": "nightly-etl", "prefix": "a1b2c3d4",
 "created_at": "2026-08-21T16:04:11+00:00", "last_used_at": null,
 "token": "uytr_a1b2c3d4_xxxxxxxxxxxx"}

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://uytrades.com/api/v1/keys/7"

Errores

Todos los errores usan el mismo formato. code es estable y sirve para ramificar; status repite el estado HTTP. Algunos errores agregan campos, como upgrade_url en 402 y reset en 429.

{"error": {"code": "unauthorized", "status": 401, "message": "Authentication required. ..."}}

Los fallos de autenticación devuelven 401 con cuerpo JSON y un header WWW-Authenticate: Bearer. Ningún endpoint bajo /api/v1 responde con una redirección, así que un cliente puede seguir redirecciones sin que eso enmascare un error de autenticación.

Descargas masivas

Esta API está diseñada para consultas acotadas. Con 60 requests por hora y 10,000 filas por request, bajar un año completo de declaraciones no es viable.

Para eso usá la exportación CSV en /app/export. Acepta el mismo token Bearer y entrega hasta 1,000,000 filas en un solo request.

curl -H "Authorization: Bearer $TOKEN" \
  "https://uytrades.com/app/export?year=2026&regimen=IMPORT&search=ACME" \
  -o acme-2026.csv

Qué es estable

Los endpoints de esta página son estables. Los campos de sus respuestas no se van a eliminar ni a cambiar de tipo sin aviso.

Cualquier otra ruta bajo /api/v1 sirve a la aplicación web o está en beta. No están versionadas y pueden cambiar o retirarse sin aviso:

• /api/v1/alerts
• /api/v1/watches
• /api/v1/views
• /api/v1/export-schedules

Aceptan la misma autenticación pero no están cubiertas por la garantía anterior.

Beta

GET /api/v1/stories/candidate recalcula un candidato de historia para el paso de reconciliación del pipeline de video. Requiere Pro, consume el presupuesto expensive y devuelve application/json. Su respuesta sigue a los formatos de historia y puede cambiar sin aviso.

Parámetros: format, period (year:YYYY o ytd:YYYY), los parámetros propios del formato, y opcionalmente through (una fecha ISO 8601) y page_size. Un parámetro desconocido devuelve 400.

curl -H "Authorization: Bearer $TOKEN" \
  "https://uytrades.com/api/v1/stories/candidate?format=A&period=year:2025&ncm=4011&regimen=I&page_size=10"