APIActualizado: Junio 2026

API — Pedidos

Crea pedidos de comida, tienda o productos desde sistemas externos (tu sitio web, app móvil o POS).

Endpoints

POST/api/v1/pedidos

Crea un nuevo pedido. El agente notifica al cliente por WhatsApp de forma automática si se incluye el teléfono.

GET/api/v1/pedidos

Lista pedidos con filtros opcionales por estado, tipo y rango de fecha.

GET/api/v1/pedidos/:id

Obtiene detalles de un pedido específico incluyendo todos los ítems y el historial de estados.

PATCH/api/v1/pedidos/:id/estado

Actualiza el estado de un pedido (ej: marcar como preparando, listo, en camino, entregado).

Request body — POST /api/v1/pedidos

typescript

interface CrearPedidoRequest {
  tipo: 'DOMICILIO' | 'RECOGER' | 'MESA'  // Tipo de pedido (requerido)
  nombreCliente: string                     // Nombre del cliente (requerido)
  telefono?: string                         // Para notificación WhatsApp
  items: Array<{
    productoId: string                      // ID del producto/platillo del catálogo
    cantidad: number                        // Cantidad (mínimo 1)
    notas?: string                          // Ej: "sin cebolla", "término 3/4"
  }>
  // Solo para DOMICILIO:
  direccionEntrega?: {
    calle: string
    colonia?: string
    referencias?: string
  }
  // Solo para MESA:
  numeroMesa?: number
  // Opcional:
  notas?: string                            // Instrucciones generales del pedido
  programadoPara?: string                   // ISO 8601 si el pedido es para después
}

Info

Los precios se toman del catálogo al momento de crear el pedido. Si un precio cambió desde que el cliente vio el menú, se aplica el precio actual. El total se calcula automáticamente.

Response

201 Created:

json

{
  "id": "ped_x1y2z3w4",
  "negocioId": "neg_xyz",
  "tipo": "DOMICILIO",
  "estado": "RECIBIDO",
  "cliente": {
    "nombre": "Carlos López",
    "telefono": "+525598765432"
  },
  "items": [
    {
      "productoId": "prd_abc",
      "nombre": "Pizza Margarita",
      "cantidad": 1,
      "precioUnitario": "180.00",
      "notas": null
    },
    {
      "productoId": "prd_def",
      "nombre": "Refresco 600ml",
      "cantidad": 2,
      "precioUnitario": "35.00",
      "notas": null
    }
  ],
  "subtotal": "250.00",
  "envio": "50.00",
  "total": "300.00",
  "direccionEntrega": {
    "calle": "Av. Insurgentes 1234",
    "colonia": "Del Valle",
    "referencias": "Edificio azul, departamento 3B"
  },
  "creadoEn": "2026-06-25T19:00:00Z"
}

Ciclo de estados

Estado	Descripción	Quién lo cambia
`RECIBIDO`	Pedido recibido, pendiente de confirmar	Automático al crear
`CONFIRMADO`	Negocio aceptó el pedido	API o panel
`PREPARANDO`	En preparación en cocina/almacén	API o panel
`LISTO`	Listo para recoger o enviar	API o panel
`EN_CAMINO`	Repartidor en camino (solo domicilio)	API o panel
`ENTREGADO`	Pedido completado	API o panel
`CANCELADO`	Pedido cancelado	API, panel o cliente via agente

Cada cambio de estado notifica automáticamente al cliente por WhatsApp si tiene teléfono registrado.

Errores específicos de pedidos

Código	HTTP	Descripción
`PRODUCTO_NOT_FOUND`	404	Un productoId no existe en el catálogo
`PRODUCTO_AGOTADO`	422	Un producto tiene inventario en 0
`PRODUCTO_INACTIVO`	422	Un producto está marcado como no disponible
`TIPO_NO_SOPORTADO`	422	El tipo de pedido no está habilitado para este negocio
`DIRECCION_REQUERIDA`	422	Pedido a domicilio sin dirección de entrega

Ejemplos

Crear pedido a domicilio

javascript

const pedido = await fetch('https://app.xambee.com/api/v1/pedidos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer xam_tu_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tipo: 'DOMICILIO',
    nombreCliente: 'Ana Martínez',
    telefono: '+525512345678',
    items: [
      { productoId: 'prd_pizza_margarita', cantidad: 1, notas: 'extra queso' },
      { productoId: 'prd_refresco_grande', cantidad: 2 }
    ],
    direccionEntrega: {
      calle: 'Calle Reforma 456',
      colonia: 'Centro',
      referencias: 'Casa azul con portón negro'
    }
  })
}).then(r => r.json())

Actualizar estado a "En camino"

bash

curl -X PATCH "https://app.xambee.com/api/v1/pedidos/ped_x1y2z3w4/estado" \
  -H "Authorization: Bearer xam_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"estado": "EN_CAMINO"}'