Referencia de eventos

Documentación detallada de todos los tipos de eventos de webhook, incluidas las estructuras de payload y las condiciones que los activan.

← Volver a la introducción a Webhooks

Descripción general de los eventos

Los eventos son la base de las notificaciones por webhook. Cada evento representa una acción o cambio de estado concreto en tu cuenta de Atoship. Entender los payloads de los eventos te ayuda a crear integraciones sólidas.

Estructura de un evento

Todos los eventos siguen una estructura uniforme con los siguientes campos:

id

Identificador único del evento (evt_xxx)

object

Siempre "Event"

type

Tipo de evento (p. ej., "label.purchased")

created_at

Marca de tiempo ISO 8601 de cuándo ocurrió el evento

data.object

El recurso afectado con su estado actual

data.previous_attributes

Campos modificados con sus valores anteriores (opcional)

Eventos de etiqueta

Eventos relacionados con el ciclo de vida de la etiqueta de envío

label.created

label

Se activa cuando se crea una nueva etiqueta de envío pero aún no se ha comprado.

Activador

Se crea una etiqueta mediante la API o el panel

Payload de ejemplo

{
  "id": "evt_abc123",
  "object": "Event",
  "type": "label.created",
  "created_at": "2025-01-12T10:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": null,
      "carrier": "USPS",
      "service": "Priority Mail",
      "status": "draft",
      "from_address": {
        "name": "Sender Name",
        "street1": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90001",
        "country": "US"
      },
      "to_address": {
        "name": "Recipient Name",
        "street1": "456 Oak Ave",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "parcel": {
        "weight": 16.0,
        "length": 10,
        "width": 8,
        "height": 4
      },
      "rate": {
        "amount": "8.95",
        "currency": "USD"
      },
      "created_at": "2025-01-12T10:00:00.000Z"
    }
  }
}

label.purchased

label

Se activa cuando una etiqueta de envío se compra correctamente y queda lista para usar.

Activador

Se procesa el pago y se genera la etiqueta

Payload de ejemplo

{
  "id": "evt_def456",
  "object": "Event",
  "type": "label.purchased",
  "created_at": "2025-01-12T10:01:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "carrier": "USPS",
      "service": "Priority Mail",
      "status": "purchased",
      "label_url": "https://atoship.com/api/labels/lbl_xyz789.pdf",
      "label_format": "PDF",
      "cost": {
        "amount": "8.95",
        "currency": "USD"
      },
      "purchased_at": "2025-01-12T10:01:00.000Z"
    },
    "previous_attributes": {
      "status": "draft",
      "tracking_number": null
    }
  }
}

label.voided

label

Se activa cuando una etiqueta de envío se anula o cancela.

Activador

La etiqueta se anula mediante la API o el panel

Payload de ejemplo

{
  "id": "evt_ghi789",
  "object": "Event",
  "type": "label.voided",
  "created_at": "2025-01-12T12:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "status": "voided",
      "voided_at": "2025-01-12T12:00:00.000Z",
      "void_reason": "Customer request"
    },
    "previous_attributes": {
      "status": "purchased"
    }
  }
}

label.refunded

label

Se activa cuando se procesa el reembolso de una etiqueta.

Activador

El transportista aprueba y procesa el reembolso

Payload de ejemplo

{
  "id": "evt_jkl012",
  "object": "Event",
  "type": "label.refunded",
  "created_at": "2025-01-15T10:00:00.000Z",
  "data": {
    "object": {
      "id": "lbl_xyz789",
      "object": "Label",
      "tracking_number": "9400111899223033005436",
      "status": "refunded",
      "refund": {
        "amount": "8.95",
        "currency": "USD",
        "refunded_at": "2025-01-15T10:00:00.000Z"
      }
    },
    "previous_attributes": {
      "status": "voided"
    }
  }
}

Referencia rápida

Tipo de evento	Categoría	Descripción
`label.created`	Eventos de etiqueta	Se activa cuando se crea una nueva etiqueta de envío pero aún no se ha comprado.
`label.purchased`	Eventos de etiqueta	Se activa cuando una etiqueta de envío se compra correctamente y queda lista para usar.
`label.voided`	Eventos de etiqueta	Se activa cuando una etiqueta de envío se anula o cancela.
`label.refunded`	Eventos de etiqueta	Se activa cuando se procesa el reembolso de una etiqueta.
`tracking.created`	Eventos de seguimiento	Se activa cuando se inicia el seguimiento de un envío.
`tracking.updated`	Eventos de seguimiento	Se activa cuando cambia el estado del seguimiento.
`tracking.delivered`	Eventos de seguimiento	Se activa cuando un paquete se entrega correctamente.
`tracking.exception`	Eventos de seguimiento	Se activa cuando ocurre una excepción de seguimiento (retraso, devolución al remitente, etc.).
`batch.created`	Eventos de lote	Se activa cuando se crea una nueva operación por lotes.
`batch.completed`	Eventos de lote	Se activa cuando una operación por lotes se completa correctamente.
`batch.failed`	Eventos de lote	Se activa cuando una operación por lotes falla por completo.
`scan_form.created`	Eventos de formulario SCAN	Se activa cuando se crea un nuevo formulario SCAN.
`scan_form.updated`	Eventos de formulario SCAN	Se activa cuando cambia el estado de un formulario SCAN.
`payment.created`	Eventos de pago	Se activa cuando se inicia un pago o cargo.
`payment.completed`	Eventos de pago	Se activa cuando un pago se completa correctamente.
`payment.failed`	Eventos de pago	Se activa cuando un pago falla.
`return.created`	Eventos de devolución	Se activa cuando se crea una etiqueta de devolución o un RMA.
`return.received`	Eventos de devolución	Se activa cuando un paquete de devolución se recibe en el almacén.
`return.completed`	Eventos de devolución	Se activa cuando una devolución se procesa por completo.
`insurance.purchased`	Eventos de seguro	Se activa cuando se contrata un seguro para un envío.
`insurance.cancelled`	Eventos de seguro	Se activa cuando se cancela un seguro.
`claim.created`	Eventos de reclamación	Se activa cuando se presenta una reclamación de seguro.
`claim.approved`	Eventos de reclamación	Se activa cuando se aprueba una reclamación de seguro.
`claim.rejected`	Eventos de reclamación	Se activa cuando se rechaza una reclamación de seguro.