# 13. 📄 Notas Fiscais

**Gestão completa de documentos fiscais** Controle de NF-e de entrada e saída com histórico completo. **Funcionalidades:**

* NF-e emitidas e de fornecedores
* Controle de status e transmissão
* Histórico de manifestação
* Integração com SEFAZ
* Transmitir NF-es para SEFAZ
* Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)
* Consultar NF-e

## Cria uma NF-e de Conta e Ordem

> \*\*Criar NF-e de Conta e Ordem no sistema\*\*\
> \
> Endpoint utilizado para criar uma Nota Fiscal Eletrônica (NF-e) de Conta e Ordem no sistema.\
> \
> \*\*ATENÇÃO:\*\* Este endpoint apenas \*\*CRIA\*\* a NF-e no sistema, mas \*\*NÃO TRANSMITE\*\* para a SEFAZ.\
> Para transmitir, utilize o endpoint \`POST /api/v2/nfes/transmitir\` após a criação.\
> \
> \*\*Informações Importantes:\*\*\
> \- A NF-e de entrada deve estar previamente cadastrada no sistema.\
> \- A \`Idempotency-Key\` deve ser passada no Header para evitar duplicidade de requisições.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/nfes/conta_e_ordem":{"post":{"summary":"Cria uma NF-e de Conta e Ordem","tags":["13. 📄 Notas Fiscais"],"description":"**Criar NF-e de Conta e Ordem no sistema**\n\nEndpoint utilizado para criar uma Nota Fiscal Eletrônica (NF-e) de Conta e Ordem no sistema.\n\n**ATENÇÃO:** Este endpoint apenas **CRIA** a NF-e no sistema, mas **NÃO TRANSMITE** para a SEFAZ.\nPara transmitir, utilize o endpoint `POST /api/v2/nfes/transmitir` após a criação.\n\n**Informações Importantes:**\n- A NF-e de entrada deve estar previamente cadastrada no sistema.\n- A `Idempotency-Key` deve ser passada no Header para evitar duplicidade de requisições.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Chave de idempotência","schema":{"type":"string"}}],"responses":{"201":{"description":"NF-e criada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"nota_fiscal":{"type":"object","properties":{"id":{"type":"string"},"serie":{"type":"string"},"numero_nfe":{"type":"string"},"status":{"type":"string"},"chave_acesso":{"type":"string","nullable":true},"destinatario":{"type":"string"}}},"produtos":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"quantidade":{"type":"string"}}}},"referencias":{"type":"array","items":{"type":"object","properties":{"chave_acesso":{"type":"string"}}}}}}}}},"422":{"description":"Erro de validação","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"string"}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nota_fiscal":{"type":"object","required":["numero","serie","destinatario"],"properties":{"numero":{"type":"string","description":"Número da NF-e de entrada"},"serie":{"type":"string","description":"Série da NF-e de entrada"},"destinatario":{"type":"string","description":"CPF ou CNPJ do destinatário (apenas números)"},"icms_produtos":{"type":"object","description":"Hash mapeando ID do movimento de estoque da entrada para a alíquota de ICMS"},"fcp_produtos":{"type":"object","description":"Hash mapeando ID do movimento de estoque da entrada para a alíquota de FCP"},"acrescimo_ao_valor_dos_produtos":{"type":"number","description":"Valor ou percentual de acréscimo"},"tipo_de_acrescimo_ao_valor_dos_produtos":{"type":"string","enum":["valor","percentual"],"description":"Tipo do acréscimo (valor fixo ou percentual)"}}}}}}}}}}}}
```

## Criar NF-e

> \*\*Criar NF-e no sistema\*\*\
> \
> Endpoint utilizado para criar uma Nota Fiscal Eletrônica (NF-e) no sistema.\
> \
> \*\*ATENÇÃO:\*\* Este endpoint apenas \*\*CRIA\*\* a NF-e no sistema, mas \*\*NÃO TRANSMITE\*\* para a SEFAZ.\
> Para transmitir, utilize o endpoint \`POST /api/v2/nfes/transmitir\` após a criação.\
> \
> \*\*Informações Importantes:\*\*\
> \- O produto deve estar previamente cadastrado no sistema com todas as informações fiscais (NCM, CEST, origem, etc.)\
> \- A \`Idempotency-Key\` deve ser passada no Header para evitar duplicidade de requisições.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/nfes":{"post":{"summary":"Criar NF-e","tags":["13. 📄 Notas Fiscais"],"description":"**Criar NF-e no sistema**\n\nEndpoint utilizado para criar uma Nota Fiscal Eletrônica (NF-e) no sistema.\n\n**ATENÇÃO:** Este endpoint apenas **CRIA** a NF-e no sistema, mas **NÃO TRANSMITE** para a SEFAZ.\nPara transmitir, utilize o endpoint `POST /api/v2/nfes/transmitir` após a criação.\n\n**Informações Importantes:**\n- O produto deve estar previamente cadastrado no sistema com todas as informações fiscais (NCM, CEST, origem, etc.)\n- A `Idempotency-Key` deve ser passada no Header para evitar duplicidade de requisições.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Chave de idempotência para evitar requisições duplicadas","schema":{"type":"string"}}],"responses":{"201":{"description":"NF-e criada com sucesso","content":{"NF-e criada":{},"application/json":{"schema":{"type":"object","properties":{"nota_fiscal":{"type":"object","properties":{"id":{"type":"string"},"serie":{"type":"string"},"numero_nfe":{"type":"string"},"tipo_documento":{"type":"integer"},"tipo_impressao_danfe":{"type":"integer"},"forma_emissao":{"type":"integer"},"finalidade_emissao":{"type":"integer"},"destinatario":{"type":"string"},"cfop":{"type":"string"},"codigo_modalidade_frete":{"type":"integer"},"codigo_meio_de_pagamento":{"type":"integer","nullable":true},"transportadora":{"type":"string","nullable":true},"codigo_processo":{"type":"string","nullable":true},"natureza_da_operacao":{"type":"string","nullable":true},"quantidade_volume":{"type":"integer","nullable":true},"especie_volumes":{"type":"string","nullable":true},"marca_volumes":{"type":"string","nullable":true},"numeracao_volumes":{"type":"string","nullable":true},"peso_bruto":{"type":"number","nullable":true},"peso_liquido":{"type":"number","nullable":true}}},"produtos":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"quantidade":{"type":"number"}}}}}}}}},"422":{"description":"Erro de validação","content":{"Erro de validação (CFOP)":{},"Erro de validação (Produto)":{},"Erro de validação (Campos Obrigatórios)":{},"Erro de validação (Referência Obrigatória)":{},"Erro de validação (Modalidade de Frete)":{},"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"string"}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nota_fiscal":{"type":"object","properties":{"serie":{"type":"string","description":"Série da NF-e"},"numero_nfe":{"type":"string","description":"Número da NF-e (opcional, gerado automaticamente se omitido)"},"tipo_documento":{"type":"string","description":"Tipo do documento (0=Entrada, 1=Saída)","enum":["0","1"]},"tipo_operacao":{"type":"string","description":"Tipo da operação (opcional). Use \"encomenda\" para NF-e de encomenda.","enum":["encomenda"]},"tipo_impressao_danfe":{"type":"string","description":"Formato de impressão (1=Retrato, 2=Paisagem)","enum":["1","2"]},"forma_emissao":{"type":"integer","description":"Forma de emissão da NF-e (1=Normal, 2=Contingência FS, 3=Contingência SCAN, 4=Contingência DPEC, 5=Contingência PS-DA, 6=Contingência SVC-AN, 7=Contingência SVC-RS, 9=Contingência Offline)","enum":[1,2,3,4,5,6,7,9]},"finalidade_emissao":{"type":"string","description":"Finalidade da emissão (1=Normal, 2=Complementar, 3=Ajuste, 4=Devolução)","enum":["1","2","3","4"]},"destinatario":{"type":"string","description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do destinatário"},"cfop":{"type":"string","description":"Código Fiscal de Operações e Prestações"},"codigo_modalidade_frete":{"type":"string","description":"Código da modalidade do frete (0=Emitente, 1=Destinatário, 2=Terceiros, 9=Sem frete)","enum":["0","1","2","9"]},"codigo_meio_de_pagamento":{"type":"string","description":"Código do meio de pagamento"},"transportadora":{"type":"string","description":"CPF/CNPJ da transportadora"},"codigo_processo":{"type":"string","description":"Código de processo ou despacho relacionado"},"quantidade_volume":{"type":"integer","description":"Quantidade de volumes transportados"},"especie_volumes":{"type":"string","description":"Espécie dos volumes (ex: CAIXA, PALLET)"},"marca_volumes":{"type":"string","description":"Marca dos volumes"},"numeracao_volumes":{"type":"string","description":"Numeração dos volumes"},"peso_bruto":{"type":"number","description":"Peso bruto total (kg)"},"peso_liquido":{"type":"number","description":"Peso líquido total (kg)"}},"required":["serie","tipo_documento","tipo_impressao_danfe","finalidade_emissao","destinatario","cfop"]},"produtos":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string","description":"Código identificador do produto no sistema"},"quantidade":{"type":"number","description":"Quantidade vendida (deve ser > 0)"},"pu_entrada":{"type":"number","description":"Preço unitário de entrada (opcional)"}},"required":["codigo","quantidade"]}},"referencias":{"type":"array","description":"Lista de notas fiscais referenciadas (obrigatório para finalidade 2=Complementar e 4=Devolução)","items":{"type":"object","properties":{"chave_acesso":{"type":"string","description":"Chave de acesso da NF-e referenciada (44 dígitos)"}},"required":["chave_acesso"]}}},"required":["nota_fiscal","produtos"]}}}}}}}}
```

## Exibir detalhes da NF-e

> \*\*Exibir detalhes de uma NF-e\*\*\
> \
> Endpoint utilizado para consultar os detalhes de uma Nota Fiscal Eletrônica (NF-e) específica.\
> Retorna todas as informações da nota, incluindo produtos e referências.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/nfes/{id}":{"get":{"summary":"Exibir detalhes da NF-e","tags":["13. 📄 Notas Fiscais"],"description":"**Exibir detalhes de uma NF-e**\n\nEndpoint utilizado para consultar os detalhes de uma Nota Fiscal Eletrônica (NF-e) específica.\nRetorna todas as informações da nota, incluindo produtos e referências.","parameters":[{"name":"id","in":"path","required":true,"description":"ID da NF-e","schema":{"type":"string"}},{"name":"produtos_page","in":"query","required":false,"description":"Número da página para paginação de produtos","schema":{"type":"integer"}},{"name":"referencias_page","in":"query","required":false,"description":"Número da página para paginação de referências","schema":{"type":"integer"}}],"responses":{"200":{"description":"Detalhes da NF-e","content":{"application/json":{"schema":{"type":"object","properties":{"nota_fiscal":{"type":"object","properties":{"id":{"type":"string"},"serie":{"type":"string"},"numero_nfe":{"type":"string"},"tipo_documento":{"type":"integer"},"tipo_impressao_danfe":{"type":"integer"},"forma_emissao":{"type":"integer"},"finalidade_emissao":{"type":"integer"},"destinatario":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true},"codigo_modalidade_frete":{"type":"integer","nullable":true},"codigo_meio_de_pagamento":{"type":"integer","nullable":true},"transportadora":{"type":"string","nullable":true},"codigo_processo":{"type":"string","nullable":true},"quantidade_volume":{"type":"integer","nullable":true},"especie_volumes":{"type":"string","nullable":true},"marca_volumes":{"type":"string","nullable":true},"numeracao_volumes":{"type":"string","nullable":true},"peso_bruto":{"type":"number","nullable":true},"peso_liquido":{"type":"number","nullable":true},"status":{"type":"string"},"chave_acesso_nfe":{"type":"string","nullable":true},"protocolo":{"type":"string","nullable":true},"dthr_emissao":{"type":"string","format":"datetime","nullable":true},"natureza_da_operacao":{"type":"string","nullable":true},"valor_total":{"type":"number"}}},"produtos":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"},"quantidade":{"type":"number"},"valor_unitario":{"type":"number"},"valor_total":{"type":"number"}}}},"referencias":{"type":"array","items":{"type":"object","properties":{"chave_acesso":{"type":"string"}}}}}}}}},"404":{"description":"NF-e não encontrada"}}}}}}
```

## Transmitir NF-e

> \*\*Transmitir NF-e para SEFAZ\*\*\
> \
> Endpoint utilizado para transmitir uma NF-e já criada no sistema Mainô para a SEFAZ.\
> A NF-e deve estar com status 'NAO\_TRANSMITIDA' para poder ser transmitida.\
> \
> \*\*Processo de transmissão:\*\*\
> 1\. A NF-e é enviada para a SEFAZ\
> 2\. O sistema aguarda o retorno do protocolo\
> 3\. A NF-e é marcada como 'ACEITA', 'REJEITADA' ou 'DENEGADA'\
> 4\. Em caso de aceitação, são gerados os arquivos DANFE (PDF) e XML\
> \
> \*\*Status possíveis da NF-e:\*\*\
> \- \`NAO\_TRANSMITIDA\`: NF-e criada mas não enviada para SEFAZ\
> \- \`EM\_TRANSMISSAO\`: NF-e sendo processada pela SEFAZ\
> \- \`ACEITA\`: NF-e aceita pela SEFAZ e protocolada\
> \- \`REJEITADA\`: NF-e rejeitada pela SEFAZ (com motivo)\
> \- \`CANCELADA\`: NF-e cancelada após transmissão\
> \- \`DENEGADA\`: NF-e denegada pela SEFAZ

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/nfes/transmitir":{"post":{"summary":"Transmitir NF-e","tags":["13. 📄 Notas Fiscais"],"description":"**Transmitir NF-e para SEFAZ**\n\nEndpoint utilizado para transmitir uma NF-e já criada no sistema Mainô para a SEFAZ.\nA NF-e deve estar com status 'NAO_TRANSMITIDA' para poder ser transmitida.\n\n**Processo de transmissão:**\n1. A NF-e é enviada para a SEFAZ\n2. O sistema aguarda o retorno do protocolo\n3. A NF-e é marcada como 'ACEITA', 'REJEITADA' ou 'DENEGADA'\n4. Em caso de aceitação, são gerados os arquivos DANFE (PDF) e XML\n\n**Status possíveis da NF-e:**\n- `NAO_TRANSMITIDA`: NF-e criada mas não enviada para SEFAZ\n- `EM_TRANSMISSAO`: NF-e sendo processada pela SEFAZ\n- `ACEITA`: NF-e aceita pela SEFAZ e protocolada\n- `REJEITADA`: NF-e rejeitada pela SEFAZ (com motivo)\n- `CANCELADA`: NF-e cancelada após transmissão\n- `DENEGADA`: NF-e denegada pela SEFAZ","parameters":[],"responses":{"202":{"description":"NF-e agendada para transmissão","content":{"Transmissão agendada com sucesso":{},"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem de confirmação"},"nota_fiscal_id":{"type":"integer","description":"ID da NF-e que foi agendada"},"status":{"type":"string","description":"Status do agendamento"}},"required":["message","nota_fiscal_id","status"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serie":{"type":"string","description":"Série da NF-e"},"numero":{"type":"string","description":"Número da NF-e"},"url":{"type":"string","description":"URL de callback (Webhook) para receber atualizações de status"}},"required":["serie","numero"]}}}}}}}}
```

## Exportar XMLs de NFes dos fornecedores

> \*\*Exportar XMLs das NF-es recebidas de fornecedores\*\*\
> \
> Endpoint utilizado para exportar os XMLs das NF-es recebidas de fornecedores em um período específico.\
> O sistema gera um arquivo ZIP contendo todos os XMLs encontrados no período informado.\
> \
> \*\*Funcionalidades:\*\*\
> \- Exportação em lote de XMLs recebidos\
> \- Filtro por período de recebimento/entrada\
> \- Download direto do arquivo ZIP\
> \- Organização automática dos arquivos\
> \
> \*\*Casos de uso:\*\*\
> \- Backup de documentos fiscais recebidos\
> \- Integração com sistemas contábeis\
> \- Auditoria de fornecedores\
> \- Controle de entrada de mercadorias\
> \- Arquivo fiscal obrigatório\
> \
> \*\*Formato dos arquivos:\*\*\
> \- Arquivo ZIP contendo XMLs individuais\
> \- Nomes dos arquivos seguem padrão: {chave\_acesso}.xml\
> \- Organização por data de recebimento

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/nfes_dos_fornecedores":{"get":{"summary":"Exportar XMLs de NFes dos fornecedores","tags":["13. 📄 Notas Fiscais"],"description":"**Exportar XMLs das NF-es recebidas de fornecedores**\n\nEndpoint utilizado para exportar os XMLs das NF-es recebidas de fornecedores em um período específico.\nO sistema gera um arquivo ZIP contendo todos os XMLs encontrados no período informado.\n\n**Funcionalidades:**\n- Exportação em lote de XMLs recebidos\n- Filtro por período de recebimento/entrada\n- Download direto do arquivo ZIP\n- Organização automática dos arquivos\n\n**Casos de uso:**\n- Backup de documentos fiscais recebidos\n- Integração com sistemas contábeis\n- Auditoria de fornecedores\n- Controle de entrada de mercadorias\n- Arquivo fiscal obrigatório\n\n**Formato dos arquivos:**\n- Arquivo ZIP contendo XMLs individuais\n- Nomes dos arquivos seguem padrão: {chave_acesso}.xml\n- Organização por data de recebimento","parameters":[{"name":"data_inicio","in":"query","required":true,"description":"Data de início do período para exportação (formato: dd/mm/yyyy)","schema":{"type":"string"}},{"name":"data_fim","in":"query","required":true,"description":"Data de fim do período para exportação (formato: dd/mm/yyyy)","schema":{"type":"string"}}],"responses":{"200":{"description":"ZIP com XMLs dos fornecedores","content":{"URL para download do ZIP":{},"application/zip":{"schema":{"type":"object","properties":{"zip_url":{"type":"string","format":"uri","description":"URL para download do arquivo ZIP contendo os XMLs"}}}},"application/json":{"schema":{"type":"object","properties":{"zip_url":{"type":"string","format":"uri","description":"URL para download do arquivo ZIP contendo os XMLs"}}}}}},"400":{"description":"Nenhuma NFe encontrada no período","content":{"Sem NFes no período":{},"application/zip":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"nfes_dos_fornecedores":{"type":"array","items":{"type":"string"}}}}}}},"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"nfes_dos_fornecedores":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"Token inválido ou expirado","content":{"Token inválido":{},"application/zip":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}},"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Listar notas fiscais confirmadas

> \*\*Listar todas as notas fiscais confirmadas\*\*\
> \
> Endpoint utilizado para consultar todas as notas fiscais que já foram confirmadas no sistema Mainô.\
> Permite filtrar por data de confirmação e oferece suporte completo à paginação.\
> \
> \*\*Comportamento do filtro por data:\*\*\
> \- Se informada \`data\_referencia '2021-08-03'\`, serão enviadas as notas confirmadas \*\*a partir de\*\* 3 de agosto de 2021\
> \- Caso não seja informada, \*\*todas as notas confirmadas\*\* serão enviadas\
> \- A data é inclusiva (inclui registros da data especificada)\
> \
> \*\*Formatos de data aceitos:\*\*\
> \- "aaaa-mm-dd" (ISO: 2021-08-03)\
> \- "dd-mm-aaaa" (BR: 03-08-2021)\
> \- "aaaa/mm/dd" (US: 2021/08/03)  \
> \- "dd/mm/aaaa" (BR: 03/08/2021)\
> \
> \*\*Casos de uso:\*\*\
> \- Sincronização de dados fiscais\
> \- Relatórios de conformidade fiscal\
> \- Auditoria de documentos confirmados\
> \- Integração com sistemas contábeis

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/notas_fiscais_confirmadas":{"get":{"summary":"Listar notas fiscais confirmadas","tags":["13. 📄 Notas Fiscais"],"description":"**Listar todas as notas fiscais confirmadas**\n\nEndpoint utilizado para consultar todas as notas fiscais que já foram confirmadas no sistema Mainô.\nPermite filtrar por data de confirmação e oferece suporte completo à paginação.\n\n**Comportamento do filtro por data:**\n- Se informada `data_referencia '2021-08-03'`, serão enviadas as notas confirmadas **a partir de** 3 de agosto de 2021\n- Caso não seja informada, **todas as notas confirmadas** serão enviadas\n- A data é inclusiva (inclui registros da data especificada)\n\n**Formatos de data aceitos:**\n- \"aaaa-mm-dd\" (ISO: 2021-08-03)\n- \"dd-mm-aaaa\" (BR: 03-08-2021)\n- \"aaaa/mm/dd\" (US: 2021/08/03)  \n- \"dd/mm/aaaa\" (BR: 03/08/2021)\n\n**Casos de uso:**\n- Sincronização de dados fiscais\n- Relatórios de conformidade fiscal\n- Auditoria de documentos confirmados\n- Integração com sistemas contábeis","parameters":[{"name":"data_referencia","in":"query","schema":{"type":"string"},"required":false,"description":"Data de confirmação para filtrar notas fiscais. Formatos aceitos: 'aaaa-mm-dd', 'dd-mm-aaaa', 'aaaa/mm/dd', 'dd/mm/aaaa'"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"required":false,"description":"Número da página para paginação (padrão: primeira página)"}],"responses":{"200":{"description":"Lista de notas fiscais confirmadas","content":{"Lista com notas confirmadas":{},"Lista vazia (sem notas)":{},"application/json":{"schema":{"type":"object","properties":{"data_referencia":{"type":"string","nullable":true,"description":"Data de referência utilizada no filtro"},"notas_fiscais":{"type":"array","description":"Lista das notas fiscais confirmadas","items":{"type":"object","properties":{"serie":{"type":"string","description":"Série da nota fiscal"},"numero_nfe":{"type":"string","description":"Número da nota fiscal"},"data_confirmacao":{"type":"string","format":"datetime","description":"Data de confirmação"},"xml":{"type":"string","description":"Conteúdo XML da nota fiscal"}}}},"pagination":{"type":"object","description":"Informações de paginação","properties":{"total":{"type":"integer","description":"Número total de registros"},"previous_page":{"type":"string","nullable":true,"description":"URL da página anterior"},"next_page":{"type":"string","nullable":true,"description":"URL da próxima página"}}}}}}}},"401":{"description":"Token inválido ou expirado","content":{"Token inválido":{},"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Listar notas fiscais emitidas

> \*\*Listar notas fiscais eletrônicas emitidas\*\*\
> \
> Endpoint para consultar todas as NF-es emitidas pela empresa em um período específico.\
> Permite filtrar por data, número da NF-e, CNPJ do destinatário e incluir os XMLs na resposta.\
> \
> \*\*Filtros disponíveis:\*\*\
> \- Período de emissão (data\_inicio e data\_fim)\
> \- Número específico da NF-e\
> \- CNPJ do destinatário\
> \- Opção para incluir conteúdo XML\
> \
> \*\*Status possíveis das NF-es:\*\*\
> \- NAO\_TRANSMITIDA\
> \- EM\_TRANSMISSAO\
> \- ACEITA\
> \- REJEITADA\
> \- CANCELADA\
> \- DENEGADA

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/notas_fiscais_emitidas":{"get":{"summary":"Listar notas fiscais emitidas","tags":["13. 📄 Notas Fiscais"],"description":"**Listar notas fiscais eletrônicas emitidas**\n\nEndpoint para consultar todas as NF-es emitidas pela empresa em um período específico.\nPermite filtrar por data, número da NF-e, CNPJ do destinatário e incluir os XMLs na resposta.\n\n**Filtros disponíveis:**\n- Período de emissão (data_inicio e data_fim)\n- Número específico da NF-e\n- CNPJ do destinatário\n- Opção para incluir conteúdo XML\n\n**Status possíveis das NF-es:**\n- NAO_TRANSMITIDA\n- EM_TRANSMISSAO\n- ACEITA\n- REJEITADA\n- CANCELADA\n- DENEGADA","parameters":[{"name":"data_inicio","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Data inicial de emissão (formato YYYY-MM-DD)"},{"name":"data_fim","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Data final de emissão (formato YYYY-MM-DD)"},{"name":"cnpj_destinatario","in":"query","schema":{"type":"string"},"required":false,"description":"CNPJ do destinatário para filtro"},{"name":"numero_nfe","in":"query","schema":{"type":"string"},"required":false,"description":"Número da NFe para busca específica"},{"name":"data_vencimento","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Data de vencimento do recebimento (formato YYYY-MM-DD)"},{"name":"data_pagamento","in":"query","schema":{"type":"string","format":"date"},"required":false,"description":"Data de liquidação do recebimento (formato YYYY-MM-DD)"},{"name":"centro_de_custo_id","in":"query","schema":{"type":"integer"},"required":false,"description":"ID do centro de custo"},{"name":"centro_de_custo_descricao","in":"query","schema":{"type":"string"},"required":false,"description":"Descrição do centro de custo (busca parcial)"},{"name":"exibir_xmls","in":"query","schema":{"type":"boolean"},"required":false,"description":"Incluir conteúdo dos XMLs na resposta"},{"name":"page","in":"query","schema":{"type":"integer"},"required":false,"description":"Número da página (padrão: 1, 25 itens por página)"}],"responses":{"200":{"description":"Lista de notas fiscais emitidas","content":{"Lista com notas fiscais":{},"Lista vazia":{},"application/json":{"schema":{"type":"object","properties":{"notas_fiscais":{"type":"array","description":"Lista das notas fiscais encontradas","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID da nota fiscal"},"xml":{"type":"string","description":"Conteúdo do XML da NFe (apenas se exibir_xmls=true)","nullable":true},"xml_cancelamento":{"type":"string","description":"Conteúdo do XML de cancelamento (apenas se exibir_xmls=true)","nullable":true},"usuario":{"type":"string","description":"Email do usuário emissor"},"serie":{"type":"string","description":"Série da nota fiscal"},"numero_nfe":{"type":"string","description":"Número da NFe"},"tipo_documento":{"type":"string","description":"Tipo do documento fiscal"},"tipo_impressao_danfe":{"type":"string","description":"Tipo de impressão do DANFE"},"dthr_emissao":{"type":"string","format":"datetime","description":"Data e hora de emissão"},"status":{"type":"string","description":"Status atual da nota fiscal","enum":["NAO_TRANSMITIDA","EM_TRANSMISSAO","ACEITA","REJEITADA","CANCELADA","DENEGADA"]},"chave_acesso_nfe":{"type":"string","description":"Chave de acesso da NFe"},"valor_nota_nfe":{"type":"number","format":"float","description":"Valor total da nota fiscal"}}}},"pagination":{"type":"object","description":"Informações de paginação","properties":{"total":{"type":"integer","description":"Total de registros"},"previous_page":{"type":"string","description":"URL da página anterior","nullable":true},"next_page":{"type":"string","description":"URL da próxima página","nullable":true}}}}}}}},"401":{"description":"Token inválido ou expirado","content":{"Token inválido":{},"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```

## Exportar XMLs de notas fiscais emitidas

> \*\*Exportar XMLs das NF-es emitidas\*\*\
> \
> Endpoint utilizado para exportar os XMLs das NF-es emitidas em um período específico.\
> O sistema gera um arquivo ZIP contendo todos os XMLs encontrados no período informado.\
> \
> \*\*Funcionalidades:\*\*\
> \- Exportação em lote de XMLs\
> \- Filtro por período de emissão\
> \- Download direto do arquivo ZIP\
> \- Processamento assíncrono para períodos grandes\
> \
> \*\*Formatos suportados:\*\*\
> \- Arquivo ZIP contendo XMLs individuais\
> \- Nomes dos arquivos seguem padrão: {chave\_acesso}.xml

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"13. 📄 Notas Fiscais","description":"**Gestão completa de documentos fiscais**\nControle de NF-e de entrada e saída com histórico completo.\n**Funcionalidades:**\n- NF-e emitidas e de fornecedores\n- Controle de status e transmissão\n- Histórico de manifestação\n- Integração com SEFAZ\n- Transmitir NF-es para SEFAZ\n- Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)\n- Consultar NF-e"}],"servers":[{"url":"https://api.maino.com.br/api/v2","description":"Servidor de Produção"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"**Token JWT de Autenticação**\nToken obtido através do endpoint `/authentication`.\n**Formato:** `Bearer {seu_token_jwt}`\n**Exemplo:** `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n**Validade:** Sem expiração"}}},"paths":{"/nfes_emitidas":{"get":{"summary":"Exportar XMLs de notas fiscais emitidas","tags":["13. 📄 Notas Fiscais"],"description":"**Exportar XMLs das NF-es emitidas**\n\nEndpoint utilizado para exportar os XMLs das NF-es emitidas em um período específico.\nO sistema gera um arquivo ZIP contendo todos os XMLs encontrados no período informado.\n\n**Funcionalidades:**\n- Exportação em lote de XMLs\n- Filtro por período de emissão\n- Download direto do arquivo ZIP\n- Processamento assíncrono para períodos grandes\n\n**Formatos suportados:**\n- Arquivo ZIP contendo XMLs individuais\n- Nomes dos arquivos seguem padrão: {chave_acesso}.xml","parameters":[{"name":"data_inicio","in":"query","schema":{"type":"string"},"required":true,"description":"Data de início do período (formato: dd/mm/aaaa)"},{"name":"data_fim","in":"query","schema":{"type":"string"},"required":true,"description":"Data de fim do período (formato: dd/mm/aaaa)"}],"responses":{"200":{"description":"Arquivo ZIP com XMLs das NF-es","content":{"URLs para download":{},"application/zip":{"schema":{"type":"object","properties":{"zip_url":{"type":"string","format":"uri","description":"URL do arquivo ZIP com XMLs"},"zip_url_danfe":{"type":"string","format":"uri","description":"URL do arquivo ZIP com DANFEs"}}}},"application/json":{"schema":{"type":"object","properties":{"zip_url":{"type":"string","format":"uri","description":"URL do arquivo ZIP com XMLs"},"zip_url_danfe":{"type":"string","format":"uri","description":"URL do arquivo ZIP com DANFEs"}}}}}},"400":{"description":"Nenhuma NFe encontrada no período","content":{"Sem NFes no período":{},"application/zip":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"nfes_emitidas":{"type":"array","items":{"type":"string"}}}}}}},"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"nfes_emitidas":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"Token inválido ou expirado","content":{"Token inválido":{},"application/zip":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}},"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}
```