Documentacao oficial da Z-API, construida com Mintlify.
- Node.js: v20+ (testado com v20.20.2)
- npm: v10+ (testado com v10.8.2)
- Mintlify CLI: v4.2+ (testado com v4.2.463)
# Instalar o Mintlify CLI globalmente
npm i -g mintlify# Na raiz do projeto (onde esta o docs.json)
mintlify devAcesse http://localhost:3000 no navegador.
Se o preview nao estiver funcionando, rode
mintlify updatepara atualizar a CLI.
O deploy e automatico. Ao fazer push na branch main, o GitHub App do Mintlify detecta as mudancas e publica automaticamente. O app esta configurado no dashboard do Mintlify.
z-api-docs-oficial/
├── docs.json # Configuracao principal (tema, cores, navegacao, API)
├── gptmaker.js # Widget de chatbot GPT Maker (balao flutuante)
├── favicon.png # Favicon do site
├── images/ # Imagens usadas nas paginas
├── snippets/ # Componentes reutilizaveis (MDX)
│ ├── pt/ # Snippets em portugues
│ │ ├── params/ # ParamFields (instance-id, token, phone)
│ │ └── response/ # ResponseFields (message-response)
│ └── en/ # Snippets em ingles (mesma estrutura)
├── en/ # Paginas em ingles (espelha a estrutura PT)
│ ├── instance/
│ ├── message/
│ ├── ...
├── instance/ # Endpoints de instancia (PT)
├── message/ # Endpoints de mensagens (PT)
├── mobile/ # Endpoints mobile (PT)
├── contacts/ # Endpoints de contatos (PT)
├── chats/ # Endpoints de chats (PT)
├── calls/ # Endpoints de chamadas (PT)
├── group/ # Endpoints de grupos (PT)
├── communities/ # Endpoints de comunidades (PT)
├── newsletter/ # Endpoints de newsletter (PT)
├── status/ # Endpoints de status (PT)
├── queue/ # Endpoints de fila de mensagens (PT)
├── business/ # Endpoints WhatsApp Business (PT)
├── webhooks/ # Endpoints de webhooks (PT)
├── partner/ # Endpoints de parceiros (PT)
├── integrators/ # Endpoints de integradores (PT)
├── metaai/ # Endpoints Meta AI (PT)
├── broadcast/ # Lista de transmissao (PT)
├── privacy/ # Endpoints de privacidade (PT)
├── quickstart/ # Pagina inicial / quickstart
├── security/ # Paginas de seguranca
├── tips/ # Dicas e boas praticas
├── api-reference/ # Introducao da API Reference
└── blog/ # Blog
O projeto e bilíngue (portugues e ingles):
- Portugues (pt-BR): idioma padrao, arquivos na raiz (ex:
message/send-text.mdx) - Ingles (en): arquivos dentro de
en/(ex:en/message/send-text.mdx)
Regra importante: toda nova pagina deve ser criada em ambos os idiomas.
"api": { "mdx": { "server": "https://api.z-api.io", "auth": { "method": "key", "name": "Client-Token" } } }
O server base e https://api.z-api.io. Os path parameters instanceId e token ficam no frontmatter de cada pagina:
api: "POST /instances/{instanceId}/token/{token}/send-text"
Isso e necessario para que o playground ("Experimentar") do Mintlify substitua corretamente as variaveis na URL. Se colocar no server base, o Mintlify nao substitui.
O Client-Token esta configurado globalmente no docs.json. Nao adicione <ParamField header="Client-Token"> nas paginas — isso causa duplicacao no playground.
- Crie o arquivo
.mdxna pasta da secao (ex:message/novo-endpoint.mdx) - Crie a versao em ingles em
en/(ex:en/message/novo-endpoint.mdx) - Use o path completo no frontmatter:
--- title: "Titulo da pagina" api: "POST /instances/{instanceId}/token/{token}/novo-endpoint" description: "Descricao do endpoint" ---
- Importe os snippets de
instanceIdetoken:
import InstanceId from '/snippets/pt/params/instance-id.mdx' import Token from '/snippets/pt/params/token.mdx'
- Use os componentes na secao de atributos:
## Atributos ### Obrigatorios <InstanceId /> <Token />
- Adicione a pagina no
docs.jsonna navegacao (tanto PT quanto EN)
Os endpoints de partner e integrators usam paths diferentes e nao levam o prefixo /instances/{instanceId}/token/{token}/. Exemplo:
api: "POST /instances/integrator/on-demand" api: "GET /instances"
Os snippets ficam em snippets/{idioma}/:
| Snippet | Caminho | Uso |
|---|---|---|
| Instance ID | snippets/pt/params/instance-id.mdx |
<InstanceId /> |
| Token | snippets/pt/params/token.mdx |
<Token /> |
| Phone | snippets/pt/params/phone.mdx |
<Phone /> |
| Message Response | snippets/pt/response/message-response.mdx |
<MessageResponse /> |
Para ingles, troque pt por en no import.
O chatbot da GPT Maker esta integrado via gptmaker.js na raiz do projeto. O Mintlify carrega automaticamente qualquer arquivo .js do diretorio.
Para trocar o widget, edite o ID no arquivo gptmaker.js:
script.src = 'https://app.gptmaker.ai/widget/{SEU_ID}/float.js';
Definidas no docs.json:
| Cor | Hex | Uso |
|---|---|---|
| Primary | #00B140 |
Cor principal (botoes, links) |
| Light | #00D455 |
Variante clara |
| Dark | #007A2C |
Variante escura |
| Background dark | #14161f |
Fundo do dark mode |