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.

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.

Body (CustomerCreate) — JSON com campos do modelo Customer (ver seção Campos do model Customer). Mínimo recomendado: razao_social, nome_fantasia, cpfecnpj, regime_tributario, cidade, estado.

Resposta 201 Created:

{
  "success": true,
  "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",
    "ativo": true
  }
}

Escopo: customers:write

GET /customers/

Lista todos os clientes cadastrados. Resposta pode ser grande; o MCP trunca em 20 resultados por padrão.

Resposta 200 OK:

{
  "success": true,
  "message": "Lista de clientes recuperada com sucesso",
  "data": [
    { "id": 1, "razao_social": "ACME LTDA", "cpfecnpj": "...", "ativo": true },
    { "id": 2, "razao_social": "BETA EIRELI", "cpfecnpj": "...", "ativo": true }
  ]
}

Escopo: customers:read

GET /customers/dctfweb

Variante da listagem otimizada para o módulo DCTFWeb — devolve apenas campos relevantes para esse filtro.

Resposta 200 OK: mesmo envelope, data é array de objetos enxutos.

Escopo: customers:read

GET /customers/city

Busca clientes por uma ou mais cidades, com exclusão opcional de regimes tributários e paginação.

Exemplo:

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

Escopo: customers:read

GET /customers/{customer_id}

Detalha um cliente pelo ID inteiro.

Resposta 200 OK:

{
  "success": true,
  "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

PUT /customers/{customer_id}

Atualiza um cliente existente. Body é um CustomerUpdate com campos parciais — somente o que vier preenchido é alterado.

Resposta 200 OK: envelope com data do cliente atualizado.

Escopo: customers:write

DELETE /customers/{customer_id}

Remove um cliente do sistema. Operação destrutiva — cascateia para activities, arquivos_processados, lembretes etc.

Escopo: customers:write

PUT /customers/desativar/{customer_id}

Inativa um cliente (ativo = false) sem apagar registros relacionados. É a forma recomendada para "desligar" um cliente.

Escopo: customers:write

GET /customers/cnpj/?cnpj={cnpj}

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

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

Escopo: customers:read

GET /customers/cnpj_parcial/?cnpj={cnpj}

Busca por prefixo numérico do CNPJ (útil para localizar a raiz XX.XXX.XXX).

Escopo: customers:read

GET /customers/razao_social/?razao_social={termo}

Match exato da razão social.

GET /customers/razao_social_parcial/?razao_social={termo}

Match por LIKE — contém a sequência.

GET /customers/razao_social_parcial_format/?razao_social={termo}

Match com normalização (remove acentos e pontuação antes de comparar).

GET /customers/razao_social_fuzzy/?razao_social={termo}

Fuzzy matching por similaridade textual — tolera erros de digitação.

GET /customers/nome_fantasia/?nome_fantasia={termo}

Match exato do nome fantasia. Existem também as variantes _parcial/, _parcial_format/ e _fuzzy/ com a mesma semântica da família razão social.

GET /customers/regime_tributario/

Agrupa todos os clientes por regime tributário.

Resposta 200 OK:

{
  "success": true,
  "message": "Clientes encontrados com sucesso",
  "data": {
    "customers": {
      "Simples Nacional": [{ "id": 1, "razao_social": "..." }],
      "Lucro Presumido": [{ "id": 7, "razao_social": "..." }],
      "Lucro Real": []
    }
  }
}

Escopo: customers:read

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, 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.

Campos do model Customer

Identificaçã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
• 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, inscricao_municipal

Contato e endereço:

• telefone, celular, email
• endereco, numero, complemento, bairro, cidade, estado (2 letras), cep

Configuração contábil:

• regime_tributario: str — Simples Nacional, Lucro Presumido, Lucro Real, MEI
• tipo_conta: str
• ativo: bool — desativar = false
• certificado: bool — possui e-CNPJ digital
• zap_contabil: bool
• representante: str
• numero_profissionais: str

ISS / nota fiscal:

• email1_iss, email2_iss, email3_iss
• aliquota_iss: bool