Referencia de la API

Crear pedido

Registra un envío en Beartrack desde tu propia tienda o sistema.

post

/integrations/public-api/packageshttps://api.beartrackapp.com/api/v1

Da de alta un paquete a nombre de tu comercio. Beartrack geocodifica la dirección, le asigna un número de seguimiento y lo deja disponible para ruteo y para el seguimiento público. Es el endpoint que usas si integras tu propio checkout, ERP o sistema de gestión.

Autenticación

Envía estas cabeceras en cada petición.

Authorizationstringrequerido

Token de acceso: Bearer seguido del access_token que devuelve POST /integrations/oauth/token.

El token se obtiene canjeando tu client_id y tu client_secret en POST /integrations/oauth/token, y dura una hora. Este endpoint exige el scope packages:write. Cómo crear las credenciales y pedir el token: Autenticación.

Cuerpo de la petición

JSON · RequestCreateOwnStorePackageDTo · requerido

typeenumrequerido

Origen del pedido. Siempre ownStore.

Valores:ownStore

receiver_namestringrequerido

Nombre de quien recibe.

receiver_lastNamestringopcional

Apellido de quien recibe.

receiver_phonestringrequerido

Teléfono de contacto del receptor, con código de país. El repartidor lo usa para coordinar la entrega.

commentsstringrequeridonullable

Instrucciones para la entrega: piso, departamento, referencias, a quién dejar el paquete.

order_idstringrequerido

Tu identificador de pedido. Es la clave de idempotencia: reintentar con el mismo order_id y los mismos datos dentro de 24 horas no duplica el pedido.

ShippingAddressrequerido

Dirección de entrega.

street_namestringrequerido

Nombre de la calle, sin el número.

street_numberstringrequerido

Número de la dirección.

commentstringopcionalnullable

Detalle adicional de la dirección.

Cityrequerido

Ciudad o región.

Neighborhoodrequerido

Barrio o sector.

Municipalityrequerido

Comuna o municipio.

delivery_preferencestringopcionalnullable

Preferencia de entrega, por ejemplo residential.

Countryrequerido

País de destino.

array<PackageProduct>opcional

Products in the package (up to 100 lines)

namestringopcional

Product name

descriptionstringopcional

Product description

skustringopcional

SKU

quantitynumberrequerido

Quantity

unitstringopcional

Unit of measure of the quantity (UN, KG, LT…)

unitValuenumberopcional

Unit price

totalValuenumberopcional

Line total

currencystringopcional

ISO currency code

weightnumberopcional

Weight in kg

PackageProductDimensionsopcional

Dimensions in cm

volumenumberopcional

Volume in cm³

PackageDimensionsopcional

Package dimensions (cm) and weight (kg)

lengthnumberopcional

Length in cm

widthnumberopcional

Width in cm

heightnumberopcional

Height in cm

weightnumberopcional

Weight in kg

Ejemplo

El cuerpo sale del spec: si cambia el contrato, cambia este snippet.

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
    }
  }'

Respuestas

201Created

El pedido se creó correctamente.

Ejemplo

{
  "order_id": "123456",
  "following_number": 268012,
  "package_id": "66ed7ae7adb0a4095c126feb",
  "qr_payload": "{\"id\":\"66ed7ae7adb0a4095c126feb\"}",
  "label_pdf_url": "https://f005.backblazeb2.com/file/ots-prd/…/etiqueta.pdf",
  "label_zpl_url": "https://f005.backblazeb2.com/file/ots-prd/…/etiqueta.zpl"
}

400Bad Request

Petición incompleta o inválida
invalid_request
Falta un dato obligatorio —la cabecera Authorization, grant_type en el token o un campo del pedido como order_id— o el cuerpo no pasó la validación. error_description dice qué falló.

401Unauthorized

Petición incompleta o inválida
invalid_request
Falta un dato obligatorio —la cabecera Authorization, grant_type en el token o un campo del pedido como order_id— o el cuerpo no pasó la validación. error_description dice qué falló.
Token inválido o vencido
invalid_token
El token no existe, venció (dura una hora) o la credencial se rotó o revocó después de emitirlo.

403Forbidden

Scope insuficiente
insufficient_scope
El token no tiene el scope que exige el endpoint: packages:write para crear y cancelar, packages:read para consultar.

429Too Many Requests

Demasiadas peticiones
too_many_requests
Superaste el límite de tu credencial, por minuto: 10 canjes de token, 120 pedidos, 300 consultas o 60 cancelaciones. Cada límite es independiente.

502Bad Gateway

No se pudo crear el pedido
server_error
Falló algo del lado de Beartrack al registrar el pedido.

503Service Unavailable

Servicio no disponible
temporarily_unavailable
Beartrack no pudo procesar la petición en este momento.

Notas

order_id es obligatorio y es la clave de idempotencia: si reintentas con el mismo order_id y los mismos datos dentro de las 24 horas siguientes (por ejemplo, tras un timeout), no se crea un segundo pedido y recibes el mismo following_number. No cambies el cuerpo entre un intento y otro.
Guarda following_number junto a tu order_id: es el número con el que se consulta el envío y el que ve el destinatario en el seguimiento.
La dirección se resuelve por texto: mientras más completos vengan street_name, street_number y municipality, mejor queda la geocodificación y el ruteo.
Cada pedido es un bulto. La API no tiene campos para cantidad de bultos, peso ni medidas: si un envío lleva varias cajas, crea un pedido por caja, cada uno con su propio order_id.
La respuesta trae la etiqueta en label_zpl_url (ZPL para impresoras Zebra, pensada para 10×15 cm a 203 dpi; el tamaño de página se configura en la impresora) y en label_pdf_url. Descárgalas y guárdalas al crear el pedido: solo vienen en esta respuesta. Cualquiera de los dos campos puede venir null si la etiqueta no se pudo generar; el pedido se creó igual.
Si generas la etiqueta en tu sistema, el QR tiene que contener exactamente qr_payload ({"id":"<package_id>"}, sin espacios ni otras claves): es lo que lee la app de los repartidores. qr_payload también viene en Consultar pedido.
Cada respuesta trae la cabecera x-correlation-id. Inclúyela si nos escribes por un pedido puntual.

Autenticación#

Cuerpo de la petición#

Ejemplo#

Respuestas#

Notas#

Autenticación

Cuerpo de la petición

Ejemplo

Respuestas

Notas