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/customersEscopos necessários
customers:read- listagem, busca e detalhamentocustomers: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) | Tipo | Obrigatório | Descrição |
|---|---|---|---|
aliquota_pis | Decimal | não | Fração decimal entre 0 e 1 (ex.: 0.0065). Default 0. |
aliquota_cofins | Decimal | não | Fração decimal entre 0 e 1. Default 0. |
aliquota_iss | Decimal | não | Fração decimal entre 0 e 1. Default 0. |
aliquota_irpj_base | Decimal | não | Percentual de presunção do IRPJ, fração entre 0 e 1. Default 0. |
aliquota_csll_base | Decimal | não | Percentual de presunção da CSLL, fração entre 0 e 1. Default 0. |
regime_apuracao | str | não | Ex.: trimestral, anual (máx. 50). |
observacoes | str | não | Observaçõ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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cidades | List[str] | query | sim | Repita o query param para múltiplas cidades. |
regimes_excluidos | List[str] | query | não | Regimes a excluir. Ex.: Simples Nacional. |
page | int >= 1 | query | não | Página. |
per_page | int 1..100 | query | não | Itens por página. |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/city?cidades=Salvador&cidades=Lauro%20de%20Freitas®imes_excluidos=MEI&page=1&per_page=50Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
ativo | bool | query | não | Filtra ativos/inativos; ausente traz todos. |
razao_social | str | query | não | Filtro por razão social. |
nome_fantasia | str | query | não | Filtro por nome fantasia. |
cpfecnpj | str | query | não | Filtro por CPF/CNPJ. |
cidades | List[str] | query | não | Repita o query param para múltiplas cidades. |
regime_tributario | str | query | não | Filtro por regime tributário. |
servico | List[TipoServico] | query | não | Contábil, Fiscal, Pessoal, Financeiro ou Todos (OR). |
page | int >= 1 | query | não | Página. |
per_page | int 1..100 | query | não | Itens 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID interno do cliente. |
ate | str | query | não | Competê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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cnpj | int | query | sim | CNPJ sem máscara (14 dígitos) |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/cnpj/?cnpj=12345678000199Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
cnpj | int | query | sim | Prefixo numérico do CNPJ (raiz) |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/cnpj_parcial/?cnpj=12345678Response 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
razao_social | str | query | sim | Razão social exata |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/razao_social/?razao_social=ACME%20SERVICOS%20LTDAResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
razao_social | str | query | sim | Trecho da razão social a buscar |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/razao_social_parcial/?razao_social=SERVICOSResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
razao_social | str | query | sim | Trecho 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=servicosResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
razao_social | str | query | sim | Termo aproximado da razão social |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/razao_social_fuzzy/?razao_social=acmi%20servicosResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nome_fantasia | str | query | sim | Nome fantasia exato |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/nome_fantasia/?nome_fantasia=ACMEResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nome_fantasia | str | query | sim | Trecho do nome fantasia a buscar |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/nome_fantasia_parcial/?nome_fantasia=ACResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nome_fantasia | str | query | sim | Trecho do nome fantasia a buscar |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/nome_fantasia_parcial_format/?nome_fantasia=acmeResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
nome_fantasia | str | query | sim | Termo aproximado do nome fantasia |
Request
Sem corpo de requisição. Exemplo de chamada:
GET /api/v1/customers/nome_fantasia_fuzzy/?nome_fantasia=acmiResponse 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
customer_id | int | path | sim | ID 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.
| Campo | Tipo | Descrição |
|---|---|---|
id | int | Chave primária, identificador canônico em todas as tools MCP. |
razao_social | str | Razão social (PJ) ou nome completo (PF). |
nome_fantasia | str | Nome fantasia. |
cpfecnpj | str | CNPJ (PJ) ou CPF (PF), com máscara. |
cpf | str | CPF do responsável (quando PJ). |
numero_dominio | str | Código no sistema Domínio. |
inscricao_estadual | str | Inscrição estadual. |
inscricao_municipal | str | Inscrição municipal. |
telefone | str | Telefone fixo. |
celular | str | Celular. |
email | str | E-mail principal. |
endereco | str | Logradouro. |
numero | str | Número. |
complemento | str | Complemento. |
bairro | str | Bairro. |
cidade | str | Cidade. |
estado | str | UF (2 letras). |
cep | str | CEP. |
regime_tributario | str | Simples Nacional, Lucro Presumido, Lucro Real ou MEI. |
tipo_conta | str | Tipo de conta. |
ativo | bool | Situação do cliente; desativar = false. |
certificado | bool | Possui e-CNPJ digital. |
zap_contabil | bool | Integração ZapContábil habilitada. |
representante | str | Representante. |
numero_profissionais | str | Número de profissionais. |
email1_iss | str | E-mail 1 para ISS / nota fiscal. |
email2_iss | str | E-mail 2 para ISS / nota fiscal. |
email3_iss | str | E-mail 3 para ISS / nota fiscal. |
aliquota_iss | bool | Indicador de alíquota de ISS. |
login_gov | str | Campo de escrita; nunca retornado nas listagens. |
senha_gov | str | Campo 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
cpfecnpjchega da WebApi sem máscara; o MCP aplica a máscaraXX.XXX.***/0001-XXantes de devolver ao LLM.