{ "openapi": "3.1.0", "info": { "title": "API LM Gestão ERP", "version": "1.0.0", "description": "A **API LM Gestão ERP** é a forma oficial de um software de terceiros consultar, incluir, editar e excluir informações de uma empresa no LM Gestão ERP. Ela cobre, nesta versão, o Fluxo de Caixa, a Cobrança, os cadastros de Clientes/Fornecedores, Serviços e Contas Bancárias, e a NFS-e — do rascunho à transmissão e ao cancelamento.\n\nTudo o que esta documentação descreve é o **contrato público**. O que não está aqui não existe para o integrador — inclusive a API interna que a interface do ERP usa, que não é suportada nem documentada.\n\n## Primeiros passos\n\n1. No ERP, acesse **Documentação - ERP › API - LM Gestão ERP** e gere uma chave para a sua integração, marcando só os escopos de que ela precisa.\n2. Copie a chave no momento em que ela aparece: o ERP guarda apenas um hash e **não a exibe de novo**.\n3. Teste a autenticação:\n\n```bash\ncurl https://lmgestao.app.br/v1/eu -H \"x-api-key: lm_test_...\"\n```\n\nA resposta traz o nome da chave, o ambiente, os escopos e o limite por minuto.\n\n## Ambientes\n\n| Ambiente | Prefixo da chave | Base URL |\n|---|---|---|\n| Sandbox | `lm_test_` | `https://homologacao.lmgestao.app.br/v1` |\n| Produção | `lm_live_` | `https://lmgestao.app.br/v1` |\n\nUma chave só funciona no ambiente correspondente: `lm_test_` em produção (e o inverso) responde `401`. Desenvolva no sandbox; só troque para a chave `lm_live_` quando a integração estiver validada.\n\n**Os dois ambientes gravam no mesmo banco de dados.** O sandbox difere pelo servidor e pela chave, não pelos dados: um lançamento criado com chave `lm_test_` aparece na empresa de verdade. Peça à LM uma **empresa de teste** e gere a chave sandbox nela. O mesmo vale para NFS-e: a transmissão segue o \"Ambiente NFS-e\" configurado na empresa em Parâmetros de Notas, e não o ambiente da chave.\n\n## Código externo e sincronização incremental\n\nTodo recurso aceita `codigo_externo` (até 120 caracteres): grave nele o identificador do registro no seu sistema e reencontre-o com `GET /?codigo_externo=...`. Clientes e fornecedores também podem ser localizados por `GET /clientes-fornecedores?cpf_cnpj=...` (com ou sem máscara).\n\n### CPF e CNPJ\n\n`cpf_cnpj` é aceito com ou sem máscara e **gravado com a máscara**, padrão do ERP: CPF `000.000.000-00`, CNPJ `00.000.000/0000-00`. A resposta traz o documento como está gravado; cadastros antigos podem vir só com dígitos. Para comparar com o seu sistema, compare os dígitos. A busca `?cpf_cnpj=` e a checagem de duplicidade acham os dois formatos. Na NFS-e, `tomador_documento` é gravado só com dígitos pela API (notas incluídas pela tela do ERP podem vir com máscara).\n\nPara conferências periódicas, use `GET /?alterado_desde=`: a listagem devolve só o que foi alterado a partir do instante, em ordem crescente de `alterado_em`, paginada por cursor. Guarde o maior `alterado_em` recebido e use-o na próxima chamada.\n\n## Identificador e rastreabilidade\n\nO `id` de todo registro é gerado pelo ERP e é o mesmo valor que aparece na tela do cadastro, no campo `ID_{MÓDULO}` do rodapé (por exemplo `ID_CLIENTES_FORNECEDORES`). Quem opera o ERP consegue ler ali o identificador que a sua integração usa nas rotas `//{id}` — útil no suporte, para conferir de qual registro se está falando.\n\nTodo recurso devolve, somente leitura, quem gravou e quando:\n\n| Campo | Conteúdo |\n|---|---|\n| `criado_em` / `alterado_em` | Instantes em ISO 8601. |\n| `criado_por` / `alterado_por` | Nome do usuário do ERP ou **o nome da chave** de integração que fez a escrita. |\n| `criado_por_tipo` / `alterado_por_tipo` | `Usuário` (tela do ERP) ou `API` (esta API). |\n\nEsses campos são preenchidos pelo ERP e ignorados se enviados. É o mesmo par de linhas que a tela do cadastro mostra no bloco **Rastreabilidade** — então dar um nome claro à chave (\"ERP CONTÁBIL\", \"LOJA VIRTUAL\") aparece para quem usa o sistema.\n\n## Autenticação\n\nEnvie a chave no cabeçalho `x-api-key` (ou em `Authorization: Bearer `). Toda comunicação é feita exclusivamente por HTTPS — requisições em HTTP puro não são atendidas.\n\n**Escopos.** Cada chave carrega apenas os escopos marcados na criação; uma rota fora deles responde `403 escopo_insuficiente`.\n\n- `financeiro:leitura`\n- `financeiro:escrita`\n- `cadastros:leitura`\n- `cadastros:escrita`\n- `notas_fiscais:leitura`\n- `notas_fiscais:escrita`\n- `gerador_demandas:leitura`\n- `gerador_demandas:escrita`\n- `parcerias:leitura`\n\n**Boas práticas.** Crie uma chave por integração, com nome que a identifique. Uma integração que só consulta não precisa de escopo de escrita. Se a chave vazar, revogue-a na tela do ERP — o efeito é imediato — e gere outra. Opcionalmente, restrinja a chave aos IPs de saída do seu servidor.\n\n## Formato das respostas\n\nSucesso devolve o registro (ou a lista) dentro de `dados`:\n\n```json\n{ \"dados\": { \"id\": \"abc123\", \"descricao\": \"MENSALIDADE\", \"valor_original\": 1500 } }\n```\n\nListas são paginadas por cursor:\n\n```json\n{ \"dados\": [ ... ], \"paginacao\": { \"limite\": 25, \"proximo_cursor\": \"xyz789\" } }\n```\n\nRepita a chamada com `?cursor=xyz789` até `proximo_cursor` vir `null`. O limite máximo por página é 100.\n\nDatas simples usam `AAAA-MM-DD`; data e hora usam ISO 8601 em UTC. Valores monetários são números com até duas casas decimais. Textos descritivos são gravados em **caixa alta** pelo ERP, como na interface.\n\n## Erros\n\nTodo erro tem o mesmo formato:\n\n```json\n{\n \"erro\": {\n \"codigo\": \"requisicao_invalida\",\n \"mensagem\": \"Os dados enviados não passaram na validação.\",\n \"campos\": [ { \"campo\": \"valor_original\", \"mensagem\": \"Deve ser um número maior que zero.\" } ],\n \"id_requisicao\": \"b7e6…\"\n }\n}\n```\n\n| HTTP | `codigo` | Quando |\n|---|---|---|\n| 400 | `requisicao_invalida` | Validação de campos, JSON malformado, referência a registro inexistente |\n| 401 | `nao_autenticado` | Chave ausente, inválida, revogada, expirada ou de outro ambiente |\n| 403 | `escopo_insuficiente` / `acesso_negado` | Chave sem o escopo da rota, ou IP fora da allowlist |\n| 404 | `nao_encontrado` | Registro inexistente — ou de outra empresa |\n| 409 | `conflito` / `dependencia_existente` | Estado incompatível (cobrança já no gateway, nota emitida, registro com vínculos) |\n| 429 | `limite_excedido` | Quota da chave excedida no minuto |\n| 502 | `servico_externo` | O gateway de pagamento ou a API de Notas recusou ou não respondeu; a mensagem traz o motivo |\n| 500 | `erro_interno` | Falha do ERP. Guarde o `id_requisicao` e acione o suporte |\n\nErros nunca expõem detalhes internos: o `id_requisicao` é o elo entre o que você viu e o que o suporte consegue investigar.\n\n## Quota\n\nCada chave tem um limite de requisições por minuto (padrão 120, ajustável na tela até 1000). Os cabeçalhos `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset` acompanham toda resposta. Ao receber `429`, aguarde `RateLimit-Reset` segundos.\n\nPrefira **webhooks** a consultas periódicas: eles avisam a sua aplicação quando algo muda, sem gastar quota.\n\n## Idempotência\n\nEm qualquer `POST`, envie `Idempotency-Key: ` (por exemplo, o id do pedido no seu sistema). Se a conexão cair antes de você receber a resposta, repita a mesma chamada com a mesma chave: a API devolve a resposta original, marcada com `Idempotent-Replayed: true`, sem criar o registro de novo. A chave vale por 24 horas e é isolada por chave de API.\n\n## Cobranças e NFS-e: ciclo completo\n\n**Cobrança.** `POST /cobrancas` cria a cobrança e o lançamento pareado. Para gerar boleto, PIX, cartão ou assinatura no gateway configurado na conta bancária da empresa (Asaas ou Mercado Pago), chame `POST /cobrancas/{id}/registrar-gateway`; a resposta traz `link_pagamento`, `linha_digitavel` e `nosso_numero`. O pagamento confirmado chega pelo webhook `cobranca.paga`.\n\n**Estorno e chargeback.** Quando o gateway estorna ou contesta (chargeback) um pagamento que já foi baixado no ERP, a baixa **não** é desfeita automaticamente: o lançamento pareado recebe `alerta_chargeback` (tipo, evento e status do gateway, valor, data e `resolvido`) e o webhook `lancamento.atualizado` é enviado. Enquanto `alerta_chargeback.resolvido` for `false`, o lançamento fica fora da conciliação bancária automática até alguém revisá-lo no ERP; se o gateway reverter a contestação, o aviso passa a `resolvido: true` sozinho. Vale para os gateways que informam chargeback pelo webhook — hoje, o Asaas.\n\n**NFS-e.** `POST /notas-fiscais` cria o rascunho com os valores calculados. `POST /notas-fiscais/{id}/emitir` reserva o RPS e transmite pela API de Notas configurada em Parâmetros de Notas; o retorno traz `status` (`Emitida`, `Erro` com `mensagem_retorno`, ou `Processando`). Se `Processando`, repita `POST /notas-fiscais/{id}/consultar` até a prefeitura responder. Para cancelar uma nota emitida, `POST /notas-fiscais/{id}/cancelar` com `justificativa` (mínimo 15 caracteres). O evento `nota_fiscal.emitida` avisa a autorização.\n\n**Goiânia.** O município adotou o formato nacional da NFS-e pelo provedor da prefeitura. O padrão de emissão é o escolhido em Parâmetros de Notas: empresa não optante do Simples Nacional deve usar o Nacional (pelo ABRASF a prefeitura recusa desde a competência 10/2026, e `/emitir` responde `400` antes de enviar); empresa optante (MEI e ME/EPP) pode seguir no ABRASF, que a prefeitura ainda aceita. Para empresa não optante do Simples Nacional, a partir da competência 10/2026 a nota precisa do grupo IBS/CBS (`cst_ibs_cbs`, `classificacao_trib_ibs_cbs` e `indicador_operacao`, na nota ou no cadastro do serviço); sem ele, `/emitir` responde `400` com os campos a preencher, antes de reservar o RPS. O cancelamento em Goiânia não é feito por webservice: Parâmetros de Notas fica com \"Permite cancelamento via API de Notas\" = Não (escolhido pela documentação da API de Notas e alterável), `/cancelar` responde `409` e a nota deve ser cancelada no portal da prefeitura; o usuário registra o cancelamento no ERP pela tela.\n\nO certificado digital e as credenciais da API de Notas ficam no ERP; a integração nunca os recebe nem os envia.\n\n**PDF e XML.** Depois da emissão, a leitura da nota traz `url_pdf` e `url_xml`, que apontam para `GET /notas-fiscais/{id}/pdf` e `GET /notas-fiscais/{id}/xml` nesta API (escopo `notas_fiscais:leitura`). As rotas entregam o arquivo; o endereço da API de Notas nunca aparece.\n\n## Gerador de Demandas: contatos, quadros e tarefas\n\nEscopos `gerador_demandas:leitura` e `gerador_demandas:escrita`.\n\n**Contatos** (`/contatos`) é a agenda da empresa, a mesma usada pelo Multi-Atendimento (WhatsApp) e pelos formulários do site. O contato **não duplica**: incluir alguém com WhatsApp, e-mail ou telefone já cadastrado atualiza o existente e devolve o mesmo `id` — use isso para sincronizar o CRM sem precisar buscar antes. Números saem no padrão internacional só com dígitos (`5562985330155`); na entrada, máscara e `+` são aceitos, e número sem DDI é tratado como do Brasil.\n\n**Quadros** (`GET /quadros`) listam os quadros da Gestão de Tarefas com as listas (colunas). **Tarefas** (`/tarefas`) exigem `quadro_id` e `titulo`; `lista_id` vazio coloca na primeira lista. Editar `lista_id`/`quadro_id` move a tarefa. `POST /tarefas/{id}/concluir`, `/reabrir` e `/comentarios` completam o ciclo. A resposta traz `situacao` calculada (`no_prazo`, `agendada`, `vencida`, `aguardando`, `concluida`).\n\nTarefa criada, movida ou concluída pela API dispara as automações do quadro, como na tela — inclusive o aviso ao cliente por WhatsApp, e-mail ou SMS, que entra no Histórico de Mensagens da Mensageria. O autor registrado é o nome da chave.\n\n## Parcerias ERP: Painel do Parceiro\n\nEscopo `parcerias:leitura` (somente leitura). Para parceiros do Programa de Parceiros LM acompanharem as indicações e revendas no próprio sistema.\n\nA chave pertence a uma empresa; a parceria é reconhecida quando o CPF/CNPJ do parceiro é o CNPJ da empresa da chave, ou quando o usuário vinculado ao parceiro tem essa empresa como principal. Sem vínculo, as rotas respondem `404`.\n\n- `GET /parceria` — dados do parceiro (código e link de indicação), resumo (indicados, contrataram, conversão, comissão prevista, devida e paga) e o painel de licenças.\n- `GET /parceria/indicacoes` — uma linha por cliente indicado (contrato vigente), com situação da licença e comissão prevista.\n- `GET /parceria/licencas-revenda` — licenças compradas pelo parceiro revendedor.\n- `GET /parceria/comissoes` — comissões geradas por pagamentos confirmados, a pagar e pagas.\n\nCadastro do parceiro, percentuais negociados e pagamento de comissões ficam com a LM (Gestão de Parceiros) e não são alterados pela API.\n\n## Isolamento de dados\n\nUma chave enxerga **apenas a empresa** para a qual foi gerada. Registros de outras empresas não existem para ela: a consulta responde `404`, a referência (por exemplo, `conta_id` apontando para a conta de outra empresa) responde `400`, e o campo `empresa_id` nunca aparece nem é aceito.\n\nAlguns dados nunca atravessam a API, em nenhuma direção: credenciais de gateway de pagamento vinculadas às contas bancárias, certificados digitais, usuários e permissões do ERP.\n\n## Webhooks\n\nEm **Documentação - ERP › Webhook - LM Gestão ERP**, cadastre uma URL HTTPS e os eventos de interesse. Cada URL cadastrada tem o seu próprio segredo de assinatura, e o corpo da entrega não identifica a empresa: cadastre uma URL por empresa (ou distinga pelo caminho da URL). O ERP faz um `POST` na URL a cada evento, com o corpo:\n\n```json\n{\n \"id\": \"entrega_id\",\n \"evento\": \"cobranca.paga\",\n \"criado_em\": \"2026-09-12T14:03:00.000Z\",\n \"dados\": { \"id\": \"…\", \"id_lancamento_cbr\": \"CBR-0000000042\", \"status\": \"Pago\" }\n}\n```\n\nOs eventos nascem das gravações feitas por esta API e dos retornos que o servidor do ERP processa (pagamento confirmado e estorno/chargeback no gateway, autorização da prefeitura). Edições feitas diretamente nas telas do ERP podem não gerar evento: para uma sincronização completa, combine os webhooks com a conferência por `alterado_desde`.\n\n### Eventos\n\n| Evento | Quando |\n|---|---|\n| `lancamento.criado` | Lançamento incluído no Fluxo de Caixa |\n| `lancamento.atualizado` | Lançamento alterado |\n| `lancamento.excluido` | Lançamento excluído |\n| `cobranca.criada` | Cobrança incluída |\n| `cobranca.atualizada` | Cobrança alterada |\n| `cobranca.paga` | Pagamento confirmado (manual ou pelo gateway) |\n| `cobranca.excluida` | Cobrança excluída |\n| `cliente_fornecedor.criado` | Cliente ou fornecedor incluído |\n| `cliente_fornecedor.atualizado` | Cliente ou fornecedor alterado |\n| `cliente_fornecedor.excluido` | Cliente ou fornecedor excluído |\n| `servico.criado` | Serviço incluído |\n| `servico.atualizado` | Serviço alterado |\n| `servico.excluido` | Serviço excluído |\n| `conta_bancaria.criada` | Conta bancária incluída |\n| `conta_bancaria.atualizada` | Conta bancária alterada |\n| `nota_fiscal.criada` | Rascunho de NFS-e incluído |\n| `nota_fiscal.atualizada` | Rascunho de NFS-e alterado |\n| `nota_fiscal.emitida` | NFS-e autorizada pela prefeitura |\n| `nota_fiscal.cancelada` | NFS-e cancelada |\n| `nota_fiscal.excluida` | Rascunho de NFS-e excluído |\n\n### Verificando a assinatura\n\nToda entrega traz o cabeçalho `X-LM-Assinatura: t=,v1=`, em que `v1` é o HMAC-SHA256, com o segredo do webhook, da string `\".\"`. Verifique **antes** de processar e rejeite carimbos com mais de 5 minutos:\n\n```js\nimport crypto from \"node:crypto\";\n\nfunction verificar(segredo, cabecalho, corpoBruto) {\n const { t, v1 } = Object.fromEntries(cabecalho.split(\",\").map((p) => p.split(\"=\")));\n if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;\n const esperado = crypto.createHmac(\"sha256\", segredo).update(`${t}.${corpoBruto}`).digest(\"hex\");\n return crypto.timingSafeEqual(Buffer.from(esperado, \"hex\"), Buffer.from(v1, \"hex\"));\n}\n```\n\n```python\nimport hmac, hashlib, time\n\ndef verificar(segredo: str, cabecalho: str, corpo_bruto: bytes) -> bool:\n partes = dict(p.split(\"=\", 1) for p in cabecalho.split(\",\"))\n if abs(time.time() - int(partes[\"t\"])) > 300:\n return False\n esperado = hmac.new(segredo.encode(), f\"{partes['t']}.\".encode() + corpo_bruto, hashlib.sha256).hexdigest()\n return hmac.compare_digest(esperado, partes[\"v1\"])\n```\n\nUse o corpo **bruto** da requisição (antes de qualquer parse) — reserializar o JSON muda bytes e invalida a assinatura.\n\n### Entrega e retentativas\n\nResponda `2xx` em até 10 segundos. Qualquer outra resposta, ou ausência dela, agenda uma nova tentativa em 1 min, 5 min, 30 min, 2 h e 12 h. Após a última, a entrega fica **esgotada** e pode ser reenviada manualmente pela tela. Vinte entregas esgotadas em sequência desativam o endpoint até você reativá-lo.\n\nEntregas podem chegar mais de uma vez (por exemplo, se o seu servidor respondeu tarde): use o `id` da entrega para descartar duplicatas.\n\n## Uso com assistentes de IA (MCP)\n\nO servidor MCP oficial, **`@lmgestao/mcp-server`**, expõe esta API como ferramentas para Claude Code, Claude Desktop, Cursor e qualquer cliente MCP. Ele herda o escopo da chave e, por padrão, é **somente leitura** — as ferramentas de inclusão, edição, exclusão e as ações (gateway, NFS-e) só aparecem com `LM_MCP_PERMITIR_ESCRITA=true`.\n\n```bash\nclaude mcp add lm-gestao -e LM_API_KEY=lm_test_... -- npx -y @lmgestao/mcp-server\n```\n\n```json\n{ \"mcpServers\": { \"lm-gestao\": { \"command\": \"npx\", \"args\": [\"-y\", \"@lmgestao/mcp-server\"], \"env\": { \"LM_API_KEY\": \"lm_test_...\" } } } }\n```\n\nFerramentas: `lm_diagnostico_chave`, `lm_listar_…` / `lm_obter_…` para os seis recursos e, com escrita, `lm_criar_…` / `lm_atualizar_…` / `lm_excluir_…`, `lm_registrar_cobranca_gateway`, `lm_emitir_nota_fiscal`, `lm_consultar_nota_fiscal` e `lm_cancelar_nota_fiscal`. Recursos `lm-gestao://openapi` (esta especificação) e `lm-gestao://guia` (o [`/llms.txt`](/llms.txt)).\n\nSem o servidor MCP, aponte o assistente para `GET /v1/openapi.json` e para o `/llms.txt`. Orientações que valem nos dois casos: use sempre o sandbox durante o desenvolvimento; peça a chave ao desenvolvedor, nunca a invente; trate `404` como \"não pertence a esta empresa\"; envie `Idempotency-Key` em todo `POST`; verifique a assinatura dos webhooks.\n\n## Versionamento\n\nO prefixo `/v1` é estável: campos podem ser **adicionados** sem aviso, nunca removidos ou renomeados. Mudanças incompatíveis chegam em `/v2`, com período de convivência anunciado nesta página.\n\n### Mudanças recentes\n\n| Versão do ERP | Mudança |\n|---|---|\n| 2.2.85 (04/10/2026) | `cpf_cnpj` de clientes/fornecedores passou a ser gravado com máscara (entrada continua aceitando os dois formatos). |\n| 2.2.86 (05/10/2026) | Novo campo somente leitura `alerta_chargeback` em lançamentos; o aviso e a reversão do chargeback emitem `lancamento.atualizado`. |\n| 2.2.88 (07/10/2026) | `POST /notas-fiscais/{id}/cancelar` responde `409` quando Parâmetros de Notas tem \"Permite cancelamento via API de Notas\" = Não (sugerido pela documentação da API de Notas; Goiânia). `rps_serie` passa a vir da \"Série do RPS/DPS\" de Parâmetros na transmissão (em branco, a nota vai sem série) e `rps_numero` fica vazio quando o \"Último RPS/DPS\" está em branco (a API de Notas numera). A competência da nota é a `data_emissao` no horário de Brasília, nunca depois de hoje. |\n| 2.2.88 (07/10/2026) | Notas da emissão automática: com \"Automatizar NFS-e\" = Não em Dados da Empresa, a confirmação do pagamento só gera o rascunho (`nota_fiscal.criada`), sem transmitir; a transmissão da nota ao cliente continua pela Mensageria. |\n| 2.2.90 (09/10/2026) | Lançamentos e cobranças: `natureza_id` e `centro_custo_id` que apontam para conta **sintética** (tipo S, que só agrupa) respondem `400 requisicao_invalida` com o campo indicado. Multa e juros de atraso deixam de ter o padrão fixo de 10% e 1%: valem `multa_perc`/`juros_perc` informados no registro ou, em branco, os Parâmetros Cobrança da empresa (zerados = sem encargos). |\n| 2.2.90 (09/10/2026) | `POST /cobrancas/{id}/registrar-gateway` e as demais ações no gateway: a recusa do Asaas volta com a descrição que ele escreveu (\"Asaas recusou criar a cobrança: ...\", chave inválida, ambiente errado, sem permissão, sem resposta), em vez de \"Erro interno\". |\n| 2.2.86 (05/10/2026) | Serviços e notas fiscais aceitam e devolvem `cst_ibs_cbs`, `classificacao_trib_ibs_cbs`, `indicador_operacao`, `tipo_operacao_ibs_cbs`, `aliquota_ibs` e `aliquota_cbs`; notas devolvem também os valores e a base do IBS/CBS. Endereço do tomador incompleto no padrão Nacional responde `400` antes da transmissão. |\n", "contact": { "name": "LM Gestão ERP", "url": "https://lmgestao.app.br" } }, "servers": [ { "url": "https://lmgestao.app.br/v1", "description": "Produção — chaves lm_live_" }, { "url": "https://homologacao.lmgestao.app.br/v1", "description": "Sandbox — chaves lm_test_. Atenção: grava no mesmo banco da empresa; use uma empresa de teste." } ], "security": [ { "ChaveApi": [] } ], "tags": [ { "name": "Diagnóstico" }, { "name": "Financeiro · Fluxo de Caixa" }, { "name": "Financeiro · Cobrança" }, { "name": "Cadastros · Clientes/Fornecedores" }, { "name": "Cadastros · Serviços" }, { "name": "Cadastros · Contas Bancárias" }, { "name": "Notas Fiscais · NFS-e" }, { "name": "Gerador de Demandas · Contatos" }, { "name": "Gerador de Demandas · Gestão de Tarefas" }, { "name": "Parcerias ERP · Painel do Parceiro" } ], "paths": { "/eu": { "get": { "tags": [ "Diagnóstico" ], "summary": "Quem sou eu", "operationId": "diagnosticoChave", "description": "Devolve o nome, ambiente, escopos e limite da chave usada. Primeiro teste de toda integração.", "responses": { "200": { "description": "Dados da chave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "chave": { "type": "string" }, "ambiente": { "type": "string", "enum": [ "producao", "sandbox" ] }, "escopos": { "type": "array", "items": { "type": "string", "enum": [ "financeiro:leitura", "financeiro:escrita", "cadastros:leitura", "cadastros:escrita", "notas_fiscais:leitura", "notas_fiscais:escrita", "gerador_demandas:leitura", "gerador_demandas:escrita", "parcerias:leitura" ] } }, "limite_por_minuto": { "type": "integer" }, "expira_em": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/NaoAutenticado" } } } }, "/eventos": { "get": { "tags": [ "Diagnóstico" ], "summary": "Catálogo de eventos de webhook", "operationId": "listarEventos", "responses": { "200": { "description": "Eventos disponíveis.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "type": "object", "properties": { "evento": { "type": "string", "enum": [ "lancamento.criado", "lancamento.atualizado", "lancamento.excluido", "cobranca.criada", "cobranca.atualizada", "cobranca.paga", "cobranca.excluida", "cliente_fornecedor.criado", "cliente_fornecedor.atualizado", "cliente_fornecedor.excluido", "servico.criado", "servico.atualizado", "servico.excluido", "conta_bancaria.criada", "conta_bancaria.atualizada", "nota_fiscal.criada", "nota_fiscal.atualizada", "nota_fiscal.emitida", "nota_fiscal.cancelada", "nota_fiscal.excluida" ] }, "descricao": { "type": "string" } } } } } } } } } } } }, "/lancamentos": { "get": { "tags": [ "Financeiro · Fluxo de Caixa" ], "summary": "Listar lançamentos", "operationId": "listar_lancamentos", "description": "Escopo `financeiro:leitura`. Lista paginada por cursor, ordenada do mais recente para o mais antigo. Com `alterado_desde`, a ordem passa a ser por `alterado_em` crescente (sincronização incremental); com `codigo_externo`, a busca é exata e sem ordenação.\n\nO ERP gera a numeração `FC-…`, calcula `valor_total`, `valor_liquido`, `status_pagamento` e a contabilização (débito/crédito) a partir da natureza financeira — ou das contas bancárias, em transferência. Textos são gravados em caixa alta.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "status_pagamento", "in": "query", "schema": { "type": "string" }, "description": "Situação do pagamento." }, { "name": "tipo_lancamento", "in": "query", "schema": { "type": "string", "enum": [ "Entrada", "Saída", "Transferência" ] }, "description": "Entrada, Saída ou Transferência." }, { "name": "cliente_fornecedor_id", "in": "query", "schema": { "type": "string" }, "description": "Id do cliente/fornecedor." }, { "name": "conta_id", "in": "query", "schema": { "type": "string" }, "description": "Id da conta bancária." }, { "name": "vencimento_de", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Vencimento a partir de (AAAA-MM-DD)." }, { "name": "vencimento_ate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Vencimento até (AAAA-MM-DD)." }, { "name": "codigo_externo", "in": "query", "schema": { "type": "string" }, "description": "Busca exata pelo identificador gravado pelo integrador em `codigo_externo`." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só registros alterados a partir deste instante (ISO 8601, ex.: 2026-09-01T00:00:00Z). Pode ser combinado com o filtro de situação e com os filtros por cliente, conta e tipo. Registros alterados apenas pela tela do ERP antes de setembro/2026 podem não ter `alterado_em`." } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Lancamento" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Financeiro · Fluxo de Caixa" ], "summary": "Incluir lançamento", "operationId": "criar_lancamentos", "description": "Escopo `financeiro:escrita`. Campos fora do esquema são ignorados.\n\nO ERP gera a numeração `FC-…`, calcula `valor_total`, `valor_liquido`, `status_pagamento` e a contabilização (débito/crédito) a partir da natureza financeira — ou das contas bancárias, em transferência. Textos são gravados em caixa alta.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LancamentoEntrada" } } } }, "responses": { "201": { "description": "Registro criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Lancamento" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/lancamentos/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Financeiro · Fluxo de Caixa" ], "summary": "Consultar lançamento", "operationId": "obter_lancamentos", "description": "Escopo `financeiro:leitura`. Registro de outra empresa responde 404.", "responses": { "200": { "description": "Registro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Lancamento" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Financeiro · Fluxo de Caixa" ], "summary": "Editar lançamento", "operationId": "atualizar_lancamentos", "description": "Escopo `financeiro:escrita`. Edição parcial: campos ausentes mantêm o valor atual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LancamentoEntrada" } } } }, "responses": { "200": { "description": "Registro atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Lancamento" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Financeiro · Fluxo de Caixa" ], "summary": "Excluir lançamento", "operationId": "excluir_lancamentos", "description": "Escopo `financeiro:escrita`.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/cobrancas": { "get": { "tags": [ "Financeiro · Cobrança" ], "summary": "Listar cobranças", "operationId": "listar_cobrancas", "description": "Escopo `financeiro:leitura`. Lista paginada por cursor, ordenada do mais recente para o mais antigo. Com `alterado_desde`, a ordem passa a ser por `alterado_em` crescente (sincronização incremental); com `codigo_externo`, a busca é exata e sem ordenação.\n\nUma cobrança criada pela API nasce pareada com um lançamento de entrada no Fluxo de Caixa (`origem_id`). Editar a cobrança repercute no lançamento. Para gerar boleto, PIX ou cartão, chame `POST /cobrancas/{id}/registrar-gateway` depois de criar; `link_pagamento` e `linha_digitavel` aparecem então. Cobranças já registradas no gateway não são editáveis pela API (409) — cancele e crie outra. Multa e juros após o vencimento: no Asaas, a cobrança é registrada com os percentuais do cadastro do cliente (`multa_percentual`, `juros_percentual`) ou, na falta deles, com os padrões da empresa em Parâmetros › Dados da Empresa; o Mercado Pago não aceita esses campos por cobrança. A resposta traz apenas `link_pagamento`, `linha_digitavel` e `nosso_numero`; PIX copia-e-cola e QR Code ficam na página do link.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Em dia", "Vencido", "Pago", "Cancelado" ] }, "description": "Situação da cobrança." }, { "name": "cliente_id", "in": "query", "schema": { "type": "string" }, "description": "Id do cliente." }, { "name": "vencimento_de", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Vencimento a partir de (AAAA-MM-DD)." }, { "name": "vencimento_ate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Vencimento até (AAAA-MM-DD)." }, { "name": "codigo_externo", "in": "query", "schema": { "type": "string" }, "description": "Busca exata pelo identificador gravado pelo integrador em `codigo_externo`." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só registros alterados a partir deste instante (ISO 8601, ex.: 2026-09-01T00:00:00Z). Pode ser combinado com o filtro de situação e com os filtros por cliente, conta e tipo. Registros alterados apenas pela tela do ERP antes de setembro/2026 podem não ter `alterado_em`." } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Cobranca" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Financeiro · Cobrança" ], "summary": "Incluir cobrança", "operationId": "criar_cobrancas", "description": "Escopo `financeiro:escrita`. Campos fora do esquema são ignorados.\n\nUma cobrança criada pela API nasce pareada com um lançamento de entrada no Fluxo de Caixa (`origem_id`). Editar a cobrança repercute no lançamento. Para gerar boleto, PIX ou cartão, chame `POST /cobrancas/{id}/registrar-gateway` depois de criar; `link_pagamento` e `linha_digitavel` aparecem então. Cobranças já registradas no gateway não são editáveis pela API (409) — cancele e crie outra. Multa e juros após o vencimento: no Asaas, a cobrança é registrada com os percentuais do cadastro do cliente (`multa_percentual`, `juros_percentual`) ou, na falta deles, com os padrões da empresa em Parâmetros › Dados da Empresa; o Mercado Pago não aceita esses campos por cobrança. A resposta traz apenas `link_pagamento`, `linha_digitavel` e `nosso_numero`; PIX copia-e-cola e QR Code ficam na página do link.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CobrancaEntrada" } } } }, "responses": { "201": { "description": "Registro criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Cobranca" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/cobrancas/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Financeiro · Cobrança" ], "summary": "Consultar cobrança", "operationId": "obter_cobrancas", "description": "Escopo `financeiro:leitura`. Registro de outra empresa responde 404.", "responses": { "200": { "description": "Registro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Cobranca" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Financeiro · Cobrança" ], "summary": "Editar cobrança", "operationId": "atualizar_cobrancas", "description": "Escopo `financeiro:escrita`. Edição parcial: campos ausentes mantêm o valor atual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CobrancaEntrada" } } } }, "responses": { "200": { "description": "Registro atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Cobranca" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Financeiro · Cobrança" ], "summary": "Excluir cobrança", "operationId": "excluir_cobrancas", "description": "Escopo `financeiro:escrita`. Cobrança paga não pode ser excluída (409). Cobrança já registrada no gateway é cancelada lá antes de ser excluída; se o gateway recusar, nada é alterado (502). O lançamento pareado criado junto com ela é excluído se ainda estiver em aberto.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/clientes-fornecedores": { "get": { "tags": [ "Cadastros · Clientes/Fornecedores" ], "summary": "Listar clientes e fornecedores", "operationId": "listar_clientes_fornecedores", "description": "Escopo `cadastros:leitura`. Lista paginada por cursor, ordenada do mais recente para o mais antigo. Com `alterado_desde`, a ordem passa a ser por `alterado_em` crescente (sincronização incremental); com `codigo_externo` ou `cpf_cnpj`, a busca é exata e sem ordenação.\n\n`cpf_cnpj` é único por empresa. Para estrangeiros, envie `is_estrangeiro: true` e `nif`.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Ativo", "Inativo", "Excluído" ] }, "description": "Ativo, Inativo ou Excluído." }, { "name": "cpf_cnpj", "in": "query", "schema": { "type": "string" }, "description": "Busca exata por CPF/CNPJ, com ou sem máscara. Como o documento é único por empresa, devolve no máximo um registro." }, { "name": "codigo_externo", "in": "query", "schema": { "type": "string" }, "description": "Busca exata pelo identificador gravado pelo integrador em `codigo_externo`." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só registros alterados a partir deste instante (ISO 8601, ex.: 2026-09-01T00:00:00Z). Pode ser combinado com o filtro de situação e com os filtros por cliente, conta e tipo. Registros alterados apenas pela tela do ERP antes de setembro/2026 podem não ter `alterado_em`." } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/ClienteFornecedor" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Cadastros · Clientes/Fornecedores" ], "summary": "Incluir cliente/fornecedor", "operationId": "criar_clientes_fornecedores", "description": "Escopo `cadastros:escrita`. Campos fora do esquema são ignorados.\n\n`cpf_cnpj` é único por empresa. Para estrangeiros, envie `is_estrangeiro: true` e `nif`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteFornecedorEntrada" } } } }, "responses": { "201": { "description": "Registro criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/ClienteFornecedor" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/clientes-fornecedores/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Cadastros · Clientes/Fornecedores" ], "summary": "Consultar cliente/fornecedor", "operationId": "obter_clientes_fornecedores", "description": "Escopo `cadastros:leitura`. Registro de outra empresa responde 404.", "responses": { "200": { "description": "Registro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/ClienteFornecedor" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Cadastros · Clientes/Fornecedores" ], "summary": "Editar cliente/fornecedor", "operationId": "atualizar_clientes_fornecedores", "description": "Escopo `cadastros:escrita`. Edição parcial: campos ausentes mantêm o valor atual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteFornecedorEntrada" } } } }, "responses": { "200": { "description": "Registro atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/ClienteFornecedor" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Cadastros · Clientes/Fornecedores" ], "summary": "Excluir cliente/fornecedor", "operationId": "excluir_clientes_fornecedores", "description": "Escopo `cadastros:escrita`. Recusada (409) quando há lançamentos, cobranças ou notas vinculados.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/servicos": { "get": { "tags": [ "Cadastros · Serviços" ], "summary": "Listar serviços", "operationId": "listar_servicos", "description": "Escopo `cadastros:leitura`. Lista paginada por cursor, ordenada do mais recente para o mais antigo. Com `alterado_desde`, a ordem passa a ser por `alterado_em` crescente (sincronização incremental); com `codigo_externo`, a busca é exata e sem ordenação.\n\nO `codigo` é sequencial e gerado pelo ERP.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Ativo", "Inativo" ] }, "description": "Ativo ou Inativo." }, { "name": "codigo_externo", "in": "query", "schema": { "type": "string" }, "description": "Busca exata pelo identificador gravado pelo integrador em `codigo_externo`." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só registros alterados a partir deste instante (ISO 8601, ex.: 2026-09-01T00:00:00Z). Pode ser combinado com o filtro de situação e com os filtros por cliente, conta e tipo. Registros alterados apenas pela tela do ERP antes de setembro/2026 podem não ter `alterado_em`." } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Servico" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Cadastros · Serviços" ], "summary": "Incluir serviço", "operationId": "criar_servicos", "description": "Escopo `cadastros:escrita`. Campos fora do esquema são ignorados.\n\nO `codigo` é sequencial e gerado pelo ERP.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoEntrada" } } } }, "responses": { "201": { "description": "Registro criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Servico" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/servicos/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Cadastros · Serviços" ], "summary": "Consultar serviço", "operationId": "obter_servicos", "description": "Escopo `cadastros:leitura`. Registro de outra empresa responde 404.", "responses": { "200": { "description": "Registro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Servico" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Cadastros · Serviços" ], "summary": "Editar serviço", "operationId": "atualizar_servicos", "description": "Escopo `cadastros:escrita`. Edição parcial: campos ausentes mantêm o valor atual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoEntrada" } } } }, "responses": { "200": { "description": "Registro atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Servico" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Cadastros · Serviços" ], "summary": "Excluir serviço", "operationId": "excluir_servicos", "description": "Escopo `cadastros:escrita`. Recusada (409) quando há NFS-e vinculada.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/contas-bancarias": { "get": { "tags": [ "Cadastros · Contas Bancárias" ], "summary": "Listar contas bancárias", "operationId": "listar_contas_bancarias", "description": "Escopo `cadastros:leitura`. Lista paginada por cursor, ordenada do mais recente para o mais antigo. Com `alterado_desde`, a ordem passa a ser por `alterado_em` crescente (sincronização incremental); com `codigo_externo`, a busca é exata e sem ordenação.\n\nAs credenciais do gateway de pagamento vinculadas à conta **nunca** são devolvidas nem aceitas pela API. Apenas os indicadores `usa_gateway`, `gateway_nome` e `gateway_ambiente` aparecem.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Ativo", "Inativo" ] }, "description": "Ativo ou Inativo (campo `situacao`)." }, { "name": "codigo_externo", "in": "query", "schema": { "type": "string" }, "description": "Busca exata pelo identificador gravado pelo integrador em `codigo_externo`." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só registros alterados a partir deste instante (ISO 8601, ex.: 2026-09-01T00:00:00Z). Pode ser combinado com o filtro de situação e com os filtros por cliente, conta e tipo. Registros alterados apenas pela tela do ERP antes de setembro/2026 podem não ter `alterado_em`." } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/ContaBancaria" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Cadastros · Contas Bancárias" ], "summary": "Incluir conta bancária", "operationId": "criar_contas_bancarias", "description": "Escopo `cadastros:escrita`. Campos fora do esquema são ignorados.\n\nAs credenciais do gateway de pagamento vinculadas à conta **nunca** são devolvidas nem aceitas pela API. Apenas os indicadores `usa_gateway`, `gateway_nome` e `gateway_ambiente` aparecem.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContaBancariaEntrada" } } } }, "responses": { "201": { "description": "Registro criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/ContaBancaria" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/contas-bancarias/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Cadastros · Contas Bancárias" ], "summary": "Consultar conta bancária", "operationId": "obter_contas_bancarias", "description": "Escopo `cadastros:leitura`. Registro de outra empresa responde 404.", "responses": { "200": { "description": "Registro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/ContaBancaria" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Cadastros · Contas Bancárias" ], "summary": "Editar conta bancária", "operationId": "atualizar_contas_bancarias", "description": "Escopo `cadastros:escrita`. Edição parcial: campos ausentes mantêm o valor atual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContaBancariaEntrada" } } } }, "responses": { "200": { "description": "Registro atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/ContaBancaria" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/notas-fiscais": { "get": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Listar notas fiscais", "operationId": "listar_notas_fiscais", "description": "Escopo `notas_fiscais:leitura`. Lista paginada por cursor, ordenada do mais recente para o mais antigo. Com `alterado_desde`, a ordem passa a ser por `alterado_em` crescente (sincronização incremental); com `codigo_externo`, a busca é exata e sem ordenação.\n\nCiclo pela API: criar o rascunho (`Em edição`) → `POST /notas-fiscais/{id}/emitir` → se `Processando`, `POST /notas-fiscais/{id}/consultar` até a prefeitura responder → `POST /notas-fiscais/{id}/cancelar` quando necessário. A transmissão usa a API de Notas configurada em Parâmetros de Notas; o certificado digital da empresa nunca passa pela API. Valores (`base_calculo`, `valor_iss`, `valor_liquido`) são calculados pelo ERP. Após a emissão, `url_pdf` e `url_xml` apontam para `GET /notas-fiscais/{id}/pdf` e `GET /notas-fiscais/{id}/xml` nesta API (escopo `notas_fiscais:leitura`), que entregam o arquivo; o endereço da API de Notas nunca é exposto.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Em edição", "Emitida", "Cancelada", "Erro", "Processando", "Processando_Cancelamento", "Erro_Cancelamento", "Substituída" ] }, "description": "Situação da nota." }, { "name": "emissao_de", "in": "query", "schema": { "type": "string" }, "description": "Emissão a partir de (ISO 8601)." }, { "name": "emissao_ate", "in": "query", "schema": { "type": "string" }, "description": "Emissão até (ISO 8601)." }, { "name": "codigo_externo", "in": "query", "schema": { "type": "string" }, "description": "Busca exata pelo identificador gravado pelo integrador em `codigo_externo`." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só registros alterados a partir deste instante (ISO 8601, ex.: 2026-09-01T00:00:00Z). Pode ser combinado com o filtro de situação e com os filtros por cliente, conta e tipo. Registros alterados apenas pela tela do ERP antes de setembro/2026 podem não ter `alterado_em`." } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/NotaFiscal" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Incluir nota fiscal (nfs-e)", "operationId": "criar_notas_fiscais", "description": "Escopo `notas_fiscais:escrita`. Campos fora do esquema são ignorados.\n\nCiclo pela API: criar o rascunho (`Em edição`) → `POST /notas-fiscais/{id}/emitir` → se `Processando`, `POST /notas-fiscais/{id}/consultar` até a prefeitura responder → `POST /notas-fiscais/{id}/cancelar` quando necessário. A transmissão usa a API de Notas configurada em Parâmetros de Notas; o certificado digital da empresa nunca passa pela API. Valores (`base_calculo`, `valor_iss`, `valor_liquido`) são calculados pelo ERP. Após a emissão, `url_pdf` e `url_xml` apontam para `GET /notas-fiscais/{id}/pdf` e `GET /notas-fiscais/{id}/xml` nesta API (escopo `notas_fiscais:leitura`), que entregam o arquivo; o endereço da API de Notas nunca é exposto.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscalEntrada" } } } }, "responses": { "201": { "description": "Registro criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/NotaFiscal" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/notas-fiscais/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Consultar nota fiscal (nfs-e)", "operationId": "obter_notas_fiscais", "description": "Escopo `notas_fiscais:leitura`. Registro de outra empresa responde 404.", "responses": { "200": { "description": "Registro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/NotaFiscal" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Editar nota fiscal (nfs-e)", "operationId": "atualizar_notas_fiscais", "description": "Escopo `notas_fiscais:escrita`. Edição parcial: campos ausentes mantêm o valor atual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscalEntrada" } } } }, "responses": { "200": { "description": "Registro atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/NotaFiscal" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Excluir nota fiscal (nfs-e)", "operationId": "excluir_notas_fiscais", "description": "Escopo `notas_fiscais:escrita`. Exclusão lógica (status `Excluída`), apenas de rascunhos (`Em edição` ou `Erro`). Nota emitida se cancela por `POST /notas-fiscais/{id}/cancelar`.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/cobrancas/{id}/registrar-gateway": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Financeiro · Cobrança" ], "summary": "Registrar no gateway de pagamento", "operationId": "registrar_gateway_cobrancas", "description": "Escopo `financeiro:escrita`. Sincroniza o cliente e cria a cobrança no gateway configurado na conta bancária (Asaas ou Mercado Pago), conforme `tipo_cobranca`: boleto/PIX, cartão, checkout ou assinatura. Preenche `link_pagamento`, `linha_digitavel` e `nosso_numero`. Cobrança já integrada responde 409; recusa do gateway responde 502 sem alterar a cobrança.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "responses": { "200": { "description": "Registro atualizado com o desfecho da operação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Cobranca" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "502": { "$ref": "#/components/responses/ServicoExterno" } } } }, "/notas-fiscais/{id}/emitir": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Transmitir à prefeitura", "operationId": "emitir_notas_fiscais", "description": "Escopo `notas_fiscais:escrita`. Reserva o número de RPS, transmite o rascunho pela API de Notas configurada em Parâmetros de Notas e grava o desfecho. `status` volta como `Emitida`, `Erro` (com `mensagem_retorno` da prefeitura) ou `Processando` — neste caso, chame `/consultar` até a prefeitura responder. Só rascunhos (`Em edição`, `Erro`) podem ser transmitidos. O limite mensal de notas do plano é respeitado.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "responses": { "200": { "description": "Registro atualizado com o desfecho da operação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/NotaFiscal" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "502": { "$ref": "#/components/responses/ServicoExterno" } } } }, "/notas-fiscais/{id}/pdf": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Baixar o PDF (DANFSE) da nota", "operationId": "pdf_notas_fiscais", "description": "Escopo `notas_fiscais:leitura`. Entrega o PDF (DANFSE) de uma nota emitida, obtido pela API de Notas com as credenciais da empresa. Responde 404 enquanto o arquivo não existir (rascunho, nota em processamento ou com erro) e 502 se a API de Notas não responder.", "responses": { "200": { "description": "Conteúdo do PDF (DANFSE).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave ausente, inválida ou de outro ambiente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } }, "403": { "description": "Chave sem o escopo `notas_fiscais:leitura`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } }, "404": { "description": "Nota inexistente para esta empresa, ou arquivo ainda indisponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } }, "502": { "description": "A API de Notas não respondeu ou recusou.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } } } } }, "/notas-fiscais/{id}/xml": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Baixar o XML da nota", "operationId": "xml_notas_fiscais", "description": "Escopo `notas_fiscais:leitura`. Entrega o XML de uma nota emitida, obtido pela API de Notas com as credenciais da empresa. Responde 404 enquanto o arquivo não existir (rascunho, nota em processamento ou com erro) e 502 se a API de Notas não responder.", "responses": { "200": { "description": "Conteúdo do XML.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave ausente, inválida ou de outro ambiente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } }, "403": { "description": "Chave sem o escopo `notas_fiscais:leitura`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } }, "404": { "description": "Nota inexistente para esta empresa, ou arquivo ainda indisponível.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } }, "502": { "description": "A API de Notas não respondeu ou recusou.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } } } } } } } }, "/notas-fiscais/{id}/consultar": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Sincronizar com a prefeitura", "operationId": "consultar_notas_fiscais", "description": "Escopo `notas_fiscais:escrita`. Consulta a situação atual na prefeitura de uma nota em processamento (emissão ou cancelamento) e atualiza o registro.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "responses": { "200": { "description": "Registro atualizado com o desfecho da operação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/NotaFiscal" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "502": { "$ref": "#/components/responses/ServicoExterno" } } } }, "/notas-fiscais/{id}/cancelar": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Notas Fiscais · NFS-e" ], "summary": "Cancelar nota emitida", "operationId": "cancelar_notas_fiscais", "description": "Escopo `notas_fiscais:escrita`. Pede o cancelamento à prefeitura. Apenas notas `Emitida` (ou `Erro_Cancelamento`, para nova tentativa). O resultado é `Cancelada`, `Processando_Cancelamento` ou `Erro_Cancelamento`. Com \"Permite cancelamento via API de Notas\" = Não em Parâmetros de Notas (sugerido pela documentação da API de Notas; Goiânia, por exemplo), responde `409`: a nota é cancelada no portal da prefeitura e registrada como cancelada no ERP.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "justificativa" ], "properties": { "justificativa": { "type": "string", "minLength": 15, "description": "Motivo do cancelamento, enviado à prefeitura (mínimo 15 caracteres)." }, "codigo_cancelamento": { "type": "string", "description": "Código de cancelamento exigido por algumas prefeituras (padrão Nacional)." } } } } } }, "responses": { "200": { "description": "Registro atualizado com o desfecho da operação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/NotaFiscal" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "502": { "$ref": "#/components/responses/ServicoExterno" } } } }, "/contatos": { "get": { "tags": [ "Gerador de Demandas · Contatos" ], "summary": "Listar contatos", "operationId": "listar_contatos", "description": "Escopo `gerador_demandas:leitura`. Ordem alfabética; com `alterado_desde`, por `atualizado_em` crescente.\n\nAgenda de contatos da empresa, compartilhada com o Multi-Atendimento (WhatsApp) e alimentada pelos formulários do site. **Não duplica**: incluir um contato com WhatsApp, e-mail ou telefone já cadastrado atualiza o existente e devolve o mesmo `id`.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "busca", "in": "query", "schema": { "type": "string" }, "description": "Nome, organização, e-mail, telefone, cliente ou etiqueta (contém, sem acento)." }, { "name": "origem", "in": "query", "schema": { "type": "string" }, "description": "whatsapp, formulario, manual, importacao, email ou trello." }, { "name": "tipo", "in": "query", "schema": { "type": "string", "enum": [ "whatsapp", "telefone", "email" ] }, "description": "Só quem tem: whatsapp, telefone ou email." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só contatos alterados a partir deste instante (ISO 8601)." } ], "responses": { "200": { "description": "Página de contatos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Contato" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Gerador de Demandas · Contatos" ], "summary": "Incluir contato", "operationId": "criar_contatos", "description": "Escopo `gerador_demandas:escrita`. Informe ao menos nome, e-mail, WhatsApp ou telefone. Campos fora do esquema são ignorados.\n\nAgenda de contatos da empresa, compartilhada com o Multi-Atendimento (WhatsApp) e alimentada pelos formulários do site. **Não duplica**: incluir um contato com WhatsApp, e-mail ou telefone já cadastrado atualiza o existente e devolve o mesmo `id`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContatoEntrada" } } } }, "responses": { "201": { "description": "Contato criado (ou o existente, atualizado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Contato" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/contatos/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Gerador de Demandas · Contatos" ], "summary": "Consultar contato", "operationId": "obter_contatos", "description": "Escopo `gerador_demandas:leitura`. Contato de outra empresa responde 404.", "responses": { "200": { "description": "Contato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Contato" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Gerador de Demandas · Contatos" ], "summary": "Editar contato", "operationId": "atualizar_contatos", "description": "Escopo `gerador_demandas:escrita`. Edição parcial. Trocar o WhatsApp para um número de outro contato responde 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContatoEntrada" } } } }, "responses": { "200": { "description": "Contato atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Contato" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "409": { "$ref": "#/components/responses/Conflito" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Gerador de Demandas · Contatos" ], "summary": "Excluir contato", "operationId": "excluir_contatos", "description": "Escopo `gerador_demandas:escrita`. As tarefas e conversas do contato continuam; perdem só o vínculo.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/quadros": { "get": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Listar quadros", "operationId": "listar_quadros", "description": "Escopo `gerador_demandas:leitura`. Quadros da Gestão de Tarefas com as listas (colunas). Use o `id` do quadro e da lista para criar e mover tarefas. Automações e o endereço de e-mail do quadro não são expostos.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "incluir_arquivados", "in": "query", "schema": { "type": "boolean" }, "description": "true para trazer quadros arquivados." } ], "responses": { "200": { "description": "Página de quadros.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Quadro" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/quadros/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Consultar quadro", "operationId": "obter_quadros", "description": "Escopo `gerador_demandas:leitura`.", "responses": { "200": { "description": "Quadro.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Quadro" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/tarefas": { "get": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Listar tarefas", "operationId": "listar_tarefas", "description": "Escopo `gerador_demandas:leitura`. Ordem do quadro; com `alterado_desde`, por `atualizado_em` crescente.", "parameters": [ { "name": "limite", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Itens por página." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de `paginacao.proximo_cursor` da página anterior." }, { "name": "quadro_id", "in": "query", "schema": { "type": "string" }, "description": "Só deste quadro." }, { "name": "situacao", "in": "query", "schema": { "type": "string", "enum": [ "no_prazo", "agendada", "vencida", "aguardando", "concluida" ] }, "description": "Situação calculada." }, { "name": "contato_id", "in": "query", "schema": { "type": "string" }, "description": "Só deste contato." }, { "name": "cliente_id", "in": "query", "schema": { "type": "string" }, "description": "Só deste cliente/fornecedor." }, { "name": "responsavel_id", "in": "query", "schema": { "type": "string" }, "description": "Só deste responsável (tarefa ou subtarefa)." }, { "name": "de", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Início, prazo ou prazo de subtarefa a partir de (ISO 8601)." }, { "name": "ate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "… até (ISO 8601)." }, { "name": "incluir_concluidas", "in": "query", "schema": { "type": "boolean" }, "description": "false para esconder as concluídas (padrão: true)." }, { "name": "incluir_arquivadas", "in": "query", "schema": { "type": "boolean" }, "description": "true para trazer as arquivadas." }, { "name": "alterado_desde", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Só tarefas alteradas a partir deste instante (ISO 8601)." } ], "responses": { "200": { "description": "Página de tarefas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Tarefa" } }, "paginacao": { "type": "object", "properties": { "limite": { "type": "integer" }, "proximo_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "post": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Incluir tarefa", "operationId": "criar_tarefas", "description": "Escopo `gerador_demandas:escrita`. `quadro_id` e `titulo` obrigatórios.\n\nTarefa criada ou movida pela API dispara as automações do quadro (mover, atribuir, avisar o cliente por WhatsApp/e-mail/SMS), como na tela. O autor registrado é a chave de integração.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarefaEntrada" } } } }, "responses": { "201": { "description": "Tarefa criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Tarefa" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/tarefas/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Consultar tarefa", "operationId": "obter_tarefas", "description": "Escopo `gerador_demandas:leitura`.", "responses": { "200": { "description": "Tarefa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Tarefa" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "put": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Editar ou mover tarefa", "operationId": "atualizar_tarefas", "description": "Escopo `gerador_demandas:escrita`. Edição parcial; `lista_id`/`quadro_id` movem a tarefa.\n\nTarefa criada ou movida pela API dispara as automações do quadro (mover, atribuir, avisar o cliente por WhatsApp/e-mail/SMS), como na tela. O autor registrado é a chave de integração.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarefaEntrada" } } } }, "responses": { "200": { "description": "Tarefa atualizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Tarefa" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } }, "delete": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Excluir tarefa", "operationId": "excluir_tarefas", "description": "Escopo `gerador_demandas:escrita`. Remove também os anexos.", "responses": { "200": { "description": "Registro excluído.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "properties": { "id": { "type": "string" }, "excluido": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/tarefas/{id}/concluir": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Concluir tarefa", "operationId": "concluir_tarefas", "description": "Escopo `gerador_demandas:escrita`. Marca como concluída (move para a lista de concluídas, se o quadro tiver) e dispara as automações de conclusão.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "responses": { "200": { "description": "Tarefa atualizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Tarefa" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/tarefas/{id}/reabrir": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Reabrir tarefa", "operationId": "reabrir_tarefas", "description": "Escopo `gerador_demandas:escrita`. Volta a tarefa concluída para a primeira lista.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "responses": { "200": { "description": "Tarefa atualizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Tarefa" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/tarefas/{id}/comentarios": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Gerador de Demandas · Gestão de Tarefas" ], "summary": "Comentar tarefa", "operationId": "comentar_tarefas", "description": "Escopo `gerador_demandas:escrita`. O comentário entra no histórico da tarefa, com a chave como autor.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Repetir o POST com a mesma chave devolve a mesma resposta sem criar de novo (24 h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "texto" ], "properties": { "texto": { "type": "string", "maxLength": 4000 } } } } } }, "responses": { "201": { "description": "Tarefa com o comentário registrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Tarefa" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/parceria": { "get": { "tags": [ "Parcerias ERP · Painel do Parceiro" ], "summary": "Dados e resumo da parceria", "operationId": "obter_parceria", "description": "Escopo `parcerias:leitura`. A chave identifica uma empresa; a parceria é reconhecida quando o CPF/CNPJ do parceiro é o CNPJ da empresa da chave, ou quando o usuário vinculado ao parceiro tem essa empresa como principal. Sem vínculo responde 404. Somente leitura: cadastro, percentuais e pagamentos de comissão ficam com a LM (Gestão de Parceiros).", "responses": { "200": { "description": "Parceria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Parceria" } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/parceria/indicacoes": { "get": { "tags": [ "Parcerias ERP · Painel do Parceiro" ], "summary": "Indicações (licenças comissionadas)", "operationId": "listar_parceria_indicacoes", "description": "Escopo `parcerias:leitura`. Uma linha por cliente (contrato vigente). A chave identifica uma empresa; a parceria é reconhecida quando o CPF/CNPJ do parceiro é o CNPJ da empresa da chave, ou quando o usuário vinculado ao parceiro tem essa empresa como principal. Sem vínculo responde 404. Somente leitura: cadastro, percentuais e pagamentos de comissão ficam com a LM (Gestão de Parceiros).", "responses": { "200": { "description": "Lista completa (sem paginação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/LicencaParceiro" } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/parceria/licencas-revenda": { "get": { "tags": [ "Parcerias ERP · Painel do Parceiro" ], "summary": "Licenças de revenda", "operationId": "listar_parceria_licencas_revenda", "description": "Escopo `parcerias:leitura`. Uma linha por cliente (contrato vigente). A chave identifica uma empresa; a parceria é reconhecida quando o CPF/CNPJ do parceiro é o CNPJ da empresa da chave, ou quando o usuário vinculado ao parceiro tem essa empresa como principal. Sem vínculo responde 404. Somente leitura: cadastro, percentuais e pagamentos de comissão ficam com a LM (Gestão de Parceiros).", "responses": { "200": { "description": "Lista completa (sem paginação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/LicencaParceiro" } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/parceria/comissoes": { "get": { "tags": [ "Parcerias ERP · Painel do Parceiro" ], "summary": "Comissões", "operationId": "listar_parceria_comissoes", "description": "Escopo `parcerias:leitura`. Uma linha por cliente (contrato vigente). A chave identifica uma empresa; a parceria é reconhecida quando o CPF/CNPJ do parceiro é o CNPJ da empresa da chave, ou quando o usuário vinculado ao parceiro tem essa empresa como principal. Sem vínculo responde 404. Somente leitura: cadastro, percentuais e pagamentos de comissão ficam com a LM (Gestão de Parceiros).", "responses": { "200": { "description": "Lista completa (sem paginação).", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/ComissaoParceiro" } } } } } } }, "400": { "$ref": "#/components/responses/RequisicaoInvalida" }, "401": { "$ref": "#/components/responses/NaoAutenticado" }, "403": { "$ref": "#/components/responses/EscopoInsuficiente" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } } }, "webhooks": { "lancamento.criado": { "post": { "summary": "Lançamento incluído no Fluxo de Caixa", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "lancamento.criado" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "lancamento.criado" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "lancamento.atualizado": { "post": { "summary": "Lançamento alterado", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "lancamento.atualizado" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "lancamento.atualizado" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "lancamento.excluido": { "post": { "summary": "Lançamento excluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "lancamento.excluido" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "lancamento.excluido" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cobranca.criada": { "post": { "summary": "Cobrança incluída", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cobranca.criada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cobranca.criada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cobranca.atualizada": { "post": { "summary": "Cobrança alterada", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cobranca.atualizada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cobranca.atualizada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cobranca.paga": { "post": { "summary": "Pagamento confirmado (manual ou pelo gateway)", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cobranca.paga" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cobranca.paga" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cobranca.excluida": { "post": { "summary": "Cobrança excluída", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cobranca.excluida" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cobranca.excluida" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cliente_fornecedor.criado": { "post": { "summary": "Cliente ou fornecedor incluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cliente_fornecedor.criado" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cliente_fornecedor.criado" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cliente_fornecedor.atualizado": { "post": { "summary": "Cliente ou fornecedor alterado", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cliente_fornecedor.atualizado" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cliente_fornecedor.atualizado" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "cliente_fornecedor.excluido": { "post": { "summary": "Cliente ou fornecedor excluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "cliente_fornecedor.excluido" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "cliente_fornecedor.excluido" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "servico.criado": { "post": { "summary": "Serviço incluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "servico.criado" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "servico.criado" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "servico.atualizado": { "post": { "summary": "Serviço alterado", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "servico.atualizado" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "servico.atualizado" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "servico.excluido": { "post": { "summary": "Serviço excluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "servico.excluido" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "servico.excluido" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "conta_bancaria.criada": { "post": { "summary": "Conta bancária incluída", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "conta_bancaria.criada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "conta_bancaria.criada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "conta_bancaria.atualizada": { "post": { "summary": "Conta bancária alterada", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "conta_bancaria.atualizada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "conta_bancaria.atualizada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "nota_fiscal.criada": { "post": { "summary": "Rascunho de NFS-e incluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "nota_fiscal.criada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "nota_fiscal.criada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "nota_fiscal.atualizada": { "post": { "summary": "Rascunho de NFS-e alterado", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "nota_fiscal.atualizada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "nota_fiscal.atualizada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "nota_fiscal.emitida": { "post": { "summary": "NFS-e autorizada pela prefeitura", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "nota_fiscal.emitida" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "nota_fiscal.emitida" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "nota_fiscal.cancelada": { "post": { "summary": "NFS-e cancelada", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "nota_fiscal.cancelada" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "nota_fiscal.cancelada" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } }, "nota_fiscal.excluida": { "post": { "summary": "Rascunho de NFS-e excluído", "description": "Entrega assinada. Verifique `X-LM-Assinatura` antes de processar (veja o guia). Responda 2xx em até 10 s; qualquer outra resposta agenda retentativa.", "parameters": [ { "name": "X-LM-Evento", "in": "header", "schema": { "type": "string", "enum": [ "nota_fiscal.excluida" ] } }, { "name": "X-LM-Entrega-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-LM-Assinatura", "in": "header", "schema": { "type": "string" }, "description": "`t=,v1=`" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id da entrega (igual a X-LM-Entrega-Id)." }, "evento": { "type": "string", "enum": [ "nota_fiscal.excluida" ] }, "criado_em": { "type": "string", "format": "date-time" }, "dados": { "type": "object", "description": "Representação pública do registro, no mesmo formato das respostas da API." } } } } } }, "responses": { "200": { "description": "Recebido." } } } } }, "components": { "securitySchemes": { "ChaveApi": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Chave gerada no ERP em Documentação - ERP > API - LM Gestão ERP. Também aceita `Authorization: Bearer `." } }, "schemas": { "Erro": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "requisicao_invalida", "nao_autenticado", "escopo_insuficiente", "acesso_negado", "nao_encontrado", "conflito", "dependencia_existente", "limite_excedido", "servico_externo", "erro_interno" ] }, "mensagem": { "type": "string" }, "campos": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string" }, "mensagem": { "type": "string" } } } }, "id_requisicao": { "type": "string", "format": "uuid", "description": "Informe ao suporte ao relatar um problema." } }, "required": [ "codigo", "mensagem", "id_requisicao" ] } } }, "Lancamento": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro. Gerado pelo ERP." }, "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "id_lancamento_fc": { "type": "string", "description": "Numeração sequencial do Fluxo de Caixa (FC-0000000000). Gerada pelo ERP." }, "descricao": { "type": "string" }, "tipo_lancamento": { "type": "string", "enum": [ "Entrada", "Saída", "Transferência" ] }, "valor_original": { "type": "number", "description": "Maior que zero." }, "valor_total": { "type": "number" }, "valor_liquido": { "type": "number", "description": "Calculado: valor_servicos − descontos − ISS retido − demais retenções." }, "valor_pago": { "type": "number" }, "data_vencimento": { "type": "string", "format": "date", "description": "Formato AAAA-MM-DD." }, "data_pagamento": { "type": "string", "format": "date", "description": "Formato AAAA-MM-DD." }, "data_inclusao": { "type": "string", "format": "date" }, "status_pagamento": { "type": "string", "enum": [ "Liquidado", "Parcial", "Em Aberto", "Vencido", "Em dia", "Previsto" ] }, "pago_recebido": { "type": "boolean" }, "dias_atraso": { "type": "number" }, "dias_correntes": { "type": "number" }, "desconto_perc": { "type": "number" }, "desconto_valor": { "type": "number" }, "juros_perc": { "type": "number" }, "juros_valor": { "type": "number" }, "multa_perc": { "type": "number" }, "multa_valor": { "type": "number" }, "numero_documento": { "type": "string" }, "numero_parcela": { "type": "string" }, "observacoes_complementares": { "type": "string" }, "cliente_fornecedor_id": { "type": "string" }, "natureza_id": { "type": "string" }, "conta_id": { "type": "string" }, "conta_origem_id": { "type": "string", "description": "Obrigatório em transferência." }, "conta_destino_id": { "type": "string", "description": "Obrigatório em transferência; diferente da origem." }, "centro_custo_id": { "type": "string" }, "departamento_id": { "type": "string" }, "projeto_id": { "type": "string" }, "veiculo_id": { "type": "string" }, "vendedor_id": { "type": "string" }, "tipo_pagamento_id": { "type": "string" }, "tipo_movimento": { "type": "string", "enum": [ "Mensal", "Avulso", "Assinatura", "Contrato" ] }, "prazo_id": { "type": "string" }, "conciliado": { "type": "boolean" }, "origem": { "type": "string" }, "alerta_chargeback": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "Chargeback", "Estorno" ] }, "evento": { "type": "string", "description": "Evento do webhook do gateway (ex.: PAYMENT_CHARGEBACK_REQUESTED)." }, "status_gateway": { "type": "string" }, "gateway": { "type": "string" }, "cobranca_id": { "type": "string" }, "payment_id": { "type": "string", "description": "Id do pagamento no gateway." }, "valor": { "type": "number" }, "data": { "type": "string", "format": "date-time" }, "resolvido": { "type": "boolean" }, "resolvido_em": { "type": "string", "format": "date-time" }, "resolvido_por": { "type": "string" }, "motivo_resolucao": { "type": "string" } }, "description": "Presente quando o gateway estornou ou contestou (chargeback) um pagamento já baixado deste lançamento. Enquanto `resolvido` for false, o lançamento fica fora da conciliação automática e precisa ser revisado na tela. Só gateways que enviam chargeback pelo webhook (hoje, Asaas). Somente leitura." }, "criado_em": { "type": "string", "format": "date-time", "description": "Instante da criação (ISO 8601)." }, "criado_por": { "type": "string", "description": "Quem incluiu o registro: nome do usuário do ERP ou nome desta chave de integração. Somente leitura." }, "criado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da inclusão: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "alterado_em": { "type": "string", "format": "date-time", "description": "Instante da última alteração pelo ERP ou pela API (ISO 8601). Base do filtro `alterado_desde`." }, "alterado_por": { "type": "string", "description": "Quem fez a última alteração: nome do usuário do ERP ou nome da chave de integração. Somente leitura." }, "alterado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da última alteração: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." } }, "required": [ "id" ] }, "LancamentoEntrada": { "type": "object", "properties": { "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "descricao": { "type": "string" }, "tipo_lancamento": { "type": "string", "enum": [ "Entrada", "Saída", "Transferência" ] }, "valor_original": { "type": "number", "description": "Maior que zero." }, "data_vencimento": { "type": "string", "format": "date", "description": "Formato AAAA-MM-DD." }, "data_pagamento": { "type": "string", "format": "date", "description": "Formato AAAA-MM-DD." }, "valor_pago": { "type": "number" }, "desconto_perc": { "type": "number" }, "desconto_valor": { "type": "number" }, "juros_perc": { "type": "number" }, "juros_valor": { "type": "number" }, "multa_perc": { "type": "number" }, "multa_valor": { "type": "number" }, "numero_documento": { "type": "string" }, "numero_parcela": { "type": "string" }, "observacoes_complementares": { "type": "string" }, "cliente_fornecedor_id": { "type": "string" }, "natureza_id": { "type": "string" }, "conta_id": { "type": "string" }, "conta_origem_id": { "type": "string", "description": "Obrigatório em transferência." }, "conta_destino_id": { "type": "string", "description": "Obrigatório em transferência; diferente da origem." }, "centro_custo_id": { "type": "string" }, "departamento_id": { "type": "string" }, "projeto_id": { "type": "string" }, "veiculo_id": { "type": "string" }, "vendedor_id": { "type": "string" }, "tipo_pagamento_id": { "type": "string" }, "tipo_movimento": { "type": "string", "enum": [ "Mensal", "Avulso", "Assinatura", "Contrato" ] }, "prazo_id": { "type": "string" } }, "required": [ "descricao", "tipo_lancamento", "valor_original", "data_vencimento" ], "additionalProperties": false }, "Cobranca": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro. Gerado pelo ERP." }, "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "id_lancamento_cbr": { "type": "string", "description": "Numeração sequencial da cobrança (CBR-0000000000). Gerada pelo ERP." }, "descricao": { "type": "string" }, "valor": { "type": "number" }, "data_vencimento": { "type": "string", "format": "date", "description": "Formato AAAA-MM-DD." }, "status": { "type": "string", "enum": [ "Em dia", "Vencido", "Pago", "Cancelado" ], "description": "Situação do registro." }, "cliente_id": { "type": "string" }, "banco": { "type": "string", "description": "Id da conta bancária de recebimento." }, "natureza_id": { "type": "string" }, "vendedor_id": { "type": "string" }, "tipo_cobranca": { "type": "string", "enum": [ "BOLETO", "PIX", "CREDIT_CARD", "UNDEFINED" ] }, "tipo_movimento": { "type": "string", "enum": [ "Mensal", "Avulso", "Assinatura", "Contrato" ] }, "numero_parcela": { "type": "string" }, "numero_documento": { "type": "string" }, "nosso_numero": { "type": "string" }, "observacoes": { "type": "string" }, "modulo_origem": { "type": "string" }, "origem_id": { "type": "string", "description": "Id do lançamento pareado no Fluxo de Caixa." }, "gateway": { "type": "string" }, "status_integracao": { "type": "string" }, "link_pagamento": { "type": "string", "description": "Preenchido após `POST /cobrancas/{id}/registrar-gateway`." }, "linha_digitavel": { "type": "string", "description": "Preenchida após `POST /cobrancas/{id}/registrar-gateway`." }, "integrar_nfse": { "type": "boolean" }, "criado_em": { "type": "string", "format": "date-time", "description": "Instante da criação (ISO 8601)." }, "criado_por": { "type": "string", "description": "Quem incluiu o registro: nome do usuário do ERP ou nome desta chave de integração. Somente leitura." }, "criado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da inclusão: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "alterado_em": { "type": "string", "format": "date-time", "description": "Instante da última alteração pelo ERP ou pela API (ISO 8601). Base do filtro `alterado_desde`." }, "alterado_por": { "type": "string", "description": "Quem fez a última alteração: nome do usuário do ERP ou nome da chave de integração. Somente leitura." }, "alterado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da última alteração: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." } }, "required": [ "id" ] }, "CobrancaEntrada": { "type": "object", "properties": { "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "descricao": { "type": "string" }, "valor": { "type": "number" }, "data_vencimento": { "type": "string", "format": "date", "description": "Formato AAAA-MM-DD." }, "cliente_id": { "type": "string" }, "banco": { "type": "string", "description": "Id da conta bancária de recebimento." }, "natureza_id": { "type": "string" }, "vendedor_id": { "type": "string" }, "tipo_cobranca": { "type": "string", "enum": [ "BOLETO", "PIX", "CREDIT_CARD", "UNDEFINED" ] }, "tipo_movimento": { "type": "string", "enum": [ "Mensal", "Avulso", "Assinatura", "Contrato" ] }, "numero_parcela": { "type": "string" }, "numero_documento": { "type": "string" }, "observacoes": { "type": "string" }, "status": { "type": "string", "enum": [ "Em dia", "Vencido", "Pago", "Cancelado" ], "description": "Situação do registro." } }, "required": [ "cliente_id", "valor", "data_vencimento" ], "additionalProperties": false }, "ClienteFornecedor": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro. Gerado pelo ERP." }, "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "nome": { "type": "string" }, "razao_social": { "type": "string" }, "nome_fantasia": { "type": "string" }, "cpf_cnpj": { "type": "string", "description": "CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00). Na entrada, com ou sem máscara: a API grava com a máscara, padrão do ERP desde a versão 2.2.85. Registros antigos podem vir só com dígitos; a busca por `cpf_cnpj` acha os dois formatos." }, "is_estrangeiro": { "type": "boolean" }, "nif": { "type": "string" }, "regime_tributario": { "type": "string", "enum": [ "0 - PF - Autônomo", "1 - MEI", "2 - Simples Nacional", "3 - Lucro Presumido", "4 - Lucro Real" ] }, "inscricao_municipal": { "type": "string" }, "inscricao_estadual": { "type": "string" }, "email_pessoal": { "type": "string" }, "email_financeiro": { "type": "string" }, "email_cnpj": { "type": "string" }, "telefone_pessoal": { "type": "string" }, "telefone_corporativo": { "type": "string" }, "telefone_cnpj": { "type": "string" }, "logradouro": { "type": "string" }, "numero": { "type": "string" }, "complemento": { "type": "string" }, "bairro": { "type": "string" }, "cidade": { "type": "string" }, "codigo_municipio": { "type": "string" }, "uf": { "type": "string" }, "cep": { "type": "string", "description": "Somente dígitos." }, "categorias": { "type": "array", "items": { "type": "string" } }, "tipo_cliente": { "type": "string", "enum": [ "Mensal", "Avulso", "Assinatura", "Contrato" ] }, "vendedor_id": { "type": "string" }, "limite_credito": { "type": "number" }, "contatos": { "type": "array", "items": { "type": "object", "properties": { "contato": { "type": "string" }, "funcao": { "type": "string" }, "telefone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "enviar_cobranca": { "type": "boolean" } } } }, "multa_percentual": { "type": "number" }, "juros_percentual": { "type": "number" }, "status": { "type": "string", "enum": [ "Ativo", "Inativo", "Excluído" ], "description": "Situação do registro." }, "criado_em": { "type": "string", "format": "date-time", "description": "Instante da criação (ISO 8601)." }, "criado_por": { "type": "string", "description": "Quem incluiu o registro: nome do usuário do ERP ou nome desta chave de integração. Somente leitura." }, "criado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da inclusão: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "alterado_em": { "type": "string", "format": "date-time", "description": "Instante da última alteração pelo ERP ou pela API (ISO 8601). Base do filtro `alterado_desde`." }, "alterado_por": { "type": "string", "description": "Quem fez a última alteração: nome do usuário do ERP ou nome da chave de integração. Somente leitura." }, "alterado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da última alteração: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." } }, "required": [ "id" ] }, "ClienteFornecedorEntrada": { "type": "object", "properties": { "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "nome": { "type": "string" }, "razao_social": { "type": "string" }, "nome_fantasia": { "type": "string" }, "cpf_cnpj": { "type": "string", "description": "CPF (000.000.000-00) ou CNPJ (00.000.000/0000-00). Na entrada, com ou sem máscara: a API grava com a máscara, padrão do ERP desde a versão 2.2.85. Registros antigos podem vir só com dígitos; a busca por `cpf_cnpj` acha os dois formatos." }, "is_estrangeiro": { "type": "boolean" }, "nif": { "type": "string" }, "motivo_ausencia_nif": { "type": "string" }, "regime_tributario": { "type": "string", "enum": [ "0 - PF - Autônomo", "1 - MEI", "2 - Simples Nacional", "3 - Lucro Presumido", "4 - Lucro Real" ] }, "inscricao_municipal": { "type": "string" }, "inscricao_estadual": { "type": "string" }, "email_pessoal": { "type": "string" }, "email_financeiro": { "type": "string" }, "email_cnpj": { "type": "string" }, "telefone_pessoal": { "type": "string" }, "telefone_corporativo": { "type": "string" }, "telefone_cnpj": { "type": "string" }, "logradouro": { "type": "string" }, "numero": { "type": "string" }, "complemento": { "type": "string" }, "bairro": { "type": "string" }, "cidade": { "type": "string" }, "codigo_municipio": { "type": "string" }, "uf": { "type": "string" }, "cep": { "type": "string", "description": "Somente dígitos." }, "categorias": { "type": "array", "items": { "type": "string" } }, "tipo_cliente": { "type": "string", "enum": [ "Mensal", "Avulso", "Assinatura", "Contrato" ] }, "vendedor_id": { "type": "string" }, "limite_credito": { "type": "number" }, "contatos": { "type": "array", "items": { "type": "object", "properties": { "contato": { "type": "string" }, "funcao": { "type": "string" }, "telefone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "enviar_cobranca": { "type": "boolean" } } } }, "multa_percentual": { "type": "number" }, "juros_percentual": { "type": "number" }, "status": { "type": "string", "enum": [ "Ativo", "Inativo", "Excluído" ], "description": "Situação do registro." } }, "required": [ "nome", "cpf_cnpj" ], "additionalProperties": false }, "Servico": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro. Gerado pelo ERP." }, "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "codigo": { "type": "string", "description": "Código sequencial do serviço (0001, 0002…). Gerado pelo ERP; ignorado se enviado." }, "nome": { "type": "string" }, "descricao": { "type": "string" }, "valor": { "type": "number" }, "codigo_servico_municipal": { "type": "string" }, "aliquota_iss": { "type": "number" }, "aliquota_iss_ret": { "type": "number" }, "aliquota_pis": { "type": "number" }, "aliquota_cofins": { "type": "number" }, "aliquota_csll": { "type": "number" }, "aliquota_inss": { "type": "number" }, "aliquota_irrf": { "type": "number" }, "aliquota_ibs": { "type": "number", "description": "Alíquota do IBS em percentual. Na nota, omitida, vem do serviço." }, "aliquota_cbs": { "type": "number", "description": "Alíquota da CBS em percentual. Na nota, omitida, vem do serviço." }, "cst_ibs_cbs": { "type": "string", "description": "CST do IBS/CBS (reforma tributária), 3 dígitos. O mesmo código vale para os dois tributos. Na nota, omitido, vem do serviço." }, "classificacao_trib_ibs_cbs": { "type": "string", "description": "Classificação tributária do IBS/CBS (cClassTrib), 6 dígitos. Na nota, omitida, vem do serviço." }, "indicador_operacao": { "type": "string", "description": "Indicador de operação do IBS/CBS (cIndOp), 6 dígitos. Na nota, omitido, vem do serviço." }, "tipo_operacao_ibs_cbs": { "type": "string", "description": "Tipo de operação do IBS/CBS (tpOper, 1 a 5). Obrigatório nos itens 10.05, 15.09, 17.12 e 25.05 da LC 116 e recusado nos demais. Na nota, omitido, vem do serviço." }, "status": { "type": "string", "enum": [ "Ativo", "Inativo" ], "description": "Situação do registro." }, "criado_em": { "type": "string", "format": "date-time", "description": "Instante da criação (ISO 8601)." }, "criado_por": { "type": "string", "description": "Quem incluiu o registro: nome do usuário do ERP ou nome desta chave de integração. Somente leitura." }, "criado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da inclusão: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "alterado_em": { "type": "string", "format": "date-time", "description": "Instante da última alteração pelo ERP ou pela API (ISO 8601). Base do filtro `alterado_desde`." }, "alterado_por": { "type": "string", "description": "Quem fez a última alteração: nome do usuário do ERP ou nome da chave de integração. Somente leitura." }, "alterado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da última alteração: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." } }, "required": [ "id" ] }, "ServicoEntrada": { "type": "object", "properties": { "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "nome": { "type": "string" }, "descricao": { "type": "string" }, "valor": { "type": "number" }, "codigo_servico_municipal": { "type": "string" }, "aliquota_iss": { "type": "number" }, "aliquota_iss_ret": { "type": "number" }, "aliquota_pis": { "type": "number" }, "aliquota_cofins": { "type": "number" }, "aliquota_csll": { "type": "number" }, "aliquota_inss": { "type": "number" }, "aliquota_irrf": { "type": "number" }, "aliquota_ibs": { "type": "number", "description": "Alíquota do IBS em percentual. Na nota, omitida, vem do serviço." }, "aliquota_cbs": { "type": "number", "description": "Alíquota da CBS em percentual. Na nota, omitida, vem do serviço." }, "cst_ibs_cbs": { "type": "string", "description": "CST do IBS/CBS (reforma tributária), 3 dígitos. O mesmo código vale para os dois tributos. Na nota, omitido, vem do serviço." }, "classificacao_trib_ibs_cbs": { "type": "string", "description": "Classificação tributária do IBS/CBS (cClassTrib), 6 dígitos. Na nota, omitida, vem do serviço." }, "indicador_operacao": { "type": "string", "description": "Indicador de operação do IBS/CBS (cIndOp), 6 dígitos. Na nota, omitido, vem do serviço." }, "tipo_operacao_ibs_cbs": { "type": "string", "description": "Tipo de operação do IBS/CBS (tpOper, 1 a 5). Obrigatório nos itens 10.05, 15.09, 17.12 e 25.05 da LC 116 e recusado nos demais. Na nota, omitido, vem do serviço." }, "status": { "type": "string", "enum": [ "Ativo", "Inativo" ], "description": "Situação do registro." } }, "required": [ "nome" ], "additionalProperties": false }, "ContaBancaria": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro. Gerado pelo ERP." }, "tipo_conta": { "type": "string", "enum": [ "Bancária", "Caixa Físico" ] }, "situacao": { "type": "string", "enum": [ "Ativo", "Inativo" ] }, "codigo_banco": { "type": "string" }, "nome_banco": { "type": "string" }, "descricao": { "type": "string" }, "agencia": { "type": "string" }, "numero_conta": { "type": "string" }, "tipo_modalidade": { "type": "string", "enum": [ "Corrente", "Poupança", "Investimentos" ] }, "saldo_inicial": { "type": "number" }, "data_saldo_inicial": { "type": "string", "format": "date" }, "chave_pix": { "type": "string" }, "limite_cheque_especial": { "type": "number" }, "identificador_caixa_fisico": { "type": "string" }, "conta_contabil_id": { "type": "string" }, "usa_gateway": { "type": "boolean" }, "gateway_nome": { "type": "string" }, "gateway_ambiente": { "type": "string" }, "criado_em": { "type": "string", "format": "date-time", "description": "Instante da criação (ISO 8601)." }, "criado_por": { "type": "string", "description": "Quem incluiu o registro: nome do usuário do ERP ou nome desta chave de integração. Somente leitura." }, "criado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da inclusão: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "alterado_em": { "type": "string", "format": "date-time", "description": "Instante da última alteração pelo ERP ou pela API (ISO 8601). Base do filtro `alterado_desde`." }, "alterado_por": { "type": "string", "description": "Quem fez a última alteração: nome do usuário do ERP ou nome da chave de integração. Somente leitura." }, "alterado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da última alteração: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." } }, "required": [ "id" ] }, "ContaBancariaEntrada": { "type": "object", "properties": { "tipo_conta": { "type": "string", "enum": [ "Bancária", "Caixa Físico" ] }, "situacao": { "type": "string", "enum": [ "Ativo", "Inativo" ] }, "codigo_banco": { "type": "string" }, "nome_banco": { "type": "string" }, "descricao": { "type": "string" }, "agencia": { "type": "string" }, "numero_conta": { "type": "string" }, "tipo_modalidade": { "type": "string", "enum": [ "Corrente", "Poupança", "Investimentos" ] }, "saldo_inicial": { "type": "number" }, "data_saldo_inicial": { "type": "string", "format": "date" }, "chave_pix": { "type": "string" }, "limite_cheque_especial": { "type": "number" }, "nome_gerente": { "type": "string" }, "telefone_gerente": { "type": "string" }, "identificador_caixa_fisico": { "type": "string" }, "conta_contabil_id": { "type": "string" } }, "required": [ "descricao", "tipo_conta" ], "additionalProperties": false }, "NotaFiscal": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do registro. Gerado pelo ERP." }, "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "id_lancamento_nfse": { "type": "string", "description": "Numeração sequencial da nota (NFSE-0000000000). Gerada pelo ERP." }, "id_lancamento_fc": { "type": "string", "description": "Numeração sequencial do Fluxo de Caixa (FC-0000000000). Gerada pelo ERP." }, "numero_documento": { "type": "string" }, "numero_nfs": { "type": "string" }, "rps_numero": { "type": "string", "description": "Número do RPS, definido pelo ERP na transmissão: o \"Último RPS/DPS\" de Parâmetros de Notas + 1 (em branco em Parâmetros, a API de Notas numera)." }, "rps_serie": { "type": "string", "description": "Série do RPS/DPS da transmissão: a \"Série do RPS/DPS\" de Parâmetros de Notas (em branco, a nota vai sem série). Somente leitura." }, "codigo_verificacao": { "type": "string" }, "status": { "type": "string", "enum": [ "Em edição", "Emitida", "Cancelada", "Erro", "Processando", "Processando_Cancelamento", "Erro_Cancelamento", "Substituída" ], "description": "Situação do registro." }, "mensagem_retorno": { "type": "string" }, "data_emissao": { "type": "string", "format": "date-time", "description": "Data da nota (AAAA-MM-DD ou data e hora). Na transmissão vira a competência, no horário de Brasília e nunca depois de hoje." }, "data_emissao_nfs": { "type": "string", "format": "date-time" }, "origem": { "type": "string" }, "tomador_localizacao": { "type": "string", "enum": [ "Brasil", "Exterior", "Não Informado" ] }, "tomador_nome": { "type": "string" }, "tomador_documento": { "type": "string", "description": "CPF ou CNPJ do tomador (11 ou 14 dígitos). Na entrada, com ou sem máscara: a API grava só os dígitos. Notas incluídas pela tela do ERP podem vir com máscara. Dispensado quando tomador_is_estrangeiro." }, "tomador_is_estrangeiro": { "type": "boolean" }, "tomador_nif": { "type": "string" }, "tomador_inscricao_municipal": { "type": "string" }, "tomador_email": { "type": "string" }, "tomador_telefone": { "type": "string" }, "tomador_cep": { "type": "string" }, "tomador_logradouro": { "type": "string" }, "tomador_numero": { "type": "string" }, "tomador_complemento": { "type": "string" }, "tomador_bairro": { "type": "string" }, "tomador_cidade": { "type": "string" }, "tomador_uf": { "type": "string" }, "tomador_municipio_codigo": { "type": "string" }, "servico_id": { "type": "string", "description": "Id de um serviço cadastrado; preenche nome, alíquota, código de tributação e IBS/CBS quando omitidos." }, "servico_nome": { "type": "string" }, "natureza_operacao": { "type": "string" }, "municipio_incidencia_codigo": { "type": "string" }, "servico_item_lista": { "type": "string" }, "servico_codigo_tributacao": { "type": "string" }, "servico_codigo_cnae": { "type": "string" }, "servico_codigo_nbs": { "type": "string" }, "servico_discriminacao": { "type": "string" }, "valor_servicos": { "type": "number" }, "valor_deducoes": { "type": "number" }, "desconto_incondicionado": { "type": "number" }, "desconto_condicionado": { "type": "number" }, "base_calculo": { "type": "number", "description": "Calculada: valor_servicos − valor_deducoes − desconto_incondicionado." }, "aliquota": { "type": "number", "description": "Alíquota de ISS em percentual (0 a 100)." }, "valor_iss": { "type": "number", "description": "Calculado: base_calculo × aliquota ÷ 100." }, "iss_retido": { "type": "boolean" }, "valor_pis": { "type": "number" }, "valor_cofins": { "type": "number" }, "valor_inss": { "type": "number" }, "valor_ir": { "type": "number" }, "valor_csll": { "type": "number" }, "outras_retencoes": { "type": "number" }, "valor_liquido": { "type": "number", "description": "Calculado: valor_servicos − descontos − ISS retido − demais retenções." }, "cst_ibs_cbs": { "type": "string", "description": "CST do IBS/CBS (reforma tributária), 3 dígitos. O mesmo código vale para os dois tributos. Na nota, omitido, vem do serviço." }, "classificacao_trib_ibs_cbs": { "type": "string", "description": "Classificação tributária do IBS/CBS (cClassTrib), 6 dígitos. Na nota, omitida, vem do serviço." }, "indicador_operacao": { "type": "string", "description": "Indicador de operação do IBS/CBS (cIndOp), 6 dígitos. Na nota, omitido, vem do serviço." }, "tipo_operacao_ibs_cbs": { "type": "string", "description": "Tipo de operação do IBS/CBS (tpOper, 1 a 5). Obrigatório nos itens 10.05, 15.09, 17.12 e 25.05 da LC 116 e recusado nos demais. Na nota, omitido, vem do serviço." }, "base_calculo_ibs_cbs": { "type": "number", "description": "Calculada (regra de 2026): valor_servicos − desconto_incondicionado − valor_iss − valor_pis − valor_cofins." }, "aliquota_ibs": { "type": "number", "description": "Alíquota do IBS em percentual. Na nota, omitida, vem do serviço." }, "valor_ibs": { "type": "number", "description": "Calculado: base_calculo_ibs_cbs × aliquota_ibs ÷ 100. Informativo: a prefeitura calcula o IBS com as alíquotas dela; não entra no valor_liquido." }, "aliquota_cbs": { "type": "number", "description": "Alíquota da CBS em percentual. Na nota, omitida, vem do serviço." }, "valor_cbs": { "type": "number", "description": "Calculado: base_calculo_ibs_cbs × aliquota_cbs ÷ 100. Informativo: a prefeitura calcula a CBS com as alíquotas dela; não entra no valor_liquido." }, "optante_simples_nacional": { "type": "boolean" }, "regime_especial_tributacao": { "type": "string" }, "outras_informacoes": { "type": "string" }, "informacoes_complementares": { "type": "string" }, "criado_em": { "type": "string", "format": "date-time", "description": "Instante da criação (ISO 8601)." }, "criado_por": { "type": "string", "description": "Quem incluiu o registro: nome do usuário do ERP ou nome desta chave de integração. Somente leitura." }, "criado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da inclusão: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "alterado_em": { "type": "string", "format": "date-time", "description": "Instante da última alteração pelo ERP ou pela API (ISO 8601). Base do filtro `alterado_desde`." }, "alterado_por": { "type": "string", "description": "Quem fez a última alteração: nome do usuário do ERP ou nome da chave de integração. Somente leitura." }, "alterado_por_tipo": { "type": "string", "enum": [ "Usuário", "API" ], "description": "Origem da última alteração: `Usuário` (tela do ERP) ou `API` (esta API). Somente leitura." }, "url_pdf": { "type": "string", "format": "uri", "readOnly": true, "description": "Link, nesta API, do PDF (DANFSE) da nota: `GET /notas-fiscais/{id}/pdf`. Presente só após a emissão. Somente leitura." }, "url_xml": { "type": "string", "format": "uri", "readOnly": true, "description": "Link, nesta API, do XML da nota autorizada: `GET /notas-fiscais/{id}/xml`. Presente só após a emissão. Somente leitura." } }, "required": [ "id" ] }, "NotaFiscalEntrada": { "type": "object", "properties": { "codigo_externo": { "type": "string", "description": "Identificador do registro no sistema do integrador (até 120 caracteres). Gravado como veio, sem espaços nas pontas; use-o para reencontrar o registro com o filtro `codigo_externo` da listagem." }, "data_emissao": { "type": "string", "format": "date-time", "description": "Data da nota (AAAA-MM-DD ou data e hora). Na transmissão vira a competência, no horário de Brasília e nunca depois de hoje." }, "tomador_localizacao": { "type": "string", "enum": [ "Brasil", "Exterior", "Não Informado" ] }, "tomador_nome": { "type": "string" }, "tomador_documento": { "type": "string", "description": "CPF ou CNPJ do tomador (11 ou 14 dígitos). Na entrada, com ou sem máscara: a API grava só os dígitos. Notas incluídas pela tela do ERP podem vir com máscara. Dispensado quando tomador_is_estrangeiro." }, "tomador_is_estrangeiro": { "type": "boolean" }, "tomador_nif": { "type": "string" }, "tomador_motivo_ausencia_nif": { "type": "string" }, "tomador_inscricao_municipal": { "type": "string" }, "tomador_email": { "type": "string" }, "tomador_telefone": { "type": "string" }, "tomador_cep": { "type": "string" }, "tomador_logradouro": { "type": "string" }, "tomador_numero": { "type": "string" }, "tomador_complemento": { "type": "string" }, "tomador_bairro": { "type": "string" }, "tomador_cidade": { "type": "string" }, "tomador_uf": { "type": "string" }, "tomador_municipio_codigo": { "type": "string" }, "servico_id": { "type": "string", "description": "Id de um serviço cadastrado; preenche nome, alíquota, código de tributação e IBS/CBS quando omitidos." }, "natureza_operacao": { "type": "string" }, "municipio_incidencia_codigo": { "type": "string" }, "servico_item_lista": { "type": "string" }, "servico_codigo_tributacao": { "type": "string" }, "servico_codigo_cnae": { "type": "string" }, "servico_codigo_nbs": { "type": "string" }, "servico_discriminacao": { "type": "string" }, "valor_servicos": { "type": "number" }, "valor_deducoes": { "type": "number" }, "desconto_incondicionado": { "type": "number" }, "desconto_condicionado": { "type": "number" }, "aliquota": { "type": "number", "description": "Alíquota de ISS em percentual (0 a 100)." }, "iss_retido": { "type": "boolean" }, "valor_pis": { "type": "number" }, "valor_cofins": { "type": "number" }, "valor_inss": { "type": "number" }, "valor_ir": { "type": "number" }, "valor_csll": { "type": "number" }, "outras_retencoes": { "type": "number" }, "cst_ibs_cbs": { "type": "string", "description": "CST do IBS/CBS (reforma tributária), 3 dígitos. O mesmo código vale para os dois tributos. Na nota, omitido, vem do serviço." }, "classificacao_trib_ibs_cbs": { "type": "string", "description": "Classificação tributária do IBS/CBS (cClassTrib), 6 dígitos. Na nota, omitida, vem do serviço." }, "indicador_operacao": { "type": "string", "description": "Indicador de operação do IBS/CBS (cIndOp), 6 dígitos. Na nota, omitido, vem do serviço." }, "tipo_operacao_ibs_cbs": { "type": "string", "description": "Tipo de operação do IBS/CBS (tpOper, 1 a 5). Obrigatório nos itens 10.05, 15.09, 17.12 e 25.05 da LC 116 e recusado nos demais. Na nota, omitido, vem do serviço." }, "aliquota_ibs": { "type": "number", "description": "Alíquota do IBS em percentual. Na nota, omitida, vem do serviço." }, "aliquota_cbs": { "type": "number", "description": "Alíquota da CBS em percentual. Na nota, omitida, vem do serviço." }, "optante_simples_nacional": { "type": "boolean" }, "regime_especial_tributacao": { "type": "string" }, "outras_informacoes": { "type": "string" }, "informacoes_complementares": { "type": "string" } }, "required": [ "tomador_nome", "tomador_documento", "servico_discriminacao", "valor_servicos" ], "additionalProperties": false }, "Contato": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "empresa_nome": { "type": "string", "description": "Organização do contato (texto livre)." }, "cargo": { "type": "string" }, "whatsapp": { "type": "string", "description": "Número internacional (E.164) só com dígitos, ex.: 5562985330155. Na entrada aceita máscara e `+`; sem DDI, assume Brasil (+55)." }, "telefone": { "type": "string", "description": "Telefone fixo, mesmo formato do `whatsapp`." }, "email": { "type": "string", "description": "Gravado em minúsculas." }, "pais_iso": { "type": "string" }, "origem": { "type": "string", "description": "De onde veio o registro (manual, whatsapp, formulario, email, importacao, trello...)." }, "formulario_nome": { "type": "string" }, "cliente_id": { "type": "string", "description": "Id do cliente/fornecedor do ERP vinculado (opcional)." }, "cliente_nome": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "observacoes": { "type": "string" }, "criado_em": { "type": "string", "format": "date-time" }, "atualizado_em": { "type": "string", "format": "date-time" }, "ultimo_contato_em": { "type": "string", "format": "date-time" } } }, "ContatoEntrada": { "type": "object", "properties": { "nome": { "type": "string" }, "empresa_nome": { "type": "string", "description": "Organização do contato (texto livre)." }, "cargo": { "type": "string" }, "whatsapp": { "type": "string", "description": "Número internacional (E.164) só com dígitos, ex.: 5562985330155. Na entrada aceita máscara e `+`; sem DDI, assume Brasil (+55)." }, "telefone": { "type": "string", "description": "Telefone fixo, mesmo formato do `whatsapp`." }, "email": { "type": "string", "description": "Gravado em minúsculas." }, "cliente_id": { "type": "string", "description": "Id do cliente/fornecedor do ERP vinculado (opcional)." }, "cliente_nome": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "observacoes": { "type": "string" } }, "additionalProperties": false }, "Quadro": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "descricao": { "type": "string" }, "cor": { "type": "string" }, "listas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "ordem": { "type": "integer" }, "concluida": { "type": "boolean", "description": "Lista que representa tarefa concluída." } } } }, "arquivado": { "type": "boolean" }, "criado_em": { "type": "string", "format": "date-time" }, "atualizado_em": { "type": "string", "format": "date-time" } } }, "Tarefa": { "type": "object", "properties": { "id": { "type": "string" }, "quadro_id": { "type": "string", "description": "Quadro da tarefa (`GET /quadros`). Obrigatório na inclusão." }, "lista_id": { "type": "string", "description": "Lista (coluna) do quadro. Na inclusão, vazia = primeira lista. Na edição, mudar move a tarefa e dispara as automações da lista." }, "titulo": { "type": "string" }, "descricao": { "type": "string" }, "etiquetas": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "a_fazer", "em_andamento", "aguardando", "concluida" ], "description": "Situação gravada na tarefa." }, "situacao": { "type": "string", "enum": [ "no_prazo", "agendada", "vencida", "aguardando", "concluida" ], "description": "Calculada pelo ERP a partir de status, início e prazo. Somente leitura." }, "inicio": { "type": "string", "format": "date-time" }, "prazo": { "type": "string", "format": "date-time" }, "concluida_em": { "type": "string", "format": "date-time" }, "responsaveis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" } } }, "description": "Usuários do ERP responsáveis (id e nome)." }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "titulo": { "type": "string" }, "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "texto": { "type": "string" }, "feito": { "type": "boolean" }, "prazo": { "type": "string", "format": "date-time", "nullable": true } } } } } } }, "subtarefas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "titulo": { "type": "string" }, "status": { "type": "string" }, "prazo": { "type": "string", "format": "date-time", "nullable": true }, "concluida_em": { "type": "string", "format": "date-time", "nullable": true }, "responsavel": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" } } } } } }, "contato_id": { "type": "string" }, "contato_nome": { "type": "string" }, "cliente_id": { "type": "string", "description": "Id do cliente/fornecedor do ERP vinculado (opcional)." }, "cliente_nome": { "type": "string" }, "origem": { "type": "string", "description": "De onde veio o registro (manual, whatsapp, formulario, email, importacao, trello...)." }, "arquivada": { "type": "boolean" }, "criado_em": { "type": "string", "format": "date-time" }, "atualizado_em": { "type": "string", "format": "date-time" } } }, "TarefaEntrada": { "type": "object", "properties": { "quadro_id": { "type": "string", "description": "Quadro da tarefa (`GET /quadros`). Obrigatório na inclusão." }, "lista_id": { "type": "string", "description": "Lista (coluna) do quadro. Na inclusão, vazia = primeira lista. Na edição, mudar move a tarefa e dispara as automações da lista." }, "titulo": { "type": "string" }, "descricao": { "type": "string" }, "etiquetas": { "type": "array", "items": { "type": "string" } }, "inicio": { "type": "string", "format": "date-time" }, "prazo": { "type": "string", "format": "date-time" }, "responsaveis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" } } }, "description": "Usuários do ERP responsáveis (id e nome)." }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "titulo": { "type": "string" }, "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "texto": { "type": "string" }, "feito": { "type": "boolean" }, "prazo": { "type": "string", "format": "date-time", "nullable": true } } } } } } }, "subtarefas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "titulo": { "type": "string" }, "status": { "type": "string" }, "prazo": { "type": "string", "format": "date-time", "nullable": true }, "concluida_em": { "type": "string", "format": "date-time", "nullable": true }, "responsavel": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" } } } } } }, "contato_id": { "type": "string" }, "cliente_id": { "type": "string", "description": "Id do cliente/fornecedor do ERP vinculado (opcional)." }, "cliente_nome": { "type": "string" }, "status": { "type": "string", "enum": [ "a_fazer", "em_andamento", "aguardando", "concluida" ], "description": "Situação gravada na tarefa." }, "arquivada": { "type": "boolean" } }, "required": [ "quadro_id", "titulo" ], "additionalProperties": false }, "LicencaParceiro": { "type": "object", "properties": { "contrato_id": { "type": "string" }, "categoria": { "type": "string", "enum": [ "indicacao", "revenda" ] }, "grupo": { "type": "string", "enum": [ "ativa", "teste", "cancelada", "inadimplente", "aguardando" ] }, "empresa_nome": { "type": "string" }, "plano_nome": { "type": "string" }, "periodicidade": { "type": "string" }, "valor_mensal": { "type": "number" }, "status_efetivo": { "type": "string", "description": "Situação da licença pela data (um contrato Ativo vencido é Suspenso)." }, "contratou": { "type": "boolean" }, "data_cadastro": { "type": "string", "nullable": true }, "data_fim_teste": { "type": "string", "nullable": true }, "proximo_vencimento": { "type": "string", "nullable": true }, "comissao_percentual": { "type": "number" }, "comissao_base": { "type": "string" }, "comissao_valor": { "type": "number", "description": "Comissão prevista (só quem paga gera comissão)." } } }, "ComissaoParceiro": { "type": "object", "properties": { "id": { "type": "string" }, "tipo": { "type": "string", "enum": [ "indicacao", "revenda" ] }, "contrato_id": { "type": "string" }, "empresa_nome": { "type": "string" }, "plano_nome": { "type": "string" }, "competencia": { "type": "string", "nullable": true }, "ciclo": { "type": "integer" }, "valor_base": { "type": "number" }, "percentual": { "type": "number" }, "base": { "type": "string" }, "valor": { "type": "number" }, "status": { "type": "string", "enum": [ "a_pagar", "paga", "cancelada" ] }, "gerada_em": { "type": "string", "format": "date-time", "nullable": true }, "paga_em": { "type": "string", "format": "date-time", "nullable": true } } }, "Parceria": { "type": "object", "properties": { "parceiro": { "type": "object", "properties": { "id": { "type": "string" }, "codigo": { "type": "string", "description": "Código do link de indicação." }, "nome": { "type": "string" }, "status": { "type": "string", "enum": [ "Ativo", "Inativo" ] }, "tipos": { "type": "array", "items": { "type": "string", "enum": [ "indicador", "revendedor" ] } } } }, "link": { "type": "string", "format": "uri", "nullable": true, "description": "Link de indicação (`?ref=CODIGO`)." }, "resumo": { "type": "object", "description": "Mesmos números do Painel do Parceiro: indicados, contrataram, em_teste, perdidos, conversao (%), comissao_prevista, revendidas, valor_revendido, valor_indicado, comissao_devida, comissao_paga." }, "dashboard": { "type": "object", "description": "Licenças revendidas, comissionadas, ativas, canceladas e inadimplentes (qtd, valor, %)." } } } }, "responses": { "RequisicaoInvalida": { "description": "Dados inválidos. `erro.campos` detalha campo a campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "NaoAutenticado": { "description": "Chave ausente, inválida, revogada, expirada ou de outro ambiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "EscopoInsuficiente": { "description": "A chave não tem o escopo exigido, ou o IP não está na allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "NaoEncontrado": { "description": "Registro inexistente — ou pertencente a outra empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "Conflito": { "description": "Operação incompatível com o estado atual do registro (ex.: cobrança já no gateway, nota emitida, registro com vínculos).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "LimiteExcedido": { "description": "Quota da chave excedida no minuto. Consulte os cabeçalhos `RateLimit-*`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "ServicoExterno": { "description": "O gateway de pagamento ou a API de Notas recusou ou não respondeu. A mensagem traz o motivo; o registro não foi alterado (exceto a nota, que fica em `Erro`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }