API de integraciones de Punto

Antes de empezar

Para conectar tu sistema hacen falta tres cosas, y las prepara el comercio desde el panel de Punto:

1. El complemento API de integraciones activo. Se contrata desde el panel, en Mi plan. Sin él, todas las llamadas responden 403 con reason: addon_api_required.
2. Una caja para el canal. Cada pedido nombra la caja de Punto contra la que se registra (registerId). Se crea como cualquier otra caja, en Configuración › Sucursales, y es la que decide todo lo fiscal: si tiene timbrado y punto de expedición cargados, las ventas salen con factura; si no, se registran sin emitir. Usá una caja dedicada, sin ningún dispositivo conectado: si en esa caja también vende una persona, los dos numeran comprobantes de la misma serie.
3. Una key de integración. Ver Autenticación.

El identificador de la caja se ve en la dirección del navegador al abrirla en Configuración.

Autenticación

Cada llamada lleva la key en el encabezado Authorization:

Authorization: Bearer <tu key>

La key se emite en Configuración › Keys de integración → Nueva key, eligiendo en Qué puede hacer la opción Integración de ventas. Se muestra una sola vez: guardala en el servidor de tu sistema, nunca en el navegador ni en una app que se distribuye.

Alcance de una key. Cada key se emite con un alcance fijo, que no se puede cambiar después (se emite una nueva y se revoca la anterior):

Los alcances no se incluyen entre sí: una key write no registra ventas y una integration no configura nada.

Una key no puede más que su dueño. Hereda los permisos y las sucursales del usuario que la emitió: emitila con un usuario que tenga permiso para vender y acceso a la sucursal de la caja del canal.

Cortar el acceso. Revocar la key en el panel la deja sin efecto en el acto, sin tocar lo que ya se registró. Si se da de baja el complemento, todas las keys dejan de responder solas.

Límites de uso

Cada key tiene dos límites, que se cuentan por key (no por comercio ni por IP):

• 60 llamadas por minuto.
• 5.000 llamadas por día.

Al pasarte, la llamada responde 429 y no se procesa. Esperá un minuto antes de reintentar y espaciá los reintentos (por ejemplo, 1, 2, 4 y 8 segundos entre intentos). Para consultar el estado fiscal de un pedido no hace falta más de una consulta cada 30 segundos.

Errores

Toda respuesta tiene la misma forma. Si salió bien:

{ "ok": true, "data": { ... } }

Si no:

{
  "ok": false,
  "error": {
    "message": "El total del pedido no coincide con lo que suman sus líneas...",
    "code": 422,
    "details": { "reason": "total_mismatch", "declared": 19000, "computed": 22000 }
  }
}

Programá contra error.details.reason, no contra el texto: el texto es para la persona que lee el registro y puede cambiar. Qué significa cada status:

Los reason de cada operación están en su sección.

Idempotencia

Cada pedido viaja con orderId: el identificador del pedido en tu sistema (letras, números, punto, guion y guion bajo, hasta 45 caracteres). Es lo que garantiza que un pedido no se registre dos veces.

• Si mandás el mismo orderId otra vez —porque se cortó la conexión y no viste la respuesta—, Punto devuelve lo que ya había registrado, con duplicated: true y status 200. Un alta nueva responde 201 con duplicated: false.
• Si llegan dos llamadas del mismo pedido a la vez, se registra una sola y las dos reciben el mismo resultado.
• El reintento devuelve lo registrado aunque el catálogo haya cambiado desde entonces: nunca te va a decir que un pedido ya facturado falló.

Ventas y órdenes tienen cada una su espacio de orderId: el mismo pedido puede entrar primero como orden y después como venta con el mismo identificador.

Precios, impuestos y totales

Cada línea nombra un artículo del catálogo de Punto (por itemId o por sku), la cantidad y el precio unitario que cobró tu sistema. Punto compara ese precio con el de su lista (la del cliente, la de la sucursal o la del catálogo, en ese orden):

• Por debajo de la lista, la diferencia queda registrada como descuento de la línea. Así el margen y el reporte de productos siguen siendo reales.
• Por encima de la lista, se acepta como precio modificado, igual que cuando el cajero cambia un precio a mano.
• Agregados (addons): se nombran por optionId y cantidad; el recargo lo pone el catálogo. El unitPrice de la línea es el precio con los agregados incluidos.
• Envíos y recargos van en charges, como línea propia con su descripción. Nunca sumados al precio de un producto.

Los impuestos los calcula Punto con las mismas reglas que una venta del mostrador: tu sistema no manda IVA ni totales por tasa, y si los manda se ignoran. Tampoco manda el número de comprobante: la numeración es de Punto.

El total se compara. Mandás en total lo que cobraste (o vas a cobrar) al comprador, y Punto lo compara con lo que suman las líneas. Si la diferencia es mayor al redondeo (una unidad de la moneda por línea), el pedido no se registra y responde 422 con reason: total_mismatch, declared y computed. Nunca se factura algo distinto de lo que vio el comprador.

Factura electrónica y KuDE

Si la caja del canal tiene facturación electrónica configurada, cada venta emite su documento electrónico. En Paraguay (SIFEN) el documento se envía a validar en segundo plano, así que la respuesta del alta todavía no trae el veredicto: se consulta después.

Cómo seguirlo. Consultá GET /v1/integrations/sales?orderId=<id> (o el de la orden, si la facturaste desde una orden) hasta que einvoice.sifenVerdict deje de ser pending. Una consulta cada 30 segundos alcanza; la mayoría se resuelven en pocos minutos.

Dónde recibe el comprador su factura. El KuDE (la representación imprimible del documento) queda disponible en el portal de Punto: einvoice.portalUrl es el link que tu tienda le muestra al comprador, por ejemplo en la confirmación del pedido o en el email que le mandás. Esta API no devuelve el PDF.

issued: true significa que el documento fue aprobado, no solo enviado: un documento puede haberse enviado y ser rechazado después.

Órdenes: del pedido a la factura

Una orden es un pedido para preparar y entregar: entra a la cola de la cocina y a la pantalla de pedidos del local como cualquier otra, con origen tienda online. No se factura al crearla.

Se factura de dos maneras:

1. Desde la caja, como cualquier orden (por ejemplo, un delivery que se cobra al volver el repartidor). Consultando GET /v1/integrations/orders vas a ver la venta cuando se cobre.
2. Desde tu sistema, con POST /v1/integrations/sales y fromOrderId: Punto registra la venta, la vincula a la orden y la cierra, como hace la caja al cobrarla. La venta toma al comprador de la orden si no mandás otro.

Una orden con scheduledFor en otro día no aparece en la cocina hasta ese día. Una orden con envío (fulfillment: delivery) necesita al comprador y la dirección: la dirección queda guardada en su ficha y la orden conserva una copia, así el pedido sigue diciendo a dónde fue aunque el cliente la cambie después.

Sincronizar el catálogo

Con la misma key podés leer el catálogo del comercio (GET /v1/items) para mantener tu tienda sincronizada: identificadores, SKU, precio de lista y agregados. Recorrelo por páginas con after.

El resto de las consultas de lectura del comercio (reportes, clientes, stock) existe y la usa el conector MCP, pero todavía no forma parte de este contrato público: puede cambiar sin aviso.