Actualizar un pedido

Este artículo cubre tres endpoints distintos para modificar un pedido existente:

PUT /orders/:orderId — actualización parcial del pedido.
PUT /orders/:orderId/customer — actualiza únicamente los datos del cliente.
POST /orders/:orderId/comments — agrega un comentario al historial del pedido.

Actualizar un pedido

Actualiza parcialmente un pedido existente

orderIdstringrequired

ID del pedido (MongoDB ObjectId de 24 caracteres).

bodyobjectrequired

Objeto parcial del pedido — solo envía las propiedades que quieres modificar.

{
  "shippingAddress": {
    "street": "Calle Insurgentes 456, Depto 3B",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zipCode": "03100",
    "country": "MX"
  },
  "notes": "Cliente cambió dirección por teléfono el 11-abr-2026"
}

200

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "orderStatus": "accepted",
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Depto 3B",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "notes": "Cliente cambió dirección por teléfono el 11-abr-2026",
    "updatedAt": "2026-04-11T15:02:44.000Z",
    "_links": {
      "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1",
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}

404

{ "error": { "code": "orders:not_found", "message": "Order not found" } }

Permiso requerido: orders:update

El cuerpo del request acepta un objeto parcial del pedido (Partial<Order>): envías solo las propiedades que quieres cambiar y el resto del documento permanece intacto.

Usa los endpoints dedicados para cambiar el estado

Este endpoint no está diseñado para avanzar el ciclo de vida del pedido. Para eso usa los endpoints de transiciones de estado (/accept, /reject, /cancel, /status, /transition), que aplican las reglas de la máquina de estados y quedan registrados en el log de auditoría. Enviar orderStatus (u otros campos calculados como items, subtotal, tax o total) directamente por este endpoint no pasa por esa validación de negocio — evita hacerlo, aunque el transporte no lo rechace explícitamente.

Ejemplo

curl -X PUT https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer fkapi_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Depto 3B",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "notes": "Cliente cambió dirección por teléfono el 11-abr-2026"
  }'

Respuesta de ejemplo

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "orderStatus": "accepted",
    "shippingAddress": {
      "street": "Calle Insurgentes 456, Depto 3B",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zipCode": "03100",
      "country": "MX"
    },
    "notes": "Cliente cambió dirección por teléfono el 11-abr-2026",
    "updatedAt": "2026-04-11T15:02:44.000Z",
    "_links": {
      "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1",
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}

Actualizar solo los datos del cliente

Endpoint dedicado para reemplazar exclusivamente la información del cliente del pedido, sin tocar el resto del documento.

Actualiza los datos del cliente asociados al pedido

orderIdstringrequired

ID del pedido.

namestringrequired

Nombre del cliente.

{ "name": "María González Reyes" }

200

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "customerInfo": { "name": "María González Reyes" },
    "updatedAt": "2026-04-11T15:05:10.000Z",
    "_links": { "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1" }
  }
}

404

{ "error": { "code": "orders:not_found", "message": "Order not found" } }

Permiso requerido: orders:update

El cuerpo acepta el mismo objeto customerInfo usado al crear un pedido: el único campo confirmado como obligatorio es name.

curl -X PUT https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1/customer \
  -H "Authorization: Bearer fkapi_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "María González Reyes" }'

Respuesta de ejemplo

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "customerInfo": { "name": "María González Reyes" },
    "updatedAt": "2026-04-11T15:05:10.000Z",
    "_links": {
      "self": "/orders/65f3a1b2c4d5e6f7a8b9c0d1"
    }
  }
}

Agregar un comentario

Agrega una nota al historial del pedido. A diferencia de notes (un campo de texto libre reemplazable vía PUT /orders/:orderId), un comentario se registra como un evento append-only.

Agrega un comentario al pedido

orderIdstringrequired

ID del pedido.

commentstringrequired

Texto del comentario.

{ "comment": "Cliente confirmó recepción vía WhatsApp" }

200

{ "data": { "success": true, "orderId": "65f3a1b2c4d5e6f7a8b9c0d1" } }

404

{ "error": { "code": "orders:not_found", "message": "Order not found" } }

Permiso requerido: orders:update

curl -X POST https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1/comments \
  -H "Authorization: Bearer fkapi_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Cliente confirmó recepción vía WhatsApp" }'

Respuesta de ejemplo

{
  "data": {
    "success": true,
    "orderId": "65f3a1b2c4d5e6f7a8b9c0d1"
  }
}

Tip

Consulta el historial completo de comentarios y eventos con GET /orders/:orderId/activity-log.

Errores

Código	Status	Descripción
`orders:not_found`	404	No existe un pedido con ese ID en tu tenant.
`validation:invalid_input`	400	El cuerpo no cumple el formato esperado (por ejemplo, falta `comment` o `name`).
`auth:invalid_token`	401	La API key es inválida o fue revocada.
`auth:permission_denied`	403	La API key no tiene el scope `orders:update`.

Consulta el catálogo completo de errores para el resto de los códigos del dominio.