Visao geral

A API externa do LIP permite que sistemas de clientes integrem-se a plataforma para enviar mensagens e templates de WhatsApp, enviar emails e campanhas, consultar conversas e mensagens, disparar flows e receber eventos via webhooks. Todas as rotas externas ficam abaixo de /api/external.

Autenticacao

Crie uma API key, entenda escopos e como autenticar cada chamada.

Requisicoes assincronas

Como funcionam os envios (202 + requestId) e o header Idempotency-Key.

Envie mensagens de texto, midia e interativas pelo WhatsApp.

Conversas

Liste conversas e leia o historico de mensagens.

Email e campanhas

Envie emails transacionais e gerencie campanhas.

Flows

Liste e dispare flows de automacao.

Webhooks

Receba eventos de WhatsApp, email e campanhas em tempo real.

Uso e status

Acompanhe o status e o historico das requisicoes da API.

Base URL

Ambiente atual:

https://lip-backend-1064145932505.southamerica-east1.run.app

Versionamento

Existem dois prefixos equivalentes:

/api/external/v1/* — recomendado para novas integracoes
/api/external/* — alias legado, mantido para compatibilidade

Use sempre /v1

Os exemplos desta documentacao usam o alias legado por brevidade, mas ambos apontam para o mesmo recurso. Em integracoes novas, prefira /api/external/v1.

Estrutura das rotas

Dominio	Prefixo
WhatsApp	`/api/external/v1/whatsapp/*`
Conversas	`/api/external/v1/conversations/*`
Email	`/api/external/v1/email/*`
Flows	`/api/external/v1/flows/*`
Webhooks	`/api/external/v1/webhooks/*`
Uso / Status	`/api/external/v1/usage/*`

Entendendo os metodos (GET, POST, PUT, PATCH, DELETE)

Cada endpoint usa um metodo HTTP que indica a intencao da operacao. A regra rapida e: GET so busca (le) dados; os outros metodos alteram algo.

GET

Buscar

Le e retorna dados. Nao altera nada no sistema.

POST

Enviar

Envia dados para criar um recurso ou disparar uma acao.

PUT

Substituir

Substitui um recurso existente por completo.

PATCH

Atualizar

Altera apenas alguns campos de um recurso existente.

DELETE

Remover

Exclui um recurso.

Em toda esta documentacao, cada endpoint aparece com um selo do metodo e a acao correspondente, assim voce sabe de imediato se a chamada busca ou envia/altera dados:

GETBuscar/api/external/conversations

Busca a lista de conversas. So le, nao altera nada.

Escopo: conversations:readSincrono — responde 200 com os dados

POSTEnviar/api/external/whatsapp/messages

Envia uma mensagem de WhatsApp. Cria/dispara uma acao no sistema.

Escopo: whatsapp:sendAssincrono — responde 202 com requestId

Operacoes sincronas x assincronas

Alem do metodo, cada operacao pode ser sincrona ou assincrona:

Sincrona (200): a resposta ja traz o resultado. E o caso das buscas (GET) e da gestao de recursos (criar template, webhook etc.).
Assincrona (202): a API valida, enfileira o job e responde com um requestId. O resultado final chega por webhook e/ou e consultado em /usage/status/{requestId}. E o caso dos envios (mensagem, template, email, disparo de campanha/flow).

Acompanhe o resultado dos envios

Um 202 significa "aceito e enfileirado", nao "entregue". Use Uso e Status ou Webhooks para saber o resultado final. Veja Idempotencia e Requisicoes Assincronas para o fluxo completo.

Inicio rapido

Gere uma API key no painel: Company > API & Webhooks.
Envie uma mensagem de teste.
Acompanhe o status em /usage/status/{requestId} ou cadastre um webhook.

Exemplo de envio (texto):

Resposta esperada (202 Accepted):

Padrao de resposta

Toda resposta segue um envelope previsivel.

Sucesso:

Sucesso paginado:

Erro:

Formatos de paginacao

Nem todos os endpoints de listagem usam o mesmo envelope. Veja Paginacao para os dois formatos em uso e qual cada rota retorna.

Regras de telefone (WhatsApp)

A validacao atual e focada em numeros do Brasil.

Use DDI 55 e numero celular valido.
A entrada pode conter apenas digitos ou formatos com simbolos; o servidor normaliza.
Numeros invalidos retornam 400.

Exemplos validos: 5511999999999, +5511999999999, 11999999999.

Proximos passos

Autenticacao e API Keys

Escopos, formato da chave e boas praticas de seguranca.

Paginacao

Como paginar listagens e os formatos de resposta.

Erros e Boas Praticas

Codigos de status, formato de erro e recomendacoes.