Beartrack

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.

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

Respuestas

201Created

El pedido se creó correctamente.

Ejemplo
{
  "order_id": "123456",
  "following_number": 268012
}
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 pedidos).

429Too Many Requests

  • Demasiadas peticiones

    too_many_requests

    Superaste el límite de tu credencial: 10 canjes de token o 120 pedidos por minuto.

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 respuesta trae la cabecera x-correlation-id. Inclúyela si nos escribes por un pedido puntual.