Pedidos y citas

Con pedidos o citas externos, Astro guarda el documento y enseguida hace POST a {origen}/astro/pedido/webhook con transaccion.crear. El campo data.tipo dice si es pedido o cita.

La primera llamada espera 5 segundos. Si respondes dentro de ese plazo, el cliente recibe el resultado en la misma conversación. Si no alcanzas, Astro le dice que el documento quedó en confirmación y le escribe de nuevo cuando tu sistema responda.

Pedido

Las líneas traen código, nombre y cantidad. El precio definitivo lo devuelves tú en la respuesta.

{
  "version": "2026-10-01",
  "evento": "transaccion.crear",
  "id_evento": "6f1c0e2a-1b2c-4d5e-8f90-123456789abc",
  "fecha": "2026-10-07T15:06:11.480000+00:00",
  "tenant_id": "0b1d5c2e-7a11-4e3a-9c2d-111111111111",
  "sucursal": { "codigo": "PTY", "nombre": "Punta Pacífica" },
  "data": {
    "tipo": "pedido",
    "referencia": "PED000000000001",
    "cliente": {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-222222222222",
      "nombre": "Ana Pérez",
      "telefono": "50760000000",
      "canal": "whatsapp"
    },
    "detalles": [
      { "codigo": "MB-01", "nombre": "Mega Burger", "cantidad": 2 }
    ],
    "notas": "Sin cebolla"
  }
}

referencia es el número del pedido en Astro: PED y 12 dígitos. cliente.canal es whatsapp, instagram, messenger o tiktok. El nombre, el teléfono, las notas y el nombre de una línea pueden llegar en null. Identifica el producto por codigo.

Cita

La cita agrega el rango y el servicio. inicio y fin van en ISO 8601 con zona horaria. El sobre (version, fecha, tenant_id, sucursal) viaja igual que en el pedido.

{
  "evento": "transaccion.crear",
  "id_evento": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "tipo": "cita",
    "referencia": "RSV000000000001",
    "cliente": {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-222222222222",
      "nombre": "Ana Pérez",
      "telefono": "50760000000",
      "canal": "whatsapp"
    },
    "cita": {
      "inicio": "2026-10-08T19:00:00+00:00",
      "fin": "2026-10-08T19:30:00+00:00",
      "servicio": "Corte"
    },
    "detalles": [
      { "codigo": "SRV-01", "nombre": "Corte", "cantidad": 1 }
    ],
    "notas": null
  }
}

referencia de una cita empieza por RSV. Astro no consulta tu agenda antes de enviar la cita. Si ese horario no se puede, responde NO_DISPONIBLE.

Cuando aceptas

id_externo es obligatorio: el identificador del documento en tu sistema, hasta 128 caracteres. numero_externo es opcional, hasta 64, y es el número que ve el negocio en tu sistema.

Si incluyes detalles, Astro reemplaza el precio provisional por el tuyo y calcula el impuesto con la configuración de la cuenta. grava_impuesto: false deja esa línea sin impuesto. Si omites detalles, Astro conserva el precio que mostró en la consulta de catálogo.

{
  "RESPUESTA": "OK",
  "MENSAJE": "Pedido creado",
  "DATA": {
    "id_externo": "F-10452",
    "numero_externo": "10452",
    "detalles": [
      {
        "codigo": "MB-01",
        "nombre": "Mega Burger",
        "cantidad": 2,
        "precio": 8.5,
        "moneda": "USD",
        "grava_impuesto": true
      }
    ]
  }
}

Cada línea necesita nombre, cantidad de 1 a 100 y precio mayor o igual a 0. Puedes enviar hasta 50 líneas. Una línea inválida, o un OK sin id_externo, cuenta como fallo técnico: Astro vuelve a llamar con la misma clave.

El stock lo descuenta tu sistema al aceptar. Astro no lo mueve.

Cuando rechazas

Responde con un código de rechazo y una frase que el cliente pueda leer. Astro cancela el documento y no reintenta.

{
  "RESPUESTA": "SIN_STOCK",
  "MENSAJE": "Mega Burger está agotado en Punta Pacífica",
  "DATA": {}
}

Ese cuerpo puede ir con HTTP 200 o con un 4xx distinto de 401, 403 y 429.

La misma clave, el mismo resultado

id_evento e Idempotency-Key identifican el alta. Si ya creaste el documento para esa clave, responde otra vez OK con el mismo id_externo. No abras un segundo pedido.

Astro repite el mismo cuerpo. Un X-Astro-Delivery distinto significa otro intento de la misma operación.

Cancelar

Cuando el cliente pide cancelar, Astro envía transaccion.cancelar a {origen}/astro/pedido/webhook. Esta llamada no entra en la cola de reintentos. Si no la confirmas, el documento sigue en Astro y la conversación pasa a una persona.

{
  "evento": "transaccion.cancelar",
  "id_evento": "c0ffee00-0000-4000-8000-000000000001",
  "data": {
    "tipo": "pedido",
    "referencia": "PED000000000001",
    "id_externo": "F-10452"
  }
}

id_externo puede llegar en null si el alta todavía no se había confirmado. La clave de esta llamada es estable y distinta de la del alta. Para anular, usa referencia e id_externo.

Responde OK si lo cancelaste. Responde NOT_FOUND si nunca lo tuviste: para Astro eso también cierra la cancelación. Cualquier otro resultado deja el documento abierto.