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.
| Endpoint | Permiso |
|---|---|
POST /quotations | quotations:write |
GET /quotations/{id} | quotations:write |
En el panel, el permiso se llama Crear cotizaciones.
Crear una cotización
POST /quotationsEncabezados
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Authorization o X-API-Key | Sí | Tu clave de API |
Content-Type | Recomendado | application/json |
X-Idempotency-Key | Sí | Un identificador único de esta cotización en tu tienda. Consulta |
Cuerpo
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
items | lista | Sí | De 1 a 200 líneas |
items[].sku | texto | Sí | SKU de la variante, escrito exactamente igual |
items[].quantity | texto | Sí | Cantidad mayor que cero, hasta 6 decimales |
branchId | texto | No | Sucursal de la cotización. Si no lo envías, se usa la de la clave |
customerId | texto o null | No | Cliente al que se le cotiza. Búscalo o créalo con |
companyId | texto o null | No | Una de las compañías del cliente. Necesita customerId |
expiresAt | fecha ISO 8601 | No | Hasta cuándo vale. Si no la envías, se usa la vigencia que configuró el comercio (30 días si no la cambió) |
notes | texto, hasta 2000 caracteres | No | Notas 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
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:
{
"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"
}| Campo | Descripción |
|---|---|
id | Identificador de la cotización. Guárdalo para consultarla después |
displayId | Número de cotización que ve el comercio |
status | draft (vigente), accepted, expired (venció) o converted (ya se convirtió en venta) |
branchId, customerId, companyId | La sucursal, el cliente y la compañía de la cotización |
items[].price | Precio por unidad sin impuesto |
items[].discount | Descuento de la línea. Al crearla por la API es "0.00" |
items[].taxRate | Porcentaje de impuesto de la línea |
subtotal, taxes, total | Totales de la cotización |
expiresAt | Hasta cuándo vale |
orderId | La venta en la que se convirtió, o null |
Consultar una cotización
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 responde403concode: "out_of_scope". - El cliente tiene que ser del comercio. Un
customerIdque no existe responde404(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
branchIdy sin sucursal en la clave, la respuesta es400(No branch was provided and this API key has no default branch).
Errores frecuentes
| HTTP | Mensaje | Causa |
|---|---|---|
400 | The X-Idempotency-Key header is required | Falta el encabezado |
400 | Unknown SKU "…" | El SKU no existe o está fuera del alcance de la clave |
400 | "companyId" requires "customerId" | Enviaste una compañía sin cliente |
403 | Insufficient permissions | La clave no tiene quotations:write |
403 | Branch "…" is outside this API key's scope | La sucursal no es una de las de la clave (code: "out_of_scope") |
404 | Branch "…" not found | La sucursal no es del comercio |
404 | Customer "…" not found | El cliente no es del comercio |
409 | This 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.