API v1

API de Papo para integraciones

Conecta tu CRM, n8n, ERPs o tu backend. Cada cuenta tiene una clave pública fija y claves secretas que generas en el panel.

Generar claves en la app Descubrimiento de la API

Clave pública

Identifica la cuenta. Puede usarse en el frontend.

Clave secreta

Autentica las solicitudes. Solo en el servidor.

REST JSON

HTTPS, Bearer token, CORS habilitado.

Autenticación

Todas las rutas (excepto GET /api/v1) requieren la clave secreta. La pública es opcional, pero si la envías debe coincidir con la secreta.

Header	Valor
Authorization	Bearer sk_live_…
X-Papo-Secret-Key	Alternativa a Bearer
X-Papo-Public-Key	pk_live_… (opcional)

URL base: https://app.papo.global/api/v1

Clave pública y secreta

pk_live_… — fija por cuenta, visible en el panel y copiable en cualquier momento.
sk_live_… — se muestra una sola vez al crearla. Se guarda como hash SHA-256. Revócala si se filtra.
Crea claves con nombre por entorno (n8n, CRM, staging).

Endpoints

GET/api/v1/me

Cuenta

Devuelve la cuenta autenticada, la clave pública y el correo electrónico.

curl https://app.papo.global/api/v1/me \
  -H "Authorization: Bearer sk_live_…" \
  -H "X-Papo-Public-Key: pk_live_…"

GET/api/v1/instances

Instancias de WhatsApp

Lista las conexiones de WhatsApp de la cuenta (estado, número, perfil).

curl https://app.papo.global/api/v1/instances \
  -H "Authorization: Bearer sk_live_…"

GET/api/v1/instances/{id}

Instancia

Obtiene una instancia por su ID interno o por su nombre.

curl https://app.papo.global/api/v1/instances/user_100001_principal \
  -H "Authorization: Bearer sk_live_…"

GET/api/v1/assistants

Asistentes de IA

Lista el prompt principal y los subasistentes de la cuenta.

curl https://app.papo.global/api/v1/assistants \
  -H "Authorization: Bearer sk_live_…"

GET/api/v1/contacts

Contactos del Extractor

Lista los leads extraídos, con paginación.

page — Página (por defecto 1)
per_page — Ítems por página (1–100, por defecto 20)
q — Busca por empresa, teléfono o correo electrónico

curl "https://app.papo.global/api/v1/contacts?page=1&per_page=20" \
  -H "Authorization: Bearer sk_live_…"

POST/api/v1/messages

Enviar mensaje

Envía un mensaje de texto por el WhatsApp de la cuenta.

{
  "to": "5511999999999",
  "text": "Olá! Mensagem via API Papo.",
  "instance_id": "opcional — ID ou nome da instância"
}

curl -X POST https://app.papo.global/api/v1/messages \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","text":"Olá pela API Papo"}'

POST/api/ai/v1/complete

Completar con IA

Genera una respuesta de IA con el prompt de la cuenta (OpenRouter). Mismas claves.

{
  "text": "Quanto custa o plano Gold?",
  "use_client_prompt": true
}

curl -X POST https://app.papo.global/api/ai/v1/complete \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Quanto custa o plano Gold?","use_client_prompt":true}'

GET/api/v1/ai/logs

IA — logs

Lista las llamadas de IA de esta cuenta (tokens, modelo, multimedia, estado).

limit — Máximo de ítems (1–100)
contact_key — Filtrar por contacto

curl "https://app.papo.global/api/v1/ai/logs?limit=20" \
  -H "Authorization: Bearer sk_live_…"

Errores

Las respuestas de error siguen el formato de abajo. Las exitosas siempre incluyen success: true y data.

{
  "success": false,
  "error": { "code": "unauthorized", "message": "…" }
}

HTTP	code	Cuándo
401	unauthorized	Clave ausente, inválida o revocada
400	invalid_request	Payload incompleto
404	not_found	Recurso inexistente

Ejemplos

JavaScript

const res = await fetch("https://app.papo.global/api/v1/me", {
  headers: {
    Authorization: "Bearer " + process.env.PAPO_SECRET_KEY,
    "X-Papo-Public-Key": process.env.PAPO_PUBLIC_KEY,
  },
});
const json = await res.json();
console.log(json.data);

Python

import os, requests

r = requests.get(
    "https://app.papo.global/api/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['PAPO_SECRET_KEY']}",
        "X-Papo-Public-Key": os.environ["PAPO_PUBLIC_KEY"],
    },
)
print(r.json())

Instancias Asistentes Mensajes Contactos