Central de Ajuda Quaza Provedores

o Projeto das API's em cSharp segue a arquitetura mais mordena de criação de API's, onde

Para o inicio do desenvolvimento das nossas API's com cSharp, temos que ter alguns conhecimentos previos, o dominio da linguagem cSharp não é essencial, pois poderá entender no decorrer do desenvolvimento, mas um certo entimento do docker, onde ficará o banco para o desenvolvimento, pelo menos subir um postgres 15 com bind de portas e salvar o storage, para quando o dokcer reiniciar nao perder o banco salvo.

o Projeto das API's em cSharp segue a arquitetura mais mordena de criação de API's, onde separaremos o maximo possivel da regra de negocio e suas responsabilidades.

Atualmente estamos organizando em 3 grandes SOLUTIONS FOLDERS, são pastas que não são criadas fisicamente, somente em exibição, serve para organizar dentro da IDE.

As SOLUTIONS FOLDERS são as Core, CrossCutting e Projects

Core

Dentro da core, irão ficar basicamente as BASES, exemplo Entity, que cada um das nossas entitdades irão extender. O RequestResponse, Command, Query, cada um desses são bases para os seus respectivos, o Core é referente as bases que todos os outros projetos vão usar, nele inclusive, ficam os pacostes NuGet's, resposavel pelos controllers e domain

Architecture

Ficara os respectivos bases da aplicação ou os bases e pacotes NuGet's referente as Aplicações, o responsavel pelas regras da aplicação, o sistema backend em si

Infrastructure

Ficara os bases e pacotes NuGet's referente a camada de infrastructure, que antigamente era chamada de DAO, a camada doi banco de dados

CrossCutting

O cross cutting, tambem chamado de "responsabilidades transversais" são serviçoes comuns fornecidos por uma camada ou serviço específico usado por todas as camadas de uma aplicação. Seria como uma camada/serviço que cruza toda a hierarquia. Ali dentro teremos separado entre os BASES, as policies, o controle de mensageria, e as coisas que tanto o Serviços externos e serviços internos vão usar

Os serviços externos serão as API's que usaremos de terceiros, exemplo, PlugNotas, Sicredi, Sicoob, DryTelecom....

Os Serviços internos serão os que usaremos internamente, RabbitMQ, Redis...

Projects serão so nossos Projetos propriamente ditos, Hoje temos 2, APEX e ATLAS

Apex é o projeto que gerenciara o que hoje chamamos de backuper, ele contera nossos clientes, quem tem permissão, versões das aplicações deles, e tudo mais, inclusive logins, inclusive tera login tanto de usuarios, que serão usuarios do tipo ADMIN, que vão poder inativar clientes e tudo mais e usuario do tipo CONSUMERS que é nossos clientes, eles vao ter acesso a consumir as API's que estamos criando

Atlas é a API que cuidará de tudo referente a GEOGRAFIA, Paises, Estados, Cidades, Provincias, Codigo de Telefone e tudo mais.

dentro de cada projeto teremos as separações, de API que é basicamente o controller que cuidará das rotas.

Aplication será o resposavel que tera os Commands, Queries e Handlers, as traduções e seus services de regra de nogocios

Domain será o resposavel aos Models do projeto/sistema, é como sera salvo no banco de dados e seus vinculos

Infrastructure fica os context, os mappings repositories, seeds, tudo relacionado a salvar ou buscar do banco de dados.

Com isso voce terá um entendimento mais amplo do que estamos tentando trabalhar

Então como estamos construindo ou como isso tudo ta funcionando, atualmente, a API.[projeto] servira basicamente um controller de rota, tem uma rota aberta, que ira receber em POST, GET, PATCH ou DELETE e ira receber um determinado DTO (Data Transfer Object), e via MediatoR ele ira enviar pro cara certo, tudo que irá modificar no banco sera um COMMAND (inserção), PATCH (alteração) ou DELETE (remoção), ou um QUERY, uma busca no banco de dados.

a função no controller é, receber um DTO em json e converter em objeto, e lançar para a aplication via MediatoR, verificar e retornar de acordo com o que foi processado

No Handler, tanto de QUERY quanto do COMMAND, terá tanto o DTO de recebimento quanto da resposta, o Handler recebera é seguira o que precisa fazer, basicamente irá chamar um grupo de services que ira manipular os dados para processamento, se precisar buscar dados do banco usará os repositories, para não precisarmos escrever a mesma consulta mais de uma vez, os services são para não escrever os mesmos processos mais de uma vez.

O Handler serve basicamente para criar um passo a passo de processamento que ele ira fazer quando receber uma chamada de uma determinada rota.

Desenvolvimento

os Commands criados, sempre serão selados (class sealed), nada pode extender eles

as Queries criadas, sempre serão registros (class record), não sofrerão mudanças do que veio via requisição

Toda a vez que criar um Service, Handler, Query, Command... devido a injeção de dependencia, teremos que  registrar e adicionar no escopo

Criei ja pipeline que compila em produção a imagem da versão e publica no nosso registry, não estamos usando um serviço como o DOCKER HUB.

Glossário

Pegadinhas frequentes

FAQ

Quem pode acessar essa funcionalidade?

Depende da permissão do usuário. Confira com o administrador do Quaza se você não vê a opção.

O que fazer se aparecer um erro?

Anote a mensagem completa, screenshot, e abra um chamado no suporte do Quaza com esses dados.

Esta funcionalidade tem versão para cliente final?

Algumas funcionalidades têm Portal do Cliente. Verifique no módulo Portal .

Posso integrar via API?

Sim — a maioria das funcionalidades do Quaza expõe endpoints REST. Consulte a documentação técnica.

Quaza tem treinamento oficial?

Sim — equipe de suporte oferece sessões de onboarding sob agendamento.

Ciclo completo da operação

Boas práticas operacionais

Para tirar o máximo desta funcionalidade, observe os pontos abaixo. São práticas que provedores experientes adotam para evitar erros recorrentes e maximizar valor extraído do Quaza.

Antes de operar

• Confirme permissão de acesso: nem todo operador tem permissão para todas as funcionalidades. Verifique com o administrador do Quaza se algo não aparece como esperado. Permissões são vinculadas a papéis (operador, supervisor, admin).
• Cadastros pré-requisitos completos: muitas funcionalidades dependem de outros cadastros estarem completos antes. Por exemplo, antes de criar um contrato você precisa ter o cliente cadastrado, plano de vendas configurado, e regras de cobrança definidas.
• Treine pelo menos 2 operadores: redundância previne paralisação por ausência. Funcionário pode sair, ficar doente, ter dia ruim. Mantenha conhecimento distribuído entre múltiplas pessoas.
• Documente procedimentos internos: crie checklist próprio para operações recorrentes. Quem opera amanhã agradece — especialmente se for funcionário novo.

Durante a operação

• Documente decisões não óbvias: se você ajustou algo de forma diferente do default, anote o porquê. Próximo operador agradece e evita refazer análise.
• Operações em massa pedem cuidado: antes de aplicar a 100+ registros, teste com 5 e revise resultado completo. Se possível, exporte CSV antes para ter como rollback.
• Backup antes de mudanças grandes: cancelar/desfazer pode não ser possível em todas as ações. Em dúvida, faça export ou imprima tela antes.
• Comunique alterações: mudanças que impactam outras equipes (atendimento, financeiro) devem ser anunciadas com antecedência. Surpresa gera retrabalho.

Acompanhamento e revisão

• Revisão semanal de 30 minutos: dedique tempo regular para revisar o que rodou, falhou, ficou pendente neste módulo. Anomalia detectada cedo custa 10x menos que descoberta tarde.
• Defina KPIs próprios: 2-3 indicadores que medem saúde da operação. Acompanhe tendências, não só valores absolutos. Variação maior que 20% merece investigação.
• Auditoria mensal: revise sample de operações do mês passado. Use logs para confirmar que tudo aconteceu como esperado, sem desvios silenciosos.
• Compare com período anterior: "Vendi R$ 100k" — é bom? Compare com mês anterior, mesmo mês ano passado. Contexto importa mais que número absoluto.

Resolução de problemas

• Anote a mensagem de erro completa: copie o texto exato. Captura de tela ajuda. Anote quais passos levaram ao problema — facilita diagnóstico.
• Tente reproduzir em ambiente de teste: se possível, simule o erro com dado dummy antes de pedir suporte. Isso acelera resolução.
• Procure no histórico: provavelmente alguém já viu erro similar. Veja log de auditoria para entender o que mudou recentemente.
• Abra chamado bem documentado: equipe de suporte do Quaza resolve mais rápido com contexto: o que esperava, o que aconteceu, frequência, screenshots.

Indicadores típicos a acompanhar

Cada provedor define seus próprios indicadores, mas alguns são quase universais para qualquer operação no Quaza:

• Volume mensal processado (registros/transações/eventos)
• Taxa de erro (% de operações que falharam)
• Tempo médio de processamento
• Cobertura (% da carteira atendida pela funcionalidade)
• Satisfação operacional (feedback da equipe que usa)

Compare valores atuais com média dos últimos 3 meses. Variação maior que 20% em qualquer direção merece investigação — pode ser melhoria sustentável ou degradação silenciosa.

Recursos relacionados no Quaza

Este recurso se conecta com outros módulos do sistema. Conhecer essas conexões ajuda no troubleshooting e em decisões operacionais:

• Cadastro de cliente — base de tudo no Quaza. Cliente bem cadastrado evita problemas downstream.
• Plano de Contas — onde o impacto financeiro é classificado contabilmente.
• Logs de auditoria — histórico de quem fez o quê e quando, essencial para diagnóstico.
• Permissões e papéis — definem quem pode operar o quê.
• Tarefas crontab — automações que tocam neste recurso periodicamente.

Referência rápida

Atalhos e shortcuts para operação eficiente:

• Busca avançada: use filtros de data, status, responsável para reduzir lista. Filtro padrão pode esconder registros antigos.
• Exportação: a maioria das listas exporta para CSV/Excel. Útil para análise externa ou backup pré-mudança.
• Histórico: cada registro tem timeline de modificações. Acesse via botão "Histórico" ou aba lateral.
• Atalhos de teclado: Ctrl+F (busca), Ctrl+S (salvar), Esc (cancelar) na maioria das telas.
• Permissão restrita: se botão estiver cinza, é falta de permissão — não bug.