# Sumário de Integração NFSe - CD9 & Digisan

Este documento descreve a arquitetura técnica e os fluxos de dados implementados para a emissão de Notas Fiscais de Serviço (NFS-e) através do gateway Digisan.

## 1. Pilha Tecnológica
- **Backend**: Laravel 9+ (PHP 8.x)
- **Frontend**: React / Next.js com Material UI (MUI)
- **Comunicação**: REST API (JSON) via HTTPS
- **Autenticação**: API Key (Header `x-api-key`)

## 2. Estrutura da Integração
A integração é centrada na classe [DigisanService.php](file:///e:/WORK/CLUBT-TI/PROJECTS/CD9/cd_back/app/Services/DigisanService.php), que abstrai as chamadas para a API da Digisan.

- **Endpoints Utilizados (Base URL: `https://api.digisan.com.br/api/v1`)**:
  - `POST /nfse`: Emissão de nova nota.
  - `GET /nfse/{id}`: Consulta de status.
  - `GET /nfse/{id}/pdf`: Recuperação do documento PDF.
  - `GET /nfse/{id}/xml`: Recuperação do arquivo XML.

## 3. Dados Enviados (Payload de Emissão)
Mapeamos os seguintes campos internos para o payload da Digisan:

| Campo Digisan | Origem no CD9 | Descrição |
| :--- | :--- | :--- |
| `tipoEmissao` | Fixo: `NORMAL` | Tipo de operação. |
| `prestador.cnpj` | `CDEmpresa (ID 14)` | CNPJ do Centro de Destroca (Prestador). |
| `tomador.cnpjCpf` | `Empresa.cnpj` | CNPJ/CPF do cliente faturado. |
| `tomador.razaoSocial` | `Empresa.nome` | Razão social do cliente. |
| `tomador.inscricaoMunicipal` | `Empresa.inscricao_municipal` | Inscrição municipal do tomador. |
| `tomador.endereco` | Vários campos de [Empresa](file:///e:/WORK/CLUBT-TI/PROJECTS/CD9/cd_back/app/Models/Cadastro/CD/CDEmpresa.php#11-40) | Logradouro, número, bairro, CEP, UF. |
| `tomador.endereco.codigoMunicipio` | `Empresa.cidade` | Código IBGE do município. |
| `servico.valorServicos` | `FinContasReceber.valor_total` | Valor bruto da fatura. |
| `servico.itemListaServicoLC116` | Contrato ou Empresa | Código do serviço (Ex: `11.04`). |
| `servico.aliquotaIss` | Contrato ou Empresa | Alíquota do ISS (Ex: `5.00`). |
| `servico.issRetido` | Fixo: `false` | Indica se o ISS é retido na fonte. |
| `servico.discriminacao` | Automático | Texto formatado com período e número da fatura. |

## 4. Fluxo de Processamento
1. **Geração de Fatura**: O sistema agrupa movimentações financeiras em um "Contas a Receber".
2. **Pré-visualização**: O usuário revisa os dados (Tomador, Valores, Impostos) em um modal no frontend.
3. **Solicitação de Emissão**: O frontend dispara o comando para o backend.
4. **Comunicação com Digisan**: O backend valida os dados, gera o payload e envia para a Digisan.
5. **Persistência**: O ID de referência da Digisan e o status inicial (`PROCESSANDO` ou `AUTORIZADA`) são salvos na tabela local `fin_notas_fiscais`.
6. **Download**: URLs de PDF/XML são disponibilizadas via proxy no backend para garantir segurança.

## 5. Pontos de Atenção para Reunião
- **Ambiente de Homologação**: Precisamos confirmar a `BASE_URL` e `API_KEY` para testes antes do Go-Live.
- **Webhook/Status**: confirmar se a Digisan utiliza webhooks para informar mudanças de status ou se devemos manter o polling via `GET /nfse/{id}`.
- **Campos Específicos**: Validar se para o município de São Luís (MA) existem campos obrigatórios adicionais não listados no padrão nacional.