VitrinaAPI

Pedidos

Cada venta como un pedido: líneas con precio del catálogo, cobro con link de Mercado Pago, despacho y entrega.

Beta
Puede cambiar en cualquier momento, con una entrada en el changelog y aviso a quienes la llamaron recientemente — ver versionado.

Descarga la proyección completa de la API pública: openapi.json.

MétodoRutaQué hace
GET/ordersList orders
POST/ordersCreate an order
GET/orders/{id}Get an order
POST/orders/{id}/cancelCancel an unpaid order
POST/orders/{id}/confirmConfirm a draft order
POST/orders/{id}/fulfilmentMove a paid order along fulfilment
POST/orders/{id}/payment-linkGet the order’s Mercado Pago link
POST/orders/{id}/refundRefund a paid order in full
GET/orders/{id}/shipmentGet an order’s shipment and label
POST/orders/{id}/shipmentDispatch an order by courier
POST/orders/checkoutOpen a storefront guest checkout
GET/orders/checkout/{id}Get a storefront checkout’s status
GET/orders/checkout/payment-providersList the payment providers a storefront may offer
GET/orders/checkout/shipping-communesList the communes the store ships to
POST/orders/checkout/shipping-quotesQuote courier delivery for a checkout
DELETE/shipping/chilexpressDisconnect the store’s Chilexpress account
GET/shipping/chilexpressGet the store’s Chilexpress connection
PUT/shipping/chilexpressConnect or update the store’s Chilexpress account
POST/shipping/estimatesEstimate a delivery to where a buyer said

GET /orders

List orders

«Pedidos»: every order of the workspace, newest first, with its lines and its derived total_clp. Filter by status and source (comma-separated), or by contact_id / conversation_id / lead_id for the orders next to a chat or a lead. Page with meta.next_cursor. Requires orders:read.

ParámetroEnTipoObligatorioRestricciones
statusquerydraft \pending_payment \paid \
sourcequerynative \shopify \woocommerce[]
contact_idqueryuuidno
conversation_idqueryuuidno
lead_idqueryuuidno
limitqueryintegerno≥ 1, ≤ 200
cursorquerystringnomáx. 200
curl https://api.vitrinadev.com/api/v1/orders \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "0199e3b0-0000-7000-8000-000000000001",
      "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
      "display_id": "O-42",
      "source": "native",
      "external_id": null,
      "status": "pending_payment",
      "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
      "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
      "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
      "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
      "currency": "CLP",
      "delivery": {
        "recipient_name": "Cliente de ejemplo",
        "address": "Av. Ejemplo 123, depto 45",
        "comuna": "Providencia",
        "region": "Metropolitana"
      },
      "notes": null,
      "shipping_clp": 0,
      "total_clp": 39980,
      "item_count": 2,
      "stock_decremented_at": null,
      "paid_at": null,
      "ready_for_pickup_at": null,
      "shipped_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "cancelled_reason": null,
      "refunded_at": null,
      "refund_reason": null,
      "refund_reference": null,
      "buyer": {},
      "attribution": {},
      "client_event_id": null,
      "return_urls": null,
      "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
      "created_at": "2026-10-15T12:00:00.000Z",
      "updated_at": "2026-10-15T12:00:00.000Z",
      "lines": [
        {
          "id": "0199e3b0-0000-7000-8000-0000000000d1",
          "position": 0,
          "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
          "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
          "title": "Polera básica",
          "variant_title": "M / Negro",
          "variant_options": [
            {
              "name": "Talla",
              "value": "M"
            },
            {
              "name": "Color",
              "value": "Negro"
            }
          ],
          "sku": "POL-M-NEG",
          "unit_price_clp": 9990,
          "quantity": 2,
          "line_total_clp": 19980,
          "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
        },
        {
          "id": "0199e3b0-0000-7000-8000-0000000000d2",
          "position": 1,
          "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
          "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
          "title": "Polera básica",
          "variant_title": "L / Blanco",
          "variant_options": [
            {
              "name": "Talla",
              "value": "L"
            },
            {
              "name": "Color",
              "value": "Blanco"
            }
          ],
          "sku": "POL-L-BLA",
          "unit_price_clp": 20000,
          "quantity": 1,
          "line_total_clp": 20000,
          "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
        }
      ]
    }
  ],
  "meta": {
    "next_cursor": null
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders

Create an order

A native order for a contact. Prices come from the catalog: each line names a variant_id (or the product_id of a product without variants) and a quantity, and its unit price is the variant’s price, else the product’s, frozen on the line. There is no price field. A line on an inactive item, an item without a CLP price, or more units than the store would sell (tracked stock, policy deny) is refused with 422 / 409 naming the line.

With status: pending_payment (the default) the payment opens in the same write: one obligation group of kind order (obligation_group_id) with one product obligation per line, so POST /orders/\{id\}/payment-link (or «Enviar link de pago» with group_id) charges it on Mercado Pago. When that payment settles the order becomes paid and its native stock is decremented once. The lead (lead_id, else the conversation’s open lead) moves to «Carrito» on an ecommerce_orders board. Fires order.created. Requires orders:write.

Cuerpo

CampoTipoObligatorioRestricciones
contact_iduuidsí
conversation_iduuid—
lead_iduuid—
linesobject[]sí
deliveryobject—
notesstring—máx. 2000
statusdraft \pending_payment—
curl -X POST https://api.vitrinadev.com/api/v1/orders \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
    "lines": [
      {
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "quantity": 2
      },
      {
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
        "quantity": 1
      }
    ],
    "delivery": {
      "recipient_name": "Cliente de ejemplo",
      "address": "Av. Ejemplo 123, depto 45",
      "comuna": "Providencia",
      "region": "Metropolitana"
    }
  }'

Ejemplo de respuesta (201)

{
  "data": {
    "id": "0199e3b0-0000-7000-8000-000000000001",
    "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
    "display_id": "O-42",
    "source": "native",
    "external_id": null,
    "status": "pending_payment",
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
    "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
    "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
    "currency": "CLP",
    "delivery": {
      "recipient_name": "Cliente de ejemplo",
      "address": "Av. Ejemplo 123, depto 45",
      "comuna": "Providencia",
      "region": "Metropolitana"
    },
    "notes": null,
    "shipping_clp": 0,
    "total_clp": 39980,
    "item_count": 2,
    "stock_decremented_at": null,
    "paid_at": null,
    "ready_for_pickup_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "cancelled_reason": null,
    "refunded_at": null,
    "refund_reason": null,
    "refund_reference": null,
    "buyer": {},
    "attribution": {},
    "client_event_id": null,
    "return_urls": null,
    "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
    "created_at": "2026-10-15T12:00:00.000Z",
    "updated_at": "2026-10-15T12:00:00.000Z",
    "lines": [
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d1",
        "position": 0,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "title": "Polera básica",
        "variant_title": "M / Negro",
        "variant_options": [
          {
            "name": "Talla",
            "value": "M"
          },
          {
            "name": "Color",
            "value": "Negro"
          }
        ],
        "sku": "POL-M-NEG",
        "unit_price_clp": 9990,
        "quantity": 2,
        "line_total_clp": 19980,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
      },
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d2",
        "position": 1,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
        "title": "Polera básica",
        "variant_title": "L / Blanco",
        "variant_options": [
          {
            "name": "Talla",
            "value": "L"
          },
          {
            "name": "Color",
            "value": "Blanco"
          }
        ],
        "sku": "POL-L-BLA",
        "unit_price_clp": 20000,
        "quantity": 1,
        "line_total_clp": 20000,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
      }
    ]
  }
}

Responde: 201 · 400 · 401 · 403 · 404 · 409 · 429

GET /orders/{id}

Get an order

One order with its lines and the buyer emails it sent (buyer_emails: kind, status, sent_at), by uuid or display id (O-42). status is the order’s lifecycle; whether money arrived is the ledger’s (GET /obligations?group_id=…). Requires orders:read.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí
curl https://api.vitrinadev.com/api/v1/orders/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "id": "0199e3b0-0000-7000-8000-000000000001",
    "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
    "display_id": "O-42",
    "source": "native",
    "external_id": null,
    "status": "paid",
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
    "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
    "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
    "currency": "CLP",
    "delivery": {
      "recipient_name": "Cliente de ejemplo",
      "address": "Av. Ejemplo 123, depto 45",
      "comuna": "Providencia",
      "region": "Metropolitana"
    },
    "notes": null,
    "shipping_clp": 0,
    "total_clp": 39980,
    "item_count": 2,
    "stock_decremented_at": null,
    "paid_at": null,
    "ready_for_pickup_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "cancelled_reason": null,
    "refunded_at": null,
    "refund_reason": null,
    "refund_reference": null,
    "buyer": {},
    "attribution": {},
    "client_event_id": null,
    "return_urls": null,
    "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
    "created_at": "2026-10-15T12:00:00.000Z",
    "updated_at": "2026-10-15T12:00:00.000Z",
    "lines": [
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d1",
        "position": 0,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "title": "Polera básica",
        "variant_title": "M / Negro",
        "variant_options": [
          {
            "name": "Talla",
            "value": "M"
          },
          {
            "name": "Color",
            "value": "Negro"
          }
        ],
        "sku": "POL-M-NEG",
        "unit_price_clp": 9990,
        "quantity": 2,
        "line_total_clp": 19980,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
      },
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d2",
        "position": 1,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
        "title": "Polera básica",
        "variant_title": "L / Blanco",
        "variant_options": [
          {
            "name": "Talla",
            "value": "L"
          },
          {
            "name": "Color",
            "value": "Blanco"
          }
        ],
        "sku": "POL-L-BLA",
        "unit_price_clp": 20000,
        "quantity": 1,
        "line_total_clp": 20000,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
      }
    ],
    "buyer_emails": [
      {
        "kind": "order_confirmed",
        "status": "delivered",
        "to": "[email protected]",
        "sent_at": "2026-10-31T14:02:11.000Z",
        "delivered_at": "2026-10-31T14:02:13.000Z",
        "failed_at": null,
        "attempts": 1,
        "created_at": "2026-10-31T14:02:10.000Z"
      }
    ]
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/{id}/cancel

Cancel an unpaid order

Cancels a draft or pending_payment order: its obligations and its group are cancelled and its Mercado Pago link stops taking money (a payment already in flight is credited to the customer, applied to nothing). An order that already received money answers 409 order_has_payments, a paid one 409 order_paid: giving money back is a refund on the payments ledger. Cancelling twice returns the cancelled order. Fires order.status_changed. Requires orders:write.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí

Cuerpo

CampoTipoObligatorioRestricciones
reasonstringsímín. 1, máx. 500
curl -X POST https://api.vitrinadev.com/api/v1/orders/<id>/cancel \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "El cliente se arrepintió antes de pagar"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "0199e3b0-0000-7000-8000-000000000001",
    "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
    "display_id": "O-42",
    "source": "native",
    "external_id": null,
    "status": "cancelled",
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
    "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
    "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
    "currency": "CLP",
    "delivery": {
      "recipient_name": "Cliente de ejemplo",
      "address": "Av. Ejemplo 123, depto 45",
      "comuna": "Providencia",
      "region": "Metropolitana"
    },
    "notes": null,
    "shipping_clp": 0,
    "total_clp": 39980,
    "item_count": 2,
    "stock_decremented_at": null,
    "paid_at": null,
    "ready_for_pickup_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": "2026-10-15T12:30:00.000Z",
    "cancelled_reason": "El cliente se arrepintió antes de pagar",
    "refunded_at": null,
    "refund_reason": null,
    "refund_reference": null,
    "buyer": {},
    "attribution": {},
    "client_event_id": null,
    "return_urls": null,
    "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
    "created_at": "2026-10-15T12:00:00.000Z",
    "updated_at": "2026-10-15T12:00:00.000Z",
    "lines": [
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d1",
        "position": 0,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "title": "Polera básica",
        "variant_title": "M / Negro",
        "variant_options": [
          {
            "name": "Talla",
            "value": "M"
          },
          {
            "name": "Color",
            "value": "Negro"
          }
        ],
        "sku": "POL-M-NEG",
        "unit_price_clp": 9990,
        "quantity": 2,
        "line_total_clp": 19980,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
      },
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d2",
        "position": 1,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
        "title": "Polera básica",
        "variant_title": "L / Blanco",
        "variant_options": [
          {
            "name": "Talla",
            "value": "L"
          },
          {
            "name": "Color",
            "value": "Blanco"
          }
        ],
        "sku": "POL-L-BLA",
        "unit_price_clp": 20000,
        "quantity": 1,
        "line_total_clp": 20000,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
      }
    ]
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/{id}/confirm

Confirm a draft order

draft → pending_payment: opens the order’s payment (its obligation group and one obligation per line) at the prices frozen when the draft was created. 409 order_not_draft for any other status. Fires order.status_changed. Requires orders:write.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí
curl -X POST https://api.vitrinadev.com/api/v1/orders/<id>/confirm \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "id": "0199e3b0-0000-7000-8000-000000000001",
    "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
    "display_id": "O-42",
    "source": "native",
    "external_id": null,
    "status": "pending_payment",
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
    "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
    "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
    "currency": "CLP",
    "delivery": {
      "recipient_name": "Cliente de ejemplo",
      "address": "Av. Ejemplo 123, depto 45",
      "comuna": "Providencia",
      "region": "Metropolitana"
    },
    "notes": null,
    "shipping_clp": 0,
    "total_clp": 39980,
    "item_count": 2,
    "stock_decremented_at": null,
    "paid_at": null,
    "ready_for_pickup_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "cancelled_reason": null,
    "refunded_at": null,
    "refund_reason": null,
    "refund_reference": null,
    "buyer": {},
    "attribution": {},
    "client_event_id": null,
    "return_urls": null,
    "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
    "created_at": "2026-10-15T12:00:00.000Z",
    "updated_at": "2026-10-15T12:00:00.000Z",
    "lines": [
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d1",
        "position": 0,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "title": "Polera básica",
        "variant_title": "M / Negro",
        "variant_options": [
          {
            "name": "Talla",
            "value": "M"
          },
          {
            "name": "Color",
            "value": "Negro"
          }
        ],
        "sku": "POL-M-NEG",
        "unit_price_clp": 9990,
        "quantity": 2,
        "line_total_clp": 19980,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
      },
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d2",
        "position": 1,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
        "title": "Polera básica",
        "variant_title": "L / Blanco",
        "variant_options": [
          {
            "name": "Talla",
            "value": "L"
          },
          {
            "name": "Color",
            "value": "Blanco"
          }
        ],
        "sku": "POL-L-BLA",
        "unit_price_clp": 20000,
        "quantity": 1,
        "line_total_clp": 20000,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
      }
    ]
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/{id}/fulfilment

Move a paid order along fulfilment

Courier: paid → preparing → shipped → delivered. Pickup: paid → preparing → ready_for_pickup → delivered («Listo para retiro»). A step may be skipped (paid → shipped, paid → delivered). An unpaid order answers 409 invalid_transition; ready_for_pickup on a courier order 409 not_a_pickup_order; shipped on a pickup order 409 pickup_order_not_shipped. A storefront buyer is emailed once per step (ready_for_pickup, shipped, delivered; the confirmation goes out when it is paid), and a failed email never fails the move. The lead follows on an ecommerce_orders board (Despachado, Postventa). Fires order.status_changed. Requires orders:write.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí

Cuerpo

CampoTipoObligatorioRestricciones
statuspreparing \ready_for_pickup \shipped \
curl -X POST https://api.vitrinadev.com/api/v1/orders/<id>/fulfilment \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "0199e3b0-0000-7000-8000-000000000001",
    "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
    "display_id": "O-42",
    "source": "native",
    "external_id": null,
    "status": "shipped",
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
    "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
    "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
    "currency": "CLP",
    "delivery": {
      "recipient_name": "Cliente de ejemplo",
      "address": "Av. Ejemplo 123, depto 45",
      "comuna": "Providencia",
      "region": "Metropolitana"
    },
    "notes": null,
    "shipping_clp": 0,
    "total_clp": 39980,
    "item_count": 2,
    "stock_decremented_at": null,
    "paid_at": null,
    "ready_for_pickup_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "cancelled_reason": null,
    "refunded_at": null,
    "refund_reason": null,
    "refund_reference": null,
    "buyer": {},
    "attribution": {},
    "client_event_id": null,
    "return_urls": null,
    "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
    "created_at": "2026-10-15T12:00:00.000Z",
    "updated_at": "2026-10-15T12:00:00.000Z",
    "lines": [
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d1",
        "position": 0,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "title": "Polera básica",
        "variant_title": "M / Negro",
        "variant_options": [
          {
            "name": "Talla",
            "value": "M"
          },
          {
            "name": "Color",
            "value": "Negro"
          }
        ],
        "sku": "POL-M-NEG",
        "unit_price_clp": 9990,
        "quantity": 2,
        "line_total_clp": 19980,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
      },
      {
        "id": "0199e3b0-0000-7000-8000-0000000000d2",
        "position": 1,
        "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
        "title": "Polera básica",
        "variant_title": "L / Blanco",
        "variant_options": [
          {
            "name": "Talla",
            "value": "L"
          },
          {
            "name": "Color",
            "value": "Blanco"
          }
        ],
        "sku": "POL-L-BLA",
        "unit_price_clp": 20000,
        "quantity": 1,
        "line_total_clp": 20000,
        "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
      }
    ]
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/{id}/payment-link

Get the order’s Mercado Pago link

The Checkout Pro link for what the order still owes, created from the workspace’s own connected Mercado Pago account and reused while the amount matches. Creating it states what is owed; it never marks anything paid. 409 order_not_payable unless the order is pending_payment, not_connected without Mercado Pago. To send it through the conversation use POST /payment-links with the order’s obligation_group_id as group_id. Requires orders:write.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí
curl -X POST https://api.vitrinadev.com/api/v1/orders/<id>/payment-link \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "checkout_id": "0199e3b0-0000-7000-8000-0000000000b1",
    "checkout_url": "https://www.mercadopago.cl/checkout/v1/redirect?pref_id=123456789-abc",
    "amount_clp": 39980,
    "installments": true,
    "receipt_url": "https://app.example.com/pago/0199e3b0-0000-7000-8000-0000000000b1",
    "obligation_id": null,
    "group_id": "0199e3b0-0000-7000-8000-000000000002"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/{id}/refund

Refund a paid order in full

Gives a paid native order back in full (paid, preparing, shipped or delivered): retracto, a defect, a unit that could not be delivered. The refund runs at the provider the order was paid with, the workspace's own Mercado Pago, Webpay Plus (a reversal the same day, an annulment later) or banca.me (the loan is cancelled and banca.me returns any installment already paid; only within 60 days of the disbursement), against the order's payment (idempotent per order: a retry never refunds twice), the payment is reversed in the ledger and the ads engine nets the Purchase, the order becomes refunded and order.status_changed fires with changes.status.to = refunded (its data.payment names the refunded payment and its provider; data.refunded_at and data.refund_reason are set). The sold units go back on hand only when the workspace's own stock is Vitrina-managed (restored_units); when another system writes on-hand counts (a back office syncing absolute stock) nothing is added: that system reacts to the event. Refunding a refunded order answers 200 with refunded: false. Errors: 409 order_not_paid (draft, pending payment or cancelled), 409 payment_not_refundable (not paid through Mercado Pago, Webpay or banca.me, e.g. a recorded transfer), 409 refund_not_supported, 409 payment_not_connected, 409 store_order; 502 refund_refused (the provider said no: past the refund window, e.g. banca.me after 60 days, a transaction not committed) or payment_provider_unavailable. On a 502 the order is unchanged and the call may be retried. Requires orders:refund (staff only; it is not part of any agent or storefront key).

ParámetroEnTipoObligatorioRestricciones
idpathstringsí

Cuerpo

CampoTipoObligatorioRestricciones
reasonstringsímín. 1, máx. 500
curl -X POST https://api.vitrinadev.com/api/v1/orders/<id>/refund \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Retracto: el cliente se arrepintió dentro de los 10 días"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "order": {
      "id": "0199e3b0-0000-7000-8000-000000000001",
      "tenant_id": "0199e3b0-0000-7000-8000-0000000000aa",
      "display_id": "O-42",
      "source": "native",
      "external_id": null,
      "status": "refunded",
      "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
      "conversation_id": "0199e3b0-0000-7000-8000-0000000000c2",
      "lead_id": "0199e3b0-0000-7000-8000-0000000000c3",
      "obligation_group_id": "0199e3b0-0000-7000-8000-000000000002",
      "currency": "CLP",
      "delivery": {
        "recipient_name": "Cliente de ejemplo",
        "address": "Av. Ejemplo 123, depto 45",
        "comuna": "Providencia",
        "region": "Metropolitana"
      },
      "notes": null,
      "shipping_clp": 0,
      "total_clp": 39980,
      "item_count": 2,
      "stock_decremented_at": null,
      "paid_at": "2026-10-15T12:05:00.000Z",
      "ready_for_pickup_at": null,
      "shipped_at": null,
      "delivered_at": null,
      "cancelled_at": null,
      "cancelled_reason": null,
      "refunded_at": "2026-10-16T09:00:00.000Z",
      "refund_reason": "Retracto: el cliente se arrepintió dentro de los 10 días",
      "refund_reference": "1318847654",
      "buyer": {},
      "attribution": {},
      "client_event_id": null,
      "return_urls": null,
      "created_by": "0199e3b0-0000-7000-8000-0000000000bb",
      "created_at": "2026-10-15T12:00:00.000Z",
      "updated_at": "2026-10-15T12:00:00.000Z",
      "lines": [
        {
          "id": "0199e3b0-0000-7000-8000-0000000000d1",
          "position": 0,
          "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
          "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
          "title": "Polera básica",
          "variant_title": "M / Negro",
          "variant_options": [
            {
              "name": "Talla",
              "value": "M"
            },
            {
              "name": "Color",
              "value": "Negro"
            }
          ],
          "sku": "POL-M-NEG",
          "unit_price_clp": 9990,
          "quantity": 2,
          "line_total_clp": 19980,
          "obligation_id": "0199e3b0-0000-7000-8000-0000000000a1"
        },
        {
          "id": "0199e3b0-0000-7000-8000-0000000000d2",
          "position": 1,
          "product_id": "0199e3b0-0000-7000-8000-0000000000e1",
          "variant_id": "0199e3b0-0000-7000-8000-0000000000f2",
          "title": "Polera básica",
          "variant_title": "L / Blanco",
          "variant_options": [
            {
              "name": "Talla",
              "value": "L"
            },
            {
              "name": "Color",
              "value": "Blanco"
            }
          ],
          "sku": "POL-L-BLA",
          "unit_price_clp": 20000,
          "quantity": 1,
          "line_total_clp": 20000,
          "obligation_id": "0199e3b0-0000-7000-8000-0000000000a2"
        }
      ]
    },
    "refunded": true,
    "restored_units": 1
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /orders/{id}/shipment

Get an order’s shipment and label

The courier shipment of an order: number, public tracking link, service, and the label to print (label.base64, a JPEG), or null once erased. 404 before dispatch. Requires orders:read.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí
curl https://api.vitrinadev.com/api/v1/orders/<id>/shipment \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "carrier": "chilexpress",
    "environment": "test",
    "shipment_number": "712678918615",
    "tracking_url": "https://centrodeayuda.chilexpress.cl/seguimiento/712678918615",
    "service_code": 3,
    "service_name": "EXPRESS",
    "reference": "O-42",
    "has_label": true,
    "created_at": "2026-10-30T12:00:00.000Z",
    "label": {
      "content_type": "image/jpeg",
      "base64": "/9j/4AAQSkZJRgABAQ…"
    }
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/{id}/shipment

Dispatch an order by courier

«Despachar»: creates the shipment (transport order) at Chilexpress for a paid order with delivery.method = shipping, stores its number, its public tracking link and its label (GET /orders/\{id\}/shipment), writes delivery.shipment on the order and moves it to shipped (fires order.status_changed). Dispatching again returns the existing shipment (200, created: false).

Refusals (error.details.reason): 409 not_a_shipping_order · order_not_dispatchable · shipping_address_incomplete · shipping_not_connected · shipping_dispatch_not_configured · shipping_key_rejected · store_order; 400 shipping_rejected (Chilexpress refused the data; details.provider_errors); 502 shipping_provider_unavailable. Requires orders:write.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí

Cuerpo

CampoTipoObligatorioRestricciones
service_codeinteger—
curl -X POST https://api.vitrinadev.com/api/v1/orders/<id>/shipment \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Ejemplo de respuesta (200)

{
  "data": {
    "shipment": {
      "carrier": "chilexpress",
      "environment": "test",
      "shipment_number": "712678918615",
      "tracking_url": "https://centrodeayuda.chilexpress.cl/seguimiento/712678918615",
      "service_code": 3,
      "service_name": "EXPRESS",
      "reference": "O-42",
      "has_label": true,
      "created_at": "2026-10-30T12:00:00.000Z"
    },
    "created": false
  }
}

Responde: 200 · 201 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/checkout

Open a storefront guest checkout

A tenant’s own website (server side) sells with one call: the buyer (name, RUT, phone and/or email), the variants, the delivery method and optionally the payment provider in; an order and its payment link out (Mercado Pago by default, Webpay with payment_provider: "webpay", or banca.me «cuotas sin tarjeta» with payment_provider: "bancame", when the tenant connected it: see GET /orders/checkout/payment-providers). The buyer is found by email, then phone, or created; their RUT fills the contact’s empty one; an opt-in is recorded; the visit’s ad touch is kept for the Purchase. Prices come from the catalog (no price field); only native products.

Holds. A variant with inventory policy deny («Solo con stock») holds the requested units for 15 minutes (50 with bancame): available = on hand − active holds, and the link stops taking money when the hold ends. With fewer units available the call is refused with 409 insufficient_stock (details.available). Two checkouts for the last unit: exactly one succeeds. A continue variant (made to order) never refuses and holds nothing. The hold ends when the payment settles (the sale: on hand goes down by the units), when the order is cancelled, or when it expires (the order is then cancelled and order.status_changed fires).

event_id is the browser InitiateCheckout eventID: the server InitiateCheckout (when the buyer opens checkout_url) and the Purchase ship under it, so Meta deduplicates. It is also the idempotency key (200 + replayed: true).

Refusals (error.details.reason): 400 buyer_contact_required · invalid_phone · invalid_rut · shipping_quote_required · shipping_address_required · shipping_phone_required · shipping_quote_unknown · shipping_service_required · shipping_service_unavailable · unknown_item · inactive_item · no_price · variant_required; 409 insufficient_stock · store_item · event_id_reused · checkout_closed · already_paid · payment_not_connected · payment_provider_not_connected · payment_buyer_has_active_loan (banca.me: the buyer already has a loan) · shipping_quote_expired · shipping_quote_used · shipping_quote_items_mismatch · shipping_quote_destination_mismatch; 502 payment_provider_unavailable. Fires order.created. Requires orders:checkout.

Cuerpo

CampoTipoObligatorioRestricciones
event_idstringsípatrón ^[A-Za-z0-9_.:-]{8,128}$
buyerobjectsí
itemsobject[]sí
deliveryobjectsí
consentobject—
attributionobject—
return_urlsobjectsí
payment_providermercadopago \webpay \bancame
notesstring—máx. 1000
curl -X POST https://api.vitrinadev.com/api/v1/orders/checkout \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "ck_01JBX4W7Q2M5Z8",
    "buyer": {
      "name": "Camila Rojas",
      "rut": "12.345.678-5",
      "phone": "+56 9 1234 5678",
      "email": "[email protected]"
    },
    "items": [
      {
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "quantity": 1
      }
    ],
    "delivery": {
      "method": "pickup"
    },
    "consent": {
      "granted": true,
      "source_url": "https://tienda.example.cl/checkout",
      "text_version": "v1"
    },
    "attribution": {
      "utm_source": "facebook",
      "utm_medium": "paid",
      "utm_campaign": "iphone14",
      "fbclid": "IwAR0abc",
      "anonymous_id": "anon_7f3c9a1b2d",
      "fbp": "fb.1.1730000000000.1234567890"
    },
    "return_urls": {
      "success": "https://tienda.example.cl/compra/ok",
      "failure": "https://tienda.example.cl/compra/error",
      "pending": "https://tienda.example.cl/compra/pendiente"
    }
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "order": {
      "order_id": "0199e3b0-0000-7000-8000-000000000001",
      "display_id": "O-42",
      "status": "pending_payment",
      "total_clp": 459990,
      "currency": "CLP",
      "lines": [
        {
          "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
          "sku": "IP14-128-NEG",
          "title": "iPhone 14 128 GB",
          "variant_title": "Negro",
          "options": [
            {
              "name": "Color",
              "value": "Negro"
            }
          ],
          "quantity": 1,
          "unit_price_clp": 459990
        }
      ],
      "delivery_method": "pickup",
      "shipping_clp": 0,
      "shipping": null,
      "paid_at": null,
      "cancelled_at": null,
      "hold_expires_at": "2026-10-29T15:15:00.000Z",
      "payment_failure": null,
      "created_at": "2026-10-29T15:00:00.000Z"
    },
    "checkout": {
      "checkout_id": "0199e3b0-0000-7000-8000-0000000000b1",
      "checkout_url": "https://api.vitrinadev.com/p/0199e3b0-0000-7000-8000-0000000000b1",
      "provider": "mercadopago",
      "amount_clp": 459990,
      "expires_at": "2026-10-29T15:15:00.000Z"
    },
    "hold": {
      "expires_at": "2026-10-29T15:15:00.000Z",
      "variant_ids": [
        "0199e3b0-0000-7000-8000-0000000000f1"
      ]
    },
    "contact_id": "0199e3b0-0000-7000-8000-0000000000c1",
    "replayed": true
  }
}

Responde: 200 · 201 · 400 · 401 · 403 · 404 · 409 · 429

GET /orders/checkout/{id}

Get a storefront checkout’s status

The status of an order opened by POST /orders/checkout (uuid or O-42), for the site’s return page: pending_payment (with hold_expires_at), paid, cancelled (expired or cancelled; payment_failure says when a banca.me application was rejected or expired, #6402). No buyer data. Any other order answers 404. Requires orders:checkout.

ParámetroEnTipoObligatorioRestricciones
idpathstringsí
curl https://api.vitrinadev.com/api/v1/orders/checkout/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "order_id": "0199e3b0-0000-7000-8000-000000000001",
    "display_id": "O-42",
    "status": "pending_payment",
    "total_clp": 459990,
    "currency": "CLP",
    "lines": [
      {
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "sku": "IP14-128-NEG",
        "title": "iPhone 14 128 GB",
        "variant_title": "Negro",
        "options": [
          {
            "name": "Color",
            "value": "Negro"
          }
        ],
        "quantity": 1,
        "unit_price_clp": 459990
      }
    ],
    "delivery_method": "pickup",
    "shipping_clp": 0,
    "shipping": null,
    "paid_at": null,
    "cancelled_at": null,
    "hold_expires_at": "2026-10-29T15:15:00.000Z",
    "payment_failure": null,
    "created_at": "2026-10-29T15:00:00.000Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /orders/checkout/payment-providers

List the payment providers a storefront may offer

The providers the tenant connected that a storefront checkout can charge through (mercadopago, webpay, bancame), in the order to offer them, and the default used when POST /orders/checkout names none. Offer a choice only when there are two or more; pass the buyer’s pick as payment_provider. Requires orders:checkout.

curl https://api.vitrinadev.com/api/v1/orders/checkout/payment-providers \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "default": "mercadopago",
    "providers": [
      {
        "provider": "mercadopago",
        "name": "Mercado Pago"
      },
      {
        "provider": "webpay",
        "name": "Webpay"
      }
    ]
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /orders/checkout/shipping-communes

List the communes the store ships to

Every commune (and locality) the store’s courier (Chilexpress) delivers to, with the coverage_code a quote takes. Cached 12 hours. 409 shipping_not_connected when the store has no courier connected. Requires orders:checkout (a storefront’s key) or orders:read.

curl https://api.vitrinadev.com/api/v1/orders/checkout/shipping-communes \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "coverage_code": "CONC",
      "name": "Concepcion",
      "commune": "Concepcion",
      "region_code": "R8",
      "region": "Biobio",
      "kind": "commune"
    }
  ]
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /orders/checkout/shipping-quotes

Quote courier delivery for a checkout

The price (and an estimated transit in business days) of delivering these items to a commune, per service the store offers, cheapest first. The package is the store’s unit box × the quantity; the declared value is the items’ catalog price. The quote is kept 30 minutes: send its quote_id (and a service_code when there are several options) in POST /orders/checkout with delivery.method = shipping; the price is charged with the products in the same payment. The caller never states a price.

Refusals (error.details.reason): 400 unknown_commune · commune_required · unknown_item · inactive_item · no_price; 409 shipping_not_connected · no_shipping_service · insufficient_stock · shipping_key_rejected; 502 shipping_provider_unavailable. Requires orders:checkout (a storefront’s key) or orders:read.

Cuerpo

CampoTipoObligatorioRestricciones
itemsobject[]sí
destinationobjectsí
curl -X POST https://api.vitrinadev.com/api/v1/orders/checkout/shipping-quotes \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "variant_id": "0199e3b0-0000-7000-8000-0000000000f1",
        "quantity": 1
      }
    ],
    "destination": {
      "coverage_code": "CONC"
    }
  }'

Ejemplo de respuesta (201)

{
  "data": {
    "quote_id": "0199e3b0-0000-7000-8000-0000000000a9",
    "carrier": "chilexpress",
    "destination": {
      "coverage_code": "CONC",
      "commune": "Concepcion",
      "region_code": "R8",
      "region": "Biobio"
    },
    "options": [
      {
        "service_code": 3,
        "service_name": "Express",
        "price_clp": 6424,
        "estimated_business_days": 2
      }
    ],
    "expires_at": "2026-10-29T15:30:00.000Z"
  }
}

Responde: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /shipping/chilexpress

Disconnect the store’s Chilexpress account

Disables the connection (reversible: connecting again re-enables it). Quotes and dispatches answer 409 shipping_not_connected until then; shipments already created keep their tracking links. Requires tenant:write.

curl -X DELETE https://api.vitrinadev.com/api/v1/shipping/chilexpress \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "connected": false,
    "environment": "test",
    "origin_coverage_code": "PROV",
    "origin_commune": "Providencia",
    "origin_region_code": "RM",
    "customer_card_number": "18578680",
    "keys": {
      "rating": "a1b2••••9f",
      "shipments": "c3d4••••0e",
      "coverage": null
    },
    "can_dispatch": true,
    "sender": {
      "name": "Tienda Ejemplo",
      "phone": "+56912345678",
      "email": "[email protected]"
    },
    "return_address": {
      "street": "Av. Ejemplo",
      "number": "123",
      "supplement": "Oficina 5"
    },
    "package": {
      "weight_kg": 0.6,
      "height_cm": 8,
      "width_cm": 12,
      "length_cm": 20
    },
    "services": [
      3
    ],
    "declared_content": "celular",
    "seller_rut": null,
    "connected_at": "2026-10-29T15:00:00.000Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /shipping/chilexpress

Get the store’s Chilexpress connection

The store’s own Chilexpress account as connected: environment, origin commune, TCC, sender, return address, default package, offered services, and masked key previews (never the keys). connected: false when none. Requires tenant:read.

curl https://api.vitrinadev.com/api/v1/shipping/chilexpress \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "connected": true,
    "environment": "test",
    "origin_coverage_code": "PROV",
    "origin_commune": "Providencia",
    "origin_region_code": "RM",
    "customer_card_number": "18578680",
    "keys": {
      "rating": "a1b2••••9f",
      "shipments": "c3d4••••0e",
      "coverage": null
    },
    "can_dispatch": true,
    "sender": {
      "name": "Tienda Ejemplo",
      "phone": "+56912345678",
      "email": "[email protected]"
    },
    "return_address": {
      "street": "Av. Ejemplo",
      "number": "123",
      "supplement": "Oficina 5"
    },
    "package": {
      "weight_kg": 0.6,
      "height_cm": 8,
      "width_cm": 12,
      "length_cm": 20
    },
    "services": [
      3
    ],
    "declared_content": "celular",
    "seller_rut": null,
    "connected_at": "2026-10-29T15:00:00.000Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /shipping/chilexpress

Connect or update the store’s Chilexpress account

Saves the store’s own Chilexpress account (developers.wschilexpress.com subscription keys, Tarjeta Cliente Chilexpress, origin commune, sender, return address, default package). The Cotizador key is verified with a real quote first; keys are stored encrypted and never returned. Keys not sent are kept. The Envíos key is proven on the first dispatch. Production keys may need a commercial agreement with Chilexpress.

Refusals (error.details.reason): 400 invalid_chilexpress_settings (details.field) · chilexpress_key_rejected · unknown_commune; 502 shipping_provider_unavailable. Requires tenant:write.

Cuerpo

CampoTipoObligatorioRestricciones
environmenttest \productionsí
rating_keystring—mín. 8, máx. 200
shipments_keystring | null—máx. 200
coverage_keystring | null—máx. 200
customer_card_numberstring | null—patrón ^[0-9]{1,12}$
origin_communestringsímín. 2, máx. 120
origin_region_codestring—máx. 4
senderobjectsí
return_addressobjectsí
packageobject—
servicesinteger[]—
declared_contentcelular \tecnologia \articulos_personales \
seller_rutstring | null—patrón ^[0-9]{6,9}$
curl -X PUT https://api.vitrinadev.com/api/v1/shipping/chilexpress \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "test",
    "rating_key": "<Cotizador primary key>",
    "shipments_key": "<Envíos primary key>",
    "customer_card_number": "18578680",
    "origin_commune": "Providencia",
    "sender": {
      "name": "Tienda Ejemplo",
      "phone": "+56912345678",
      "email": "[email protected]"
    },
    "return_address": {
      "street": "Av. Ejemplo",
      "number": "123",
      "supplement": "Oficina 5"
    },
    "declared_content": "celular"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "connected": true,
    "environment": "test",
    "origin_coverage_code": "PROV",
    "origin_commune": "Providencia",
    "origin_region_code": "RM",
    "customer_card_number": "18578680",
    "keys": {
      "rating": "a1b2••••9f",
      "shipments": "c3d4••••0e",
      "coverage": null
    },
    "can_dispatch": true,
    "sender": {
      "name": "Tienda Ejemplo",
      "phone": "+56912345678",
      "email": "[email protected]"
    },
    "return_address": {
      "street": "Av. Ejemplo",
      "number": "123",
      "supplement": "Oficina 5"
    },
    "package": {
      "weight_kg": 0.6,
      "height_cm": 8,
      "width_cm": 12,
      "length_cm": 20
    },
    "services": [
      3
    ],
    "declared_content": "celular",
    "seller_rut": null,
    "connected_at": "2026-10-29T15:00:00.000Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /shipping/estimates

Estimate a delivery to where a buyer said

Prices a Chilexpress delivery from the store’s connection (its origin, the services it offers, its default box times quantity) to a destination as a buyer wrote it: a commune («Ñuñoa», «Stgo centro»), an address («Av. Alemania 0450, Temuco») and/or a region. Stores nothing: there is no quote id, and a checkout still needs POST /orders/checkout/shipping-quotes. Never creates a shipment. Without an item (or one with no price) the declared value, which changes Chilexpress’s price, is the median price of the store’s active catalog × quantity (declared.basis). status: quoted (destination + options), needs_commune (reason missing / ambiguous / region_mismatch / not_found, with candidates to ask about; send the chosen coverage_code back), not_covered (no offered service reaches it), unknown_item. The same answer the AI agent’s quote_shipping tool gives. 409 shipping_not_connected without a courier. Requires orders:read.

Cuerpo

CampoTipoObligatorioRestricciones
communestring—máx. 120
addressstring—máx. 300
regionstring—máx. 80
coverage_codestring—máx. 6
itemstring—máx. 120
quantityinteger—≥ 1, ≤ 10
curl -X POST https://api.vitrinadev.com/api/v1/shipping/estimates \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "Av. Alemania 0450, Temuco"
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "status": "quoted",
    "carrier": "chilexpress",
    "destination": {
      "coverage_code": "TEMU",
      "commune": "Temuco",
      "region_code": "R9",
      "region": "Araucania"
    },
    "options": [
      {
        "service_code": 3,
        "service_name": "Express",
        "price_clp": 6965,
        "estimated_business_days": 2
      }
    ],
    "item": null,
    "declared": {
      "value_clp": 580000,
      "basis": "catalog_median"
    },
    "package": {
      "weight_kg": 0.6,
      "height_cm": 8,
      "width_cm": 12,
      "length_cm": 20
    },
    "units": 1
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

Buzones de envío

Los buzones desde los que la persona conectada puede enviar un correo nuevo: el suyo y el principal del workspace, con cuál se usa por defecto. Su id es el `from_account_id` de un envío o un borrador.

Datos legales

La identidad legal de la automotora (razón social, RUT, giro, domicilio, representante y escritura) y sus poderes. Sin ella, imprimir una nota de venta o una compraventa responde 409.

En esta página

GET /ordersPOST /ordersGET /orders/{id}POST /orders/{id}/cancelPOST /orders/{id}/confirmPOST /orders/{id}/fulfilmentPOST /orders/{id}/payment-linkPOST /orders/{id}/refundGET /orders/{id}/shipmentPOST /orders/{id}/shipmentPOST /orders/checkoutGET /orders/checkout/{id}GET /orders/checkout/payment-providersGET /orders/checkout/shipping-communesPOST /orders/checkout/shipping-quotesDELETE /shipping/chilexpressGET /shipping/chilexpressPUT /shipping/chilexpressPOST /shipping/estimates