Smart: Taxa de Cartão

Endpoints da WebApiAlcance para o CRUD de taxas de cartão consumido pelo produto Smart. Cada registro representa um lote de movimentação de cartão junto a uma credenciadora/convênio de maquininha (mcc), com os créditos e débitos do lote, a conciliação de saldo e os totais disponíveis para repasse. Os endpoints cobrem listagem com filtro por CNPJ e paginação, consulta por ID, criação, atualização e exclusão.

Base path

/api/v1/smart-taxa-cartao

Escopos necessários

• smart_taxa_cartao:read - listagem e consulta por ID
• smart_taxa_cartao:write - criação, atualização e exclusão

O escopo é derivado do prefixo público da rota: /smart-taxa-cartao vira o recurso smart_taxa_cartao (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/PATCH/DELETE).

Endpoints

GET /smart-taxa-cartao/

Lista as taxas de cartão, com filtro opcional por CNPJ e paginação. Lista vazia é um estado válido - o retorno normal é 200 OK com data: [], não um erro.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Taxas de cartão recuperadas com sucesso",
  "data": [
    {
      "id": 6601,
      "cnpj": "12345678000199",
      "mcc_cnv": "CIELO",
      "mcc_lote": 990,
      "mcc_dt": "2026-01-10T00:00:00",
      "saldo": "-248235.22",
      "co_mcc_cre": "12000.00",
      "co_mcc_deb": "12300.00",
      "cfo_nome": "CIELO S.A.",
      "mcc_obs": null,
      "mcc_doc": "990",
      "st_mw": "CONCILIADO",
      "saldo_fim": "-248235.22",
      "saldo_conc": "-200000.00",
      "saldo_nao_conc": "-48235.22",
      "tot_disp": "11500.00",
      "ccr_ccr_sini": "0.00",
      "tot_rec": "11500.00",
      "tipo": "CARTAO CREDITO",
      "saldo_ini_grupo": "-236235.22",
      "saldo_subtotal": "-248235.22",
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_taxa_cartao:read

GET /smart-taxa-cartao/{smart_taxa_id}

Busca uma taxa de cartão pelo ID.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Taxa de cartão recuperada com sucesso",
  "data": {
    "id": 6601,
    "cnpj": "12345678000199",
    "saldo": "-248235.22",
    "...": "demais campos como em SmartTaxaCartaoRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Taxa de cartão não encontrada."}. Escopo: smart_taxa_cartao:read

POST /smart-taxa-cartao/

Cria uma nova taxa de cartão.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo é o schema SmartTaxaCartaoCreate.

Request

{
  "cnpj": "12.345.678/0001-99",
  "mcc_cnv": "CIELO",
  "mcc_lote": 990,
  "mcc_dt": "2026-01-10T00:00:00",
  "saldo": -248235.22,
  "co_mcc_cre": 12000.00,
  "co_mcc_deb": 12300.00,
  "cfo_nome": "CIELO S.A.",
  "mcc_doc": "990",
  "st_mw": "CONCILIADO",
  "saldo_fim": -248235.22,
  "saldo_conc": -200000.00,
  "saldo_nao_conc": -48235.22,
  "tot_disp": 11500.00,
  "tot_rec": 11500.00,
  "tipo": "CARTAO CREDITO",
  "saldo_ini_grupo": -236235.22,
  "saldo_subtotal": -248235.22
}

Response 201 Created

{
  "status": "success",
  "message": "Taxa de cartão criada com sucesso",
  "data": {
    "id": 6601,
    "cnpj": "12345678000199",
    "saldo": "-248235.22",
    "...": "demais campos como em SmartTaxaCartaoRead"
  }
}

Em falha inesperada ao persistir, retorna 500 Internal Server Error com {"message": "Não foi possível criar a taxa de cartão."}. Escopo: smart_taxa_cartao:write

PUT /smart-taxa-cartao/{smart_taxa_id}

Atualiza uma taxa de cartão existente. O cnpj não é editável por este endpoint - o schema de atualização não o inclui.

Parâmetros

O corpo é o schema SmartTaxaCartaoUpdate, com todos os campos opcionais.

Request

{
  "st_mw": "CONCILIADO",
  "saldo_nao_conc": 0.00
}

Response 200 OK

{
  "status": "success",
  "message": "Taxa de cartão atualizada com sucesso",
  "data": {
    "id": 6601,
    "cnpj": "12345678000199",
    "st_mw": "CONCILIADO",
    "saldo_nao_conc": "0.00",
    "...": "demais campos como em SmartTaxaCartaoRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Taxa de cartão não encontrada."}. Escopo: smart_taxa_cartao:write

DELETE /smart-taxa-cartao/{smart_taxa_id}

Remove uma taxa de cartão.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Taxa de cartão removida com sucesso",
  "data": null
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Taxa de cartão não encontrada."}. Escopo: smart_taxa_cartao:write

Schemas

SmartTaxaCartaoCreate

Corpo do POST /smart-taxa-cartao/. Todos os campos são opcionais no schema (nenhum é obrigatório para o Pydantic aceitar o payload), mas cnpj é a chave prática de identificação do cliente. Os campos monetários são Decimal. Diferente dos demais domínios da família Smart, este schema não tem o campo cfg_emp.

SmartTaxaCartaoUpdate

Corpo do PUT /smart-taxa-cartao/{smart_taxa_id}. Mesmos campos de SmartTaxaCartaoCreate, exceto cnpj - trocar o CNPJ dono do registro não é permitido por este endpoint. Todos os campos são opcionais.

SmartTaxaCartaoRead

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartTaxaCartaoCreate com:

Notas

• Toda resposta segue o envelope { status: "success", message, data }.
• Os campos monetários (saldo, co_mcc_cre, co_mcc_deb, saldo_fim, saldo_conc, saldo_nao_conc, tot_disp, ccr_ccr_sini, tot_rec, saldo_ini_grupo, saldo_subtotal) são Decimal e trafegam como string em JSON, tanto na entrada (aceita número ou string) quanto na saída (sempre string). Valores negativos são normais (saldo devedor do lote).
• Erros de negócio manualmente sinalizados pela rota (404 Not Found, 500 Internal Server Error) seguem o formato { "message": "..." } - não usam o campo detail.
• Erros de validação de schema (tipo/formato inválido no payload) seguem o padrão do FastAPI: 422 Unprocessable Entity com { "detail": [...] }.
• GET /smart-taxa-cartao/ sempre retorna 200 OK; lista vazia (data: []) é estado normal, não um erro.
• O filtro ?cnpj= aceita o CNPJ com ou sem máscara; internamente é normalizado antes da consulta.