Customers

Endpoints da WebApiAlcance para o cadastro de clientes (pessoa física e jurídica) da Alcance Contabilidade. Cobrem listagem, busca por múltiplos critérios (ID, CNPJ, razão social, nome fantasia, cidade, regime tributário), criação, atualização e desativação lógica.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/customers

Escopos necessários

  • customers:read - listagem, busca e detalhamento
  • customers:write - criação, atualização, desativação e exclusão

API Keys emitidas para o gateway MCP devem usar apenas os escopos estritamente necessários - preferencialmente customers:read.

Endpoints

POST /customers/

Cria um novo cliente (PF ou PJ). Restrita a usuários com permissão adicional; sem ela, a resposta é 403. Para criar o cliente já com a configuração fiscal, use POST /customers/with-fiscal-config. Os campos login_gov e senha_gov são de escrita: aceitos na criação, mas nunca retornados nas listagens.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerCreate). Campos obrigatórios: razao_social e nome_fantasia; recomendados: cpfecnpj, regime_tributario, cidade e estado.

Request

{
  "razao_social": "ACME SERVICOS LTDA",
  "nome_fantasia": "ACME",
  "cpfecnpj": "12.345.678/0001-99",
  "regime_tributario": "Simples Nacional",
  "cidade": "Salvador",
  "estado": "BA"
}

Response 201 Created

{
  "status": "success",
  "message": "Cliente criado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "nome_fantasia": "ACME",
    "cpfecnpj": "12.345.678/0001-99",
    "regime_tributario": "Simples Nacional",
    "cidade": "Salvador",
    "estado": "BA",
    "ativo": true
  }
}

Escopo: customers:write

POST /customers/with-fiscal-config

Cria o cliente e a sua configuração fiscal (1:1) em uma única transação: se qualquer parte falhar, nada é gravado. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo (CustomerWithFiscalConfigCreate) tem dois objetos: customer (mesmos campos de POST /customers/) e fiscal_config (sem id_customer, que é resolvido na criação).

Campo (fiscal_config)TipoObrigatórioDescrição
aliquota_pisDecimalnãoFração decimal entre 0 e 1 (ex.: 0.0065). Default 0.
aliquota_cofinsDecimalnãoFração decimal entre 0 e 1. Default 0.
aliquota_issDecimalnãoFração decimal entre 0 e 1. Default 0.
aliquota_irpj_baseDecimalnãoPercentual de presunção do IRPJ, fração entre 0 e 1. Default 0.
aliquota_csll_baseDecimalnãoPercentual de presunção da CSLL, fração entre 0 e 1. Default 0.
regime_apuracaostrnãoEx.: trimestral, anual (máx. 50).
observacoesstrnãoObservações livres (máx. 500).

Request

{
  "customer": {
    "razao_social": "ACME SERVICOS LTDA",
    "nome_fantasia": "ACME",
    "cpfecnpj": "12.345.678/0001-99",
    "regime_tributario": "Lucro Presumido"
  },
  "fiscal_config": {
    "aliquota_iss": "0.0500",
    "aliquota_irpj_base": "0.0800",
    "aliquota_csll_base": "0.1200",
    "regime_apuracao": "trimestral"
  }
}

Response 201 Created

{
  "status": "success",
  "message": "Cliente e configuração fiscal criados com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "nome_fantasia": "ACME",
    "cpfecnpj": "12.345.678/0001-99",
    "ativo": true,
    "fiscal_config": {
      "id": 88,
      "id_customer": 1234,
      "aliquota_iss": "0.0500",
      "regime_apuracao": "trimestral"
    }
  }
}

Erros: 404 (recurso vinculado inexistente), 409 (configuração fiscal já existe) e 422 (validação de campo ou de alíquota fora de 0..1).

Escopo: customers:write (restrita a usuários com permissão adicional; sem ela, 403)

GET /customers/

Lista os clientes cadastrados. Lista vazia é estado válido, retornando data: [] com a mensagem "Nenhum cliente encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lista de clientes recuperada com sucesso",
  "data": [
    { "id": 1, "razao_social": "ACME LTDA", "cpfecnpj": "11.111.111/0001-11", "ativo": true },
    { "id": 2, "razao_social": "BETA EIRELI", "cpfecnpj": "22.222.222/0001-22", "ativo": true }
  ]
}

Escopo: customers:read

GET /customers/dctfweb

Variante da listagem otimizada para o módulo DCTFWeb - devolve apenas os campos relevantes para esse filtro. Lista vazia retorna data: [] com a mensagem "Nenhum cliente encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Lista de clientes recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "razao_social": "ACME LTDA",
      "cpfecnpj": "11.111.111/0001-11",
      "regime_tributario": "Lucro Presumido"
    }
  ]
}

Escopo: customers:read

PUT /customers/{customer_id}

Atualiza um cliente existente. O body é um CustomerUpdate com campos parciais - somente o que vier preenchido é alterado. Quando o cliente não existe, retorna erro com a mensagem "Cliente não encontrado.". ativo: null significa não alterar (o campo não aceita nulo); o mesmo vale para login_gov e senha_gov vazios. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID interno do cliente

Request (CustomerUpdate - todos os campos opcionais)

{
  "razao_social": "ACME SERVICOS S.A.",
  "regime_tributario": "Lucro Presumido"
}

Response 200 OK

{
  "status": "success",
  "message": "Cliente atualizado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS S.A.",
    "nome_fantasia": "ACME",
    "cpfecnpj": "12.345.678/0001-99",
    "regime_tributario": "Lucro Presumido",
    "ativo": true
  }
}

Escopo: customers:write

DELETE /customers/{customer_id}

Remove um cliente do sistema. Operação destrutiva - cascateia para activities, arquivos_processados, lembretes etc. Restrita a usuários com permissão adicional; sem ela, a resposta é 403 Forbidden. Quando há registros vinculados que impedem a exclusão (por exemplo, lançamentos contábeis importados via Open Finance), retorna 409 Conflict com a mensagem do impedimento; exclua os vínculos antes.

O gateway MCP não expõe este endpoint. Para inativar um cliente, prefira PUT /customers/desativar/{customer_id}.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID interno do cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Cliente deletado com sucesso",
  "data": null
}

Escopo: customers:write

GET /customers/city

Busca clientes por uma ou mais cidades, com exclusão opcional de regimes tributários e paginação. Sem resultados, retorna a mensagem "Nenhum cliente encontrado." com details: [].

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cidadesList[str]querysimRepita o query param para múltiplas cidades.
regimes_excluidosList[str]querynãoRegimes a excluir. Ex.: Simples Nacional.
pageint >= 1querynãoPágina.
per_pageint 1..100querynãoItens por página.

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/city?cidades=Salvador&cidades=Lauro%20de%20Freitas&regimes_excluidos=MEI&page=1&per_page=50

Response 200 OK

{
  "status": "success",
  "message": "Clientes recuperados com sucesso",
  "data": [
    { "id": 1, "razao_social": "ACME LTDA", "cidade": "Salvador", "estado": "BA", "ativo": true }
  ]
}

Escopo: customers:read

GET /customers/with-services

Lista apenas os clientes para os quais a firma presta serviços (com ao menos um customer_service ativo), com filtros e paginação opcionais. O filtro servico combina os tipos por OR; Todos seleciona clientes com os quatro tipos ativos.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
ativoboolquerynãoFiltra ativos/inativos; ausente traz todos.
razao_socialstrquerynãoFiltro por razão social.
nome_fantasiastrquerynãoFiltro por nome fantasia.
cpfecnpjstrquerynãoFiltro por CPF/CNPJ.
cidadesList[str]querynãoRepita o query param para múltiplas cidades.
regime_tributariostrquerynãoFiltro por regime tributário.
servicoList[TipoServico]querynãoContábil, Fiscal, Pessoal, Financeiro ou Todos (OR).
pageint >= 1querynãoPágina.
per_pageint 1..100querynãoItens por página.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Clientes atendidos recuperados com sucesso",
  "data": {
    "items": [{ "id": 1, "razao_social": "ACME LTDA", "nome_fantasia": "ACME", "ativo": true }],
    "total": 1,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 50
  }
}

Escopo: customers:read

GET /customers/{customer_id}/credenciais-gov

Retorna as credenciais governamentais (login_gov, senha_gov) de um cliente. É a única rota de leitura que devolve esses campos. O acesso é auditado.

Rota que devolve credenciais governamentais do cliente; uso exclusivo de processos internos autorizados. Não armazene nem registre a resposta.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID interno do cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Credenciais recuperadas com sucesso",
  "data": {
    "id": 1234,
    "login_gov": "<valor sensível>",
    "senha_gov": "<valor sensível>"
  }
}

Cliente inexistente retorna o envelope de erro com a mensagem "Cliente não encontrado.". Credenciais de integração recebem 403 com { "message": "..." }.

Escopo: customers:read

Restrita a usuários com permissão adicional; sem ela, a resposta é 403. Exige login de usuário (sessão); credenciais de integração recebem 403.

GET /customers/{customer_id}

Detalha um cliente pelo ID inteiro. Quando não encontrado, retorna a mensagem "Cliente não encontrado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID interno do cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "nome_fantasia": "ACME",
    "cpfecnpj": "12.345.678/0001-99",
    "cidade": "Salvador",
    "estado": "BA",
    "regime_tributario": "Simples Nacional",
    "ativo": true
  }
}

Escopo: customers:read

GET /customers/{customer_id}/faturamento-resumo

Faturamento do cliente: valor mensal da competência ate e valor anual dos 12 meses que terminam nela. Disponível com o escopo de leitura.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID interno do cliente.
atestrquerynãoCompetência final YYYY-MM (inclusiva). Default: último mês fechado (mês anterior ao atual). Formato inválido retorna 422.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Faturamento do cliente recuperado com sucesso",
  "data": {
    "mensal": {
      "competencia": "2026-05",
      "total": 18250.4,
      "fonte": "nfse_importada",
      "rotulo": "NFS-e importadas"
    },
    "anual": {
      "inicio": "2025-06",
      "fim": "2026-05",
      "total": 201300.0,
      "meses_com_dado": 11,
      "meses_sem_dado": 1,
      "fontes": ["nfse_importada"],
      "rotulo": "NFS-e importadas"
    },
    "motivo_vazio": null
  }
}

Sem dado não é zero

total: null significa sem dado para o período; 0 só aparece quando existe registro cuja soma é zero. Meses sem registro entram em meses_sem_dado. Para regimes sem fonte de faturamento (por exemplo MEI e pessoa física), total vem null e motivo_vazio explica o motivo. Cliente inexistente retorna 404.

Escopo: customers:read

GET /customers/cnpj/

Busca exata pelo CNPJ numérico (apenas dígitos). Note a barra final obrigatória antes da query string (ver Notas).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cnpjintquerysimCNPJ sem máscara (14 dígitos)

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/cnpj/?cnpj=12345678000199

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "cpfecnpj": "12.345.678/0001-99",
    "ativo": true
  }
}

Escopo: customers:read

GET /customers/cnpj_parcial/

Busca por prefixo numérico do CNPJ (útil para localizar a raiz XX.XXX.XXX). Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
cnpjintquerysimPrefixo numérico do CNPJ (raiz)

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/cnpj_parcial/?cnpj=12345678

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    {
      "id": 1234,
      "razao_social": "ACME SERVICOS LTDA",
      "cpfecnpj": "12.345.678/0001-99",
      "ativo": true
    }
  ]
}

Escopo: customers:read

GET /customers/razao_social/

Match exato da razão social. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
razao_socialstrquerysimRazão social exata

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/razao_social/?razao_social=ACME%20SERVICOS%20LTDA

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "cpfecnpj": "12.345.678/0001-99",
    "ativo": true
  }
}

Escopo: customers:read

GET /customers/razao_social_parcial/

Match por LIKE - retorna clientes cuja razão social contém a sequência informada. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
razao_socialstrquerysimTrecho da razão social a buscar

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/razao_social_parcial/?razao_social=SERVICOS

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    {
      "id": 1234,
      "razao_social": "ACME SERVICOS LTDA",
      "cpfecnpj": "12.345.678/0001-99",
      "ativo": true
    }
  ]
}

Escopo: customers:read

GET /customers/razao_social_parcial_format/

Match parcial com normalização - remove acentos e pontuação antes de comparar. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
razao_socialstrquerysimTrecho da razão social a buscar

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/razao_social_parcial_format/?razao_social=servicos

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    {
      "id": 1234,
      "razao_social": "ACME SERVICOS LTDA",
      "cpfecnpj": "12.345.678/0001-99",
      "ativo": true
    }
  ]
}

Escopo: customers:read

GET /customers/razao_social_fuzzy/

Fuzzy matching por similaridade textual - tolera erros de digitação. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
razao_socialstrquerysimTermo aproximado da razão social

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/razao_social_fuzzy/?razao_social=acmi%20servicos

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    {
      "id": 1234,
      "razao_social": "ACME SERVICOS LTDA",
      "cpfecnpj": "12.345.678/0001-99",
      "ativo": true
    }
  ]
}

Escopo: customers:read

GET /customers/nome_fantasia/

Match exato do nome fantasia. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
nome_fantasiastrquerysimNome fantasia exato

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/nome_fantasia/?nome_fantasia=ACME

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "nome_fantasia": "ACME",
    "ativo": true
  }
}

Escopo: customers:read

GET /customers/nome_fantasia_parcial/

Match por LIKE - retorna clientes cujo nome fantasia contém a sequência informada. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
nome_fantasiastrquerysimTrecho do nome fantasia a buscar

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/nome_fantasia_parcial/?nome_fantasia=AC

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    { "id": 1234, "razao_social": "ACME SERVICOS LTDA", "nome_fantasia": "ACME", "ativo": true }
  ]
}

Escopo: customers:read

GET /customers/nome_fantasia_parcial_format/

Match parcial do nome fantasia com normalização - remove acentos e pontuação antes de comparar. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
nome_fantasiastrquerysimTrecho do nome fantasia a buscar

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/nome_fantasia_parcial_format/?nome_fantasia=acme

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    { "id": 1234, "razao_social": "ACME SERVICOS LTDA", "nome_fantasia": "ACME", "ativo": true }
  ]
}

Escopo: customers:read

GET /customers/nome_fantasia_fuzzy/

Fuzzy matching do nome fantasia por similaridade textual - tolera erros de digitação. Exige a barra final antes da query string.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
nome_fantasiastrquerysimTermo aproximado do nome fantasia

Request

Sem corpo de requisição. Exemplo de chamada:

GET /api/v1/customers/nome_fantasia_fuzzy/?nome_fantasia=acmi

Response 200 OK

{
  "status": "success",
  "message": "Cliente encontrado com sucesso",
  "data": [
    { "id": 1234, "razao_social": "ACME SERVICOS LTDA", "nome_fantasia": "ACME", "ativo": true }
  ]
}

Escopo: customers:read

GET /customers/regime_tributario/

Agrupa todos os clientes por regime tributário. Retorna um objeto customers com uma lista por regime.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Clientes encontrados com sucesso",
  "data": {
    "customers": {
      "Simples Nacional": [{ "id": 1, "razao_social": "ACME LTDA" }],
      "Lucro Presumido": [{ "id": 7, "razao_social": "BETA EIRELI" }],
      "Lucro Real": []
    }
  }
}

Escopo: customers:read

PUT /customers/desativar/{customer_id}

Inativa um cliente (ativo = false) sem apagar registros relacionados. É a forma recomendada para "desligar" um cliente. Quando não encontrado, retorna a mensagem "Cliente não encontrado.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
customer_idintpathsimID interno do cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Cliente atualizado com sucesso",
  "data": {
    "id": 1234,
    "razao_social": "ACME SERVICOS LTDA",
    "ativo": false
  }
}

Escopo: customers:write

Schemas

Customer

Campos do model Customer retornado no data das respostas, agrupados por categoria.

CampoTipoDescrição
idintChave primária, identificador canônico em todas as tools MCP.
razao_socialstrRazão social (PJ) ou nome completo (PF).
nome_fantasiastrNome fantasia.
cpfecnpjstrCNPJ (PJ) ou CPF (PF), com máscara.
cpfstrCPF do responsável (quando PJ).
numero_dominiostrCódigo no sistema Domínio.
inscricao_estadualstrInscrição estadual.
inscricao_municipalstrInscrição municipal.
telefonestrTelefone fixo.
celularstrCelular.
emailstrE-mail principal.
enderecostrLogradouro.
numerostrNúmero.
complementostrComplemento.
bairrostrBairro.
cidadestrCidade.
estadostrUF (2 letras).
cepstrCEP.
regime_tributariostrSimples Nacional, Lucro Presumido, Lucro Real ou MEI.
tipo_contastrTipo de conta.
ativoboolSituação do cliente; desativar = false.
certificadoboolPossui e-CNPJ digital.
zap_contabilboolIntegração ZapContábil habilitada.
representantestrRepresentante.
numero_profissionaisstrNúmero de profissionais.
email1_issstrE-mail 1 para ISS / nota fiscal.
email2_issstrE-mail 2 para ISS / nota fiscal.
email3_issstrE-mail 3 para ISS / nota fiscal.
aliquota_issboolIndicador de alíquota de ISS.
login_govstrCampo de escrita; nunca retornado nas listagens.
senha_govstrCampo de escrita; nunca retornado nas listagens.

Notas

Armadilha de roteamento FastAPI. A rota dinâmica GET /{customer_id} é declarada antes das rotas estáticas GET /cnpj/, GET /razao_social/, GET /nome_fantasia/. Para que o FastAPI case a rota estática (e não interprete cnpj como um customer_id inválido), a barra final é obrigatória na chamada: use /customers/cnpj/?cnpj=..., nunca /customers/cnpj?cnpj=....

  • Toda resposta segue o envelope { status, message, data } (ou { status: "error", message, details } em erro). Códigos HTTP refletem semântica REST padrão.
  • Resultados grandes (GET /customers/) devem ser paginados ou filtrados pelo cliente. O gateway MCP trunca em 20 itens com footer orientativo.
  • O campo cpfecnpj chega da WebApi sem máscara; o MCP aplica a máscara XX.XXX.***/0001-XX antes de devolver ao LLM.