# LinkZap — API e webhooks

> API REST para enviar e ler mensagens de WhatsApp pelos números conectados a uma organização do LinkZap, gerir contatos e conversas, iniciar fluxos e receber cada evento assinado por webhook. Autenticação por chave em cabeçalho; sem OAuth e sem SDK obrigatório.

A URL base é `https://linkzap.orion.moe/api/v1`. A chave (`lz_…`) vai em `Authorization: Bearer` ou em `x-api-key`. O que volta fica dentro de `data`. O freio é de 120 chamadas por minuto por chave e 600 por organização; o 429 traz `retry-after` em segundos. Não há CORS: chame do seu servidor.

## Contrato

- [OpenAPI 3.1](https://linkzap.orion.moe/openapi.json): a especificação completa — rotas, campos de entrada e de saída, erros e os eventos de webhook.
- [Referência navegável](https://linkzap.orion.moe/developers/api-reference): as mesmas rotas em HTML, para conferir com um humano ao lado.

## Primeiros passos

Do zero à primeira mensagem enviada por API.

- [Começar](https://linkzap.orion.moe/developers/start.md): O que dá para automatizar, e o caminho de três minutos até a primeira mensagem enviada pela API.
- [Autenticação](https://linkzap.orion.moe/developers/authentication.md): A chave lz_…, os dois escopos (a conta inteira ou um canal), como rotacionar e o que fazer se ela vazar.
- [Convenções e erros](https://linkzap.orion.moe/developers/conventions.md): URL base, paginação, datas, telefone, o formato dos erros e o limite de chamadas por minuto.

## Referência da API

Cada rota, com os campos que entram e os que saem.

- [Canais](https://linkzap.orion.moe/developers/channels.md): Os números conectados e o channelId que quase toda escrita pede. Comece por aqui.
- [Contatos](https://linkzap.orion.moe/developers/contacts.md): Listar, criar e atualizar pelo telefone, com etiquetas, campos próprios e opt-in.
- [Conversas](https://linkzap.orion.moe/developers/conversations.md): As conversas da caixa, com contato, canal, responsável e o estado de atendimento.
- [Mensagens](https://linkzap.orion.moe/developers/messages.md): Enviar texto e mídia pelo número conectado, e ler o histórico de uma conversa.
- [Fluxos](https://linkzap.orion.moe/developers/flows.md): Listar os fluxos e iniciar um deles para um telefone, de fora do LinkZap.
- [Negócios](https://linkzap.orion.moe/developers/deals.md): O funil do CRM: listar os funis e as etapas, criar negócio, mover de etapa, ganhar e perder.
- [Tarefas](https://linkzap.orion.moe/developers/tasks.md): As tarefas da equipe: listar, criar com prazo e responsável, concluir e reabrir.

## Webhooks

Os dois sentidos: o que você nos manda e o que nós te mandamos.

- [Webhook de entrada](https://linkzap.orion.moe/developers/inbound-webhook.md): Uma URL por canal: o formulário do seu site, o CRM ou o Zapier viram contato e conversa.
- [Webhooks de saída](https://linkzap.orion.moe/developers/webhooks.md): Receber no seu sistema tudo o que acontece aqui, assinado com HMAC. Com a verificação em Node, PHP e Python.

## Exemplos

Integrações inteiras, prontas para copiar.

- [Receitas](https://linkzap.orion.moe/developers/recipes.md): Quatro integrações inteiras: lead do site, disparo pelo CRM, espelho da caixa e chatbot próprio.

## Conectar números

Guias para ligar o WhatsApp ao LinkZap.

- [API oficial com o seu app](https://linkzap.orion.moe/developers/whatsapp-own-app.md): Conectar um número oficial do WhatsApp usando um app seu na Meta: as cinco chaves e onde achar cada uma.

## Optional

Pode ser pulado quando o contexto é curto — é conteúdo que já está acima, noutra forma.

- [Documentação inteira em markdown](https://linkzap.orion.moe/llms-full.txt): todas as páginas acima concatenadas, num arquivo só.
- [Índice em HTML](https://linkzap.orion.moe/developers): a porta de entrada para humanos.