Manual de integración

API REST para cotizar envíos dentro de Chile. Envías origen, destino, peso y dimensiones; recibes la tarifa en CLP para entrega en agencia y a domicilio.

1 · Autenticación

Crea tu API key en el panel (API keys → Crear key). La key completa se muestra una sola vez. Envíala en cada request:

X-API-Key: sk_live_abc123...
# o bien
Authorization: Bearer sk_live_abc123...

Llama a la API siempre desde tu servidor, nunca desde el navegador: expondrías tu key.

2 · Cotizar un envío

POST /api/v1/quote — de 1 a 20 bultos; cada bulto se tarifica por separado y se suma.

{
  "origen": "SANTIAGO",          // ciudad, comuna o ciud_codigo
  "destino": "PUERTO MONTT",
  "bultos": [
    { "alto": 20, "largo": 30, "ancho": 15, "peso": 2.5 }
  ],
  "valor_declarado": 10000,      // opcional, > 0, ≤ 1.000.000
  "tipo_entrega": "AMBOS"        // AGENCIA | DOMICILIO | AMBOS
}

Respuesta:

{
  "origen_zona": "CENTRO",
  "destino_zona": "SUR",
  "peso_facturable": 2.5,        // max(peso, alto×largo×ancho / 4000)
  "opciones": [
    { "tipo_entrega": "AGENCIA",   "tarifa_base": 8220, "recargo": 2000, "tarifa": 10220, "dias_entrega": "2-4" },
    { "tipo_entrega": "DOMICILIO", "tarifa_base": 8650, "recargo": 2000, "tarifa": 10650, "dias_entrega": "3-5" }
  ],
  "moneda": "CLP",
  "exactitud": "exacta",         // "estimada" si se resolvió por zona
  "nota": "Tarifa referencial. Incluye recargo configurado por el comercio."
}

• · Cada lado máximo 650 cm; peso mayor que 0.
• · El valor declarado no afecta el precio (seguro incluido hasta $50.000).
• · tarifa_base es el valor del modelo; recargo es lo que configuraste en el panel (fijo + %); tarifa es lo que muestras al comprador final.

3 · Códigos de error

4 · Límites y cuotas

• · FREE: 500 cotizaciones exitosas por mes calendario.
• · PRO (USD 15/mes): ilimitadas.
• · 10 requests/segundo y 5 consultas simultáneas por key.
• · Abuso sostenido → bloqueo temporal de 15 minutos.

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 342
Retry-After: 60        # solo en 429

Ante un 429 espera lo que indique Retry-After o aplica backoff exponencial (1s, 2s, 4s, máximo 3 intentos). Cachea cotizaciones repetidas en tu servidor: las tarifas cambian poco.

5 · Catálogo de ciudades

2.167 localidades reales en 16 regiones. Descárgalo, cachéalo y refréscalo cada 30 días:

GET /api/v1/cities?q=temuco&page_size=100
GET /api/v1/cities?region=13
GET /api/v1/cities/resolve?q=PROVIDENCIA
→ { "ciudad": "SANTIAGO", "ciud_codigo": 1, "zona": "CENTRO", ... }

Nota técnica: la macrozona de una localidad se hereda de la central de carga que la atiende, no de su región administrativa (Angol está en La Araucanía pero tarifica como Biobío). El catálogo ya trae la zona resuelta: usa siempre el campo zona.

6 · Ejemplos de código

cURL

curl -X POST https://api.envioschile.net/api/v1/quote \
  -H "X-API-Key: $ENVIOSCHILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origen":"SANTIAGO","destino":"PUERTO MONTT",
       "bultos":[{"alto":20,"largo":30,"ancho":15,"peso":2.5}]}'

PHP (WordPress)

$response = wp_remote_post( 'https://api.envioschile.net/api/v1/quote', array(
  'headers' => array(
    'X-API-Key'    => get_option( 'envioschile_api_key' ),
    'Content-Type' => 'application/json',
  ),
  'body' => wp_json_encode( array(
    'origen'  => 'SANTIAGO',
    'destino' => $comuna_destino,
    'bultos'  => $bultos,
  ) ),
  'timeout' => 10,
) );
$quote = json_decode( wp_remote_retrieve_body( $response ), true );

Node.js

const res = await fetch('https://api.envioschile.net/api/v1/quote', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ENVIOSCHILE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ origen, destino, bultos }),
});
const quote = await res.json();

7 · Plugin WooCommerce

El plugin solo toma la comuna del checkout y los bultos del carrito, llama a la API desde el servidor y muestra las opciones como métodos de envío. Toda la lógica de zonas y tarifas queda en la API. El esqueleto completo del shipping method (clase WC_Shipping_Method, caché con transients y manejo de 429) está en el manual descargable.

8 · Notas legales

EnviosChile no es Starken ni está afiliado, patrocinado ni autorizado por Starken u otro courier. "Starken" es una marca de su titular y se menciona solo con fines descriptivos de compatibilidad. Las tarifas entregadas son estimaciones referenciales que pueden diferir del cobro oficial y cambiar en el tiempo; verifica siempre el valor final con el courier. El servicio se entrega tal cual, con los límites de cuota y disponibilidad del plan contratado.