# Fluxo Jurídico — API REST

> CRM de atendimento por WhatsApp para escritórios de advocacia, com robôs de qualificação,
> funil de vendas, agenda integrada ao Google e assinatura eletrônica de contrato.
> Esta API expõe o núcleo do produto para integração com sites, CRMs e ferramentas de automação.

URL base: https://api.fluxojuridico.com.br/functions/v1/public-api
Documentação: https://fluxojuridico.com.br/api-docs
Especificação OpenAPI 3.1: https://api.fluxojuridico.com.br/functions/v1/public-api/openapi.json

## Autenticação

Cabeçalho `Authorization: Bearer fj_live_…`. A chave é por WORKSPACE (não por usuário), tem
permissões escolhidas na criação, pode ser revogada a qualquer momento e aparece em texto uma
única vez. O workspace é sempre deduzido da chave — nenhum endpoint aceita workspace no corpo.

## Convenções

- Listagens: `limit` (padrão 25, máximo 100) e `offset`; a resposta traz `pagination`.
- Datas em ISO-8601 UTC.
- Erros: `{ "error": { "code", "message", "request_id" } }` — trate pelo `code`.
- Limite de chamadas por chave, informado nos cabeçalhos `X-RateLimit-*`.
- POST de efeito colateral aceita `Idempotency-Key`.

## Regra do WhatsApp que muda a integração

Mensagem livre só pode ser enviada até 24 horas depois da última mensagem do contato. Fora dessa
janela o WhatsApp exige um template aprovado pela Meta — a API responde `WINDOW_CLOSED` e nada é
cobrado. Consulte os templates aprovados em `GET /templates`.

## Endpoints

### Conta

Conferir a chave, o consumo e a lista de erros possíveis. Comece por aqui.

- `GET /errors` — Listar todos os códigos de erro da API
- `GET /me` — Conferir a chave e o workspace
- `GET /usage` — Consultar o consumo da chave

### Contatos

O cadastro de pessoas: criar a partir do site, atualizar, marcar, mesclar duplicados e atender pedido de exclusão de dados.

- `GET /contacts` — Listar contatos (permissão: contacts:read)
- `GET /contacts/{id}` — Obter um contato (permissão: contacts:read)
- `GET /contacts/{id}/conversations` — Listar conversas de um contato (permissão: conversations:read)
- `GET /contacts/{id}/custom-fields` — Ler os campos personalizados de um contato (permissão: contacts:read)
- `GET /contacts/{id}/media` — Listar arquivos trocados com o contato (permissão: conversations:read)
- `GET /contacts/{id}/notes` — Listar notas do contato (permissão: contacts:read)
- `GET /contacts/{id}/tickets` — Histórico de atendimentos do contato (permissão: tickets:read)
- `GET /contacts/lookup` — Buscar contato por telefone (permissão: contacts:read)
- `GET /custom-fields` — Listar campos personalizados do workspace (permissão: contacts:read)
- `POST /contacts` — Criar contato (ou atualizar o existente pelo telefone) (permissão: contacts:write)
- `POST /contacts/{id}/block` — Bloquear contato (permissão: contacts:write)
- `POST /contacts/{id}/notes` — Adicionar nota ao contato (permissão: contacts:write)
- `POST /contacts/{id}/tags` — Marcar contato com etiquetas (permissão: tags:write)
- `POST /contacts/{id}/unblock` — Desbloquear contato (permissão: contacts:write)
- `POST /contacts/merge` — Mesclar dois contatos (permissão: contacts:write)
- `PUT /contacts/{id}/custom-fields` — Gravar campos personalizados de um contato (permissão: contacts:write)
- `PATCH /contacts/{id}` — Atualizar contato (permissão: contacts:write)
- `DELETE /contacts/{id}` — Excluir ou anonimizar um contato (LGPD) (permissão: contacts:delete)
- `DELETE /contacts/{id}/tags/{tag}` — Remover uma etiqueta do contato (permissão: tags:write)

### Etiquetas

As marcações usadas para segmentar contatos.

- `GET /labels` — Listar etiquetas cadastradas (permissão: tags:read)
- `GET /tags` — Listar as etiquetas em uso (permissão: tags:read)
- `POST /labels` — Criar etiqueta (permissão: tags:write)
- `PATCH /labels/{id}` — Editar etiqueta (permissão: tags:write)
- `DELETE /labels/{id}` — Excluir etiqueta (permissão: tags:write)

### Conversas

A linha do tempo com cada contato e o histórico de mensagens.

- `GET /conversations` — Listar conversas (permissão: conversations:read)
- `GET /conversations/{id}` — Obter uma conversa (permissão: conversations:read)
- `GET /conversations/{id}/messages` — Listar mensagens de uma conversa (permissão: conversations:read)
- `POST /conversations/{id}/notes` — Registrar nota interna na conversa (permissão: conversations:write)

### Mensagens

Enviar WhatsApp e consultar o que já foi trocado.

- `GET /messages/{id}` — Obter uma mensagem (permissão: messages:read)
- `GET /messages/search` — Buscar no texto das mensagens (permissão: messages:read)
- `POST /messages` — Enviar mensagem de WhatsApp (permissão: messages:send)

### Atendimentos

O ciclo de trabalho: encerrar, transferir, priorizar, adiar e mover no funil.

- `GET /tickets` — Listar atendimentos (permissão: tickets:read)
- `GET /tickets/{id}` — Obter um atendimento (permissão: tickets:read)
- `GET /tickets/{id}/stage-history` — Histórico de etapas do atendimento (permissão: tickets:read)
- `POST /tickets/{id}/close` — Encerrar atendimento (permissão: tickets:write)
- `POST /tickets/{id}/priority` — Mudar a prioridade do atendimento (permissão: tickets:write)
- `POST /tickets/{id}/snooze` — Adiar o atendimento (permissão: tickets:write)
- `POST /tickets/{id}/stage` — Mover o atendimento de etapa no funil (permissão: tickets:write)
- `POST /tickets/{id}/transfer` — Transferir atendimento (permissão: tickets:write)
- `POST /tickets/{id}/unsnooze` — Trazer de volta um atendimento adiado (permissão: tickets:write)

### Funis

Os quadros e etapas por onde os atendimentos caminham.

- `GET /boards` — Listar quadros do funil (permissão: pipelines:read)
- `GET /boards/{id}/stages` — Listar as etapas de um quadro (permissão: pipelines:read)
- `GET /stages` — Listar todas as etapas do workspace (permissão: pipelines:read)
- `POST /boards` — Criar quadro do funil (permissão: pipelines:write)
- `POST /stages` — Criar etapa no funil (permissão: pipelines:write)
- `PATCH /boards/{id}` — Editar quadro do funil (permissão: pipelines:write)
- `PATCH /stages/{id}` — Editar etapa do funil (permissão: pipelines:write)
- `DELETE /boards/{id}` — Excluir quadro do funil (permissão: pipelines:write)
- `DELETE /stages/{id}` — Excluir etapa do funil (permissão: pipelines:write)

### Filas

Os grupos de atendimento e a situação de cada um agora.

- `GET /queues` — Listar filas de atendimento (permissão: queues:read)
- `GET /queues/stats` — Situação das filas agora (permissão: queues:read)

### Canais

Os números e contas conectados. Nunca devolve credencial.

- `GET /channels` — Listar canais conectados (permissão: channels:read)

### Templates

Os modelos aprovados pela Meta — o que permite falar fora da janela de 24 horas.

- `GET /templates` — Listar templates de WhatsApp (permissão: templates:read)
- `GET /templates/{id}` — Obter um template (permissão: templates:read)

### Campanhas

Acompanhar os disparos em massa e os números de entrega. Somente leitura.

- `GET /broadcasts` — Listar campanhas (permissão: broadcasts:read)
- `GET /broadcasts/{id}` — Obter uma campanha (permissão: broadcasts:read)

### Agenda

Consultar horários livres e marcar reuniões, com o evento criado na Google Agenda.

- `GET /appointments` — Listar agendamentos (permissão: agenda:read)
- `GET /appointments/{id}` — Obter um agendamento (permissão: agenda:read)
- `GET /schedules` — Listar agendas (permissão: agenda:read)
- `GET /schedules/{id}` — Obter uma agenda (permissão: agenda:read)
- `GET /schedules/{id}/availability` — Consultar horários livres (permissão: agenda:read)
- `POST /appointments` — Marcar um agendamento (permissão: agenda:write)
- `DELETE /appointments/{id}` — Cancelar um agendamento (permissão: agenda:write)

### Robôs

Os robôs de atendimento e o controle de ligar/desligar por conversa.

- `GET /bots` — Listar robôs (permissão: bots:read)
- `POST /conversations/{id}/bot/activate` — Ligar o robô numa conversa (permissão: bots:write)
- `POST /conversations/{id}/bot/deactivate` — Desligar o robô numa conversa (permissão: bots:write)

### Documentos

Contratos enviados para assinatura eletrônica e a situação de cada um.

- `GET /documents` — Listar documentos de assinatura (permissão: documents:read)
- `GET /documents/{id}` — Obter um documento de assinatura (permissão: documents:read)

### Ligações

O registro de ligações, com duração e transcrição.

- `GET /calls` — Listar ligações (permissão: calls:read)

### Base de conhecimento

O material que o robô consulta para responder — sincronizável com o site do escritório.

- `GET /kb/articles` — Listar artigos da base de conhecimento (permissão: kb:read)
- `GET /kb/articles/{id}` — Obter um artigo (permissão: kb:read)
- `GET /kb/categories` — Listar categorias da base de conhecimento (permissão: kb:read)
- `POST /kb/articles` — Criar artigo (permissão: kb:write)
- `POST /kb/categories` — Criar categoria (permissão: kb:write)
- `PATCH /kb/articles/{id}` — Editar artigo (permissão: kb:write)
- `DELETE /kb/articles/{id}` — Excluir artigo (permissão: kb:write)

### Biblioteca

Respostas rápidas e macros usadas pela equipe.

- `GET /macros` — Listar macros (permissão: library:read)
- `GET /quick-replies` — Listar respostas rápidas (permissão: library:read)

### Webhooks

O caminho inverso: nós avisamos o seu sistema quando algo acontece aqui.

- `GET /webhooks` — Listar avisos automáticos configurados (permissão: webhooks:read)
- `GET /webhooks/{id}/deliveries` — Ver o histórico de entregas de um webhook (permissão: webhooks:read)
- `GET /webhooks/events` — Listar os eventos que podem ser assinados
- `POST /webhooks` — Criar aviso automático (permissão: webhooks:write)
- `PATCH /webhooks/{id}` — Editar aviso automático (permissão: webhooks:write)
- `DELETE /webhooks/{id}` — Remover aviso automático (permissão: webhooks:write)

### Relatórios

Os mesmos números da tela de Relatórios, para alimentar o seu painel.

- `GET /reports/by-label` — Relatório por etiqueta (permissão: reports:read)
- `GET /reports/first-contact` — Relatório de primeiro contato (permissão: reports:read)
- `GET /reports/queue-status` — Relatório de situação por fila (permissão: reports:read)
- `GET /reports/time-in-stage` — Relatório de tempo em cada etapa do funil (permissão: reports:read)

### Equipe

Quem faz parte do workspace, para atribuir atendimento e reunião.

- `GET /users` — Listar membros do workspace (permissão: users:read)

### Auditoria

Tudo o que foi feito no workspace, inclusive pela própria API.

- `GET /audit-logs` — Consultar o registro de auditoria (permissão: audit:read)

## Erros

- `MISSING_KEY` (HTTP 401) — Chave de API ausente. Envie o cabeçalho Authorization: Bearer fj_live_… Inclua o cabeçalho Authorization com a chave gerada em Configurações › Empresa › Chaves de API.
- `INVALID_KEY` (HTTP 401) — Chave de API inválida. Confira se copiou a chave inteira. A chave só aparece uma vez, na criação; se perdeu, gere outra.
- `KEY_REVOKED` (HTTP 401) — Esta chave de API foi revogada. Gere uma chave nova em Configurações › Empresa › Chaves de API e atualize a integração.
- `KEY_EXPIRED` (HTTP 401) — Esta chave de API expirou. Gere uma chave nova, ou crie sem data de validade se a integração for permanente.
- `WORKSPACE_INACTIVE` (HTTP 403) — O workspace está suspenso ou com a assinatura vencida. Regularize a assinatura. Enquanto isso a API fica bloqueada, mas nenhum dado é perdido.
- `FORBIDDEN_SCOPE` (HTTP 403) — Esta chave não tem permissão para esta operação. Edite a chave em Configurações › Empresa › Chaves de API e marque a permissão indicada em `required_scope`.
- `RATE_LIMITED` (HTTP 429) — Limite de chamadas excedido. Espere o tempo indicado em Retry-After e reduza a frequência. Os cabeçalhos X-RateLimit-* mostram quanto resta.
- `NOT_FOUND` (HTTP 404) — Endpoint não encontrado. Confira o caminho e o método em /openapi.json. Todo caminho começa com a URL base da API.
- `METHOD_NOT_ALLOWED` (HTTP 405) — Método não permitido para este endpoint. Veja em /openapi.json qual verbo o endpoint aceita.
- `INVALID_JSON` (HTTP 400) — O corpo da requisição não é um JSON válido. Envie Content-Type: application/json e um corpo JSON bem formado.
- `VALIDATION` (HTTP 400) — Dados inválidos na requisição. O campo `details` aponta exatamente qual campo está errado e por quê.
- `INVALID_PARAM` (HTTP 400) — Parâmetro inválido. Confira o nome e o formato do parâmetro na documentação do endpoint.
- `IDEMPOTENCY_CONFLICT` (HTTP 409) — A mesma Idempotency-Key já foi usada com um corpo diferente. Use uma Idempotency-Key nova para cada operação distinta, e repita a mesma só para reenviar a MESMA operação.
- `IDEMPOTENCY_IN_PROGRESS` (HTTP 409) — Uma requisição com esta Idempotency-Key ainda está em andamento. Espere alguns segundos e repita. A resposta guardada será devolvida assim que a primeira terminar.
- `RESOURCE_NOT_FOUND` (HTTP 404) — Registro não encontrado neste workspace. Confira o identificador. Registro de outro workspace nunca é visível — a resposta é a mesma de inexistente, de propósito.
- `CONFLICT` (HTTP 409) — Já existe um registro com esses dados. O campo `details` diz qual valor está duplicado.
- `IN_USE` (HTTP 409) — O registro está em uso e não pode ser excluído. Remova primeiro os vínculos indicados em `details`.
- `WINDOW_CLOSED` (HTTP 422) — A janela de 24 horas está fechada. Fora dela o WhatsApp só aceita template aprovado. Envie type="template" com um template aprovado, ou espere o contato responder para reabrir a janela.
- `TEMPLATE_NOT_APPROVED` (HTTP 422) — O template não existe ou não está aprovado para este canal. Confira o nome e o idioma em GET /templates. Template aprovado num canal não vale para outro.
- `TEMPLATE_INVALID` (HTTP 400) — O template precisa de `name` e `language`. Informe o nome exato e o código do idioma, por exemplo "pt_BR".
- `CHANNEL_NOT_FOUND` (HTTP 422) — Canal não encontrado ou desconectado. Liste os canais em GET /channels e use um com status "connected".
- `CHANNEL_UNLINKED` (HTTP 422) — A conversa não está vinculada a nenhum canal. Informe `channel_id` explicitamente no envio.
- `CONTACT_INVALID` (HTTP 422) — O contato não tem um telefone válido. Atualize o contato com um celular brasileiro no formato +55DDD9XXXXXXXX.
- `SEND_FAILED` (HTTP 422) — O WhatsApp recusou o envio. O campo `details` traz o código e o motivo da Meta. Códigos 131xxx costumam ser regra de política ou janela.
- `SEND_UNAVAILABLE` (HTTP 503) — O WhatsApp não respondeu a tempo. A falha é transitória. Repita a chamada com a MESMA Idempotency-Key — se a primeira tiver funcionado, nada é enviado em dobro.
- `MEDIA_NOT_FOUND` (HTTP 422) — O arquivo indicado não foi encontrado. Envie `media_url` acessível publicamente, ou o `media_storage_path` devolvido por um upload anterior.
- `BOT_NOT_CONFIGURED` (HTTP 422) — O robô não está configurado para operar. O campo `details` traz o que falta (tese, canal, chave de IA). Ajuste em Robôs, no aplicativo.
- `SLOT_UNAVAILABLE` (HTTP 409) — O horário escolhido não está mais livre. Consulte GET /schedules/{id}/availability de novo e escolha outro horário.
- `LIMIT_REACHED` (HTTP 422) — Limite do plano atingido. O campo `details` diz qual limite. Aumente o plano no aplicativo.
- `INTERNAL` (HTTP 500) — Erro interno. A falha foi registrada do nosso lado. Repita em alguns instantes. Persistindo, informe o `request_id` da resposta ao suporte.
- `DB_ERROR` (HTTP 500) — Erro ao consultar o banco de dados. Repita em alguns instantes. Persistindo, informe o `request_id` da resposta ao suporte.