Esta página se genera automáticamente desde el catálogo de APIs de Connecto (
Core\Api\Catalogo): lo que ves aquí es exactamente lo que ofrece la aplicación. No la edites a mano; para cambiarla modifica el catálogo y vuelve a generarla.
Todas las APIs usan la misma dirección base, https://tu-dominio/api/v1, y la misma autenticación (Authorization: Bearer cnx_TU_LLAVE). Las credenciales, los permisos y los límites se explican en APIs y webhooks. Todas las APIs vienen habilitadas; el acceso a cada una lo da la credencial: en Configuración → APIs y Webhooks se marcan (y se pueden editar cuando quieras) sus permisos de lectura y de escritura.
Resumen#
| API | Tipo | Permisos | Endpoints |
|---|---|---|---|
| Consulta de contactos | Lectura | contactos:consultar | 3 |
| Correos (enviar a un contacto) | Escritura y Lectura | correos:enviar, correos:leer | 2 |
| Listas de distribución (ver y suscribir) | Lectura y Escritura | listas:leer, listas:suscribir | 2 |
| Cupones de descuento (validar y canjear) | Lectura y Escritura | cupones:validar, cupones:canjear | 5 |
| Contactos (listar, crear y editar) | Lectura y Escritura | contactos:leer, contactos:escribir | 4 |
| Conversaciones y mensajes | Lectura | conversaciones:leer | 3 |
| Oportunidades | Lectura y Escritura | oportunidades:leer, oportunidades:escribir | 5 |
| Pedidos | Lectura y Escritura | pedidos:leer, pedidos:escribir | 4 |
Permisos especiales que cubren también las APIs que se construyan después: *:lectura (todas las de lectura) y *:escritura (todas las que modifican datos).
Consulta de contactos#
Busca contactos por uno o varios campos (por ejemplo la cédula, el correo o un campo que tú creaste) y devuelve todos sus datos y las redes o canales asociados.
| Permiso | Tipo | Qué permite |
|---|---|---|
contactos:consultar | Lectura | Consultar contactos y sus redes |
POST /api/v1/contactos/consultar#
Devuelve los contactos que cumplen TODOS los filtros enviados (o alguno, con «coincidencia»: «alguno»). Permiso: contactos:consultar.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
filtros | objeto {campo: valor}. El valor puede ser un texto, un número, una lista de valores (basta con que coincida uno) o {"operador": "...", "valor": "..."}. |
coincidencia | «todos» (por defecto: se cumplen todos los filtros) o «alguno». |
pagina | número de página (1 por defecto) |
limite | resultados por página, de 1 a 100 (25 por defecto) |
{
"filtros": {
"numero_documento": "1020304050",
"estado": "ACTIVO"
},
"coincidencia": "todos"
}GET /api/v1/contactos/consultar#
Lo mismo que el POST, con los filtros en la dirección: ?filtro[campo]=valor&filtro[otro_campo]=valor. Para varios valores de un campo: ?filtro[estado][]=ACTIVO&filtro[estado][]=INACTIVO. Permiso: contactos:consultar.
| Parámetro | Qué es |
|---|---|
filtro[campo] | un filtro por cada campo a consultar |
coincidencia | todos |
pagina | número de página |
limite | de 1 a 100 |
GET /api/v1/contactos/campos#
Lista los campos por los que se puede consultar (incluidos los que se crearon a mano), su tipo, los operadores que admiten y sus valores válidos. Permiso: contactos:consultar.
Qué devuelve: Cada contacto trae sus datos básicos, el tipo de contacto, el propietario, los campos opcionales activos (documento, nacionalidad, departamento, ciudad…), los campos personalizados y «redes»: una entrada por canal (WhatsApp, Messenger, Instagram, Telegram…) con las cuentas del contacto y los canales conectados por los que ha conversado.
Detalle completo de los campos, operadores y respuesta: API: Consulta de contactos.
Correos (enviar a un contacto)#
Un sistema externo envía un correo a un contacto a través del CRM: queda registrado en la actividad del contacto y lleva un píxel que cuenta cuántas veces lo abrió. Envía mensajes reales, por eso nace apagada y su permiso se da de forma explícita.
| Permiso | Tipo | Qué permite |
|---|---|---|
correos:enviar | Escritura | Enviar correos a contactos |
correos:leer | Lectura | Consultar cuántas veces se abrió un correo enviado por la API |
POST /api/v1/correos/enviar#
Envía un correo al contacto. El correo sale por la conexión SMTP de notificaciones del sistema, lleva el píxel de lectura y queda en la actividad del contacto (asunto, contenido y lecturas). El HTML se limpia (sin scripts, iframes ni manejadores de eventos). Devuelve un «id» para consultar después cuántas veces se abrió. Permiso: correos:enviar.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
destinatario | obligatorio: el correo del destinatario (o {"email": "…", "nombre": "…"}). Debe ser el correo de un contacto del CRM. |
asunto | obligatorio, hasta 300 caracteres |
cuerpo_html | obligatorio: el contenido del correo en HTML (hasta 500 KB) |
contacto_id | opcional: id del contacto, si ya lo conoces (el correo debe ser uno de los suyos) |
crear_contacto | opcional: true para crear el contacto si no existe uno con ese correo (si no, responde 404 contacto_no_encontrado) |
{
"destinatario": "[email protected]",
"asunto": "Tu pedido fue recibido",
"cuerpo_html": "<h2>¡Gracias por tu compra!</h2><p>Recibimos tu pedido <b>PED-000123</b>.</p>"
}GET /api/v1/correos/consultar#
Cuántas veces se abrió un correo enviado por la API: cantidad de lecturas, primera y última y el detalle de las más recientes. Solo ve correos enviados por la API. Permiso: correos:leer.
| Parámetro | Qué es |
|---|---|
id | el «id» que devolvió /correos/enviar |
Qué devuelve: enviar: {"datos": {"enviado": true, "id": 57, "contacto_id": 12, "contacto_creado": false, "destinatario": "…", "con_pixel": true}}. consultar: {"datos": {"id", "destinatario", "asunto", "enviado_at", "aperturas": 2, "primera_apertura_at", "ultima_apertura_at", "lecturas": [{"at"}]}}. Errores: 404 contacto_no_encontrado, 422 dato_invalido / correo_no_pertenece, 502 envio_fallido (no hay SMTP configurado o el servidor lo rechazó), 503 api_deshabilitada.
Listas de distribución (ver y suscribir)#
Un sistema externo ve el listado de listas de distribución de correo y suscribe a un contacto a una o varias. Al suscribir se deja su autorización para recibir correos, por eso nace apagada y suscribir es un permiso explícito.
| Permiso | Tipo | Qué permite |
|---|---|---|
listas:leer | Lectura | Ver las listas de distribución |
listas:suscribir | Escritura | Suscribir contactos a listas de distribución |
GET /api/v1/listas#
Lista las listas de distribución de correo activas: id, nombre, descripción y cuántos contactos tienen. Con «q» filtra por nombre; paginado. Permiso: listas:leer.
| Parámetro | Qué es |
|---|---|
q | texto que debe contener el nombre de la lista |
pagina | número de página (1 por defecto) |
limite | resultados por página, de 1 a 100 (25 por defecto) |
POST /api/v1/listas/suscribir#
Suscribe un contacto a una o varias listas de distribución y deja su autorización para recibir correos como «otorgada» (quien integra responde de haberla obtenido). El contacto se busca por su correo (o contacto_id). Una baja no se revierte sola: si el contacto se dio de baja de los correos, no se suscribe (responde baja_previa) salvo que se envíe «reactivar_baja»: true porque la persona volvió a pedirlo. Permiso: listas:suscribir.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
email | el correo del contacto (obligatorio si no envías contacto_id) |
listas | obligatorio: lista de ids de las listas (GET /listas), hasta 50 |
contacto_id | opcional: id del contacto; el correo debe ser uno de los suyos |
crear_contacto | opcional: true para crear el contacto si no existe uno con ese correo |
nombre | opcional: nombre para el contacto nuevo |
reactivar_baja | opcional: true solo si la persona se dio de baja y volvió a pedir suscribirse |
{
"email": "[email protected]",
"listas": [
1172,
917
],
"crear_contacto": true,
"nombre": "Ana Pérez"
}Qué devuelve: listar: {"datos": [{"id", "nombre", "descripcion", "contactos", "creada_at"}], "total", "pagina", "limite", "hay_mas"}. suscribir: {"datos": {"contacto_id", "contacto_creado", "se_dio_de_baja", "autorizacion_correo", "listas": [{"lista_id", "nombre", "estado": "suscrito" | "ya_estaba" | "baja_previa" | "no_existe"}]}}. Errores: 404 contacto_no_encontrado, 422 dato_invalido / correo_no_pertenece / contacto_sin_correo, 503 api_deshabilitada.
Cupones de descuento (validar y canjear)#
Para tiendas y carritos externos: comprueba un código de cupón contra el carrito y devuelve el descuento, lo canjea cuando se paga el pedido (sin pasarse del límite de usos) y lo libera si el pedido se cancela.
| Permiso | Tipo | Qué permite |
|---|---|---|
cupones:validar | Lectura | Validar cupones y calcular su descuento (no los gasta) |
cupones:canjear | Escritura | Canjear y liberar cupones |
GET /api/v1/cupones/consultar#
Solo CARGA el cupón por su código: devuelve cómo está configurado (tipo y valor, tope, vigencia, usos, límites, mínimos, combinable, productos incluidos y excluidos y su estado). No lo valida contra un carrito, no calcula descuentos y no gasta usos. Responde 404 si el código no existe. Permiso: cupones:validar.
| Parámetro | Qué es |
|---|---|
codigo | el código del cupón (no distingue mayúsculas) |
POST /api/v1/cupones/consultar#
Lo mismo que el GET, con el código en el cuerpo (JSON). Permiso: cupones:validar.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
codigo | el código del cupón |
{
"codigo": "BIENVENIDA10"
}POST /api/v1/cupones/validar#
Comprueba si el código se puede usar con este comprador y este carrito y calcula el descuento. NO gasta el cupón: llámalo cada vez que el cliente cambie el carrito. Un cupón que no se puede usar responde 200 con valido=false y un «motivo» (no_existe, inactivo, no_iniciado, vencido, agotado, limite_contacto, contacto_no_elegible, contacto_requerido, no_es_primera_compra, no_combinable, sin_productos_elegibles, monto_minimo, cantidad_minima…) y un «mensaje» listo para mostrar. Permiso: cupones:validar.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
codigo | el código del cupón (no distingue mayúsculas) |
contacto | quién compra: {"id": 123} o {"email": "..."} o {"telefono": "..."} o {"numero_documento": "..."} (necesario si el cupón tiene límite por contacto, es para contactos concretos o es de primera compra) |
items | el carrito: lista de {"producto_id", "precio_id" (la referencia), "referencia", "cantidad", "precio"?}. Basta producto_id, precio_id o referencia; el precio sale del catálogo salvo que lo envíes. Necesario para cupones de porcentaje. |
codigos_aplicados | otros cupones que el carrito ya tiene (solo se pueden sumar los marcados como combinables) |
{
"codigo": "BIENVENIDA10",
"contacto": {
"email": "[email protected]"
},
"items": [
{
"producto_id": 12,
"precio_id": 30,
"cantidad": 2
}
]
}POST /api/v1/cupones/canjear#
Gasta un uso del cupón cuando el pedido se confirma o se paga. Vuelve a validar todas las reglas y es seguro con compras simultáneas (nunca supera el límite de usos). Es idempotente: repetir la llamada con la misma «referencia_externa» devuelve el mismo canje sin gastar otro uso. Permiso: cupones:canjear.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
codigo | el código del cupón |
referencia_externa | obligatoria: el número de pedido de tu tienda |
contacto | igual que en validar |
items | igual que en validar |
codigos_aplicados | igual que en validar |
pedido_id | opcional: id del pedido en Connecto, si lo creaste por la API de pedidos |
{
"referencia_externa": "WEB-1001",
"codigo": "BIENVENIDA10",
"contacto": {
"email": "[email protected]"
},
"items": [
{
"producto_id": 12,
"precio_id": 30,
"cantidad": 2
}
]
}POST /api/v1/cupones/liberar#
Devuelve el uso del cupón (pedido cancelado, pago fallido). Idempotente. Permiso: cupones:canjear.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
codigo | el código del cupón |
referencia_externa | la misma referencia con la que se canjeó |
{
"codigo": "BIENVENIDA10",
"referencia_externa": "WEB-1001"
}Qué devuelve: validar: {"datos": {"valido": true, "codigo", "tipo": "pct|envio", "valor", "descuento" (USD), "envio_gratis", "subtotal_elegible", "lineas": [{"indice", "elegible", "descuento"}], "combinable", "vence_at", "usos_restantes"}} o {"valido": false, "motivo", "mensaje"}. canjear: {"datos": {"canjeado": true, "uso_id", "descuento", "envio_gratis", "repetido"}}. Si el módulo de cupones está apagado: error 503 «modulo_apagado».
Contactos (listar, crear y editar)#
Lista y consulta contactos con un conjunto básico de datos, crea contactos nuevos y edita nombre, teléfono, correo y tipo.
| Permiso | Tipo | Qué permite |
|---|---|---|
contactos:leer | Lectura | Listar y ver contactos |
contactos:escribir | Escritura | Crear y editar contactos |
GET /api/v1/contactos#
Lista contactos. Filtros: q (texto libre), email, telefono, actualizado_desde, limite, pagina. Permiso: contactos:leer.
| Parámetro | Qué es |
|---|---|
q | texto libre |
email | correo exacto |
telefono | teléfono |
actualizado_desde | fecha (2026-01-31) |
limite | 1 a 100 |
pagina | página |
GET /api/v1/contactos/{id}#
Un contacto por su id. Permiso: contactos:leer.
POST /api/v1/contactos#
Crea un contacto (exige nombre y, al menos, teléfono o correo). Opcionalmente guarda su documento y su ubicación (se validan contra los catálogos; lo que no se pueda aplicar se omite y se informa en «advertencias»). Si ya existe un contacto con ese teléfono, correo o número de documento responde 409 con su id. Permiso: contactos:escribir.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
nombre | obligatorio |
apellidos | opcional |
telefono | opcional |
email | opcional |
tipo_contacto_id | opcional |
whatsapp | opcional: true si el teléfono también tiene WhatsApp |
numero_documento | opcional |
tipo_documento | opcional: nombre («Cédula de ciudadanía») o id |
pais | opcional: código (CO) o nombre |
departamento | opcional: nombre o id |
ciudad | opcional: nombre o id |
direccion | opcional |
{
"nombre": "Ana Pérez",
"telefono": "+57 300 123 4567",
"email": "[email protected]",
"numero_documento": "1020304050",
"tipo_documento": "Cédula de ciudadanía",
"pais": "Colombia",
"departamento": "Antioquia",
"ciudad": "Medellín"
}PATCH /api/v1/contactos/{id}#
Edita nombre, apellidos, teléfono, correo, tipo de contacto y la ubicación (país, departamento, ciudad y dirección). La ubicación se envía por nombre o por id/código y se valida contra los catálogos; lo que no se pueda aplicar (un nombre que no está en el catálogo o un campo desactivado en Configuración › Contactos) se omite y se informa en «advertencias» sin impedir el resto. Permiso: contactos:escribir.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
nombre | opcional |
apellidos | opcional |
telefono | opcional |
email | opcional |
tipo_contacto_id | opcional |
pais | opcional: código (CO) o nombre |
departamento | opcional: nombre o id |
ciudad | opcional: nombre o id |
direccion | opcional |
numero_documento | opcional: solo se completa si el contacto no tiene uno |
tipo_documento | opcional: solo se completa si el contacto no tiene uno |
{
"telefono": "+57 311 000 0000",
"pais": "Colombia",
"departamento": "Antioquia",
"ciudad": "Medellín"
}Conversaciones y mensajes#
Lee las conversaciones (con su canal, estado y asesor) y los mensajes de cada una.
| Permiso | Tipo | Qué permite |
|---|---|---|
conversaciones:leer | Lectura | Leer conversaciones y mensajes |
GET /api/v1/conversaciones#
Lista conversaciones. Filtros: estado (open, pending, resolved), contacto_id, actualizada_desde, limite, pagina. Permiso: conversaciones:leer.
| Parámetro | Qué es |
|---|---|
estado | open |
contacto_id | id del contacto |
actualizada_desde | fecha |
limite | 1 a 100 |
pagina | página |
GET /api/v1/conversaciones/{id}#
Una conversación. Permiso: conversaciones:leer.
GET /api/v1/conversaciones/{id}/mensajes#
Mensajes de una conversación (los más recientes primero). Permiso: conversaciones:leer.
| Parámetro | Qué es |
|---|---|
limite | 1 a 100 |
antes_de_id | para seguir con los más antiguos |
Oportunidades#
Consulta las oportunidades (procesos de venta), agrega un contacto a un embudo definido y la mueve de etapa.
| Permiso | Tipo | Qué permite |
|---|---|---|
oportunidades:leer | Lectura | Leer oportunidades y embudos |
oportunidades:escribir | Escritura | Crear oportunidades y cambiarlas de etapa |
GET /api/v1/oportunidades#
Lista oportunidades. Filtros: estado (abierto, ganado, perdido), contacto_id, limite, pagina. Permiso: oportunidades:leer.
| Parámetro | Qué es |
|---|---|
estado | abierto |
contacto_id | id del contacto |
limite | 1 a 100 |
pagina | página |
GET /api/v1/oportunidades/{id}#
Una oportunidad. Permiso: oportunidades:leer.
GET /api/v1/embudos#
Lista los embudos activos con sus etapas (id, nombre, tipo abierta/ganada/perdida): sirven para saber qué embudo_id y etapa_id usar. Permiso: oportunidades:leer.
POST /api/v1/oportunidades#
Agrega un contacto a un proceso de venta: crea su oportunidad en el embudo (y la etapa) que indiques. Un contacto solo puede tener UNA oportunidad abierta por embudo (si ya la tiene responde 409 con su id), salvo que envíes «varias»: true (p. ej. una oportunidad por cada pedido de la web). Se ejecutan las acciones automáticas de la etapa. Permiso: oportunidades:escribir.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
contacto_id | id del contacto (o bien numero_documento, o bien email) |
embudo_id | id del embudo (o «embudo»: su nombre). Si no lo envías se usa el embudo por defecto |
etapa_id | opcional: id de una etapa abierta (o «etapa»: su nombre). Por defecto, la primera etapa del embudo |
titulo | opcional |
valor | opcional |
moneda | opcional |
producto_id | opcional |
fecha_cierre_esperada | opcional, AAAA-MM-DD |
propietario_id | opcional: id del usuario responsable |
varias | opcional (true/false): permite que el contacto tenga varias oportunidades abiertas en el embudo (una por cada pedido); por defecto solo una |
pedido_id | opcional: id de un pedido ya creado del mismo contacto (o «pedido_numero»: su número); queda enlazado a la oportunidad |
nota | opcional: nota inicial |
{
"numero_documento": "1020304050",
"embudo": "Ventas",
"etapa": "Contactado",
"titulo": "Matrícula Procuraduría",
"valor": 325000
}PATCH /api/v1/oportunidades/{id}#
Cambia la oportunidad de etapa (por etapa_id o por nombre, dentro de su embudo) y/o edita sus datos. Respeta las reglas del embudo y de la etapa: transiciones permitidas, datos requeridos y motivo al perder (422 si no se cumplen); si la etapa pide aprobación responde 202. DATOS DEL PEDIDO: si la etapa destino tiene acciones «Cambiar un dato» sobre el pedido (Configuración › Oportunidades › acciones de la etapa), el valor de cada dato se envía en el MISMO cuerpo, con el nombre del dato como nombre del campo (por ejemplo comprobante_url); al entrar a la etapa, la acción lo guarda en el pedido de la oportunidad. Si la etapa no tiene esa acción, el dato se ignora. También se aceptan en POST /oportunidades cuando nace directamente en una etapa con esa acción. Respuesta 422 si el valor no es válido (la URL debe ser http o https). Permiso: oportunidades:escribir.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
etapa_id | id de la etapa destino (o «etapa»: su nombre) |
motivo_perdida_id | obligatorio si el embudo lo exige y la etapa es de pérdida |
nota | opcional |
titulo | opcional |
valor | opcional |
moneda | opcional |
producto_id | opcional |
fecha_cierre_esperada | opcional |
propietario_id | opcional |
comprobante_url | dato del pedido: URL de la imagen del comprobante de pago. Se guarda en el pedido de la oportunidad SOLO si la etapa destino tiene la acción «Cambiar un dato → Comprobante de pago»; el nombre del campo es el nombre del dato |
envio_guia | dato del pedido (ver comprobante_url): guía de envío |
envio_metodo | dato del pedido: método de envío |
envio_direccion | dato del pedido: dirección de envío |
notas | dato del pedido: notas |
{
"etapa": "Pago confirmado",
"comprobante_url": "https://w3.grupogeard.com/comprobantes/GG-261021-7C0451.jpg"
}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.
| Permiso | Tipo | Qué permite |
|---|---|---|
pedidos:leer | Lectura | Leer pedidos |
pedidos:escribir | Escritura | Crear y actualizar pedidos (incluye pagos, reembolsos y entregas) |
GET /api/v1/pedidos#
Lista pedidos (más recientes primero) con sus totales y estados, sin las líneas. Filtros opcionales. Permiso: pedidos:leer.
| Parámetro | Qué es |
|---|---|
estado | borrador |
estado_pago | sin_pagar |
estado_entrega | sin_entregar |
fuente | manual |
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 |
GET /api/v1/pedidos/{id}#
Un pedido completo: líneas (producto, precio, descuento, IVA, total, entregado), descuento general, envío, totales, pagos y reembolsos. Permiso: pedidos:leer.
POST /api/v1/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.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
contacto_id | id del contacto (o bien numero_documento, o bien email) |
items | lista de líneas: {producto_id |
descuento_general | opcional: {tipo: pct |
envio | opcional: un monto, o {monto, impuesto_pct?, direccion?, metodo?, guia?} |
moneda | opcional, 3 letras (por defecto la configurada) |
estado | opcional: borrador |
pagos | opcional (solo con estado pendiente): [{monto, metodo?: transferencia |
fuente | opcional: api (por defecto) |
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"
}PATCH /api/v1/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.
| Dato del cuerpo (JSON) | Qué es |
|---|---|
items | reemplaza todas las líneas (misma forma que al crear) |
descuento_general | {tipo: pct |
envio | monto, o {monto, impuesto_pct, direccion, metodo, guia} |
estado | borrador |
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 |
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"
}
}