Ir al contenido
Documentación de Connecto
connecto.lat
API para desarrolladoresReferencia

Pedidos

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#

PermisoPara qué sirveTipo
pedidos:leerLeer pedidoslectura
pedidos:escribirCrear 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ámetroDescripción
estadoborrador | pendiente | en_proceso | completado | cancelado | reembolsado
estado_pagosin_pagar | parcial | pagado | reembolsado_parcial | reembolsado
estado_entregasin_entregar | parcial | entregado | devuelto
fuentemanual | cotizacion | oportunidad | api | web | woocommerce | otro
contacto_idid del contacto
oportunidad_idid de la oportunidad
cotizacion_idid de la cotización
referencia_externaid del pedido en tu sistema
qtexto: número, cliente o referencia
desdeAAAA-MM-DD
hastaAAAA-MM-DD
limite1 a 100
paginapágina
Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos?estado=valor" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
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();
Ejemplo en php
$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

Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/pedidos/{id}" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
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();
Ejemplo en php
$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)#

CampoDescripción
contacto_idid del contacto (o bien numero_documento, o bien email)
itemslista 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_generalopcional: {tipo: pct|valor, valor, motivo?}; se reparte entre las líneas
envioopcional: un monto, o {monto, impuesto_pct?, direccion?, metodo?, guia?}
monedaopcional, 3 letras (por defecto la configurada)
estadoopcional: borrador | pendiente (por defecto el estado inicial configurado)
pagosopcional (solo con estado pendiente): [{monto, metodo?: transferencia|breb|efectivo|pasarela, referencia?, nota?}]
fuenteopcional: api (por defecto) | web | woocommerce | otro
fuente_detalleopcional: por ejemplo la web de origen
referencia_externaopcional: el id de este pedido en tu sistema (evita duplicados)
oportunidad_idopcional
cotizacion_idopcional
responsable_idopcional: id del usuario
notasopcional
terminosopcional
comprobante_urlopcional: URL (http o https) de la imagen del comprobante de pago
complemento_correoopcional: 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)
Ejemplo de cuerpo
{
  "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"
}
Ejemplo en curl
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"}'
Ejemplo en javascript
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();
Ejemplo en php
$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)#

CampoDescripción
itemsreemplaza todas las líneas (misma forma que al crear)
descuento_general{tipo: pct|valor, valor, motivo?}; con valor 0 se quita
enviomonto, o {monto, impuesto_pct, direccion, metodo, guia}
estadoborrador | pendiente | en_proceso | completado | cancelado
motivoopcional: motivo de la cancelación
pago{monto, metodo?, referencia?, nota?}
pagoslista de pagos como el anterior
reembolso{monto, metodo?, referencia?, nota?}
entrega{estado: sin_entregar | entregado | devuelto} o {items: {id_de_linea: cantidad_entregada}}
responsable_idid del usuario
notastexto
terminostexto
comprobante_urlURL (http o https) de la imagen del comprobante de pago; con texto vacío se quita
complemento_correoopcional: 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)
Ejemplo de cuerpo
{
  "pago": {
    "monto": 150000,
    "metodo": "transferencia",
    "referencia": "TRX-9981"
  },
  "entrega": {
    "estado": "entregado"
  }
}
Ejemplo en curl
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"}}'
Ejemplo en javascript
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();
Ejemplo en php
$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);
¿Te fue útil esta página?
Última actualización: 14/11/2026