Visão Geral do Serviço

O serviço bravalara é responsável por mapear dados fiscais para detalhes de pedidos e gerar notas fiscais através do serviço de terceiros Avalara. Atua como o único ponto de acesso à Avalara, significando que todas as solicitações destinadas à Avalara devem passar por este microsserviço. O BRavalara depende da importação de dados fiscais do Netsuite para seu banco de dados.

Principais Funcionalidades

• Geração de Notas Fiscais: Gera notas fiscais para pedidos entregues no Brasil através da integração com Avalara
• Gerenciamento de Dados Fiscais: Gerencia dados fiscais de hubs e produtos importados do Netsuite
• Validação de Prontidão Fiscal: Valida o status de prontidão fiscal para hubs e produtos
• Geração de Chave de Acesso da Nota Fiscal: Gera chaves de acesso de notas fiscais seguindo a lógica da SEFAZ
• API GraphQL: Expõe APIs GraphQL para geração de notas fiscais e gerenciamento de dados fiscais
• Exportação para Data Warehouse: Exporta dados de notas fiscais para data warehouse para análises

Objetivo

Gerar notas fiscais para os pedidos que entregamos, garantindo 100% de geração de notas fiscais para pedidos “aplicáveis”. Pedidos não aplicáveis são pedidos cancelados ou pedidos sem itens.

Dependências

Serviços Externos:

• Avalara: Serviço de terceiros para cálculo de impostos e geração de notas fiscais
• Netsuite: Sistema ERP que fornece dados fiscais de hubs e produtos
• Snowflake: Data warehouse para exportação de dados fiscais
• Cloud Functions: Para importação de dados fiscais do Snowflake
• MONY: Serviço backend para gerenciamento de números de notas fiscais

Fontes de Dados:

• Dados fiscais de Hub/Localização do Netsuite (exportados diariamente às 3:00 AM horário BR)
• Dados fiscais de Produto/Item do Netsuite (exportados a cada 2 horas)

Componentes da Arquitetura

Serviços Principais

Invoice Service

• Processa solicitações de geração de notas fiscais
• Mapeia dados de pedidos para o formato de transação Avalara
• Gerencia o ciclo de vida da nota fiscal (solicitação, confirmação, atualização)
• Trata erros e tentativas de notas fiscais

Location Service

• Gerencia dados fiscais de hub/localização
• Valida a completude dos dados de localização
• Trata importações de dados de localização do Netsuite

Item Service

• Gerencia dados fiscais de produto/item
• Valida a prontidão fiscal para produtos
• Trata importações de dados de itens do Netsuite
• Exporta dados fiscais de itens para sistemas downstream

Processamento de Eventos

O serviço processa eventos de geração de notas fiscais de forma assíncrona:

1. Recepção de Evento: Recebe eventos invoice_generation do canal bravalara-invoice-generation
2. Mapeamento de Dados: Mapeia dados de pedidos para o formato de solicitação de transação Avalara
3. Enriquecimento de Dados Fiscais: Enriquece a solicitação com dados fiscais de hub e produto do banco de dados
4. Geração de Nota Fiscal: Envia solicitação de transação para a API Avalara
5. Confirmação de Nota Fiscal: Confirma a geração da nota fiscal com a Avalara
6. Exportação de Dados: Exporta dados da nota fiscal para o data warehouse

API GraphQL

O serviço expõe APIs GraphQL para:

Queries

• checkTaxReadiness(externalId: String!): Verifica se um produto possui todos os dados fiscais necessários
• getTaxReadinessStatus(sku: String!): Obtém o status detalhado de prontidão fiscal de um produto
• fetchInvoice(accessKey: String!): Busca detalhes da nota fiscal pela chave de acesso
• checkHubsTaxReadiness(hubIds: [String]): Verifica a prontidão fiscal para múltiplos hubs
• getInvoiceErrors(beginDate: String, endDate: String): Obtém erros de geração de notas fiscais

Mutations

• importLocationData(data: [ImportLocationDataInput]): Importa dados fiscais de hub/localização
• importProductData(data: [ImportProductDataInput]): Importa dados fiscais de produto/item
• updateLocationData(data: UpdateLocationDataInput): Atualiza dados de localização (ex: série da nota fiscal)
• getInvoice(orderData: OrderData!): Gera nota fiscal de forma síncrona
• getInvoiceAsync(orderData: OrderData!): Gera nota fiscal de forma assíncrona (retorna ID do pedido)

Fluxo de Dados

Fluxo de Importação de Dados Fiscais

1. Exportação do Netsuite: Dados exportados do Netsuite para o Snowflake via Stitch

   • Dados de localização: Diariamente às 3:00 AM horário BR
   • Dados de itens: A cada 2 horas

2. Processamento de Cloud Function: Cloud Functions executam consultas SQL no Snowflake

   • Filtra hubs do Brasil (BR-%)
   • Exclui itens expirados (%_exp)
   • Exclui itens GPA (GPA-%)

3. Importação BRavalara: Cloud Functions encaminham dados para o BRavalara

   • Dados armazenados no banco de dados PostgreSQL
   • Validados e enriquecidos com metadados adicionais

Fluxo de Geração de Nota Fiscal

1. Recepção de Evento: Recebe evento invoice_generation com dados do pedido
2. Enriquecimento de Dados:
   • Busca dados fiscais do hub no banco de dados
   • Busca dados fiscais do produto para cada item da linha
   • Valida a prontidão fiscal
3. Mapeamento da Nota Fiscal: Mapeia dados do pedido para o formato de transação Avalara
   • Endereço e dados fiscais do cliente
   • Endereço e dados fiscais do hub
   • Itens da linha com informações fiscais
   • Atribuição de número e série da nota fiscal
4. Integração Avalara:
   • Envia solicitação de transação para a Avalara
   • Confirma a geração da nota fiscal
   • Trata erros e tentativas
5. Exportação de Dados: Exporta dados da nota fiscal para o data warehouse

Gerenciamento de Série da Nota Fiscal

A Série da Nota Fiscal é um campo crítico que deve ser definido manualmente para cada hub:

• Série 1: Nunca usada no BRavalara (foi usada pelo ERP anterior OMIE)
• Série 2: Série padrão para a maioria dos hubs (usada pelo Netsuite)
• Série 3: Usada para Food Trucks RIO777 e SAO777 (compartilham entidades legais com outros hubs)

Os números das notas fiscais devem ser:

• Sequenciais por hub
• Nunca repetir
• Consecutivos sem números faltando

Chave de Acesso da Nota Fiscal

A Chave de Acesso da Nota Fiscal é montada a partir dos dados da nota fiscal e contém um dígito verificador. Pode ser usada para consultar detalhes da nota fiscal no site público da SEFAZ.

Estrutura:

• 2 dígitos: Prefixo do código da cidade
• 4 dígitos: Ano e mês
• 14 dígitos: CNPJ da empresa
• 2 dígitos: Modelo NF-e (sempre “55”)
• 3 dígitos: Série da nota fiscal
• 9 dígitos: Número da nota fiscal
• 1 dígito: Tipo de documento
• 8 dígitos: Código numérico da chave
• 1 dígito: Dígito verificador

URLs de Consulta:

• Produção: https://www.nfe.fazenda.gov.br/portal/consultaRecaptcha.aspx
• Sandbox: https://homologacao.nfe.fazenda.sp.gov.br/ConsultaNFe/consulta/publica/ConsultarNFe.aspx

Canais

Canais de Entrada

• bravalara-invoice-generation: Recebe solicitações de geração de notas fiscais

Canais de Saída

• bravalara-item-tax-out: Publica atualizações de status de prontidão fiscal de itens
• ordr-data-warehouse: Exporta dados de notas fiscais falhadas para o data warehouse

Eventos Publicados

item_tax.updated

Publicado quando o status de prontidão fiscal de um produto muda. Este evento é acionado quando:

• Dados fiscais do produto são importados ou atualizados via API GraphQL
• O status de prontidão fiscal muda (pronto ↔ não pronto)
• A prontidão fiscal é determinada pela presença de: Código HS, Origem, Conta de Ativo, Conta de Despesa e Conta de Receita

Canal: bravalara-item-tax-out

dwh_failed_invoice

Publicado quando a geração da nota fiscal falha. Este evento contém:

• ID do Pedido e ID do Hub
• Código de erro e mensagem de erro
• JSON completo da solicitação que foi enviada para a Avalara
• Chave de acesso e número da nota fiscal (se parcialmente criada)

Canal: ordr-data-warehouse

Configuração

Variáveis de Ambiente

Configuração Avalara:

• AVALARA_BASE_URI: URL base da API Avalara
• AVALARA_OAUTH_TOKEN_URI: Endpoint de token OAuth
• AVALARA_CLIENT_ID: ID do cliente OAuth
• AVALARA_CLIENT_SECRET: Segredo do cliente OAuth

Configuração PubSub:

• PUBSUB_BRAVALARA_INVOICE_GENERATION: Tópico de entrada para eventos de geração de notas fiscais
• PUBSUB_SUBSCRIPTION: Nome da assinatura
• PUBSUB_DEADLETTER: Tópico de dead letter
• PUBSUB_ORDR_DATA_WAREHOUSE_TOPIC: Tópico de exportação para data warehouse
• PUBSUB_BRAVALARA_ITEM_TAX_OUT_TOPIC: Tópico de exportação de impostos de itens

Configuração de Processamento:

• INVOICE_REQUEST_WORKERS: Número de workers concorrentes para solicitações de notas fiscais
• INVOICE_REQUEST_TIMER: Intervalo do timer para solicitações de notas fiscais (segundos)
• INVOICE_UPDATE_TIMER: Intervalo do timer para atualizações de notas fiscais (segundos)
• INVOICE_INVALID_RETRIES: Número de tentativas para notas fiscais inválidas

Tratamento de Erros

O serviço implementa tratamento abrangente de erros:

• Tentativas de Notas Fiscais Inválidas: Contagem configurável de tentativas para notas fiscais inválidas
• Fila de Dead Letter: Mensagens falhadas enviadas para o tópico de dead letter
• Registro de Erros: Todos os erros registrados com logging estruturado
• API de Consulta de Erros: Query GraphQL para recuperar erros de notas fiscais

Métricas e Monitoramento

Métricas Principais:

• Taxa de sucesso de geração de notas fiscais
• Taxa de validação de prontidão fiscal
• Latência de geração de notas fiscais
• Taxas de erro por tipo

SLO do Serviço:

• Meta: 100% de geração de notas fiscais para pedidos aplicáveis
• Pedidos não aplicáveis: Pedidos cancelados ou pedidos sem itens