Conectá tu sistema.
Nosotros movemos los paquetes.

Autenticación

Login con las 3 credenciales → devuelve el token Bearer.

curl -X POST https://api.sellergo.com.ar/api/v1/integrations/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"apiUser":"int_xxx","apiPassword":"xxx","apiKey":"slg_xxx"}'

// → { "token": "eyJ...", "tokenType": "Bearer", "expiresIn": 7200 }

Cotizar

Un request, todas las opciones: cada cotización trae el carrier, el precio final y la ETA para que elijas con cuál despachar. Mandá un elemento en packages por cada bulto, con su peso en kg y sus medidas en cm.

{
  "origin":      { "postalCode": "1414", "province": "Capital Federal" },
  "destination": { "postalCode": "5000", "province": "Cordoba" },
  "serviceType": "Agencia a Domicilio",
  "declaredValue": 5000,
  "packages": [
    { "weight": 12.5, "length": 60, "width": 50, "height": 40 },
    { "weight": 2,    "length": 20, "width": 15, "height": 10 }
  ]
}

Tipo de servicio:serviceType acepta el mismo valor que el alta (AGENCY_HOME | AGENCY_AGENCY) o el nombre ("Agencia a Domicilio" | "Agencia a Agencia").

Varios bultos: cada carrier los opera a su manera y el precio lo refleja. Algunos tarifan bulto por bulto (dos bultos cuestan el doble que uno) y otros despachan el envío entero en una sola guía, cobrando por el peso y el volumen sumados y emitiendo un rótulo por bulto. Los que no admiten varios bultos en una guía no aparecen en la respuesta: darte un precio que después no se puede despachar sería peor que no ofrecerlo.

Peso volumétrico: si mandás las medidas, cada bulto se cobra por el mayor entre su peso real y su aforo (volumen × 250 kg/m³) y recién después se suman. Te recomendamos mandar siempre las medidas para que el precio coincida con lo que factura el carrier.

Formato anterior:weight + dimensions + pieces sigue funcionando y describe N bultos iguales de ese peso y esas medidas.

Geografía: no necesitás cargar códigos postales ni provincias — mandá el CP como texto y el nombre de la provincia; SellerGo los resuelve contra su propia base (entiende "Capital Federal", "CABA", acentos, etc.).

Crear envío

El precio lo determina SellerGo (recotiza server-side) y se cobra a tu cuenta corriente — no mandás precio. Usá el header X-Idempotency-Key (ej. tu número de pedido) para que un reintento no duplique el envío.

{
  "carrierId": "andreani",
  "serviceType": "AGENCY_HOME",
  "origin":      { "postalCode": "1414", "province": "Capital Federal", "name": "Mi Depósito", "address": "Calle 1 123" },
  "destination": { "postalCode": "5000", "province": "Cordoba", "name": "Juan Perez", "address": "Av 2 456", "phone": "351..." },
  "packages": [
    { "weight": 12.5, "length": 60, "width": 50, "height": 40 },
    { "weight": 2,    "length": 20, "width": 15, "height": 10 }
  ],
  "declaredValue": 5000,
  "reference": "pedido-1234"
}

// → { "id": "...", "sellergoTrackingCode": "SG...", "price": 8684, "labelUrl": "..." }

Mandá los mismos bultos con los que cotizaste: el precio se recalcula sobre esa lista y es esa lista la que se le declara al carrier.

Para envíos a sucursal (AGENCY_AGENCY) mandá carrierBranchId con el id de una agencia del carrier:

Buscar y cancelar

Si se perdió la respuesta del alta, buscá el envío por tu reference o por la X-Idempotency-Key que usaste (coincidencia exacta, solo tus envíos). Si no aparece, el alta no se creó y podés reintentarla con la misma key.

// → { "trackingCode": "SG...", "status": "CANCELLED", "refunded": 8684, "alreadyCancelled": false }

Se puede cancelar un envío ya registrado en el courier (QUOTED, READY_FOR_PICKUP, ASSIGNED) antes de que el courier retire el paquete; en otro estado responde 409 INVALID_STATUS_TRANSITION. Si el envío tiene guía y el courier no permite anularla por API, responde 409 CARRIER_CANCEL_UNAVAILABLE sin tocar el envío: pedile la cancelación a SellerGo. Si el cargo ya salió en la factura del cierre de período de tu cuenta corriente, responde 409 SHIPMENT_PERIOD_INVOICED y no se toca nada: un envío facturado no se cancela. Es idempotente: un reintento devuelve alreadyCancelled: true y no devuelve la plata dos veces.

Etiqueta y tracking

La etiqueta puede responder 409 LABEL_NOT_READY, y no es un error definitivo: algunos carriers no tienen API y su rótulo oficial llega de forma asincrónica. Hasta que llega no entregamos el PDF, porque una etiqueta sin el rótulo del courier es indistinguible de una completa y terminaría en un bulto despachado sin él. A los 15 minutos del alta se entrega igual, sólo con la etiqueta SellerGo y marcada.

Si imprimís automáticamente: tratá el 409 como “todavía no” y reintentá en unos minutos, y antes de dar una impresión por buena mirá el header X-Label-Estado (lista | solo-sellergo) y X-Label-Rotulo-Carrier (incluido | ausente).

Límites y errores

Rate-limit por credencial: 120 req/min por defecto (headers X-RateLimit-*). Todas las llamadas quedan auditadas.

Todos los errores tienen el mismo shape. Matcheá por code, no por el texto: error/message son legibles y pueden cambiar de redacción; code es contrato estable. Incluí el requestId en cualquier reporte a soporte.

{
  "error": "El carrier elegido no cotiza para esa ruta/servicio/peso",
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "El carrier elegido no cotiza para esa ruta/servicio/peso",
  "details": null,
  "requestId": "57a550e8-…"
}