import { CardGrid, LinkCard, TabItem, Tabs } from '@astrojs/starlight/components';
import Faq from '@components/Faq.astro';

La **API pública** (`/public/v1`) es una superficie REST curada de 5 recursos — leads, contactos,
conversaciones, citas y tickets — autenticada por clave de API, disponible en los planes **Pro** y
**Enterprise**.

<CardGrid>
  <LinkCard title="Empezar con la API" href="/api/getting-started/" description="Crea tu clave y haz tu primera llamada en menos de 10 minutos." />
  <LinkCard title="Autenticación" href="/api/authentication/" description="Cabecera X-API-Key, scopes por recurso y por acción." />
</CardGrid>

## Tu primera petición

`GET /me` no exige ningún permiso propio — solo una clave válida de un tenant con plan elegible — así que es
la forma más rápida de comprobar que tu clave funciona:

<Tabs>
  <TabItem label="curl">
    ```bash
    curl https://api.aymaragents.com/public/v1/me \
      -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
    ```
  </TabItem>
  <TabItem label="Python">
    ```python
    import requests

    res = requests.get(
        "https://api.aymaragents.com/public/v1/me",
        headers={"X-API-Key": "aa_TU_CLAVE_COMPLETA"},
    )
    res.raise_for_status()
    print(res.json())
    ```
  </TabItem>
  <TabItem label="JavaScript">
    ```javascript
    const res = await fetch("https://api.aymaragents.com/public/v1/me", {
      headers: { "X-API-Key": "aa_TU_CLAVE_COMPLETA" },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    console.log(await res.json());
    ```
  </TabItem>
</Tabs>

## Guías

<CardGrid>
  <LinkCard title="Planes y límites" href="/api/plans-and-limits/" description="Qué plan necesitas y cuántas peticiones puedes hacer." />
  <LinkCard title="Errores" href="/api/errors/" description="Formato de error y códigos que puede devolver la API." />
  <LinkCard title="Versionado" href="/api/versioning/" description="Cómo evoluciona /public/v1 sin romper tu integración." />
  <LinkCard title="Casos de uso de la API" href="/api/use-cases/" description="Escenarios reales de integración." />
</CardGrid>

## Referencia generada

<LinkCard title="Endpoints" href="/api/reference/" description="Cada operación de /public/v1, generada de la misma definición OpenAPI que usa el servidor MCP." />

## Herramientas relacionadas

<CardGrid>
  <LinkCard title="Servidor MCP" href="/mcp/" description="Conecta tu asistente de IA a la misma API." />
  <LinkCard title="llms.txt" href="/llms.txt" description="Índice de todo el portal en texto plano." />
</CardGrid>

## Preguntas frecuentes

<Faq items={[
  { question: '¿Qué plan necesito para usar la API pública?', answer: 'Pro o Enterprise. Con el plan Starter, cualquier llamada a <code>/public/v1/*</code> responde <code>403 PLAN_NOT_ELIGIBLE</code>, aunque la clave exista y tenga el scope correcto. Ver <a href="/api/plans-and-limits/">Planes y límites</a>.' },
  { question: '¿Qué pasa si mi clave no tiene el scope exacto que pide un endpoint?', answer: 'Recibes <code>403 PERMISSION_DENIED</code>, aunque tenga el resto de sus permisos. Cada recurso tiene dos scopes independientes — lectura y gestión. Ver <a href="/api/authentication/">Autenticación</a>.' },
  { question: '¿Cómo roto una clave sin cortar mi integración?', answer: 'Hoy no hay un endpoint de rotación atómica: crea una clave nueva con los mismos scopes, actualiza el secreto en tu integración y luego revoca la antigua — hay una ventana breve con ambas activas.' },
  { question: '¿Qué devuelve la API si pido un recurso de otro tenant?', answer: '<code>404</code>, exactamente igual que si el recurso no existiera — nunca <code>403</code>, que confirmaría que el dato existe en otra cuenta.' },
  { question: '¿Cuántas peticiones puedo hacer por minuto?', answer: '180/minuto y 50.000/día en Pro; 600/minuto y 200.000/día en Enterprise. El cupo se contabiliza por clave, no por IP. Ver <a href="/api/plans-and-limits/">Planes y límites</a>.' },
  { question: '¿Puedo borrar un lead, un contacto o cualquier otro recurso por la API?', answer: 'No — <code>/public/v1</code> no tiene ningún endpoint <code>DELETE</code>. Ver <a href="/api/use-cases/">Casos de uso de la API</a>.' },
  { question: '¿Qué pasa si envío un mensaje de WhatsApp fuera de la ventana de 24 horas?', answer: 'Recibes <code>409 WHATSAPP_SESSION_WINDOW_CLOSED</code> — usa <code>POST /conversations/start</code> con una plantilla aprobada en su lugar. Ver <a href="/api/errors/">Errores</a>.' },
]} />

## Siguiente

<LinkCard title="Servidor MCP" href="/mcp/" description="Conecta Claude, Cursor u otro asistente de IA a tu cuenta." />