> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cardapioweb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeiros passos

> Guia rápido para navegar a documentação e começar a integrar com a API aberta da Cardápio Web.

Use esta página como mapa da documentação. Ela indica por onde começar e onde encontrar cada detalhe. Os tutoriais completos ficam nas páginas específicas de cada tema.

## Escolha sua trilha

<Tabs>
  <Tab title="Novo app (CW App Store)">
    Para integrações que serão publicadas no marketplace e instaladas pelos estabelecimentos:

    <Steps>
      <Step title="Entenda o ecossistema">
        Leia a [visão geral da CW App Store](/cw-app-store/visao-geral) para conhecer os papéis de integradora, app, estabelecimento e instalação.
      </Step>

      <Step title="Cadastre o app">
        Prepare os dados e envie o cadastro conforme [Cadastro e publicação](/cw-app-store/cadastro-e-publicacao). Comece pelo **Sandbox** para validar tudo antes de Produção.
      </Step>

      <Step title="Entenda a instalação">
        Leia [Instalação e autorização](/cw-app-store/instalacao-e-autorizacao) para entender o fluxo do estabelecimento (Instalar, onboarding, consentimento) e o que a integradora precisa implementar em cada etapa.
      </Step>

      <Step title="Implemente OAuth">
        Implemente PKCE, redirect ao portal e troca de token conforme [OAuth](/autenticacao/oauth).
      </Step>

      <Step title="Consuma a API">
        Com um token válido, siga os [Fluxos de integração](/fluxo-integracao) e consulte a [Referência da API](/api-reference/loja/loja/consultar-loja).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Integração legada (API Key)">
    Para integrações existentes que ainda usam `X-API-KEY` e não passam pela CW App Store:

    1. Leia [Modelos de autenticação](/autenticacao/modelos-de-autenticacao) e [API Key legado](/autenticacao/api-key-legado).
    2. Consulte [Sobre a API](/sobre-a-api) para ambientes, formatos e limites.
    3. Siga os [Fluxos de integração](/fluxo-integracao) para Loja, Catálogo e Pedidos.

    <Warning>
      Novos apps devem usar OAuth. A API Key é um modelo legado mantido apenas para integrações já existentes.
    </Warning>
  </Tab>
</Tabs>

## A integração em resumo

```mermaid theme={null}
flowchart LR
  A[Cadastro do app] --> B[Aprovação]
  B --> C[Instalação]
  C --> D[OAuth]
  D --> E[API aberta]
```

A integradora cadastra o app, a Cardápio Web aprova, o estabelecimento instala e autoriza os escopos, e o app passa a consumir a API com tokens OAuth. Cada token representa uma instalação específica: um app autorizado por um estabelecimento.

## Como navegar a documentação

A documentação está organizada em duas abas:

| Aba                   | Conteúdo                                                                       |
| --------------------- | ------------------------------------------------------------------------------ |
| **Documentação**      | Guias conceituais: CW App Store, autenticação, webhooks e fluxos de integração |
| **Referência da API** | Endpoints, schemas e playground interativo para testar requisições             |

Dentro da aba **Documentação**, as seções mais usadas no início são:

<CardGroup cols={2}>
  <Card title="CW App Store" icon="store" href="/cw-app-store/visao-geral">
    Marketplace, cadastro, publicação e instalação de apps.
  </Card>

  <Card title="Sobre a API" icon="book-open" href="/sobre-a-api">
    Ambientes, formatos, códigos HTTP e rate limits.
  </Card>

  <Card title="OAuth" icon="key-round" href="/autenticacao/oauth">
    Autorização, tokens, escopos, renovação e erros comuns.
  </Card>

  <Card title="Fluxos de integração" icon="route" href="/fluxo-integracao">
    Módulos Loja, Catálogo e Pedidos: polling, webhooks e status.
  </Card>

  <Card title="Desenvolva com IA" icon="sparkles" href="/desenvolva-com-ia">
    Menu de ações, servidor MCP e exemplos de prompts para integração.
  </Card>
</CardGroup>

## Módulos da API

Depois da autenticação, use os módulos conforme a necessidade da integração:

| Módulo   | Escopo OAuth | Guia                                                                      |
| -------- | ------------ | ------------------------------------------------------------------------- |
| Loja     | `store`      | [Consultar loja](/api-reference/loja/loja/consultar-loja)                 |
| Catálogo | `catalog`    | [Consultar catálogo](/api-reference/catalogo/consultar-catalogo-completo) |
| Pedidos  | `orders`     | [Polling de pedidos](/api-reference/pedidos/polling-de-pedidos)           |

Para entender quando usar cada módulo e como combiná-los, consulte [Fluxos de integração](/fluxo-integracao). Para receber eventos em tempo real (como novos pedidos), configure [Webhooks](/webhooks/visao-geral).

<Tip>
  Use o **playground interativo** na aba Referência da API para explorar endpoints e testar requisições sem escrever código.
</Tip>

## Ambientes

| Ambiente | Base URL                                     |
| -------- | -------------------------------------------- |
| Sandbox  | `https://integracao.sandbox.cardapioweb.com` |
| Produção | `https://integracao.cardapioweb.com`         |

Sandbox e Produção são independentes: apps, credenciais, instalações e tokens não são compartilhados. Use o Sandbox para validar o fluxo completo antes de solicitar publicação em Produção.

Detalhes em [Sobre a API](/sobre-a-api#ambiente-de-testes-e-de-producao).

## Precisa de ajuda?

Para cadastro de apps, aprovação, autenticação ou dúvidas técnicas, entre em contato pelo e-mail `integracao@cardapioweb.com`.