Quickstart

Esta guía te lleva de cero a hacer tu primera llamada exitosa a la API Comex de EURUS PRO® en menos de cinco minutos. Al finalizar tendrás una petición autenticada funcionando desde tu terminal o desde un script.

Prerrequisitos

Para hacer tu primera llamada necesitas tres datos que debe proveerte EURUS PRO®:

Dato	Descripción	Ejemplo
`idAgencia`	ID de tu agencia en EURUS PRO®. Es un string opaco, no un número.	`z_cl_demo`
`key`	API Key secreta para autenticar las llamadas.	`AIzaSy...`
`rut`	RUT del cliente final, cuerpo más dígito verificador (ver Formato de RUT). Acota los despachos que ves.	`999999999`

Además necesitas:

Una herramienta para hacer peticiones HTTP. En los ejemplos usaremos cURL, Node.js (con fetch nativo, Node ≥ 18) y Python 3 (con httpx o requests).
Un numeroDespacho válido del cliente con el que vas a probar.
Conexión a internet hacia https://api-comex.eurus.pro.

Paso 1 — Obtener credenciales

Contacta al equipo de EURUS PRO® para solicitar acceso a la API:

Envía un correo a soporte@eurus.pro con el nombre de tu organización, el uso previsto y la dirección IP pública desde la que consumirás la API (opcional, para restringir el key).
Recibirás:
- Tu idAgencia asignado.
- Un API Key único y secreto.
Guárdalo en un lugar seguro (gestor de secretos, variables de entorno, vault). Nunca lo subas a un repositorio público.

Seguridad del API Key

El API Key identifica a tu organización frente a la API Comex. Trátalo como una contraseña: nunca lo compartas, no lo publiques y rótalo si sospechas que se ha filtrado. Ver Autenticación → Buenas prácticas.

Paso 2 — Hacer tu primera llamada

Vamos a listar los documentos asociados a un despacho conocido. La URL sigue el patrón:

GET https://api-comex.eurus.pro/{idAgencia}/v1/dispatch/{numeroDespacho}/files?key=<API_KEY>&rut=<RUT>

Reemplaza {idAgencia}, <API_KEY>, {numeroDespacho} y <RUT> por tus valores reales.

Formato del RUT

El parámetro rut es el cuerpo más el dígito verificador. Se aceptan varias formas y la API las normaliza internamente a la misma consulta:

Lo que envías	Se consulta como
`999999999`	`999999999`
`99.999.999-9`	`999999999`
`99999999K`	`999999991`

La forma canónica —solo dígitos, con la K convertida a 1— es la recomendada. Ver Convenciones → Formato de RUT para qué se rechaza y por qué.

El rut acota lo que ves: solo se devuelven despachos de esa cuenta y sus documentos. Un despacho de otro cliente responde 404, igual que uno inexistente.

cURL

export EURUS_API_KEY="tu-api-key-aqui"
export EURUS_AGENCIA="z_cl_demo"
export EURUS_RUT="999999999"

curl -X GET \
  "https://api-comex.eurus.pro/$EURUS_AGENCIA/v1/dispatch/123457/files?key=$EURUS_API_KEY&rut=$EURUS_RUT" \
  -H "Accept: application/json"

Node.js (Node ≥ 18, `fetch` nativo)

const API_KEY = process.env.EURUS_API_KEY;
const AGENCIA = process.env.EURUS_AGENCIA;       // ej. "z_cl_demo"
const RUT = process.env.EURUS_RUT;               // ej. "999999999"
const numeroDespacho = "123457";

const url = new URL(
  `https://api-comex.eurus.pro/${AGENCIA}/v1/dispatch/${encodeURIComponent(numeroDespacho)}/files`
);
url.searchParams.set("key", API_KEY);
url.searchParams.set("rut", RUT);

const response = await fetch(url, {
  headers: { "Accept": "application/json" },
});

if (!response.ok) {
  throw new Error(`Error ${response.status}: ${await response.text()}`);
}

const { data, nextToken, unsignedCount } = await response.json();

// No hay campo `total`: se cuenta lo que trajo la pagina.
console.log(`${data.length} documentos en esta pagina`);
if (nextToken) console.log("Hay mas paginas; pedir con ?nextToken=" + nextToken);
if (unsignedCount) console.warn(`${unsignedCount} documento(s) sin URL de descarga`);

for (const doc of data) {
  // `name` es el TIPO de documento. Y `url` puede faltar: el documento no
  // tiene archivo, o su URL no se pudo firmar.
  console.log(`- ${doc.name ?? "(sin tipo)"}: ${doc.url ?? "(sin URL)"}`);
}

Python 3 (`httpx`)

import os
import httpx

API_KEY = os.environ["EURUS_API_KEY"]
AGENCIA = os.environ["EURUS_AGENCIA"]    # e.g. "z_cl_demo"
RUT = os.environ["EURUS_RUT"]            # e.g. "999999999"
numero_despacho = "123457"

base = f"https://api-comex.eurus.pro/{AGENCIA}/v1"
response = httpx.get(
    f"{base}/dispatch/{numero_despacho}/files",
    params={"key": API_KEY, "rut": RUT},
    headers={"Accept": "application/json"},
    timeout=30.0,
)
response.raise_for_status()

payload = response.json()

# No hay campo `total`: se cuenta lo que trajo la pagina.
print(f"{len(payload['data'])} documentos en esta pagina")
if payload.get("nextToken"):
    print("Hay mas paginas; pedir con ?nextToken=" + payload["nextToken"])
if payload.get("unsignedCount"):
    print(f"{payload['unsignedCount']} documento(s) sin URL de descarga")

for doc in payload["data"]:
    # `name` es el TIPO de documento, y `url` puede faltar.
    print(f"- {doc.get('name', '(sin tipo)')}: {doc.get('url', '(sin URL)')}")

Paso 3 — Entender la respuesta

Un request exitoso devuelve HTTP 200 con un cuerpo JSON como el siguiente. dispatch está abreviado: en la respuesta real trae siempre las 28 claves del despacho (ver Referencia de la API).

{
  "date": "2026-01-31T22:04:31.000Z",
  "data": [
    {
      "id": "SqboswZtrqP1mDJl6dFj",
      "isActive": true,
      "name": "FACTURA AGENCIA",
      "numeroDespacho": "123457",
      "dispatch": {
        "id": "123457",
        "referencia": "REF-DEMO-0001",
        "estadoAforo": "Aforo Documental",
        "fechaEta": "2026-01-07T00:00:00.000Z",
        "valorCif": 15250.75
      },
      "infoDoc": {
        "document": {
          "number": "45",
          "type": "FACTURA ELECTRONICA",
          "issueDate": "2026-01-05"
        }
      },
      "url": "https://storage.googleapis.com/demo-bucket/files/45.pdf?X-Goog-Signature=..."
    },
    {
      "id": "FILE-001",
      "isActive": false,
      "dispatch": {
        "id": "123457",
        "referencia": "",
        "estadoAforo": "",
        "fechaEta": null,
        "valorCif": null
      },
      "infoDoc": {}
    }
  ]
}

Cuatro cosas de esta respuesta que conviene mirar antes de escribir el parser:

Observación	Detalle
`date` es el instante de la respuesta	No es una fecha del documento ni del rango consultado.
No hay `total`	La paginación es por cursor: ver Convenciones → Paginación.
`name` es el tipo de documento	No es el nombre del archivo. Es el mismo valor que se envía en `fileTypeName`.
El segundo elemento es real, no un relleno	Muestra el mínimo garantizado: solo `id`, `isActive`, `dispatch` e `infoDoc` están siempre. El resto desaparece del JSON cuando su valor es vacío, y puede variar entre elementos de la misma respuesta.
`dispatch` es la excepción	Nunca se vacía: trae siempre todas sus claves, con `""` en los textos y `null` en fechas y montos.

infoDoc existe siempre, pero puede venir vacío

Y {} es truthy en JavaScript, así que if (item.infoDoc) se cumple aunque no haya nada dentro. Verifica contenido: item.infoDoc?.document?.number. Está explicado en Convenciones → Presencia de campos.

La url es una URL firmada que puedes usar para descargar el documento directamente, y caduca en 1 hora. Puede faltar por dos motivos distintos: el documento no tiene archivo asociado, o su URL no se pudo firmar — ese segundo caso se cuenta en unsignedCount.

Si algo falla, recibirás un código HTTP de error con el cuerpo estándar. Ver Errores.

Paso 4 — Qué hacer a continuación

Filtrar por tipo de documento: añade el parámetro fileTypeName=FACTURA%20AGENCIA a la misma llamada para obtener solo facturas de agencia. Consulta la lista completa de fileTypeName — y lee la advertencia sobre URL encoding porque los valores contienen espacios.
Consultar por rango de fechas: usa el segundo endpoint GET /files con startDate, endDate y fileTypeName para extraer todos los documentos de un tipo en un período. Ver la referencia interactiva.
Leer las convenciones de RUT, formatos y versionado — ver Convenciones.
Explorar el módulo de Documentación con más detalles y casos de uso.

Prerrequisitos​

Paso 1 — Obtener credenciales​

Paso 2 — Hacer tu primera llamada​

cURL​

Node.js (Node ≥ 18, fetch nativo)​

Python 3 (httpx)​

Paso 3 — Entender la respuesta​

Paso 4 — Qué hacer a continuación​