# AdvBox — how to use (mcp.ai)

Wrapper da API oficial do AdvBox (software jurídico): processos (e histórico, movimentações, publicações), clientes/contatos, tarefas/anotações e financeiro (transações). Leitura + criação e atualização de processos e transações. Autenticação por token de API do escritório.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_advbox?ms=1781044440000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `advbox_create_customer`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/advbox`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/advbox/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/advbox/create/customer` — Cria um novo contato/cliente. Campos conforme a API oficial (ex.: name, type, cpf/cnpj, email, phone) — envie o restante via `extra`.
  - body: { name?: string, email?: string, cpf?: string, cnpj?: string, extra?: object }
- `POST https://api.mcp.ai/api/advbox/create/lawsuit` — Cria um processo. Campos conforme a API oficial (use advbox_settings para descobrir IDs de tipo/responsável); envie via campos nomeados + `extra`.
  - body: { number?: string, extra?: object }
- `POST https://api.mcp.ai/api/advbox/create/movement` — Adiciona uma movimentação manual a um processo. Vincule ao processo (campo conforme a API oficial) + descrição; demais campos via `extra`.
  - body: { description?: string, extra?: object }
- `POST https://api.mcp.ai/api/advbox/create/post` — Cria um novo post/anotação. Campos conforme a API oficial via campos nomeados + `extra`.
  - body: { text?: string, extra?: object }
- `POST https://api.mcp.ai/api/advbox/create/transaction` — Cria um lançamento financeiro (receita ou despesa). Campos conforme a API oficial (ex.: type, value, due_date) via campos nomeados + `extra`.
  - body: { type?: string, value?: string, due_date?: string, extra?: object }
- `POST https://api.mcp.ai/api/advbox/customers/birthdays` — Lista aniversariantes (para campanhas de relacionamento).
  - body: { page?: integer, page_size?: integer, query?: object }
- `POST https://api.mcp.ai/api/advbox/get/customer` — Busca os dados completos de um contato por ID.
  - body: { id: string, query?: object, ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/get/lawsuit` — Busca um processo por ID (dados completos).
  - body: { id: string, query?: object, ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/get/transaction` — Detalha uma transação por ID.
  - body: { id: string, query?: object, ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/last/movements` — Última atualização de cada processo (resumo recente).
  - body: { page?: integer, page_size?: integer, query?: object }
- `POST https://api.mcp.ai/api/advbox/lawsuit/history` — Histórico completo de um processo.
  - body: { lawsuit_id: string, page?: integer, page_size?: integer, query?: object, lawsuit_ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/lawsuit/movements` — Lista todas as movimentações de um processo.
  - body: { lawsuit_id: string, page?: integer, page_size?: integer, query?: object, lawsuit_ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/list/customers` — Lista clientes/contatos com filtros avançados (nome, cpf, cnpj, e-mail etc. via `query`).
  - body: { page?: integer, page_size?: integer, name?: string, cpf?: string, cnpj?: string, email?: string, query?: object }
- `POST https://api.mcp.ai/api/advbox/list/lawsuits` — Lista/busca processos (22+ filtros). Filtros comuns via `query`: numero, parte, cpf, cnpj, responsavel, status, comarca, uf, datas.
  - body: { page?: integer, page_size?: integer, number?: string, cpf?: string, cnpj?: string, status?: string, query?: object }
- `POST https://api.mcp.ai/api/advbox/list/posts` — Lista posts e anotações (tarefas/notas).
  - body: { page?: integer, page_size?: integer, query?: object }
- `POST https://api.mcp.ai/api/advbox/list/transactions` — Lista transações financeiras com filtros de data/tipo/status (via `query`).
  - body: { page?: integer, page_size?: integer, type?: string, status?: string, start_date?: string, end_date?: string, query?: object }
- `POST https://api.mcp.ai/api/advbox/publications` — Lista as publicações oficiais de um processo.
  - body: { lawsuit_id: string, page?: integer, page_size?: integer, query?: object, lawsuit_ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/settings` — Obtém todos os IDs e configurações da conta (usuários, origens, tipos de tarefa, fases, tipos de processo). Use para descobrir os IDs exigidos por create/update.
  - body: { query?: object }
- `POST https://api.mcp.ai/api/advbox/update/lawsuit` — Atualiza um processo existente por ID. Envie só os campos a alterar (nomeados + `extra`).
  - body: { id: string, extra?: object, ids?: string[] }
- `POST https://api.mcp.ai/api/advbox/update/transaction` — Atualiza valor, vencimento ou status de pagamento de uma transação por ID. Envie só os campos a alterar (nomeados + `extra`).
  - body: { id: string, value?: string, due_date?: string, status?: string, extra?: object, ids?: string[] }

## Example prompts
- "Busque o processo número X no AdvBox e mostre as últimas movimentações"
- "Liste as transações financeiras vencidas este mês"
- "Crie uma movimentação manual no processo Y registrando o andamento"

## More
- Page: https://mcp.ai/advbox
- Agent spec (llms.txt): https://mcp.ai/advbox/llms.txt
- Postman collection: https://mcp.ai/advbox/postman.json