Paso 1 — la clave API, sin registro de desarrollador
No hay consola de desarrollador ni validación manual. El comerciante abre su conversación de WhatsApp con Fatora-Bot y escribe «api»: el bot responde con su clave personal, en formato fk_ seguido de 40 caracteres. Esa es la clave que tu aplicación guarda y pasa en la cabecera Authorization: Bearer.
La clave es propia de cada comerciante: emite en SU numeración y solo ve SUS documentos. «api reset» la regenera en cualquier momento — la antigua queda revocada de inmediato. Un GET /v1/account es la forma más simple de comprobar que una clave pegada por el usuario es válida: devuelve el perfil de empresa, el plan y la cuota restante.
Paso 2 — emitir el documento
Una sola llamada: POST /v1/documents, con el nombre del cliente (y su ICE en B2B), y las líneas — descripción, cantidad, precio unitario. La API calcula el IVA línea a línea, aplica el régimen fiscal del comerciante, genera el PDF con logo y sello, y responde 201 con el número asignado, los totales, el enlace del PDF y la URL de un código QR.
Dos opciones cambian el día a día. "type": "quote" emite un presupuesto (numerado DEV-, válido 30 días, fuera de la cuota) en lugar de una factura. "priceIsTtc": true indica que tus importes llevan impuestos: la API reconstruye la base sin impuestos por sí misma — imprescindible cuando tus precios de venta se muestran con IVA.
Para corregir un documento ya emitido, no hay esquema de actualización que aprender: el endpoint de modificación acepta una instrucción en texto libre («sustituye la formación por 3 días a 1200 dh el día») y la aplica sobre el mismo número, con PDF regenerado y totales recalculados.
La numeración sigue siendo continua: modificar nunca crea un hueco en la secuencia, y anular pasa por una factura de abono — como exige la normativa marroquí.
Paso 3 — entregar la factura al cliente
Generar el PDF no sirve de nada si el cliente no lo recibe. Hay tres canales disponibles, al crear (campos "sendToPhone" y "sendToEmail") o después mediante el endpoint de envío:
- WhatsApp: el PDF llega a la conversación del cliente, a nombre del comerciante.
- Email: un mensaje cuidado con la factura adjunta.
- Código QR: cada documento expone una imagen PNG pública — muéstrala en caja, imprímela en el ticket, el cliente escanea y descarga su factura.
Los errores que tu código debe gestionar
La API devuelve siempre un JSON con dos campos: "error" (código máquina estable) y "message" (explicación mostrable tal cual). Cuatro casos merecen un tratamiento específico en tu interfaz: el 402 cuota alcanzada (la respuesta lleva used y limit — muéstralos, el comerciante sube de plan en dos mensajes de WhatsApp), el 401 clave inválida (a menudo una clave regenerada con «api reset» — pide la nueva), el 422 instrucción no entendida (propón reformular, nada fue modificado), y el 429 por encima de 60 peticiones por minuto (encola y reintenta).
La lista completa de códigos, cada uno con un ejemplo de respuesta, está en la página API del sitio — cada ejemplo fue reproducido contra la API de producción.
Preguntas frecuentes
¿Necesito una cuenta de desarrollador o una validación para usar la API?
No. La clave se obtiene escribiendo «api» al bot de WhatsApp de la cuenta de Fatora en cuestión, en segundos. No hay consola, ni contrato, ni coste: la API está incluida en todos los planes, prueba gratuita incluida.
¿El PDF generado resiste realmente una inspección fiscal?
El PDF lleva las menciones del artículo 145 del código fiscal: ICE, identificador fiscal, tasa profesional, IVA detallado, importe en letras, numeración continua, y las menciones de régimen (auto-emprendedor, exento) cuando aplican. El sello y el logo del comerciante se aplican automáticamente.
¿Puedo emitir presupuestos y convertirlos en facturas?
Sí. "type": "quote" emite un presupuesto numerado DEV- válido 30 días, gratuito y fuera de la cuota. La conversión se hace con la instrucción libre («convierte el presupuesto DEV-2026-0012 en factura») — la factura toma un número FAT- normal.
¿Cómo pruebo sin ensuciar la numeración del comerciante?
Emite presupuestos durante tus pruebas: son gratuitos, ilimitados y no tocan la secuencia de facturas. Reserva las facturas reales para producción — cada factura emitida entra en la numeración legal y se anula con un abono, no borrándola.
Esta guía presenta el marco general aplicable en Marruecos. No sustituye el asesoramiento de tu contable ni los textos publicados por la Dirección General de Impuestos.