Empezar con la API

Qué se puede hacer

La API de AtiendeFácil es una API REST con JSON. Con una clave, tu sistema trabaja sobre los datos de un negocio: el de la clave. Lo que escribe pasa por las mismas reglas que el panel, así que hace exactamente lo mismo que el botón equivalente (avisarle al cliente por WhatsApp, imprimir la comanda, quedar en la auditoría).

Además, GET /me dice si el bot está en pausa, si el WhatsApp está conectado y cuánto saldo queda, y GET /team lista al equipo (ver Rutas generales). Para mantener una copia al día sin bajarte todo cada vez, está la sincronización incremental.

Primeros pasos

1. Pídele al dueño una clave de API

   La crea él (o alguien del equipo con permiso para editar Ajustes) y se enseña una sola vez. Empieza por af_live_. Un negocio puede tener hasta 10 claves activas: lo normal es una por sistema conectado.

   Panel web

   AjustesIntegraciones

   App

   MásAjustesIntegraciones

2. Guárdala en tu servidor

   En una variable de entorno o en el gestor de secretos que uses. Nunca en el código de una página web ni de una app que se instala en teléfonos: cualquiera la vería.

3. Haz la primera llamada: GET /me

   Devuelve el negocio al que pertenece la clave. Si responde, estás dentro.

curl https://api.atiendefacil.com/api/v1/me \
  -H "Authorization: Bearer af_live_TU_CLAVE_AQUI"

// Node.js 18+ (fetch viene incluido). Nunca en el navegador: la clave quedaría a la vista.
const API = "https://api.atiendefacil.com/api/v1";
const KEY = process.env.ATIENDEFACIL_API_KEY; // af_live_…

const res = await fetch(`${API}/me`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error?.code}: ${body.error?.message}`);
console.log(body.company.name, body.company.business_mode);

<?php
$api = 'https://api.atiendefacil.com/api/v1';
$key = getenv('ATIENDEFACIL_API_KEY'); // af_live_…

$ch = curl_init("$api/me");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $key"],
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
  throw new Exception("$status {$body['error']['code']}: {$body['error']['message']}");
}
echo $body['company']['name'];

import os
import requests  # pip install requests

API = "https://api.atiendefacil.com/api/v1"
KEY = os.environ["ATIENDEFACIL_API_KEY"]  # af_live_…

res = requests.get(f"{API}/me", headers={"Authorization": f"Bearer {KEY}"}, timeout=15)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
print(body["company"]["name"], body["company"]["business_mode"])

Respuesta:

{
  "company": {
    "id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
    "name": "Pizzería La Esquina",
    "business_mode": "orders",
    "base_currency": "USD"
  },
  "api_key": {
    "id": "9f1c2b3a-4d5e-4f60-8a7b-1c2d3e4f5a6b",
    "name": "Tienda online",
    "access": "full"
  },
  "bot": { "paused": false, "pause_source": null, "pause_reason": null },
  "whatsapp": { "status": "connected", "phone": "584140000000", "channel": "qr" },
  "balance": { "tokens": 184250, "low": false },
  "location": { "lat": 10.4806, "lng": -66.9036, "address": "Av. Bolívar, local 3, Caracas" }
}

business_mode dice qué tipo de negocio es: orders (pedidos), appointments (citas), mototaxi (transporte con conductores) o support (solo soporte). Te sirve para saber qué partes de la API tienen datos: un negocio de citas no tiene pedidos, uno de transporte no tiene catálogo y uno de soporte no tiene pedidos, citas, pagos ni viajes. api_key.id es el id de tu clave; guárdalo, porque los webhooks lo usan para decirte qué cambios hiciste tú (ver tus propios cambios).base_currency es la moneda en la que el negocio pone sus precios, y bot, whatsapp y balance dicen cómo está la cuenta ahora mismo (ver Rutas generales).

URL base y autenticación

Todas las rutas cuelgan de:

https://api.atiendefacil.com/api/v1

Cada petición lleva la clave en la cabecera Authorization:

Authorization: Bearer af_live_…

También se acepta X-Api-Key: af_live_…. Solo HTTPS. La clave abre únicamente la API: no sirve para entrar al panel, y el acceso del panel no sirve aquí.

• Cada clave es de acceso completo o de solo lectura; lo elige el dueño al crearla y no se cambia después. Una de solo lectura puede hacer todos los GET y nada más: cualquier otra petición responde 403 read_only_key, también las que no cambian nada pero van por POST (cotizar un viaje, probar un webhook). Cuál tienes lo dice api_key.access (full o read) en GET /me.
• Una clave es del negocio, no de una persona: sigue funcionando aunque quien la creó deje el equipo. Deja de funcionar al revocarla o si el negocio se desactiva.
• Todo lo que haces con ella queda en la auditoría del negocio a nombre de la clave («API · Tienda online»), y los pagos que apruebas o registras quedan firmados así.
• No hay ningún parámetro para cambiar de negocio. Si pides un id de otro negocio, la respuesta es 404, igual que si no existiera.

Convenciones

Paginación

Las listas (GET /orders, /customers, /payments…) se piden por páginas con page (desde 1) y limit (de 1 a 100; 25 si no lo mandas). La respuesta siempre tiene esta forma:

{
  "data": [ { "id": "…", "object": "order", … }, … ],
  "page": 1,
  "limit": 25,
  "has_more": true
}

has_more: true quiere decir que hay otra página. Para traerlo todo, pide páginas hasta que venga en false:

// Recorre todas las páginas de una lista (aquí, los pedidos entregados de septiembre).
async function all(path, params = {}) {
  const out = [];
  for (let page = 1; ; page++) {
    const qs = new URLSearchParams({ ...params, limit: "100", page: String(page) });
    const res = await fetch(`${API}${path}?${qs}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();
    out.push(...body.data);
    if (!body.has_more) return out;
  }
}

const orders = await all("/orders", {
  status: "completed",
  created_after: "2026-09-01T00:00:00-04:00",
  created_before: "2026-09-30T23:59:59-04:00",
});

Sincronización incremental

Si tu sistema guarda una copia de los datos (para facturar, para reportes), no hace falta bajártelo todo cada vez. Con updated_after la lista trae solo lo que cambió (se creó o se modificó) desde esa fecha, incluida:

Así basta con guardar el updated_at del último que procesaste y, en la siguiente vuelta, pedir desde ahí. El último de la vuelta anterior vuelve a salir (el filtro incluye la fecha exacta): guarda por id y reemplaza, no añadas.

// Sincronización incremental: cada vuelta trae solo lo que cambió desde la anterior.
// Con updated_after la lista va del cambio más viejo al más nuevo, así que basta con
// guardar el updated_at del último que procesaste y volver a pedir desde ahí.
async function syncOrders(db) {
  let since = (await db.get("orders_since")) ?? "2026-01-01T00:00:00Z";
  let page = 1;
  for (;;) {
    const qs = new URLSearchParams({ updated_after: since, limit: "100", page: String(page) });
    const res = await fetch(`${API}/orders?${qs}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();
    for (const order of body.data) {
      await db.upsertOrder(order); // por id: si ya lo tienes, lo reemplaza
    }
    const last = body.data.at(-1)?.updated_at;
    if (last && last !== since) {
      since = last; // se sigue desde el último visto, otra vez en la página 1
      page = 1;
      await db.set("orders_since", since);
    } else {
      page++; // una página entera con la misma hora: se avanza por posición
    }
    if (!body.has_more) return;
  }
}

• Lo borrado. Un producto borrado deja de salir en GET /products; con include_deleted=true salen también los borrados, con la fecha en deleted_at, que es lo que necesitas para quitarlos de tu copia. Los clientes y las citas borrados desaparecen de la API: para enterarte, usa los webhooks customer.deleted y appointment.deleted.
• Los carritos no salen. Un pedido que el bot todavía está armando no aparece en GET /orders hasta que el cliente lo cierra; cuando lo hace, su updated_at cambia y entra en la siguiente vuelta.
• Webhooks y sincronización se complementan. Los webhooks te avisan al momento; una vuelta de updated_after cada cierto tiempo (cada hora, cada noche) recoge lo que se hubiera perdido si tu servidor estuvo caído.

Reintentar sin duplicar (Idempotency-Key)

Si mandas un POST y la respuesta no te llega (se cortó la red, saltó tu tiempo de espera), no sabes si el pedido se creó. Reintentar a ciegas puede dejarlo dos veces. Para evitarlo, manda una cabecera Idempotency-Key con un valor único por operación (un uuid sirve) y repite la misma en cada reintento:

curl -X POST https://api.atiendefacil.com/api/v1/orders \
  -H "Authorization: Bearer af_live_…" \
  -H "Idempotency-Key: 7f3c2b1a-9d4e-4c6f-8a1b-2c3d4e5f6a7b" \
  -H "Content-Type: application/json" \
  -d '{ … }'

• La primera vez la petición se ejecuta normal. Si llega otra con la misma clave y el mismo cuerpo, no se ejecuta: recibes la misma respuesta que la primera, con la cabecera Idempotent-Replayed: true.
• Vale en todo lo que escribe (POST, PUT, PATCH, DELETE); en los GET se ignora. Es opcional: sin la cabecera todo funciona como siempre.
• Solo se recuerdan las respuestas 2xx, durante 24 horas. Si la primera falló (un 4xx o un 5xx), no quedó nada hecho y el reintento con la misma clave se ejecuta de verdad.
• La clave es de una sola operación: usarla con otra ruta u otro cuerpo responde 422 idempotency_key_reused. Si la primera petición todavía se está ejecutando, la segunda responde 409 idempotency_in_progress.
• Hasta 200 caracteres, sin espacios ni acentos. Cada negocio tiene sus propias claves.

Úsala sobre todo donde repetir cuesta dinero o molesta a un cliente: crear pedidos, citas y viajes, registrar cobros y movimientos del banco, y enviar mensajes.

Errores

Los errores de la API responden con un código HTTP 4xx y siempre con esta forma. code es estable (programa contra él); message está en español y es para leerlo una persona, puede cambiar.

{
  "error": {
    "code": "invalid_transition",
    "message": "No se puede pasar el pedido de completed a preparing."
  }
}

Límites

Cada ruta lleva su propia cuenta: consultar GET /orders no gasta lo de GET /customers. Todas las respuestas traen cuánto te queda:

HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 37
retry-after: 37

{ "error": "Rate limit exceeded, retry in 37 seconds" }

Compatibilidad

• Esta es la versión 1 (/api/v1). Dentro de ella solo se añaden cosas: campos nuevos en los recursos, rutas nuevas, eventos nuevos. Quitar o renombrar un campo exigiría una /api/v2.
• Por eso tu código tiene que ignorar los campos que no conozca y no romperse si un estado trae un valor nuevo.
• Los recursos de la API y los que van dentro de los webhooks tienen exactamente la misma forma: aprendes un solo formato.

Buenas prácticas

• Webhooks en vez de preguntar a cada rato. Consultar la API cada pocos segundos gasta tu límite y llega tarde; un webhook te avisa al instante. Usa la API para la carga inicial y para leer el detalle.
• La clave, solo en tu servidor. Un navegador o una app de teléfono no deben hablar con la API directamente: que hablen con tu servidor, y tu servidor con AtiendeFácil.
• Reintenta con espera ante 429 y 5xx, respetando retry-after. Un 4xx distinto de 429 no se arregla reintentando: lee el code.
• Cuidado al reintentar lo que crea algo. La API no tiene claves de idempotencia. Si un POST /orders/{id}/payments, un POST /payments/collect o un POST /messages se corta sin respuesta, comprueba antes de repetir (GET /payments?order_id=…) o te arriesgas a registrar el cobro o mandar el mensaje dos veces. PUT, PATCH y POST /bank-movements (que descarta referencias repetidas) sí se pueden repetir sin miedo.
• Una clave por sistema. Si conectas la tienda online y la contabilidad, que cada una tenga la suya: en la auditoría se sabe quién hizo qué y puedes revocar una sin tumbar la otra.

// Reintenta ante 429 y 5xx, respetando retry-after y esperando cada vez más.
async function call(path, init = {}, tries = 5) {
  for (let i = 0; ; i++) {
    const res = await fetch(`${API}${path}`, {
      ...init,
      headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", ...init.headers },
    });
    const retriable = res.status === 429 || res.status >= 500;
    if (!retriable || i === tries - 1) return res;
    const wait = Number(res.headers.get("retry-after")) || 2 ** i; // segundos
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

Rutas generales

Lo mismo va dentro de los webhooks bot.*, whatsapp.* y account.balance_low, como objeto account (ver Webhooks).

{
  "object": "summary",
  "currency": "USD",
  "today": { "sales": "184.50", "orders": 12, "appointments": 0, "appointment_sales": "0.00", "conversations": 31 },
  "month": { "sales": "2310.00", "appointment_sales": "0.00", "messages_received": 1840, "messages_sent": 2105 },
  "pending": { "conversations": 2, "payments": 1, "to_collect": "45.00", "to_collect_orders": 3 },
  "orders": { "completed": 412, "cancelled": 37, "in_progress": 6 },
  "last_7_days": [ { "date": "2026-10-05", "sales": "150.00" }, … ],
  "top_products": [ { "name": "Pizza de pepperoni", "quantity": 96, "sales": "960.00" }, … ],
  "customers": 538,
  "catalog_items": 64
}

• Los importes van en currency, la moneda base del negocio. sales suma los pedidos confirmados en adelante (no los que esperan pago ni los cancelados); appointment_sales, el precio de las citas confirmadas o atendidas.
• «Hoy» y «el mes» se cortan con el reloj del servidor (UTC), igual que en el Dashboard: para un rango exacto en tu hora, filtra GET /orders con created_after y created_before.
• pending.conversations son los chats que esperan a una persona; pending.payments, los pedidos con el comprobante por revisar; to_collect, lo que falta cobrar en total, y en cuántos pedidos.
• orders y top_products (los 5 más vendidos) son de todo el historial, no del mes.

curl "https://api.atiendefacil.com/api/v1/team?role=delivery&active=true" \
  -H "Authorization: Bearer af_live_TU_CLAVE_AQUI"

{
  "data": [
    { "id": "d9e0f1a2-b3c4-4d5e-8f6a-7b8c9d0e1f2a", "object": "team_member", "name": "Carlos", "role": "delivery", "active": true },
    { "id": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e", "object": "team_member", "name": "Luis", "role": "delivery", "active": true }
  ]
}

WhatsApp: vincular el número y enviar avisos

Para el sistema que quiere un solo WhatsApp: vincula el número del negocio desde su propia pantalla y manda por él sus avisos (facturas, recordatorios), en vez de mantener otra sesión aparte.

• POST /whatsapp/send no es el chat: no abre conversación ni pasa por el asistente. Para responderle a un cliente que escribió usa POST /messages.
• Cada aviso pasa por los mismos topes y pausas que protegen al número del bloqueo. Si no sale, responde 409 not_sent (el número no tiene WhatsApp o se llegó al tope) o 409 whatsapp_not_connected (no hay número vinculado). Con el canal de Meta, si el saldo no cubre el mensaje (10.000 tokens cada uno), responde 402 meta_no_credit y no sale.
• Con el canal de Meta no hay código que escanear. Dentro de la ventana de 24 horas de ese número (desde su último mensaje al negocio) sale lo que mandes, como por QR.
• Cambio desde el 15/10/2026: con el canal de Meta, fuera de la ventana de 24 horas, un texto ya no se mete solo en la plantilla de avisos al cliente. Responde 409 outside_service_window («fuera de esa ventana solo salen plantillas aprobadas»), salvo que pidas una plantilla con template.key: customer_notice (cualquier aviso), order_status (estado de un pedido), payment_result (resultado de un pago), appointment_update (novedad de una cita) o ride_update (novedad de un viaje). Tu text va dentro, en una sola línea, con el nombre del negocio delante (los textos de cada una, en Plantillas de Meta). Úsalas solo para lo que dice su nombre: una promoción dentro de una plantilla de servicio hace que Meta la reclasifique o la pause para todo el negocio. Otra clave responde 400 invalid_template, y una que Meta aún no aprobó en el número, 409 template_not_approved. Por QR, o dentro de la ventana, template se ignora.
• Un documento fuera de la ventana con el canal de Meta responde 409 outside_service_window antes de intentarlo (antes salía not_sent). Cada mensaje que sale por Meta descuenta su tarifa del saldo del negocio, como cualquier otro.

Preguntas frecuentes