Lee, crea y actualiza pedidos: el contacto asociado a sus productos, con precio y descuento de cada uno (o general), IVA, envío, estado del pedido, del pago y de la entrega.
Permisos#
| Permiso | Para qué sirve | Tipo |
|---|---|---|
pedidos:leer | Leer pedidos | lectura |
pedidos:escribir | Crear y actualizar pedidos (incluye pagos, reembolsos y entregas) | escritura |
Endpoints#
GET /pedidos#
Lista pedidos (más recientes primero) con sus totales y estados, sin las líneas. Filtros opcionales.
Permiso: pedidos:leer · lectura
Parámetros de la consulta#
| Parámetro | Descripción |
|---|---|
estado | borrador | pendiente | en_proceso | completado | cancelado | reembolsado |
estado_pago | sin_pagar | parcial | pagado | reembolsado_parcial | reembolsado |
estado_entrega | sin_entregar | parcial | entregado | devuelto |
fuente | manual | cotizacion | oportunidad | api | web | woocommerce | otro |
contacto_id | id del contacto |
oportunidad_id | id de la oportunidad |
cotizacion_id | id de la cotización |
referencia_externa | id del pedido en tu sistema |
q | texto: número, cliente o referencia |
desde | AAAA-MM-DD |
hasta | AAAA-MM-DD |
limite | 1 a 100 |
pagina | página |
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos?estado=valor" \
-H "Authorization: Bearer cnx_TU_LLAVE"const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos?estado=valor", {
method: "GET",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos?estado=valor");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);GET /pedidos/{id}#
Un pedido completo: líneas (producto, precio, descuento, IVA, total, entregado), descuento general, envío, totales, pagos y reembolsos.
Permiso: pedidos:leer · lectura
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}" \
-H "Authorization: Bearer cnx_TU_LLAVE"const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}", {
method: "GET",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);POST /pedidos#
Crea un pedido para un contacto. Cada línea puede ser un producto del catálogo (producto_id; el precio sale del catálogo si no envías «precio», y con varios precios puedes elegir «precio_id») o una línea libre (solo «nombre» y «precio»). Los descuentos pueden ser por línea y/o generales, en porcentaje (pct) o valor fijo; se aplican ANTES del IVA. La fuente queda registrada (por defecto «api»). Si envías «referencia_externa» y ya existe un pedido con esa referencia y fuente, responde 409 con su id (así puedes reintentar sin duplicar). Con «estado»: «pendiente» puedes incluir «pagos». VARIABLE ADICIONAL complemento_correo: texto HTML (medio de pago y datos de la cuenta, por ejemplo) que el correo del pedido incrusta tal cual con la variable {{pedido:complemento_correo}}; se limpia (sin scripts ni formularios, solo estilos en línea), máximo 20.000 caracteres.
Permiso: pedidos:escribir · escritura
Cuerpo (JSON)#
| Campo | Descripción |
|---|---|
contacto_id | id del contacto (o bien numero_documento, o bien email) |
items | lista de líneas: {producto_id | nombre, cantidad (1 por defecto), precio?, precio_id?, descuento: {tipo: pct|valor, valor}?, impuesto_pct? (por defecto el IVA configurado), adicionales?: [{adicional_id, cantidad?}]} |
descuento_general | opcional: {tipo: pct|valor, valor, motivo?}; se reparte entre las líneas |
envio | opcional: un monto, o {monto, impuesto_pct?, direccion?, metodo?, guia?} |
moneda | opcional, 3 letras (por defecto la configurada) |
estado | opcional: borrador | pendiente (por defecto el estado inicial configurado) |
pagos | opcional (solo con estado pendiente): [{monto, metodo?: transferencia|breb|efectivo|pasarela, referencia?, nota?}] |
fuente | opcional: api (por defecto) | web | woocommerce | otro |
fuente_detalle | opcional: por ejemplo la web de origen |
referencia_externa | opcional: el id de este pedido en tu sistema (evita duplicados) |
oportunidad_id | opcional |
cotizacion_id | opcional |
responsable_id | opcional: id del usuario |
notas | opcional |
terminos | opcional |
comprobante_url | opcional: URL (http o https) de la imagen del comprobante de pago |
complemento_correo | opcional: bloque HTML con el medio de pago y los datos de la cuenta, que el correo del pedido incrusta con la variable {{pedido:complemento_correo}} (máx. 20.000 caracteres; se limpia: sin scripts ni formularios, solo estilos en línea, imágenes y enlaces http/https) |
{
"numero_documento": "1020304050",
"items": [
{
"producto_id": 12,
"cantidad": 1,
"descuento": {
"tipo": "pct",
"valor": 10
}
},
{
"nombre": "Material impreso",
"cantidad": 2,
"precio": 15000,
"impuesto_pct": 0
}
],
"descuento_general": {
"tipo": "valor",
"valor": 5000
},
"envio": {
"monto": 12000,
"direccion": "Calle 1 # 2-3, Bogotá"
},
"estado": "pendiente",
"referencia_externa": "WEB-10234"
}curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos" \
-H "Authorization: Bearer cnx_TU_LLAVE" \
-H "Content-Type: application/json" \
-d '{"numero_documento":"1020304050","items":[{"producto_id":12,"cantidad":1,"descuento":{"tipo":"pct","valor":10}},{"nombre":"Material impreso","cantidad":2,"precio":15000,"impuesto_pct":0}],"descuento_general":{"tipo":"valor","valor":5000},"envio":{"monto":12000,"direccion":"Calle 1 # 2-3, Bogotá"},"estado":"pendiente","referencia_externa":"WEB-10234"}'const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos", {
method: "POST",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"numero_documento": "1020304050",
"items": [
{
"producto_id": 12,
"cantidad": 1,
"descuento": {
"tipo": "pct",
"valor": 10
}
},
{
"nombre": "Material impreso",
"cantidad": 2,
"precio": 15000,
"impuesto_pct": 0
}
],
"descuento_general": {
"tipo": "valor",
"valor": 5000
},
"envio": {
"monto": 12000,
"direccion": "Calle 1 # 2-3, Bogotá"
},
"estado": "pendiente",
"referencia_externa": "WEB-10234"
})
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(array (
'numero_documento' => '1020304050',
'items' =>
array (
0 =>
array (
'producto_id' => 12,
'cantidad' => 1,
'descuento' =>
array (
'tipo' => 'pct',
'valor' => 10,
),
),
1 =>
array (
'nombre' => 'Material impreso',
'cantidad' => 2,
'precio' => 15000,
'impuesto_pct' => 0,
),
),
'descuento_general' =>
array (
'tipo' => 'valor',
'valor' => 5000,
),
'envio' =>
array (
'monto' => 12000,
'direccion' => 'Calle 1 # 2-3, Bogotá',
),
'estado' => 'pendiente',
'referencia_externa' => 'WEB-10234',
)),
]);
$datos = json_decode(curl_exec($ch), true);PATCH /pedidos/{id}#
Actualiza un pedido. Los productos, descuentos y el envío solo se cambian mientras el pedido es borrador (o pendiente sin pagos); las notas, los datos de envío y el responsable, siempre que no esté cancelado o reembolsado. Además: cambiar de «estado» (solo transiciones válidas), registrar un «pago» o «pagos» (no puede superar el saldo), un «reembolso» y la «entrega». Todo se aplica en una sola operación: si algo falla (422), no se guarda nada.
Permiso: pedidos:escribir · escritura
Cuerpo (JSON)#
| Campo | Descripción |
|---|---|
items | reemplaza todas las líneas (misma forma que al crear) |
descuento_general | {tipo: pct|valor, valor, motivo?}; con valor 0 se quita |
envio | monto, o {monto, impuesto_pct, direccion, metodo, guia} |
estado | borrador | pendiente | en_proceso | completado | cancelado |
motivo | opcional: motivo de la cancelación |
pago | {monto, metodo?, referencia?, nota?} |
pagos | lista de pagos como el anterior |
reembolso | {monto, metodo?, referencia?, nota?} |
entrega | {estado: sin_entregar | entregado | devuelto} o {items: {id_de_linea: cantidad_entregada}} |
responsable_id | id del usuario |
notas | texto |
terminos | texto |
comprobante_url | URL (http o https) de la imagen del comprobante de pago; con texto vacío se quita |
complemento_correo | opcional: bloque HTML con el medio de pago y los datos de la cuenta, que el correo del pedido incrusta con la variable {{pedido:complemento_correo}} (máx. 20.000 caracteres; se limpia: sin scripts ni formularios, solo estilos en línea, imágenes y enlaces http/https) |
{
"pago": {
"monto": 150000,
"metodo": "transferencia",
"referencia": "TRX-9981"
},
"entrega": {
"estado": "entregado"
}
}curl -X PATCH "https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}" \
-H "Authorization: Bearer cnx_TU_LLAVE" \
-H "Content-Type: application/json" \
-d '{"pago":{"monto":150000,"metodo":"transferencia","referencia":"TRX-9981"},"entrega":{"estado":"entregado"}}'const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}", {
method: "PATCH",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"pago": {
"monto": 150000,
"metodo": "transferencia",
"referencia": "TRX-9981"
},
"entrega": {
"estado": "entregado"
}
})
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(array (
'pago' =>
array (
'monto' => 150000,
'metodo' => 'transferencia',
'referencia' => 'TRX-9981',
),
'entrega' =>
array (
'estado' => 'entregado',
),
)),
]);
$datos = json_decode(curl_exec($ch), true);