Beartrack

Guía

Inicio rápido

De cero a tu primer envío creado. Son cinco pasos y no necesitas instalar nada: basta con poder hacer un POST desde tu servidor.

1 Crea tus credenciales

Entra al portal de Beartrack y ve a Integraciones → API para desarrolladores. Crea una credencial y copia su client_id y su client_secret.

El client secret se muestra una sola vez

Guárdalo en ese momento como variable de entorno de tu servidor. Si lo pierdes, rota la credencial desde el portal. Más detalle en Autenticación.

2 Pide un token

Canjea la credencial por un token de acceso. Dura una hora: reutilízalo en todas las peticiones de ese período.

curl -X POST 'https://api.beartrackapp.com/api/v1/integrations/oauth/token' \
  -u 'btc_tu-client-id:bts_tu-client-secret' \
  -d 'grant_type=client_credentials'

La respuesta trae access_token y expires_in. Guarda el token para el paso siguiente.

3 Crea un pedido

Un POST con el token, el receptor y la dirección de entrega. Beartrack geocodifica la dirección y devuelve el número de seguimiento en following_number.

curl -X POST 'https://api.beartrackapp.com/api/v1/integrations/public-api/packages' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer bta_tu-token' \
  -d '{
    "type": "ownStore",
    "receiver_name": "MARÍA",
    "receiver_lastName": "MUÑOZ",
    "receiver_phone": "+56942405123",
    "comments": "Departamento 602, dejar en conserjería",
    "order_id": "123456",
    "shipping_address": {
      "street_name": "Avenida Siempre Viva",
      "street_number": "742",
      "city": {
        "name": "Región Metropolitana"
      },
      "neighborhood": {
        "name": "Barrio Italia"
      },
      "municipality": {
        "name": "Ñuñoa"
      },
      "country": {
        "name": "Chile"
      }
    },
    "products": [
      {
        "name": "Aceite de motor 10w30",
        "description": "Botella 946 ml",
        "sku": "CUP000019",
        "quantity": 2,
        "unit": "UN",
        "unitValue": 9990,
        "totalValue": 19980,
        "currency": "CLP",
        "weight": 1.9,
        "dimensions": {
          "length": 10,
          "width": 10,
          "height": 25
        },
        "volume": 2500
      }
    ],
    "packageDimensions": {
      "length": 30,
      "width": 30,
      "height": 60,
      "weight": 3.8
    }
  }'

Antes de probar, cambia el order_id y los datos del ejemplo por los de un pedido tuyo. order_id es obligatorio: si reintentas con el mismo y los mismos datos dentro de 24 horas, no se crea un segundo pedido. Los campos y las respuestas están en la referencia de Crear pedido.

4 Verifica el envío

Con el número de seguimiento que devolvió el paso anterior y el mismo token, consulta el pedido: su estado, el contenido del QR de la etiqueta y, cuando se entregue, la evidencia.

curl -X GET 'https://api.beartrackapp.com/api/v1/integrations/public-api/packages/268012' \
  -H 'Authorization: Bearer bta_tu-token'

También puedes buscarlo por tu order_id (Buscar por order_id), y el destinatario lo sigue con el mismo número en beartrackapp.com/tracking.

5 Pasa a producción

  • Guarda client_id y client_secret como variables de entorno del servidor. Nunca en el navegador, en una app ni en el repositorio.
  • Reutiliza el token durante su hora de vida y renuévalo ante un 401 con invalid_token. Pedir uno por request agota el límite del canje.
  • Persiste el following_number junto a tu propio order_id: es la llave para consultar el envío después.
  • Descarga la etiqueta (label_zpl_url o label_pdf_url) apenas creas el pedido: solo viene en esa respuesta. Si la generas tú, el QR lleva exactamente qr_payload.
  • Si la creación de un pedido termina en timeout, reintenta con el mismo order_id y los mismos datos: dentro de 24 horas no se duplica.
  • Reintenta con backoff sólo ante errores de red, 429 o 5xx. Un 400, 401 o 403 no mejoran reintentando igual.