Skip to content

Cotizaciones ​

Cuando un comprador pide un presupuesto en tu tienda en línea, regístralo en Zenci con POST /quotations. La cotización aparece en Ventas › Cotizaciones del comercio, que puede ajustarla en el POS y convertirla en venta cuando el cliente acepta. Crear una cotización no reserva unidades ni emite factura.

EndpointPermiso
POST /quotationsquotations:write
GET /quotations/{id}quotations:write

En el panel, el permiso se llama Crear cotizaciones.

Crear una cotización ​

http
POST /quotations

Encabezados ​

EncabezadoObligatorioDescripción
Authorization o X-API-KeySíTu clave de API
Content-TypeRecomendadoapplication/json
X-Idempotency-KeySíUn identificador único de esta cotización en tu tienda. Consulta

Cuerpo ​

CampoTipoObligatorioDescripción
itemslistaSíDe 1 a 200 líneas
items[].skutextoSíSKU de la variante, escrito exactamente igual
items[].quantitytextoSíCantidad mayor que cero, hasta 6 decimales
branchIdtextoNoSucursal de la cotización. Si no lo envías, se usa la de la clave
customerIdtexto o nullNoCliente al que se le cotiza. Búscalo o créalo con
companyIdtexto o nullNoUna de las compañías del cliente. Necesita customerId
expiresAtfecha ISO 8601NoHasta cuándo vale. Si no la envías, se usa la vigencia que configuró el comercio (30 días si no la cambió)
notestexto, hasta 2000 caracteresNoNotas para el cliente

Los precios no se envían: salen del catálogo o de la lista de precios de la clave, igual que en . La cotización no aplica promociones ni descuentos; si hace falta, el comercio los ajusta en el POS.

Ejemplo ​

bash
curl -X POST https://api.zenci.app/public/v1/quotations \
  -H "Authorization: Bearer $ZENCI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: presupuesto-2291" \
  -d '{
    "customerId": "u3i7o1p5a9s2d6f0g4h8j2k6",
    "notes": "Entrega en la oficina del cliente",
    "items": [
      { "sku": "MB-029-CRU-38", "quantity": "10" }
    ]
  }'

Respuesta 201:

json
{
  "id": "q6w0e4r8t2y5u9i3o7p1a5s9",
  "displayId": "000214",
  "status": "draft",
  "branchId": "b7n2q8w4e1r9t3y6u0i5o2p7",
  "customerId": "u3i7o1p5a9s2d6f0g4h8j2k6",
  "companyId": null,
  "items": [
    {
      "sku": "MB-029-CRU-38",
      "name": "Sandalia Crucero - Cruda / 38",
      "quantity": "10",
      "price": "36.00",
      "discount": "0.00",
      "taxRate": "7.00"
    }
  ],
  "subtotal": "360.00",
  "taxes": "25.20",
  "total": "385.20",
  "notes": "Entrega en la oficina del cliente",
  "expiresAt": "2026-12-11T15:20:00.000Z",
  "orderId": null,
  "createdAt": "2026-11-11T15:20:00.000Z"
}
CampoDescripción
idIdentificador de la cotización. Guárdalo para consultarla después
displayIdNúmero de cotización que ve el comercio
statusdraft (vigente), accepted, expired (venció) o converted (ya se convirtió en venta)
branchId, customerId, companyIdLa sucursal, el cliente y la compañía de la cotización
items[].pricePrecio por unidad sin impuesto
items[].discountDescuento de la línea. Al crearla por la API es "0.00"
items[].taxRatePorcentaje de impuesto de la línea
subtotal, taxes, totalTotales de la cotización
expiresAtHasta cuándo vale
orderIdLa venta en la que se convirtió, o null

Consultar una cotización ​

http
GET /quotations/{id}

Devuelve la cotización con la misma forma. Úsala para saber si el cliente aceptó: cuando el comercio la convierte en venta, status pasa a converted y orderId trae el id de la venta.

Cada clave ve solo las cotizaciones que creó ella. Una cotización de otra clave o del POS responde 404 (Quotation not found).

Validaciones ​

  • La sucursal tiene que ser del comercio. Una sucursal que no existe responde 404 (Branch "…" not found). Si tu clave está , una sucursal fuera de ellas responde 403 con code: "out_of_scope".
  • El cliente tiene que ser del comercio. Un customerId que no existe responde 404 (Customer "…" not found).
  • Los SKU tienen que estar en el catálogo de la clave. Uno que no existe o que está fuera del alcance de la clave responde 400 (Unknown SKU "…").
  • Sin branchId y sin sucursal en la clave, la respuesta es 400 (No branch was provided and this API key has no default branch).

Errores frecuentes ​

HTTPMensajeCausa
400The X-Idempotency-Key header is requiredFalta el encabezado
400Unknown SKU "…"El SKU no existe o está fuera del alcance de la clave
400"companyId" requires "customerId"Enviaste una compañía sin cliente
403Insufficient permissionsLa clave no tiene quotations:write
403Branch "…" is outside this API key's scopeLa sucursal no es una de las de la clave (code: "out_of_scope")
404Branch "…" not foundLa sucursal no es del comercio
404Customer "…" not foundEl cliente no es del comercio
409This X-Idempotency-Key was already used for a different request…Reusaste la clave de idempotencia con otro cuerpo (code: "idempotency_key_reused")

Siguientes pasos ​

  • — Cómo las ve y las convierte el comercio.
  • — Registra la venta directamente desde tu tienda.
  • — Idempotencia, formato de los datos y errores.

Documentación oficial de Zelta