LinkZap

Referência da API

Todas as rotas

Gerada do OpenAPI 3.1 desta instalação — que por sua vez sai das mesmas validações que as rotas usam. Para a explicação em prosa de cada uma, veja a documentação.

get/api/v1/me

Confere a chave

Diz de qual organização é a chave e se ela alcança a conta inteira (`scope: account`) ou um número só (`scope: channel`). É a primeira chamada a fazer com uma chave nova.

Respostas

  • 200

    Os dados da chave e da organização.

  • 401

  • 422

  • 429

  • 500

get/api/v1/channels

Lista os números conectados

Traz o `channelId` que quase toda escrita pede, em ordem alfabética pelo rótulo. **Não é paginada.** `ready: false` vem com `reason` — o MESMO motivo que um envio recusaria com 409, o que permite checar antes em vez de tentar e tratar o erro. Uma chave de canal vê só o próprio.

Respostas

  • 200

    Os canais da organização.

  • 401

  • 422

  • 429

  • 500

get/api/v1/contacts

Lista e busca contatos

Do mais recentemente atualizado para o mais antigo. **Uma chave de canal vê todos os contatos da conta** — contato pertence à organização, não ao canal.

Parâmetros

  • querystring

    Busca por nome, telefone ou e-mail.

  • phonestring

    Acha o contato exato. Aceita qualquer formatação; 422 se não for um telefone válido.

  • pageinteger

    A partir de 1.

  • limitinteger

    De 1 a 200.

Respostas

  • 200

    A página de contatos.

  • 401

  • 422

  • 429

  • 500

post/api/v1/contacts

Cria ou atualiza um contato

Idempotente pelo telefone: chamar duas vezes atualiza, não duplica. O campo `created` da resposta diz qual dos dois aconteceu — e é o mesmo corpo nos dois status.

Corpo (JSON)

  • phonestringobrigatório

    Telefone com DDI + DDD + número, só dígitos (ex.: 5592999990000). Aceita +, espaço, parêntese e traço, e normaliza.

  • namestring

    Nome do contato.

  • emailtexto

    E-mail válido, ou string vazia para limpar o que estava lá.

  • fieldsobject

    Campos próprios seus. Mesclam com os que já existem — mandar um campo não apaga os outros.

  • tagsarray

    Nomes de etiqueta. As que não existem são criadas, e aplicar uma etiqueta pode disparar um fluxo que a esteja esperando.

  • optInboolean

    true registra o opt-in (origem `api`); false registra o opt-out. Ausente não mexe no que já estava.

Respostas

  • 200

    O contato já existia e foi atualizado.

  • 201

    O contato foi criado.

  • 400

  • 401

  • 422

  • 429

  • 500

get/api/v1/conversations

Lista conversas

Da que teve mensagem mais recente para a mais antiga. Uma chave de canal vê só as do próprio canal.

Parâmetros

  • statusstring (open | in_flow | resolved)

    Filtra pelo estado de atendimento.

  • channelIdstring

    Filtra por número. Uma chave de canal que pedir outro recebe 403.

  • contactIdstring

    Todas as conversas de um contato.

  • pageinteger

    A partir de 1.

  • limitinteger

    De 1 a 200.

Respostas

  • 200

    A página de conversas.

  • 401

  • 403

  • 422

  • 429

  • 500

get/api/v1/messages

Lê o histórico de uma conversa

Da mais recente para a mais antiga. O envelope traz também o `conversationId` pedido.

Parâmetros

  • conversationIdstringobrigatório

    Obrigatório. Ache o id em `GET /api/v1/conversations`.

  • pageinteger

    A partir de 1.

  • limitinteger

    De 1 a 200.

  • includeNotesboolean

    Inclui as notas internas da equipe. Padrão `false`.

Respostas

  • 200

    As mensagens da conversa.

  • 401

  • 403

  • 404

  • 422

  • 429

  • 500

post/api/v1/messages

Envia uma mensagem

Manda texto ou mídia pelo número conectado. Se o telefone ainda não é contato, o contato e a conversa nascem aqui. **Não é idempotente**: cada chamada envia uma mensagem. Regras que o schema não expressa: - Informe `phone` ou `conversationId`. - Informe `text`, `mediaUrl` ou `mediaId`.

Corpo (JSON)

  • channelIdstring

    Por qual número falar. Obrigatório com a chave da conta; com uma chave de canal pode ser omitido, porque o escopo preenche.

  • phonestring

    Telefone com DDI + DDD + número, só dígitos (ex.: 5592999990000). Aceita +, espaço, parêntese e traço, e normaliza.

  • conversationIdstring

    Responder numa conversa que já existe. Precisa ser do mesmo canal.

  • textstring

    O texto da mensagem. Com mídia junto, vira a legenda se não houver `caption`.

  • mediaUrlstring

    Um arquivo numa URL pública, que nós baixamos e enviamos. O endereço precisa ser público de verdade: se ele aponta para rede interna (ou redireciona para lá), ou se redireciona mais de três vezes, a resposta é 422 e nada é enviado.

  • mediaIdstring

    Um arquivo do Drive do LinkZap — mais confiável que URL para o que você reenvia sempre.

  • captionstring

    Legenda da mídia.

Respostas

  • 201

    A mensagem foi aceita e enfileirada para envio.

  • 400

  • 401

  • 403

  • 404

  • 409

  • 422

  • 429

  • 500

get/api/v1/flows

Lista os fluxos

Em ordem alfabética pelo nome. **Não é paginada.** `channelId: null` significa que o fluxo atende qualquer número — por isso uma chave de canal enxerga os daquele número e os sem número.

Parâmetros

  • enabledboolean

    `true` traz só os ligados — os únicos que dá para iniciar.

Respostas

  • 200

    Os fluxos da organização.

  • 401

  • 422

  • 429

  • 500

post/api/v1/flows/{id}/start

Inicia um fluxo para um telefone

Coloca a conversa daquele telefone dentro do fluxo. Um fluxo já em andamento não é interrompido.

Parâmetros

  • idno caminho · stringobrigatório

    O id do fluxo (`GET /api/v1/flows`).

Corpo (JSON)

  • channelIdstring

    Por qual número. Obrigatório com a chave da conta; com uma chave de canal o escopo preenche.

  • phonestringobrigatório

    Telefone com DDI + DDD + número, só dígitos (ex.: 5592999990000). Aceita +, espaço, parêntese e traço, e normaliza.

Respostas

  • 201

    O fluxo começou (`result: started`).

  • 400

  • 401

  • 403

  • 404

  • 409

    A conversa não aceita automação agora (`result: skipped`) — mesmo corpo do 201, sem `error`.

  • 422

  • 429

  • 500

get/api/v1/pipelines

Lista os funis e as etapas

Traz o `stageId` que criar e mover negócio pedem. **Não é paginada.** As etapas vêm na ordem do quadro. O funil padrão nasce na primeira leitura, se a conta ainda não tem nenhum.

Respostas

  • 200

    Os funis da organização.

  • 401

  • 422

  • 429

  • 500

get/api/v1/deals

Lista negócios

Do mexido mais recentemente para o mais antigo. **Uma chave de canal vê todos os negócios da conta** — negócio pertence à organização, como o contato.

Parâmetros

  • statusstring (open | won | lost)

    Filtra pelo estado.

  • pipelineIdstring

    Os negócios de um funil.

  • stageIdstring

    Os negócios de uma etapa.

  • contactIdstring

    Os negócios de um contato.

  • pageinteger

    A partir de 1.

  • limitinteger

    De 1 a 200.

Respostas

  • 200

    A página de negócios.

  • 401

  • 422

  • 429

  • 500

post/api/v1/deals

Cria um negócio

Para um contato que já existe. **Não é idempotente**: cada chamada cria um negócio — se o seu sistema pode repetir a chamada, confira antes com `GET /deals?contactId=&status=open`. Dispara o webhook `deal.created`. Regras que o schema não expressa: - Informe `contactId` OU `phone` — um dos dois, nunca os dois.

Corpo (JSON)

  • contactIdstring

    O contato do negócio. Use este OU `phone`.

  • phonestring

    O telefone de um contato que JÁ existe (crie antes com `POST /contacts`). Use este OU `contactId`.

  • titlestringobrigatório

    O que está sendo negociado.

  • valueCentsinteger

    O valor em CENTAVOS de real: R$ 1.250,00 é `125000`. Ausente = sem valor.

  • stageIdstring

    A etapa de entrada (`GET /pipelines`). Ausente = a primeira etapa do funil padrão.

  • ownerIdstring

    O id de uma pessoa da equipe, como responsável pelo negócio.

  • expectedCloseOnstring

    A previsão de fechamento, um dia (`AAAA-MM-DD`).

  • conversationIdstring

    A conversa de onde o negócio nasceu. Só é guardada se for daquele contato.

Respostas

  • 201

    O negócio foi criado.

  • 400

  • 401

  • 404

  • 422

  • 429

  • 500

post/api/v1/deals/{id}

Muda um negócio: dados, etapa ou estado

Tudo ou nada: se um dos passos é recusado, nenhum é gravado. Mover dispara `deal.stage_changed`; fechar dispara `deal.won` ou `deal.lost`. Regras que o schema não expressa: - Envie ao menos um campo. - `status: lost` exige `lostReason`, e `lostReason` só vale com `status: lost`.

Parâmetros

  • idno caminho · stringobrigatório

    O id do negócio.

Corpo (JSON)

  • titlestring

    Novo título.

  • valueCentsinteger

    Novo valor, em centavos de real.

  • ownerIdtexto

    Novo responsável; `null` tira.

  • expectedCloseOnstringnull

    Nova previsão de fechamento; `null` tira.

  • stageIdstring

    Move o negócio para esta etapa (ele entra no topo dela). Só com o negócio em aberto.

  • statusstring

    `won` ou `lost` fecha o negócio; `open` reabre um fechado.

  • lostReasonstring

    Por que se perdeu. Obrigatório com `status: lost`, e só vale com ele.

Respostas

  • 200

    O negócio como ficou.

  • 400

  • 401

  • 404

  • 409

  • 422

  • 429

  • 500

get/api/v1/tasks

Lista tarefas

Da criada mais recentemente para a mais antiga. A chave de API vê as tarefas de toda a equipe.

Parâmetros

  • statusstring (open | done)

    `open` = em aberto; `done` = concluídas.

  • contactIdstring

    As tarefas de um contato.

  • dealIdstring

    As tarefas de um negócio.

  • assigneeIdstring

    As tarefas de uma pessoa da equipe.

  • pageinteger

    A partir de 1.

  • limitinteger

    De 1 a 200.

Respostas

  • 200

    A página de tarefas.

  • 401

  • 422

  • 429

  • 500

post/api/v1/tasks

Cria uma tarefa

Com ou sem contato. **Não é idempotente.** O prazo é um dia (e, se quiser, uma hora) no fuso da organização; quem recebe a tarefa é lembrado por e-mail. Dispara o webhook `task.created`. Regras que o schema não expressa: - `contactId` e `phone` não vão juntos. - `dueTime` só vale com `dueOn`.

Corpo (JSON)

  • titlestringobrigatório

    O que tem de ser feito.

  • notesstring

    Detalhes, para quem vai fazer.

  • contactIdstring

    O contato da tarefa. Opcional: tarefa pode não ser de ninguém.

  • phonestring

    Em vez de `contactId`: o telefone de um contato que já existe.

  • dealIdstring

    O negócio da tarefa. Com ele, o contato é o do negócio.

  • assigneeIdstring

    O id de quem vai fazer. É quem recebe o lembrete por e-mail.

  • dueOnstring

    O dia do prazo (`AAAA-MM-DD`), no fuso da organização.

  • dueTimestring

    A hora do prazo (`HH:MM`). Sem ela, a tarefa vale o dia inteiro.

Respostas

  • 201

    A tarefa foi criada.

  • 400

  • 401

  • 404

  • 422

  • 429

  • 500

post/api/v1/tasks/{id}

Conclui, reabre ou edita uma tarefa

Concluir a que já está concluída não muda nada e responde 200. Concluir dispara o webhook `task.completed`. Regras que o schema não expressa: - Envie ao menos um campo.

Parâmetros

  • idno caminho · stringobrigatório

    O id da tarefa.

Corpo (JSON)

  • doneboolean

    `true` conclui a tarefa; `false` reabre.

  • titlestring

    Novo título.

  • notestexto

    Novos detalhes; `null` apaga.

  • assigneeIdtexto

    Novo responsável; `null` tira.

  • dueOnstringnull

    Novo dia do prazo; `null` tira o prazo.

  • dueTimetexto

    Nova hora do prazo; `null` volta a valer o dia inteiro.

Respostas

  • 200

    A tarefa como ficou.

  • 400

  • 401

  • 404

  • 422

  • 429

  • 500

get/api/webhooks/channel/{id}

O contrato do webhook de entrada

Abrir a URL no navegador devolve o formato esperado, com o schema derivado da mesma validação que o POST usa. **Não exige autenticação** — é um dump do contrato, não dos dados.

Parâmetros

  • idno caminho · stringobrigatório

    O `channelId` do número.

Respostas

  • 200

    O contrato em JSON.

  • 401

  • 422

  • 429

  • 500

post/api/webhooks/channel/{id}

Webhook de entrada: contato, mensagem ou fluxo num POST

O atalho sem código: um formulário de site, Zapier, Make, n8n ou o gatilho do seu CRM viram contato e conversa. Prefira a **chave do canal** (Canais → Copiar chave de API); a chave da conta também vale, a de outro canal não. Regras que o schema não expressa: - Envie `message` OU `flowId`, nunca os dois.

Parâmetros

  • idno caminho · stringobrigatório

    O `channelId` do número.

Corpo (JSON)

  • phonestringobrigatório

    Telefone com DDI + DDD + número, só dígitos (ex.: 5592999990000). Aceita +, espaço, parêntese e traço, e normaliza.

  • namestring

    Nome do contato.

  • emailtexto

    E-mail válido.

  • messagestring

    Texto enviado ao contato pelo canal, como automação. Use este OU `flowId`.

  • flowIdstring

    Em vez de texto: inicia este fluxo na conversa do contato.

  • tagsarray

    Nomes de etiquetas; as que não existem são criadas.

  • fieldsobject

    Campos próprios seus.

  • optInboolean

    true registra opt-in com origem `webhook`; false registra opt-out.

Respostas

  • 200

    O contato já existia e foi atualizado, sem mensagem nem fluxo pedidos.

  • 201

    Criou o contato, ou enviou a mensagem, ou iniciou o fluxo.

  • 400

  • 401

  • 403

  • 404

  • 409

  • 422

  • 429

  • 500

  • 503

Consumir por máquina

OpenAPI 3.1curl
# baixar a especificação
curl https://linkzap.orion.moe/openapi.json -o linkzap.json

# gerar um cliente (exemplo com o openapi-generator)
npx @openapitools/openapi-generator-cli generate \
  -i linkzap.json -g typescript-fetch -o ./linkzap-client