Saltar al contenido
rayocreativo.com Abrir ticket
Todas las secciones

Cómo conectar tu propio sistema con la API y los webhooks

Facturador · Configuración 4 min de lectura Actualizada el
En esta guía
  1. Antes de empezar
  2. Paso a paso
  3. 1. La API
  4. 2. Los webhooks
  5. Ejemplo práctico
  6. Si no ves esto
  7. Si algo no funciona
  8. Preguntas frecuentes
  9. Guías relacionadas

Para qué sirve: conectar tu CRM, ERP o una automatización (Zapier, Make, n8n): con la API creás clientes y emitís comprobantes desde afuera; con los webhooks el sistema les avisa a tus otros programas cuando pasa algo.

Antes de empezar

  • Facturador activo y ARCA conectado si vas a emitir con CAE.
  • Alguien que pueda hacer pedidos HTTP (un desarrollador, o una herramienta como Zapier, Make o n8n).
  • Permiso para facturar canales (Administrador y Facturación — Operador).

Paso a paso

1. La API

  1. Entrá a Integraciones (en Ajustes) y abrí la pestaña API.
  2. Arriba ves la Base URL de tu empresa (termina con el slug) y la Autenticación: se manda la clave en el header X-Api-Key, o como Authorization: Bearer tu_clave.
  3. En Claves de acceso escribí un Nombre (por ejemplo, «WooCommerce producción») y tocá Generar clave.
  4. Copiá la clave en ese momento: se muestra una sola vez. Guardala en un lugar seguro.
  5. Probá con GET /ping. La Guía rápida de la derecha lista el resto: crear clientes (POST /clients), emitir (POST /invoices), leer ventas y cobros (GET /orders, GET /payments) y consultar un comprobante (GET /invoices/{id}). Más abajo está la Documentación de endpoints.
Pestaña API con la base URL, la autenticación y el formulario para generar una clave marcado en rojo.
Pestaña API con la base URL, la autenticación y el formulario para generar una clave marcado en rojo.

Podés tener hasta 5 claves activas. Con Revocar dejás sin acceso a una clave (por ejemplo, si se filtró) sin tocar las demás.

2. Los webhooks

  1. Abrí la pestaña Webhooks.
  2. En Agregar destino pegá la URL (empieza con https://). Si usás Zapier, es la de su paso «Webhook / Catch hook».
  3. Escribí un Nombre (opcional) y elegí Qué avisar: Todo o solo algunos eventos (una venta, un comprobante, un cobro, un cliente o un turno nuevo).
  4. Tocá Agregar destino. Se muestra el Secreto de firma, una sola vez: copialo.
Pestaña Webhooks con el formulario Agregar destino marcado en rojo y, a la derecha, cómo llega el aviso.
Pestaña Webhooks con el formulario Agregar destino marcado en rojo y, a la derecha, cómo llega el aviso.
  1. En Tus destinos vas a ver cada uno con su estado, Activo o Pausado, y los botones Probar, Pausar / Activar, Nuevo secreto y Eliminar.
  2. Tocá Probar para mandar un aviso de prueba. En Últimos envíos ves el evento, el destino, el estado y los intentos.

Cómo llega: un POST con un JSON que trae el id, el event, la fecha y los data. Para comprobar que viene de nosotros, usá el header X-Gestion-Signature con el secreto. Si usás Zapier o Make podés ignorar la firma. Si tu servidor no responde con un código 2xx, reintentamos a los 1, 5 y 30 minutos, y a las 2 y 12 horas. Con 25 fallas seguidas el destino se pausa.

Ejemplo práctico

Distribuidora CM quiere que cada cobro quede en una planilla de Google. Su administrativo arma un «Catch hook» en Zapier, pega esa URL como destino en Webhooks, le pone el nombre «Zapier → planilla de ventas» y deja Todo. Toca Probar, ve que el envío salió bien y desde ese momento cada cobro suma una fila.

Si no ves esto

  • No ves la pestaña API o Webhooks: la pantalla de Integraciones necesita el permiso de facturar canales. Con Solo lectura o Contador no se ve.
  • Al tocar «Generar clave» aparece «Máximo 5 claves activas»: revocá una que no uses antes de generar otra.
  • No ves la clave que generaste: solo se muestra al crearla. Revocala y generá otra.
  • No ves el secreto del webhook: también se muestra una sola vez; tocá Nuevo secreto para generar uno.
  • Estás en otra empresa: la base URL y las claves son de cada empresa. Revisá el selector de empresas.

Si algo no funciona

  • La API responde un error de autenticación: falta la clave, está mal copiada o fue revocada. Mandala en X-Api-Key o como Bearer.
  • Emitir por API devuelve error de cupo (402): se terminó el cupo de tu plan. Ampliá en Mi plan.
  • El destino quedó «Pausado»: tu servidor falló 25 veces seguidas. Arreglalo, tocá Activar y probalo con Probar.
  • No llegan los avisos: revisá que la URL sea https y pública, y mirá Últimos envíos para ver el estado y los intentos.
  • La firma no coincide: probablemente cambiaste el secreto con Nuevo secreto; el anterior deja de validar.

Preguntas frecuentes

¿La API y los webhooks tienen costo? No. Lo que descuenta es el cupo de comprobantes si emitís.

¿Puedo tener varios destinos? Sí, uno por sistema, cada uno con su propio nombre y eventos.

¿Qué eventos puedo recibir? Ventas, comprobantes, cobros, clientes y turnos. Elegís cuáles al agregar el destino.

¿Es seguro compartir la clave? No la compartas por chat público. Si se filtra, Revocar y generá una nueva.

¿Necesito programar? Para la API sí (o una herramienta que haga pedidos HTTP). Para los webhooks alcanza con Zapier, Make o n8n.

Guías relacionadas

¿Te resultó útil esta guía?

Más de Facturador · Configuración

¿No encontrás lo que buscás?

Escribinos y una persona del equipo de Rayo Creativo te ayuda.

Abrir un ticket