{
    "openapi": "3.0.0",
    "info": {
        "title": "API do AdvPlan",
        "description": "API REST do AdvPlan — gestão jurídica.\n\nTodos os endereços respondem JSON e exigem uma chave do escritório, criada em\n**Configurações → Chaves de API**. A chave enxerga exatamente o que a pessoa\nque a criou enxerga no painel: mesmo escritório, mesmas permissões.\n\n### Testando aqui mesmo\n\nClique em **Authorize**, cole a chave e use o **Try it out** de qualquer\nendereço — as chamadas saem de verdade, contra este ambiente.\n\n### Webhooks: o AdvPlan avisa você\n\nEm vez de ficar perguntando o que mudou, cadastre um endereço em\n**Configurações → Webhooks**. A cada fato assinado sai um `POST` com JSON:\n\n```json\n{\n  \"evento\": \"caso.fase_alterada\",\n  \"ocorrido_em\": \"2026-08-30T14:03:11-03:00\",\n  \"fase_anterior\": \"consultivo\",\n  \"dados\": { \"id\": 1234, \"codigo_interno\": \"BR-2026-0042\", \"fase\": \"processual\" }\n}\n```\n\nO campo `dados` é o **mesmo objeto** que os endereços abaixo devolvem.\n\nEventos disponíveis: `cliente.criado`, `cliente.atualizado`, `caso.criado`,\n`caso.fase_alterada`, `caso.encerrado`, `caso.risco_alterado`, `prazo.criado`,\n`prazo.aprovado`, `prazo.protocolado`, `cobranca.criada`, `cobranca.paga`.\n\n`caso.risco_alterado` sai quando muda a provisão do processo (chance, natureza ou\nvalor) e traz `chance_anterior` junto — é o gancho para o ERP refazer o quadro do\nbalanço sem ninguém redigitar.\n\nCabeçalhos de cada envio: `X-AdvPlan-Evento`, `X-AdvPlan-Entrega` (número da\ntentativa) e `X-AdvPlan-Assinatura` — `sha256=` seguido do HMAC-SHA256 do\ncorpo cru com o segredo do webhook. **Confira a assinatura antes de confiar\nno aviso.**\n\nResponda 2xx em até 15 segundos. Se falhar, tentamos de novo em 10s, 1min e\n5min; depois de 15 falhas seguidas o endereço é desligado sozinho e a tela\nmostra o motivo, com o log de cada tentativa.",
        "contact": {
            "name": "Suporte AdvPlan",
            "email": "contato@advplan.com.br"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "https://app.advplan.com.br",
            "description": "Este ambiente (o que você está lendo agora)"
        }
    ],
    "paths": {
        "/api/v1/casos": {
            "get": {
                "tags": [
                    "Casos"
                ],
                "summary": "Lista os casos do escritório",
                "operationId": "5917df8dbf0d67429c2b113fb1a4aeae",
                "parameters": [
                    {
                        "name": "fase",
                        "in": "query",
                        "description": "Chave da fase (prospeccao, processual, execucao…)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cliente_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "busca",
                        "in": "query",
                        "description": "Código interno, número CNJ ou assunto",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista paginada de casos"
                    },
                    "401": {
                        "description": "Chave ausente ou inválida"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Casos"
                ],
                "summary": "Cria um caso",
                "description": "O código interno é gerado pelo AdvPlan. Cliente vinculado que era prospecto passa a ativo. Dispara o webhook caso.criado.",
                "operationId": "e5cb3127589d3effbe4a433172d1a49c",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "fase",
                                    "advogado_responsavel_id"
                                ],
                                "properties": {
                                    "fase": {
                                        "description": "Chave de uma fase do kanban do escritório",
                                        "type": "string",
                                        "example": "consultivo"
                                    },
                                    "advogado_responsavel_id": {
                                        "type": "integer",
                                        "example": 7
                                    },
                                    "numero_cnj": {
                                        "type": "string",
                                        "example": "5001234-56.2026.8.08.0014"
                                    },
                                    "assunto": {
                                        "type": "string",
                                        "example": "Revisão de contrato bancário"
                                    },
                                    "tribunal": {
                                        "type": "string",
                                        "example": "TJES"
                                    },
                                    "comarca": {
                                        "type": "string",
                                        "example": "Colatina"
                                    },
                                    "valor_causa": {
                                        "type": "number",
                                        "example": 25000
                                    },
                                    "segredo_justica": {
                                        "type": "boolean",
                                        "example": false
                                    },
                                    "clientes": {
                                        "type": "array",
                                        "items": {
                                            "properties": {
                                                "id": {
                                                    "type": "integer",
                                                    "example": 34
                                                },
                                                "papel": {
                                                    "type": "string",
                                                    "enum": [
                                                        "autor",
                                                        "reu",
                                                        "interessado",
                                                        "investigado",
                                                        "representante_vitima"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Caso criado, com o código interno gerado"
                    },
                    "403": {
                        "description": "Algum cliente informado está fora do alcance da chave"
                    },
                    "422": {
                        "description": "Dados inválidos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/casos/{caso}": {
            "get": {
                "tags": [
                    "Casos"
                ],
                "summary": "Mostra um caso",
                "operationId": "b654c19efdbbea17a84ec5f5cdb9b0bb",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Caso, com cliente e responsável"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Casos"
                ],
                "summary": "Atualiza um caso",
                "description": "Também aceita PATCH. Mudar a fase por aqui vale o mesmo que PUT /casos/{caso}/fase.",
                "operationId": "f01f4d6730f29704ab72fdc4ce3a4b67",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Mesmos campos do cadastro; mande só o que muda.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "vara": {
                                        "type": "string",
                                        "example": "2ª Vara Cível"
                                    },
                                    "risco_chance": {
                                        "type": "string",
                                        "enum": [
                                            "provavel",
                                            "possivel",
                                            "remoto"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Caso atualizado"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    },
                    "422": {
                        "description": "Dados inválidos, ou a fase nova não aceita o caso agora"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Casos"
                ],
                "summary": "Remove um caso",
                "operationId": "d655c1028d1f4673876ac2c948b0189c",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removido: {deleted: true}"
                    },
                    "403": {
                        "description": "A chave não tem permissão de excluir casos"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/casos/{caso}/timeline": {
            "get": {
                "tags": [
                    "Casos"
                ],
                "summary": "Linha do tempo do caso",
                "description": "Tudo o que aconteceu no caso, do mais recente para o mais antigo: publicações, prazos, documentos e comunicação com o cliente.",
                "operationId": "817b4ed7e52a4260d64c8b50768e651e",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Eventos da linha do tempo"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/casos/{caso}/eventos": {
            "post": {
                "tags": [
                    "Casos"
                ],
                "summary": "Registra um fato na linha do tempo do caso",
                "operationId": "54c4c144696616dc56726b419519836f",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "tipo",
                                    "descricao"
                                ],
                                "properties": {
                                    "tipo": {
                                        "type": "string",
                                        "enum": [
                                            "contratacao",
                                            "documentacao",
                                            "acordo_tentativa",
                                            "acordo_fechado",
                                            "protocolo",
                                            "intimacao",
                                            "despacho",
                                            "decisao",
                                            "audiencia",
                                            "manifestacao",
                                            "recurso",
                                            "sentenca",
                                            "transito",
                                            "comunicacao_cliente",
                                            "observacao"
                                        ],
                                        "example": "observacao"
                                    },
                                    "descricao": {
                                        "type": "string",
                                        "example": "Cliente enviou o comprovante de residência."
                                    },
                                    "data_evento": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-10-04"
                                    },
                                    "visibilidade": {
                                        "description": "publica aparece no portal do cliente; o padrão é publica",
                                        "type": "string",
                                        "enum": [
                                            "publica",
                                            "interna"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Evento registrado"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    },
                    "422": {
                        "description": "Dados inválidos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/casos/{caso}/fase": {
            "put": {
                "tags": [
                    "Casos"
                ],
                "summary": "Move o caso de fase",
                "description": "Mesma mudança que arrastar o card no kanban — inclusive dispara os fluxos automáticos configurados para a fase de destino.",
                "operationId": "b20f323615171a3e2bfe3a46778e5605",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "fase"
                                ],
                                "properties": {
                                    "fase": {
                                        "type": "string",
                                        "example": "execucao"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Caso na fase nova"
                    },
                    "422": {
                        "description": "Fase inexistente no escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/casos/{caso}/encerrar": {
            "post": {
                "tags": [
                    "Casos"
                ],
                "summary": "Encerra o caso",
                "description": "Move para a fase encerrado e dispara os webhooks caso.encerrado e caso.fase_alterada.",
                "operationId": "be76a9fc07803204178877b9bd74feed",
                "parameters": [
                    {
                        "name": "caso",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "motivo"
                                ],
                                "properties": {
                                    "motivo": {
                                        "type": "string",
                                        "enum": [
                                            "sentenca_favoravel",
                                            "sentenca_desfavoravel",
                                            "acordo",
                                            "desistencia",
                                            "prescricao",
                                            "outro"
                                        ],
                                        "example": "acordo"
                                    },
                                    "data_encerramento": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-10-04"
                                    },
                                    "observacoes": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Caso encerrado"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    },
                    "422": {
                        "description": "Motivo inválido"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/clientes": {
            "get": {
                "tags": [
                    "Clientes"
                ],
                "summary": "Lista os clientes do escritório",
                "operationId": "275ddabe0ff3df657edd035747f2c43a",
                "parameters": [
                    {
                        "name": "busca",
                        "in": "query",
                        "description": "Procura por nome, CPF/CNPJ ou e-mail",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "description": "ativo, inadimplente, prospecto…",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "fase_funil",
                        "in": "query",
                        "description": "Etapa do funil de leads (novo, contato, proposta…)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Itens por página (padrão 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista paginada de clientes"
                    },
                    "401": {
                        "description": "Chave ausente ou inválida"
                    },
                    "402": {
                        "description": "O plano do escritório não inclui a API"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Clientes"
                ],
                "summary": "Cadastra um cliente",
                "operationId": "d82cb60437b288da7843df7826fad22f",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "nome"
                                ],
                                "properties": {
                                    "nome": {
                                        "type": "string",
                                        "example": "Construtora Amaral Ltda"
                                    },
                                    "tipo": {
                                        "type": "string",
                                        "enum": [
                                            "pf",
                                            "pj"
                                        ],
                                        "example": "pj"
                                    },
                                    "cpf_cnpj": {
                                        "type": "string",
                                        "example": "10.620.937/0001-13"
                                    },
                                    "email": {
                                        "type": "string",
                                        "example": "contato@amaral.com.br"
                                    },
                                    "telefone": {
                                        "type": "string",
                                        "example": "(27) 99999-0000"
                                    },
                                    "fase_funil": {
                                        "description": "Chave de uma etapa ativa do funil de leads deste escritório",
                                        "type": "string",
                                        "example": "contato"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Cliente criado"
                    },
                    "422": {
                        "description": "Dados inválidos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/clientes/{cliente}": {
            "get": {
                "tags": [
                    "Clientes"
                ],
                "summary": "Mostra um cliente",
                "operationId": "ab4ce3009d7508c93f86a31ca7afca31",
                "parameters": [
                    {
                        "name": "cliente",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cliente"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Clientes"
                ],
                "summary": "Atualiza um cliente",
                "description": "Também aceita PATCH, com o mesmo corpo. Dispara o webhook cliente.atualizado. Se fase_funil mudar, dispara também cliente.fase_funil_alterada (a etapa anterior vai no campo fase_anterior).",
                "operationId": "d73c1716e55d5b6be632db863d3fda4d",
                "parameters": [
                    {
                        "name": "cliente",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "description": "Mande só os campos que mudam; aceita os mesmos do cadastro.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "example": "financeiro@amaral.com.br"
                                    },
                                    "telefone": {
                                        "type": "string",
                                        "example": "(27) 98888-0000"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Cliente atualizado"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    },
                    "422": {
                        "description": "Dados inválidos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Clientes"
                ],
                "summary": "Remove um cliente",
                "operationId": "49710823fcda170cb253efe37c6339e6",
                "parameters": [
                    {
                        "name": "cliente",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removido: {deleted: true}"
                    },
                    "403": {
                        "description": "A chave não tem permissão de excluir clientes"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/cobrancas": {
            "get": {
                "tags": [
                    "Cobranças"
                ],
                "summary": "Lista cobranças",
                "operationId": "552fc16dadd5f03ca13480f709184115",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "description": "pendente, pago, atrasado…",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cliente_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista paginada de cobranças"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Cobranças"
                ],
                "summary": "Emite uma cobrança para o cliente",
                "description": "Gera a fatura no gateway configurado pelo escritório. Dispara o webhook cobranca.criada e, ao pagar, cobranca.paga.",
                "operationId": "c9d3b23f1be9e1c18be00cbf370924a4",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "cliente_id",
                                    "valor",
                                    "descricao",
                                    "forma_pagamento",
                                    "tipo",
                                    "vencimento"
                                ],
                                "properties": {
                                    "cliente_id": {
                                        "type": "integer",
                                        "example": 34
                                    },
                                    "caso_id": {
                                        "type": "integer",
                                        "example": 56
                                    },
                                    "valor": {
                                        "type": "number",
                                        "example": 1500
                                    },
                                    "descricao": {
                                        "type": "string",
                                        "example": "Honorários iniciais"
                                    },
                                    "forma_pagamento": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "pix",
                                                "boleto",
                                                "cartao",
                                                "transferencia"
                                            ]
                                        },
                                        "example": [
                                            "pix",
                                            "boleto"
                                        ]
                                    },
                                    "tipo": {
                                        "type": "string",
                                        "enum": [
                                            "honorario_fixo",
                                            "honorario_exito",
                                            "custas",
                                            "multa"
                                        ]
                                    },
                                    "vencimento": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-10-20"
                                    },
                                    "installments": {
                                        "description": "Parcelas, de 1 a 24",
                                        "type": "integer",
                                        "example": 3
                                    },
                                    "recorrente": {
                                        "description": "Mensalidade de honorários",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Cobrança emitida no gateway do escritório"
                    },
                    "403": {
                        "description": "A chave não pode emitir cobrança"
                    },
                    "422": {
                        "description": "Dados inválidos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/documentos": {
            "get": {
                "tags": [
                    "Documentos"
                ],
                "summary": "Lista documentos",
                "operationId": "e5ee7c2cf84a8db11aa3fd0a29f7478b",
                "parameters": [
                    {
                        "name": "caso_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "cliente_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista paginada de documentos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/documentos/{documento}": {
            "get": {
                "tags": [
                    "Documentos"
                ],
                "summary": "Mostra os dados de um documento",
                "operationId": "6c95ba4002cd987c31604a992599a692",
                "parameters": [
                    {
                        "name": "documento",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Documento"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Documentos"
                ],
                "summary": "Remove um documento",
                "operationId": "afaff6fa23120f8930ca927a97956196",
                "parameters": [
                    {
                        "name": "documento",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Documento removido"
                    },
                    "403": {
                        "description": "A chave não tem permissão de excluir documentos"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/documentos/gerar": {
            "post": {
                "tags": [
                    "Documentos"
                ],
                "summary": "Gera um documento a partir de um modelo",
                "description": "As variáveis do modelo são preenchidas com os dados do cliente e do caso informados. O documento nasce como rascunho, para revisão.",
                "operationId": "b2aa5a339646c062782766b34ae44b49",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "template_id"
                                ],
                                "properties": {
                                    "template_id": {
                                        "type": "integer",
                                        "example": 12
                                    },
                                    "cliente_id": {
                                        "type": "integer",
                                        "example": 34
                                    },
                                    "caso_id": {
                                        "type": "integer",
                                        "example": 56
                                    },
                                    "extras": {
                                        "description": "Variáveis personalizadas do modelo",
                                        "type": "object",
                                        "example": {
                                            "valor_honorarios": "5000"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Documento gerado"
                    },
                    "422": {
                        "description": "Modelo inexistente ou variável obrigatória faltando"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/documentos/{documento}/download": {
            "get": {
                "tags": [
                    "Documentos"
                ],
                "summary": "Baixa o arquivo do documento",
                "operationId": "6003682a7de69cd7478995395a2e1fbb",
                "parameters": [
                    {
                        "name": "documento",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "O arquivo, com o tipo original"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/documentos/{documento}/texto": {
            "get": {
                "tags": [
                    "Documentos"
                ],
                "summary": "Devolve o texto do documento",
                "description": "PDF, Word e imagem passam por extração e OCR. Útil para IA e automação que não abrem o binário.",
                "operationId": "1cf2d545c8af4fc87f214c4468fe5d5b",
                "parameters": [
                    {
                        "name": "documento",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "{data: {id, nome, texto}}"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/prazos": {
            "get": {
                "tags": [
                    "Prazos"
                ],
                "summary": "Lista prazos",
                "operationId": "bbda8e49a80eeece3d6458d60806f183",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "description": "pendente_aprovacao, aprovado, protocolado…",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "caso_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "situacao",
                        "in": "query",
                        "description": "para_aprovar, em_aberto, proximos (em aberto sem os vencidos), vencidos ou encerrados",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "meus",
                        "in": "query",
                        "description": "1 = só os prazos de quem chama (responsável ou acompanhante)",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista paginada de prazos"
                    },
                    "401": {
                        "description": "Chave ausente ou inválida"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Prazos"
                ],
                "summary": "Cria um prazo (nasce aguardando aprovação)",
                "description": "O AdvPlan calcula a data fatal com feriados, recesso e suspensões do tribunal do caso. O prazo só entra na agenda depois de aprovado por uma pessoa.",
                "operationId": "cce845963350b7ec55c8ad2d82372b24",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "caso_id",
                                    "advogado_id",
                                    "ato",
                                    "termo_inicial",
                                    "prazo_dias"
                                ],
                                "properties": {
                                    "caso_id": {
                                        "type": "integer",
                                        "example": 56
                                    },
                                    "advogado_id": {
                                        "type": "integer",
                                        "example": 7
                                    },
                                    "ato": {
                                        "type": "string",
                                        "example": "Contestação"
                                    },
                                    "termo_inicial": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-10-05"
                                    },
                                    "prazo_dias": {
                                        "type": "integer",
                                        "example": 15
                                    },
                                    "em_dias_uteis": {
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "urgencia": {
                                        "type": "string",
                                        "enum": [
                                            "baixa",
                                            "media",
                                            "alta"
                                        ]
                                    },
                                    "observacoes": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Prazo criado com status pendente_aprovacao"
                    },
                    "403": {
                        "description": "O caso está fora do alcance da chave"
                    },
                    "422": {
                        "description": "Dados inválidos"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/prazos/{prazo}": {
            "get": {
                "tags": [
                    "Prazos"
                ],
                "summary": "Mostra um prazo, com a memória de cálculo",
                "operationId": "bc11f1be27698de34a485b969a4727f7",
                "parameters": [
                    {
                        "name": "prazo",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Prazo"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/prazos/{prazo}/aprovar": {
            "put": {
                "tags": [
                    "Prazos"
                ],
                "summary": "Aprova o prazo",
                "operationId": "32085bd2abfb03085faece4841e43fdf",
                "parameters": [
                    {
                        "name": "prazo",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "notificar_cliente": {
                                        "description": "Avisa o cliente pelo canal configurado; padrão true",
                                        "type": "boolean",
                                        "example": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Prazo com o status novo"
                    },
                    "403": {
                        "description": "A chave não tem permissão para esta ação"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/prazos/{prazo}/rejeitar": {
            "put": {
                "tags": [
                    "Prazos"
                ],
                "summary": "Rejeita o prazo sugerido",
                "operationId": "2997e28034fb784e8739bf26fc673665",
                "parameters": [
                    {
                        "name": "prazo",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "motivo": {
                                        "type": "string",
                                        "example": "Prazo já contado em outro caso"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Prazo com o status novo"
                    },
                    "403": {
                        "description": "A chave não tem permissão para esta ação"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        },
        "/api/v1/prazos/{prazo}/cancelar": {
            "put": {
                "tags": [
                    "Prazos"
                ],
                "summary": "Cancela o prazo",
                "operationId": "8a41ea60b1ba2dfd881ad78bbfe4ab0c",
                "parameters": [
                    {
                        "name": "prazo",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "motivo": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Prazo com o status novo"
                    },
                    "403": {
                        "description": "A chave não tem permissão para esta ação"
                    },
                    "404": {
                        "description": "Não existe, ou é de outro escritório"
                    }
                },
                "security": [
                    {
                        "chaveDoEscritorio": []
                    }
                ]
            }
        }
    },
    "components": {
        "securitySchemes": {
            "chaveDoEscritorio": {
                "type": "http",
                "description": "Cole a chave criada em Configurações → Chaves de API. No cabeçalho vai como: Authorization: Bearer SUA_CHAVE",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Clientes",
            "description": "Cadastro de clientes do escritório"
        },
        {
            "name": "Casos",
            "description": "Processos e casos, com linha do tempo e fases"
        },
        {
            "name": "Prazos",
            "description": "Prazos processuais. Criar prazo pela API NÃO dispensa a aprovação humana no painel."
        },
        {
            "name": "Documentos",
            "description": "Documentos do caso e geração a partir de modelos"
        },
        {
            "name": "Cobranças",
            "description": "Honorários e despesas"
        }
    ]
}