API de integraciones de Plusdiario

Tu primera integración

1. En el CRM abrí Control de Empresa → API de Ingesta de Leads Externos y generá un token. Copialo: se muestra completo una sola vez.
2. En Permisos de la API comercial v2, seleccioná el token, su usuario operativo y los permisos necesarios. Para este ejemplo: contactos:read y contactos:write.
3. Enviá solicitudes desde tu servidor con Authorization: Bearer TU_TOKEN_API. Nunca pongas el token en JavaScript del navegador, URLs ni repositorios.
4. Elegí una Idempotency-Key estable para cada operación. Guardala y reutilizala si se corta la conexión.

curl --request POST 'https://www.plusdiario.com.ar/api/v2/contactos.php' \
  --header 'Authorization: Bearer TU_TOKEN_API' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: contacto-web-123' \
  --data '{"external_id":"cliente-123","nombre":"Ana Ejemplo","telefono":"1112345678"}'

La respuesta contiene data.id y data.version. Los IDs son de ejemplo: consultá los reales y enviá identificadores como texto.

{
  "status": "ok",
  "data": {"id": "123", "nombre": "Ana Ejemplo", "scoring": 0, "version": "..."},
  "error": null,
  "meta": {"request_id": "...", "version": "2", "replayed": false}
}

El ejemplo abrevia los campos de data. La documentación no ejecuta operaciones contra tu empresa.

De dónde vienen los clics de WhatsApp

Desde Control de Empresa → Origen de los clics de WhatsApp, agregá tu sitio y sus dominios HTTPS exactos. Incluí por separado la dirección con y sin www si usás ambas. Copiá el código que aparece allí e instalalo antes de </body> en cada página pública.

<script defer src="https://www.plusdiario.com.ar/js/pd-web-attribution.js" data-site="00000000000000000000000000000000"></script>

Usá el código real del panel. Su atributo data-site es un identificador público de medición; nunca debe contener el token de la API comercial. La medición no crea leads, no altera los enlaces ni agrega referencias al mensaje.

• Origen: etiquetas utm_source, utm_medium y utm_campaign, señales de clic de Google o Meta, y dominio de referencia disponible. Ejemplo: https://tuweb.com/producto?utm_source=instagram&utm_medium=social&utm_campaign=lanzamiento.
• Sesión: se conserva en la pestaña durante 30 minutos de inactividad. El primer origen se mantiene al navegar; un nuevo origen explícito también queda registrado. Pestañas y navegadores diferentes pueden representar sesiones distintas.
• Clic: se detectan enlaces a wa.me, api.whatsapp.com, web.whatsapp.com, www.whatsapp.com y whatsapp:, incluso si aparecen después por AJAX. Podés identificar un botón con data-placement="producto" o excluir un área con data-pd-tracking="off".
• Lectura del informe: un clic no demuestra que se envió un mensaje. fbclid solo no distingue Facebook de Instagram ni demuestra tráfico pago. Si falta información se informa Directo / no identificado.
• Almacenamiento: se conservan 90 días de eventos; se omiten query strings completas, fragmentos, contenido de mensajes, teléfonos de destino e IP sin procesar. La protección contra abuso usa un hash temporal de IP con sal privada. El identificador del navegador no se vincula automáticamente con personas del CRM.

Para esperar el consentimiento de tu web, agregá data-consent="required" al script y llamá window.PlusdiarioTracking?.setConsent(true) después de obtenerlo; setConsent(false) detiene la medición y borra el estado local. Se respetan Do Not Track y Global Privacy Control. En una web con navegación sin recarga, llamá window.PlusdiarioTracking?.trackPage() tras cambiar de página.

La medición pública valida los dominios habilitados y limita el tráfico, pero las etiquetas son datos declarados por el navegador. No sirven como prueba de identidad, pago o venta. Los bloqueadores, restricciones del navegador y la falta de consentimiento pueden reducir los conteos.

Qué representa cada operación

Reglas comunes

• Base: https://www.plusdiario.com.ar/api/v2/. Solicitudes JSON de hasta 2 MiB.
• Permisos: recurso:read para GET y recurso:write para POST/PATCH. También se verifican el usuario operativo, sus módulos y su visibilidad del CRM. La empresa sale del token.
• Moneda y precisión: nuevas operaciones en ARS. Dinero y cantidades usan punto decimal, sin miles, hasta 2 decimales; enviarlos como texto evita pérdida de precisión. El límite de importes y cantidades individuales es 9.999.999,99. stock_minimo conserva los 3 decimales de su ficha.
• Idempotencia: toda escritura requiere Idempotency-Key de 8 a 190 caracteres: letras, números, _ . : -. Misma clave y mismo contenido devuelven el resultado anterior; otro contenido produce 409. Las claves y referencias se conservan para proteger reintentos históricos.
• Identidad externa: external_id se vincula por empresa, token y recurso. Si repetís una referencia ya creada se devuelve el registro original; para modificarlo usá PATCH. Si los datos de contacto coinciden con otros registros, se devuelve un conflicto para evitar fusiones incorrectas.
• Edición: consultá el registro por GET y enviá su version en PATCH o transiciones. No se borran operaciones confirmadas; las correcciones se registran con trazabilidad.
• Páginas: las colecciones paginadas devuelven items y next_after. Enviá ese cursor en after; limit vale 50 de forma predeterminada y admite hasta 100. Usá webhooks para cambios sobre registros ya leídos.
• Límite por minuto: se configura por token, entre 10 y 1.000 solicitudes, inicialmente 120. Respetá X-RateLimit-Remaining y Retry-After.

Referencia por endpoint

GET consulta; POST crea o ejecuta acciones; PATCH actualiza campos editables. El campo id se envía en la URL para consultar un registro, editarlo o cambiar su estado.

{
    "nombre": "Ana Ejemplo",
    "telefono": "1112345678",
    "external_id": "cliente-123"
}

{
    "nombre": "Ana Ejemplo",
    "telefono": "1112345678",
    "mensaje": "Quiero información",
    "source": "web_form",
    "external_id": "lead-123"
}

{
    "codigo": "SKU-123",
    "nombre": "Producto de ejemplo",
    "precio_venta": "100.00",
    "controlar_stock": true
}

{
    "inventario_id": "10",
    "action": "entrada",
    "cantidad": "10.00",
    "motivo": "Recepción de mercadería",
    "external_id": "recepcion-123"
}

{
    "cliente_id": "123",
    "items": [
        {
            "inventario_id": "10",
            "cantidad": "2.00"
        }
    ],
    "observaciones": "Presupuesto de ejemplo"
}

{
    "cliente_id": "123",
    "items": [
        {
            "inventario_id": "10",
            "cantidad": "2.00"
        }
    ],
    "direccion_entrega": "Dirección de ejemplo",
    "ciudad_entrega": "Ciudad"
}

{
    "modo": "operativa",
    "cliente_id": "123",
    "items": [
        {
            "inventario_id": "10",
            "cantidad": "2.00"
        }
    ],
    "afectar_stock": true,
    "pagos": [],
    "sucursal_id": "1",
    "external_id": "venta-123"
}

{
    "venta_id": "456",
    "monto": "100.00",
    "metodo_pago": "transferencia",
    "sucursal_id": "1",
    "external_id": "pago-123"
}

{
    "venta_id": "456",
    "items": [
        {
            "sale_item_id": "789",
            "cantidad": "1.00"
        }
    ],
    "motivo": "Devolución acordada",
    "reponer_stock": true,
    "reintegro": "0.00",
    "external_id": "devolucion-123"
}

{
    "action": "factura",
    "venta_id": "456",
    "tipo": "C",
    "condicion_iva": "Consumidor Final",
    "concepto_arca": 1,
    "external_id": "factura-123"
}

{
    "recurso": "contactos",
    "metodo": "POST",
    "items": [
        {
            "data": {
                "nombre": "Ana Ejemplo",
                "telefono": "1112345678"
            }
        }
    ],
    "external_id": "importacion-123"
}

{
    "url": "https://integracion.example.com/webhooks/plusdiario",
    "topics": [
        "ventas.created",
        "stock.created"
    ],
    "enabled": true
}

Campos obligatorios según operación

• Contacto: nombre. Lead: nombre y mensaje. Teléfono, email y documentos ayudan a detectar conflictos.
• Producto: nombre y codigo; comienza con stock cero. Stock: inventario_id, action, cantidad y motivo; ajuste exige stock_esperado. Productos con lotes requieren un lote para ingresos; sus salidas usan lotes disponibles por vencimiento. Los ajustes de compuestos se realizan sobre sus componentes.
• Presupuesto/pedido: cliente_id e items, o presupuesto_id para crear un pedido desde uno existente. Los artículos usan cantidad y un inventario_id; si no están en catálogo necesitan articulo y precio_unitario.
• Venta: modo, sucursal_id y cliente_id con items, o un presupuesto_id/pedido_id válido que provea cliente y artículos. El modo operativa exige afectar_stock y pagos. Si afecta stock, todos los artículos necesitan inventario_id.
• Cobro: venta_id, monto y metodo_pago. Devolución: venta_id, items con sale_item_id y cantidad, motivo, reponer_stock y reintegro (incluso 0.00).
• Factura: venta_id, tipo y condicion_iva; para A/B, iva_alicuota. El documento se toma del contacto o de doc_tipo/doc_nro explícitos. Para servicios se exigen sus tres fechas.
• Nota de crédito: action=nota_credito, venta_id y devolucion_id; toma clase, receptor y alícuota de la factura autorizada.

Recorridos completos

Del contacto a la factura

1. Creá o consultá el contacto y guardá su ID.
2. Consultá productos y sucursales, creá el presupuesto y guardá su ID y version.
3. En presupuestos.php?id=ID enviá {"action":"convertir_pedido","version":"..."}.
4. En pedidos.php?id=ID avanzá con confirmar, preparar y despachar cuando corresponda. Cada acción devuelve una nueva version.
5. Para entregar enviá {"action":"entregar","version":"...","afectar_stock":true,"pagos":[],"sucursal_id":"1"}. Se confirma la venta y entrega sin inventar un cobro.
6. Cuando recibas el pago, registralo en cobros.php; conservá el recibo y consultá el saldo.
7. Solicitá la factura en comprobantes.php y consultá ?job_id=ID. Solo done con comprobante autorizado permite mostrar la factura como emitida.

Importar una venta realizada en otro sistema

Usá modo externa, una referencia comercial estable y los artículos/importes originales. Se crea la venta y se aplica scoring 20; stock, pagos y factura permanecen separados. Si necesitás reflejar movimientos reales adicionales, registralos explícitamente y vinculalos con venta_id.

Devolución parcial

Consultá la venta para obtener items[].id. Enviá ese valor como sale_item_id, la cantidad devuelta y si debe reponerse. Informá el reintegro efectivamente realizado; no se ejecuta una transferencia. Si la venta fue facturada, solicitá después su nota de crédito con devolucion_id. La venta original y su scoring se conservan.

Actualizar sin perder cambios

Hacé GET, tomá version y enviá PATCH con solo los campos que quieras cambiar. Ante 409, volvé a consultar y revisá el conflicto; una corrección del contenido necesita una nueva Idempotency-Key.

PHP, JavaScript de servidor, n8n y Make

$body = json_encode(['external_id'=>'cliente-123','nombre'=>'Ana Ejemplo','telefono'=>'1112345678']);
$curl = curl_init('https://www.plusdiario.com.ar/api/v2/contactos.php');
curl_setopt_array($curl, [
    CURLOPT_POST=>true, CURLOPT_POSTFIELDS=>$body, CURLOPT_RETURNTRANSFER=>true,
    CURLOPT_TIMEOUT=>30,
    CURLOPT_HTTPHEADER=>['Content-Type: application/json',
        'Authorization: Bearer '.getenv('PLUSDIARIO_API_TOKEN'),
        'Idempotency-Key: contacto-web-123']
]);
$response = curl_exec($curl);
$httpStatus = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
// Evaluá httpStatus y error.code. Conservá la misma clave en reintentos.

const response = await fetch('https://www.plusdiario.com.ar/api/v2/contactos.php', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PLUSDIARIO_API_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'contacto-web-123'
  },
  body: JSON.stringify({ external_id: 'cliente-123', nombre: 'Ana Ejemplo', telefono: '1112345678' })
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
// Persistí result.data.id para vincular las operaciones siguientes.

• n8n: usá HTTP Request, autenticación por header Bearer y cuerpo JSON. Derivá Idempotency-Key del ID estable del evento de origen. Guardá data.id; para trabajos asíncronos consultá job_id hasta un estado final. Ramificá errores por código.
• Make: usá HTTP → Make a request con los mismos headers. Guardá el token en una conexión privada y los IDs en tu almacenamiento. No generes una clave nueva en cada reintento del mismo evento.
• Lotes: POST a lotes.php con recurso, metodo e items de la forma {"query":{"id":"123"},"data":{...}}. Los elementos son independientes; creá primero los registros de los que dependen otros lotes. Consultá cada resultado y usá action=reintentar para fallidos. Los elementos exitosos no se ejecutan nuevamente.

Recibir cambios mediante webhooks

Registrá un destino HTTPS y topics exactos en webhooks.php. Guardá el secret de la respuesta de creación de forma privada. La suscripción comienza con los eventos posteriores a su alta y respeta los permisos actuales del token y del usuario.

X-PD-Event-ID: 123
X-PD-Timestamp: 1793050000
X-PD-Signature: v1=FIRMA_HEXADECIMAL

{"id":"123","type":"ventas.created","occurred_at":"2026-10-26T12:00:00-03:00","data":{"id":"456"}}

Firma esperada: HMAC-SHA256(secret, timestamp + "." + cuerpo_original)

Verificá la firma sobre el cuerpo recibido sin modificarlo, comparala en tiempo constante y rechazá timestamps con más de 5 minutos de diferencia. Guardá event.id para deduplicar; puede repetirse y los eventos pueden llegar fuera de orden. Consultá el recurso por ID para obtener su estado actual.

Respondé 2xx después de guardar el evento. Las entregas tienen hasta 7 intentos, con esperas de 1 minuto, 5 minutos, 15 minutos, 1 hora, 6 horas y 24 horas. Un destino inválido o permisos revocados detienen la entrega. Consultá ?action=entregas&id=WEBHOOK_ID y reenviá una entrega mediante {"action":"reenviar","delivery_id":"123"}.

Eventos: contactos.created, contactos.updated, productos.created, productos.updated, stock.created, stock.updated, presupuestos.created, presupuestos.updated, pedidos.created, pedidos.updated, ventas.created, ventas.updated, cobros.created, cobros.updated, comprobantes.created, comprobantes.updated, devoluciones.created, devoluciones.updated, leads.created, leads.updated. Los cambios de interfaz y procesos internos también se registran mediante eventos transaccionales.

Errores y recuperación

Cortes durante facturación

pending espera al worker; processing está en curso; done tiene comprobante autorizado; rejected indica rechazo fiscal y necesita datos corregidos; failed falló antes de confirmar una emisión; uncertain exige conciliar la numeración reservada. El reintento de un resultado incierto consulta ARCA antes de emitir. Si no puede confirmarse, permanece pendiente de conciliación: no se genera otra factura a ciegas.

La caída de ARCA no revierte ni duplica la venta o sus cobros. La activación fiscal usa los certificados y el ambiente configurados para la empresa; las pruebas se hacen en homologación.

Compatibilidad y límites de esta entrega

La API v1 conserva su URL, sus tokens y su respuesta. La v2 usa otro contrato. No incluye pasarelas bancarias, múltiples monedas de escritura, financiación nueva ni comprobantes con varias alícuotas en una misma solicitud. Las devoluciones automáticas requieren el detalle trazable v2; los históricos permanecen consultables.

Cambios

2.0.0: API comercial, permisos por recurso, idempotencia, control de versiones, lotes, webhooks y facturación asíncrona. Requiere instalación y habilitación administrativa.