Ayuda: APIs de Catálogo

APIs de catálogo y existencias Permiso 436

Genera las credenciales para que un sistema externo —típicamente una tienda en línea— consulte el catálogo y las existencias de la empresa.

Las credenciales son como una llave Entrégueselas solo a quien desarrolla la tienda y revóquelas cuando esa persona deje de trabajar con usted.

La dirección del servicio es https://apis.factupos.com/v1 y es la misma para todas las empresas: la credencial es la que dice de qué empresa se trata.

Qué puede y qué no puede hacer Toda credencial lee catálogo, precios y existencias. Además, si usted se lo habilita, puede registrar los pedidos que le hagan en la tienda. Lo que nunca hace es facturar: no emite documentos electrónicos, no cobra y no cambia precios. La factura la sigue haciendo su personal desde el sistema.

El procedimiento completo

Esto es todo lo que hay que hacer, en orden, desde que decide conectar la tienda hasta que los pedidos le entran solos. Su parte son los pasos 1 al 5; del 6 en adelante lo hace quien le desarrolla la tienda.

Paso	Qué se hace	Dónde
1	Marque qué artículos se publican. Solo salen los que tienen encendido «Mostrar en Web». Para muchos de una vez, use Cambios Globales.	Inventario → Artículos
2	Decida de cuál bodega salen las existencias que verá la tienda, y con cuál lista de precio se cobra.	—
3	Si además quiere recibir los pedidos: decida a nombre de quién quedan (un cliente fijo tipo «Tienda en línea», que hay que crear antes, o cada comprador por su cédula) y a cuál correo se avisa.	Clientes, si va a usar cliente fijo
4	Emita la credencial con todo eso. Cópiela en ese momento: se muestra una sola vez.	Inventario → Herramientas → APIs de Integración
5	Entréguesela a quien desarrolla la tienda, junto con la dirección `https://apis.factupos.com/v1`.	—
6	Prueban con `/ping`, que confirma a qué empresa, bodega y lista apunta la credencial y qué tiene permitido hacer.	Lo hace la tienda
7	Bajan el catálogo completo una vez, con `/products`.	Lo hace la tienda
8	Cada pocos minutos consultan `/products/stock` pidiendo solo lo que cambió, y una vez al día hacen la vuelta completa.	Lo hace la tienda
9	Cuando alguien compra, la tienda manda el pedido con `/orders`.	Lo hace la tienda
10	Usted factura el pedido, que le aparece marcado como «Tienda en línea (API)».	Facturación → Pedidos

Quién hace qué Usted no tiene que programar nada ni instalar nada. Su trabajo es decidir qué se publica, emitir la credencial y facturar los pedidos. Todo lo técnico lo hace quien le desarrolla la tienda, con la credencial que usted le entrega.

Emitir una credencial

Desde Inventario → Herramientas → APIs de Integración, con el botón Nueva credencial. Se le piden estas cosas:

Dato	Qué decide
Nombre	Solo para reconocerla después en la lista. No lo ve la tienda.
Bodega	De qué bodega salen las existencias que ve la tienda. Si no elige ninguna, ve el total de todas juntas. Si la tienda despacha de un solo local, elija esa bodega, o va a ofrecer artículos que en realidad están en otro lado.
Lista de precio	Cuál de los diez niveles de precio se publica (1 = detalle, 2 = mayoreo…).
Qué puede hacer	Si además de leer el catálogo puede registrar pedidos. Nace apagado: hay que encenderlo a propósito. En la lista de credenciales se ve cuál es cuál.
Los pedidos quedan a nombre de	Solo si registra pedidos. En blanco, cada comprador se busca por cédula y se crea si no existe. Con un código de cliente —por ejemplo uno llamado «Tienda en línea»— todos los pedidos quedan a ese nombre, y los datos de quien compró van en las observaciones del documento.
Avisar cada pedido a	Solo si registra pedidos. Correo al que llega el aviso de cada venta. En blanco, va al correo de la empresa.
Vencimiento	Cuándo deja de servir sola. Sin vencimiento, sirve hasta que usted la revoque.

La credencial se muestra UNA sola vez Al crearla aparece completa en pantalla. Cópiela en ese momento y guárdela: el sistema guarda solo una huella y no hay forma de volver a verla. Si se pierde, se revoca y se emite otra.

Revocar una credencial la deja inservible al instante, pero no la borra: se conserva quién la emitió, cuántas consultas hizo y cuándo se usó por última vez.

Conviene usar dos credenciales, no una Una que solo lea el catálogo y otra que registre pedidos. Si la que vive dentro de la tienda se llegara a filtrar, lo peor que puede pasar es que alguien vea su catálogo —no que le meta pedidos falsos—. Cambiar una sola credencial tampoco le tumba las dos cosas a la vez.

Qué artículos se publican

Solo salen los que tienen encendido «Mostrar en Web» Es la casilla del catálogo de artículos que decide qué se ve en la tienda. Si la API le devuelve pocos artículos —o ninguno— casi siempre es esto, no un problema de la credencial.

Para encenderla en muchos artículos de una sola vez, use Cambios Globales en Inventario.

Un artículo deja de publicarse cuando se inactiva, se elimina, se descontinúa o se le apaga esa casilla. En todos esos casos la tienda se entera (ver más abajo).

Las consultas disponibles

La credencial viaja en el encabezado Authorization: Bearer fp_… de cada consulta.

Consulta	Para qué sirve
/v1/ping	Comprueba que la credencial sirve y dice a qué empresa, bodega y lista de precio apunta. Es la primera que conviene probar.
/v1/products	El catálogo completo, con nombre, precio, existencias, categorías, marca y código de barras.
/v1/products/stock	Versión liviana: solo existencias y precio. Es la que conviene consultar cada pocos minutos.
/v1/products/{id}	Un artículo puntual. Acepta tanto el identificador interno como el código del artículo.
/v1/categories	Las categorías y subcategorías que tienen artículos publicados.

Las listas vienen de a páginas: por omisión 200 artículos, y se puede pedir hasta 500 con limit. Cuando hay más, la respuesta trae has_more en verdadero y un next_cursor que se manda en la consulta siguiente para seguir donde iba.

Sobre el precio price viene con impuesto incluido —lo que paga el comprador, igual que en el catálogo público—, y además se envían price_net (sin impuesto) y tax_rate por separado, por si la tienda necesita armarlo de otra forma.

Traer solo lo que cambió

Agregando updated_since con una fecha, la API devuelve únicamente lo que se movió desde ese momento. Así la tienda se mantiene al día sin volver a bajar todo el catálogo.

Las bajas también viajan Cuando un artículo se inactiva, se elimina o se le apaga «Mostrar en Web», aparece en la lista con su nuevo estado en lugar de desaparecer. Si desapareciera sin más, la tienda lo seguiría vendiendo para siempre.

Un cambio que hoy no viaja: el precio editado a mano Los cambios de existencias y las ediciones del artículo sí se detectan. Un precio cambiado a mano, en cambio, todavía no queda marcado con fecha, así que no aparece en la consulta de cambios. Mientras tanto, la recomendación es hacer una vuelta completa al día (sin updated_since), que recupera cualquier precio que se haya movido.

Cómo trabaja día con día

Una vez conectada, la cosa camina sola. Esto es lo que pasa en un día normal, para que sepa qué esperar y dónde mirar.

Cuándo	Qué pasa
Cada pocos minutos	La tienda pregunta qué cambió y actualiza precios y existencias. Si usted sube un precio o entra una compra, la tienda se entera sin que nadie haga nada.
Una vez al día	La tienda baja el catálogo completo, por si algo se quedó atrás.
Cuando alguien compra	Entra el pedido a Facturación → Pedidos y le llega un correo. Las unidades vendidas dejan de ofrecerse en la tienda de inmediato.
Cuando usted lo factura	Sale la factura normal, con su documento electrónico. Ahí es cuando baja el inventario.
Si el comprador se arrepiente	La tienda cancela el pedido y la mercadería vuelve a ofrecerse.
Si inactiva un artículo	La tienda se entera en la siguiente consulta y lo despublica. No hay que avisar aparte.

Los pedidos sin facturar apartan mercadería Mientras un pedido esté pendiente, esas unidades no se le ofrecen a nadie más en la tienda. Es lo que evita vender dos veces lo mismo, pero significa que un pedido olvidado en la bandeja mantiene producto apartado. Si al final no se va a vender, cancélelo.

Recibir pedidos de la tienda

Cuando alguien compra en su tienda en línea, la tienda le puede avisar a FactuPOS de una vez. El pedido cae en Facturación → Pedidos, en la misma bandeja donde ya ve los pedidos de sus vendedores, marcado con el origen «Tienda en línea (API)». Desde ahí su personal lo abre y lo factura como cualquier otro.

Hay que habilitarlo en la credencial Al emitir la credencial, encienda «puede registrar pedidos». Una credencial normal solo lee: si la tienda intenta mandar un pedido con ella, se le rechaza.

Qué pasa con cada cosa del pedido:

Dato	Cómo se resuelve
El precio	Manda el suyo, el de la lista de precio de la credencial. La tienda puede enviar el precio que le cobró al comprador, y si no coincide con el suyo el pedido se rechaza en vez de entrar con un monto equivocado.
La bodega	La de la credencial. Por eso conviene elegirla al emitirla.
El cliente	Depende de cómo emitió la credencial: o se busca por cédula y se crea si no existe, o todos los pedidos quedan a nombre de un cliente fijo. En este segundo caso los datos de quien compró no se pierden: aparecen en las observaciones del documento, para que al facturar usted decida a quién le factura.
Las existencias	Si un artículo no alcanza, el pedido no entra, y se le devuelve a la tienda el detalle de cuáles renglones fallaron para que le avise al comprador.

En la tienda no se vende lo que no hay En el mostrador, la casilla «Sobregira» de un artículo deja que el vendedor lo venda aunque esté en cero: tiene al cliente enfrente y sabe si el producto llega mañana. En la tienda esa casilla no se toma en cuenta, porque no hay nadie decidiendo: se le cobraría a alguien algo que no se le puede entregar. Si de verdad quiere vender sin existencias también por la web, eso se habilita para toda la empresa con el parámetro de sobregiro general.

Un pedido repetido no se duplica Si a la tienda se le corta el internet justo al mandar un pedido, va a reintentar sin saber si el primero entró. FactuPOS reconoce el reintento por el número de pedido de la tienda y devuelve el mismo pedido en vez de crear otro. Usted nunca va a ver la misma venta dos veces.

Cómo afecta las existencias

En FactuPOS el inventario baja cuando se factura, no cuando se pide. Un pedido de la tienda no mueve existencias por su cuenta: las mueve la factura que hace su personal.

Pero lo que la tienda VE ya viene descontado La existencia que publica la API es la que hay menos la que está en pedidos sin facturar. Así la tienda no vuelve a ofrecer lo que ya se vendió por la web mientras el pedido espera en la bandeja. Es automático: no hay nada que configurar.

Un ejemplo: si de un artículo tiene 10 en bodega y hay un pedido de la web por 4 sin facturar, la tienda va a ver 6. Su mostrador sigue viendo los 10 físicos, porque esas 4 todavía están en la percha.

Conviénele facturar los pedidos a tiempo Un pedido que queda semanas en la bandeja mantiene esa mercadería apartada para la tienda. Si al final no se va a vender, cancélelo: eso la libera de inmediato.

Cancelar un pedido

Si al comprador le rechazan el pago o se arrepiente, la tienda puede cancelar el pedido y lo apartado vuelve a quedar disponible.

Solo mientras nadie lo haya tomado Si su personal ya abrió el pedido para facturarlo, la tienda ya no lo puede cancelar: se le devuelve un aviso claro. Y si la factura ya salió, la vuelta atrás es una nota de crédito hecha desde el sistema, como cualquier otra venta.

Cancelar dos veces el mismo pedido no da error: queda cancelado igual.

Límites y errores

Cada credencial admite 120 consultas por minuto. Bajar un catálogo de 40.000 artículos son unas 200 consultas, o sea menos de dos minutos.

Si se pasa de ese ritmo, la API contesta con el código 429 e indica cuántos segundos hay que esperar. Los errores siempre vienen con la misma forma:

Código	Qué pasó
401	La credencial falta, está mal escrita, venció o fue revocada.
400	Un parámetro mal armado (una fecha que no se entiende, un cursor inválido).
404	La dirección no existe, o el artículo pedido no está.
429	Se pasó del límite de consultas. Espere los segundos que indica y reintente.

Si algo no funciona

Lo que más se consulta, con la causa real de cada caso.

Síntoma	Qué suele ser
La tienda no ve casi ningún artículo	Casi siempre es «Mostrar en Web» apagado, no la credencial. Enciéndalo con Cambios Globales.
Dice «credencial inválida»	Fue revocada, venció, o se copió incompleta. Emita una nueva: no hay forma de recuperar la anterior.
Dice que no puede registrar pedidos	Esa credencial es de solo lectura. Hay que emitir una con «puede registrar pedidos» encendido.
Un pedido no entra por existencias	No hay suficiente en la bodega de la credencial. En la tienda no se toma en cuenta la casilla «Sobregira» del artículo.
Un pedido no entra por precio	El precio que muestra la tienda no coincide con el de su lista. Suele ser que la tienda tiene el catálogo viejo: que vuelvan a sincronizar.
Los pedidos salen a nombre equivocado	Revise el cliente fijo de la credencial. Si está en blanco, cada comprador se crea por su cédula.
El aviso de pedidos llega a otro correo	Se toma el de la credencial y, si está vacío, el de la empresa. Emita la credencial de nuevo con el correo que quiere.
La tienda ofrece algo que ya no hay	Recuerde que la tienda consulta cada pocos minutos, no al instante. Entre dos consultas puede vender algo que se acabó en el mostrador.

Antes de llamar a soporte Pídale a quien desarrolla la tienda que pruebe /ping y le pase la respuesta. Ahí se ve la empresa, la bodega, la lista de precio y qué tiene permitido hacer esa credencial: con eso se resuelve la mayoría de los casos sin dar más vueltas.

Enviarle este manual a un usuario