> For the complete documentation index, see [llms.txt](https://changelog.maino.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changelog.maino.com.br/api-reference-maino/12.-notas-fiscais.md).

# 12. 📄 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":"12. 📄 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":["12. 📄 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)"}}}}}}}}}}}}
```

## Importa o XML de uma NF-e autorizada

> \*\*Registrar no sistema uma NF-e já autorizada pela SEFAZ a partir do XML\*\*\
> \
> Recebe o XML completo da NF-e (\`nfeProc\`, com o protocolo de autorização) e registra a nota na\
> empresa autenticada, como a importação de XML pela tela.\
> \
> \- Quando a empresa é a \*\*emitente\*\*, a NF-e é registrada como nota própria (\`registro\_tipo: nota\_fiscal\`).\
> \- Quando a empresa é a \*\*destinatária\*\*, a NF-e é registrada como compra (\`registro\_tipo: compra\`).\
> \- \`baixa\_estoque\` movimenta o estoque com os itens da nota: nota de saída dá \*\*saída\*\* no estoque; nota de\
> &#x20; \*\*entrada\*\* (compra ou nota própria de entrada) dá \*\*entrada\*\* no estoque.\
> \- \`gera\_titulo\` gera as contas a receber (nota própria de saída) ou a pagar (compra e nota própria de\
> &#x20; entrada) a partir das \*\*duplicatas do XML\*\*; sem duplicatas, nenhum título é criado. A opção da tela\
> &#x20; "fatura para 30 dias" não existe na API.\
> \- Empresa que exige plano de contas, com \`gera\_titulo\` e sem \`plano\_de\_conta\_id\` válido: a \*\*nota própria\*\* é\
> &#x20; registrada com aviso \`importacao\_incompleta\` (o título não é criado), enquanto a \*\*compra\*\* é recusada com\
> &#x20; \`plano\_de\_contas\_nao\_selecionado\` e nada é gravado.\
> \
> \*\*Leia sempre \`avisos\`:\*\* o status \`criada\_com\_avisos\` indica que a nota foi registrada, mas o estoque\
> ou os títulos ficaram incompletos (código \`importacao\_incompleta\`, com o motivo em \`detalhe\`).\
> \
> \*\*Informações Importantes:\*\*\
> \- O header \`Idempotency-Key\` é obrigatório: reenviar com a mesma chave devolve a mesma resposta, sem\
> &#x20; registrar a nota de novo.\
> \- A mesma NF-e enviada com outra \`Idempotency-Key\` é recusada com \`nota\_ja\_existe\`. Se a conexão cair\
> &#x20; antes da resposta, reenvie com a mesma chave; se receber \`nota\_ja\_existe\`, a nota já está registrada.\
> \- Duas requisições simultâneas com a mesma NF-e: uma registra a nota e a outra é recusada com\
> &#x20; \`importacao\_em\_andamento\`. Essa recusa não é guardada pela idempotência: reenvie em instantes e receba\
> &#x20; \`criada\` ou \`nota\_ja\_existe\`.\
> \- O XML aceito tem no máximo 1.024.000 bytes (acima disso, \`xml\_acima\_do\_limite\`) e 990 itens \`det\`, o\
> &#x20; limite de \`nItem\` do leiaute (acima disso, \`estrutura\_invalida\`).\
> \- A chave de acesso do protocolo deve ter 44 caracteres, só dígitos exceto as 12 primeiras posições do CNPJ\
> &#x20; (que aceitam letras maiúsculas, para CNPJ alfanumérico), e ser igual à identificação da NF-e (\`infNFe/@Id\`).\
> \
> \*\*Códigos de recusa (422):\*\* \`estrutura\_invalida\`, \`documento\_nao\_suportado\`, \`sem\_protocolo\`,\
> \`sem\_chave\_de\_acesso\`, \`cnpj\_nao\_pertence\_a\_empresa\`, \`nota\_ja\_existe\`, \`registro\_invalido\`,\
> \`nota\_nao\_autorizada\`, \`plano\_de\_contas\_nao\_selecionado\`, \`importacao\_em\_andamento\`, \`parametro\_invalido\`\
> e \`xml\_acima\_do\_limite\`.\
> Sem o header \`Idempotency-Key\`, a recusa vem como \`{"errors": \["mensagem"]}\`.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"12. 📄 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"}},"schemas":{"ResultadoDaImportacaoDeXml":{"type":"object","description":"Registro criado pela importação de XML de NF-e","properties":{"status":{"type":"string","enum":["criada","criada_com_avisos"],"description":"`criada_com_avisos` indica que o registro foi gravado, mas algum lançamento (estoque ou títulos) ficou incompleto: leia `avisos`"},"registro_tipo":{"type":"string","enum":["nota_fiscal","compra"],"description":"`nota_fiscal` quando a empresa é a emitente; `compra` quando é a destinatária"},"registro_id":{"type":"integer","description":"ID do registro criado"},"avisos":{"type":"array","description":"Avisos da importação; vazio quando `status` é `criada`","items":{"$ref":"#/components/schemas/OcorrenciaDaImportacaoDeXml"}}},"required":["status","registro_tipo","registro_id","avisos"]},"OcorrenciaDaImportacaoDeXml":{"type":"object","description":"Erro ou aviso da importação de XML de NF-e. O `codigo` é estável e deve ser usado pelo integrador para decidir o que fazer; a `mensagem` é texto para pessoas e pode mudar.","properties":{"codigo":{"type":"string","description":"Código estável da ocorrência"},"mensagem":{"type":"string","description":"Descrição legível da ocorrência"},"detalhe":{"type":"string","nullable":true,"description":"Complemento da ocorrência: o campo recusado em `parametro_invalido` e `xml_acima_do_limite`, ou as mensagens de validação em `registro_invalido` e `importacao_incompleta`"}},"required":["codigo","mensagem","detalhe"]},"ErrosDaImportacaoDeXml":{"type":"object","description":"Recusa da importação de XML de NF-e. Nada é gravado quando a importação é recusada.","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/OcorrenciaDaImportacaoDeXml"}}},"required":["errors"]}}},"paths":{"/nfes/importacao_de_xml":{"post":{"summary":"Importa o XML de uma NF-e autorizada","tags":["12. 📄 Notas Fiscais"],"description":"**Registrar no sistema uma NF-e já autorizada pela SEFAZ a partir do XML**\n\nRecebe o XML completo da NF-e (`nfeProc`, com o protocolo de autorização) e registra a nota na\nempresa autenticada, como a importação de XML pela tela.\n\n- Quando a empresa é a **emitente**, a NF-e é registrada como nota própria (`registro_tipo: nota_fiscal`).\n- Quando a empresa é a **destinatária**, a NF-e é registrada como compra (`registro_tipo: compra`).\n- `baixa_estoque` movimenta o estoque com os itens da nota: nota de saída dá **saída** no estoque; nota de\n  **entrada** (compra ou nota própria de entrada) dá **entrada** no estoque.\n- `gera_titulo` gera as contas a receber (nota própria de saída) ou a pagar (compra e nota própria de\n  entrada) a partir das **duplicatas do XML**; sem duplicatas, nenhum título é criado. A opção da tela\n  \"fatura para 30 dias\" não existe na API.\n- Empresa que exige plano de contas, com `gera_titulo` e sem `plano_de_conta_id` válido: a **nota própria** é\n  registrada com aviso `importacao_incompleta` (o título não é criado), enquanto a **compra** é recusada com\n  `plano_de_contas_nao_selecionado` e nada é gravado.\n\n**Leia sempre `avisos`:** o status `criada_com_avisos` indica que a nota foi registrada, mas o estoque\nou os títulos ficaram incompletos (código `importacao_incompleta`, com o motivo em `detalhe`).\n\n**Informações Importantes:**\n- O header `Idempotency-Key` é obrigatório: reenviar com a mesma chave devolve a mesma resposta, sem\n  registrar a nota de novo.\n- A mesma NF-e enviada com outra `Idempotency-Key` é recusada com `nota_ja_existe`. Se a conexão cair\n  antes da resposta, reenvie com a mesma chave; se receber `nota_ja_existe`, a nota já está registrada.\n- Duas requisições simultâneas com a mesma NF-e: uma registra a nota e a outra é recusada com\n  `importacao_em_andamento`. Essa recusa não é guardada pela idempotência: reenvie em instantes e receba\n  `criada` ou `nota_ja_existe`.\n- O XML aceito tem no máximo 1.024.000 bytes (acima disso, `xml_acima_do_limite`) e 990 itens `det`, o\n  limite de `nItem` do leiaute (acima disso, `estrutura_invalida`).\n- A chave de acesso do protocolo deve ter 44 caracteres, só dígitos exceto as 12 primeiras posições do CNPJ\n  (que aceitam letras maiúsculas, para CNPJ alfanumérico), e ser igual à identificação da NF-e (`infNFe/@Id`).\n\n**Códigos de recusa (422):** `estrutura_invalida`, `documento_nao_suportado`, `sem_protocolo`,\n`sem_chave_de_acesso`, `cnpj_nao_pertence_a_empresa`, `nota_ja_existe`, `registro_invalido`,\n`nota_nao_autorizada`, `plano_de_contas_nao_selecionado`, `importacao_em_andamento`, `parametro_invalido`\ne `xml_acima_do_limite`.\nSem o header `Idempotency-Key`, a recusa vem como `{\"errors\": [\"mensagem\"]}`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Chave de idempotência da requisição","schema":{"type":"string"}}],"responses":{"201":{"description":"NF-e registrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultadoDaImportacaoDeXml"}}}},"401":{"description":"Usuário não autenticado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"422":{"description":"NF-e recusada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrosDaImportacaoDeXml"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["xml"],"properties":{"xml":{"type":"string","description":"Conteúdo do XML da NF-e autorizada (nfeProc)"},"baixa_estoque":{"type":"boolean","nullable":true,"description":"Movimenta o estoque com os itens da nota (padrão: false)"},"gera_titulo":{"type":"boolean","nullable":true,"description":"Gera os títulos a partir das duplicatas do XML (padrão: false)"},"plano_de_conta_id":{"type":"integer","nullable":true,"description":"Plano de contas dos títulos; plano de outra empresa é ignorado"}}}}}}}}}}
```

## Listar NF-es

> \*\*Listar NF-es do usuario autenticado\*\*\
> \
> Retorna as NF-es do usuario. Por padrao, retorna apenas NF-es protocoladas (status A, C, N).\
> Para obter NF-es finalizadas (pre-notas nao transmitidas), use o parametro \`status=finalizada\`.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"12. 📄 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":{"get":{"summary":"Listar NF-es","tags":["12. 📄 Notas Fiscais"],"description":"**Listar NF-es do usuario autenticado**\n\nRetorna as NF-es do usuario. Por padrao, retorna apenas NF-es protocoladas (status A, C, N).\nPara obter NF-es finalizadas (pre-notas nao transmitidas), use o parametro `status=finalizada`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["finalizada"]},"required":false,"description":"Filtro por status (finalizada = pre-notas nao transmitidas)"},{"name":"page","in":"query","schema":{"type":"integer"},"required":false,"description":"Numero da pagina (25 itens por pagina)"}],"responses":{"200":{"description":"Lista de NF-es","content":{"application/json":{"schema":{"type":"object","properties":{"notas_fiscais":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"serie":{"type":"string"},"numero_nfe":{"type":"string"},"tipo_documento":{"type":"integer"},"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"},"destinatario":{"type":"string","nullable":true},"cfop":{"type":"string","nullable":true}}}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"previous_page":{"type":"string","nullable":true},"next_page":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Token invalido ou expirado"}}}}}}
```

## 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":"12. 📄 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":["12. 📄 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"},"cliente":{"type":"object","description":"**Cadastro automático do destinatário, caso ele não exista.**\n\nCampo **opcional**. Quando omitido, o comportamento atual é mantido: o destinatário é buscado pelo documento informado em `destinatario` e a requisição retorna 422 caso ele não exista.\n\nQuando informado, o destinatário é localizado ou criado a partir do documento em `destinatario` (CPF de 11 dígitos cria pessoa física, CNPJ de 14 dígitos cria pessoa jurídica). O documento (CPF/CNPJ) **não** é informado dentro de `cliente` — ele vem sempre do campo `destinatario`.\n\nRegras de comportamento:\n- Destinatário já cadastrado com o mesmo endereço (mesmo CEP, UF e município) → retornado sem alteração.\n- Destinatário não cadastrado → criado com os dados fornecidos.\n\n**Obrigatoriedade dos sub-campos:** os sub-campos de `cliente` não são individualmente obrigatórios. A validação que retorna 422 incide sobre o documento informado em `destinatario` (CPF/CNPJ inválido). O **endereço é cadastrado em bloco**: só é gravado quando `cep`, `estado` e `municipio` são informados **e** o `estado` (sigla da UF) e o `municipio` correspondem a registros válidos no sistema; informar o endereço parcialmente (ex: apenas `cep`) faz com que o endereço **não seja cadastrado**, sem erro. Documento inválido retorna 422 com a mensagem do sistema.","properties":{"nome":{"type":"string","description":"Nome ou razão social do destinatário (opcional)"},"email":{"type":"string","description":"E-mail de contato do destinatário (opcional)"},"cep":{"type":"string","description":"CEP do endereço, com ou sem hífen (obrigatório para cadastrar o endereço, junto com `estado` e `municipio`)"},"logradouro":{"type":"string","description":"Logradouro do endereço (opcional)"},"numero":{"type":"string","description":"Número do endereço (opcional)"},"complemento":{"type":"string","description":"Complemento do endereço (opcional)"},"bairro":{"type":"string","description":"Bairro do endereço (opcional)"},"municipio":{"type":"string","description":"Nome do município do endereço, deve corresponder a um município válido da UF informada (obrigatório para cadastrar o endereço, junto com `cep` e `estado`)"},"estado":{"type":"string","description":"Sigla da unidade federativa (UF) do endereço, ex: SP (obrigatório para cadastrar o endereço, junto com `cep` e `municipio`)"}}},"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.\
> \
> Os \`produtos\` saem na ordem do item no XML (\`numero\_item\`, igual ao \`nItem\`), 25 por página, e trazem\
> identificação, códigos (CFOP, CST ou CSOSN), valores e tributos de cada item calculados pelos mesmos métodos\
> que geram o XML da nota.\
> \
> Os campos numéricos do item saem null quando a nota é de entrada e o usuário autenticado não tem a permissão 'Permitir visualização de PU de entrada'. Identificação e códigos continuam preenchidos, e valor\_unitario, valor\_total e preco\_unitario não mudam.

```json
{"openapi":"3.0.1","info":{"title":"Mainô API","version":"v2.0"},"tags":[{"name":"12. 📄 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":["12. 📄 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.\n\nOs `produtos` saem na ordem do item no XML (`numero_item`, igual ao `nItem`), 25 por página, e trazem\nidentificação, códigos (CFOP, CST ou CSOSN), valores e tributos de cada item calculados pelos mesmos métodos\nque geram o XML da nota.\n\nOs campos numéricos do item saem null quando a nota é de entrada e o usuário autenticado não tem a permissão 'Permitir visualização de PU de entrada'. Identificação e códigos continuam preenchidos, e valor_unitario, valor_total e preco_unitario não mudam.","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},"created_at":{"type":"string","format":"datetime","description":"Data de criação da nota no Mainô"},"natureza_da_operacao":{"type":"string","nullable":true},"valor_total":{"type":"number"},"pedido_id":{"type":"string","nullable":true,"description":"Identificador (UUID) do pedido de venda de origem da nota, o mesmo enviado no webhook nota_fiscal.autorizada e aceito em GET /pedidos/{id}. Nulo quando a nota não tem pedido."}}},"produtos":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"},"quantidade":{"type":"string","description":"Quantidade comercial do item, como texto decimal"},"valor_unitario":{"type":"number"},"valor_total":{"type":"number"},"numero_item":{"type":"integer","nullable":false,"description":"Número do item na NF-e, igual ao nItem do XML."},"ncm":{"type":"string","nullable":false,"description":"NCM do item, como sai no XML."},"chave_acesso_nfe":{"type":"string","nullable":true,"description":"Chave de acesso da NF-e do item. null enquanto a nota não tem chave."},"cfop":{"type":"string","nullable":true,"description":"CFOP do item (tag CFOP). Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"cst_icms":{"type":"string","nullable":true,"description":"CST do ICMS (tag CST do grupo ICMS). null para emitente do Simples Nacional, que usa csosn. Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"csosn":{"type":"string","nullable":true,"description":"CSOSN do ICMS (tag CSOSN do grupo ICMSSN). Só para emitente do Simples Nacional; null nos demais, que usam cst_icms. Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"cst_ipi":{"type":"string","nullable":true,"description":"CST do IPI (tag CST do grupo IPI). Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"cst_pis":{"type":"string","nullable":true,"description":"CST do PIS (tag CST do grupo PIS). Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"cst_cofins":{"type":"string","nullable":true,"description":"CST da COFINS (tag CST do grupo COFINS). Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"cst_ibs_cbs":{"type":"string","nullable":true,"description":"CST do IBS e da CBS (tag CST do grupo IBSCBS). Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"classificacao_tributaria_ibs_cbs":{"type":"string","nullable":true,"description":"Classificação tributária do IBS e da CBS (tag cClassTrib). Sai o código registrado no item mesmo quando o XML não emite o grupo. null quando o item não tem o código."},"valor_produto":{"type":"number","nullable":true,"description":"Valor total bruto do item (vProd).","format":"float"},"valor_frete":{"type":"number","nullable":true,"description":"Frete do item (vFrete). 0 quando o XML não traz a tag.","format":"float"},"valor_seguro":{"type":"number","nullable":true,"description":"Seguro do item (vSeg). 0 quando o XML não traz a tag.","format":"float"},"valor_outras_despesas":{"type":"number","nullable":true,"description":"Outras despesas acessórias do item (vOutro), que somam as despesas aduaneiras. 0 quando o XML não traz a tag.","format":"float"},"base_ii":{"type":"number","nullable":true,"description":"Base de cálculo do II. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"aliquota_ii":{"type":"number","nullable":true,"description":"Alíquota do II (%), do cadastro do item com 2 casas: o XML não tem pII.","format":"float"},"valor_ii":{"type":"number","nullable":true,"description":"Valor do II. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"base_ipi":{"type":"number","nullable":true,"description":"Base de cálculo do IPI. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"aliquota_ipi":{"type":"number","nullable":true,"description":"Alíquota do IPI (%). Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"valor_ipi":{"type":"number","nullable":true,"description":"Valor do IPI. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"base_pis":{"type":"number","nullable":true,"description":"Base de cálculo do PIS. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"aliquota_pis":{"type":"number","nullable":true,"description":"Alíquota do PIS (%). Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"valor_pis":{"type":"number","nullable":true,"description":"Valor do PIS. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"base_cofins":{"type":"number","nullable":true,"description":"Base de cálculo do COFINS. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"aliquota_cofins":{"type":"number","nullable":true,"description":"Alíquota do COFINS (%). Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"valor_cofins":{"type":"number","nullable":true,"description":"Valor do COFINS. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"base_icms":{"type":"number","nullable":true,"description":"Base de cálculo do ICMS. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"aliquota_icms":{"type":"number","nullable":true,"description":"Alíquota do ICMS (%). Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"valor_icms":{"type":"number","nullable":true,"description":"Valor do ICMS (vICMS). No CST 51, o valor efetivo, já descontado o diferimento.","format":"float"},"base_icms_st":{"type":"number","nullable":true,"description":"Base de cálculo do ICMS-ST. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"aliquota_icms_st":{"type":"number","nullable":true,"description":"Alíquota do ICMS-ST (pICMSST). Na NF-e 4.00, sem o FCP-ST, que o XML informa em grupo próprio.","format":"float"},"valor_icms_st":{"type":"number","nullable":true,"description":"Valor do ICMS-ST. Quando o XML não destaca o tributo (por exemplo, CST isento ou não tributado), devolve o valor registrado no item, que pode ser diferente de 0 e não indica destaque na NF-e.","format":"float"},"base_fcp":{"type":"number","nullable":true,"description":"Base de cálculo do FCP. Valor registrado no item, formatado como as tags vBCFCP/pFCP/vFCP. Preenchido só quando o item tem alíquota e valor do FCP e a NF-e é 4.00, a mesma condição em que o XML emite o grupo; senão 0. Fora da 4.00 é sempre 0, porque o XML soma o FCP-ST ao ICMS-ST. O despacho por CST não é espelhado: em CST que não emite o grupo, sai o valor registrado. No CST 00 o XML não traz vBCFCP, e base_fcp devolve a base registrada.","format":"float"},"aliquota_fcp":{"type":"number","nullable":true,"description":"Alíquota do FCP (%). Valor registrado no item, formatado como as tags vBCFCP/pFCP/vFCP. Preenchido só quando o item tem alíquota e valor do FCP e a NF-e é 4.00, a mesma condição em que o XML emite o grupo; senão 0. Fora da 4.00 é sempre 0, porque o XML soma o FCP-ST ao ICMS-ST. O despacho por CST não é espelhado: em CST que não emite o grupo, sai o valor registrado.","format":"float"},"valor_fcp":{"type":"number","nullable":true,"description":"Valor do FCP. Valor registrado no item, formatado como as tags vBCFCP/pFCP/vFCP. Preenchido só quando o item tem alíquota e valor do FCP e a NF-e é 4.00, a mesma condição em que o XML emite o grupo; senão 0. Fora da 4.00 é sempre 0, porque o XML soma o FCP-ST ao ICMS-ST. O despacho por CST não é espelhado: em CST que não emite o grupo, sai o valor registrado.","format":"float"},"base_fcp_st":{"type":"number","nullable":true,"description":"Base de cálculo do FCP-ST. Valor registrado no item, formatado como as tags vBCFCPST/pFCPST/vFCPST. Preenchido só quando o item tem alíquota e valor do FCP-ST e a NF-e é 4.00, a mesma condição em que o XML emite o grupo; senão 0. Fora da 4.00 é sempre 0, porque o XML soma o FCP-ST ao ICMS-ST. O despacho por CST não é espelhado: em CST que não emite o grupo, sai o valor registrado.","format":"float"},"aliquota_fcp_st":{"type":"number","nullable":true,"description":"Alíquota do FCP-ST (%). Valor registrado no item, formatado como as tags vBCFCPST/pFCPST/vFCPST. Preenchido só quando o item tem alíquota e valor do FCP-ST e a NF-e é 4.00, a mesma condição em que o XML emite o grupo; senão 0. Fora da 4.00 é sempre 0, porque o XML soma o FCP-ST ao ICMS-ST. O despacho por CST não é espelhado: em CST que não emite o grupo, sai o valor registrado.","format":"float"},"valor_fcp_st":{"type":"number","nullable":true,"description":"Valor do FCP-ST. Valor registrado no item, formatado como as tags vBCFCPST/pFCPST/vFCPST. Preenchido só quando o item tem alíquota e valor do FCP-ST e a NF-e é 4.00, a mesma condição em que o XML emite o grupo; senão 0. Fora da 4.00 é sempre 0, porque o XML soma o FCP-ST ao ICMS-ST. O despacho por CST não é espelhado: em CST que não emite o grupo, sai o valor registrado.","format":"float"},"base_ibs_cbs":{"type":"number","nullable":true,"description":"Base de cálculo do IBS e da CBS (vBC do grupo gIBSCBS).","format":"float"},"aliquota_ibs_uf":{"type":"number","nullable":true,"description":"Alíquota do IBS estadual (pIBSUF).","format":"float"},"valor_ibs_uf":{"type":"number","nullable":true,"description":"Valor do IBS estadual (vIBSUF).","format":"float"},"aliquota_ibs_mun":{"type":"number","nullable":true,"description":"Alíquota do IBS municipal (pIBSMun).","format":"float"},"valor_ibs_mun":{"type":"number","nullable":true,"description":"Valor do IBS municipal (vIBSMun).","format":"float"},"aliquota_cbs":{"type":"number","nullable":true,"description":"Alíquota da CBS (pCBS).","format":"float"},"valor_cbs":{"type":"number","nullable":true,"description":"Valor da CBS (vCBS).","format":"float"}}}},"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":"12. 📄 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":["12. 📄 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":"12. 📄 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":["12. 📄 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":"12. 📄 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":["12. 📄 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":"12. 📄 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":["12. 📄 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":"12. 📄 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":["12. 📄 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"}}}}}}}}}}}
```
