> 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)"}}}}}}}}}}}} ``` ## 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"},"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":"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.","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":"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"}}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://changelog.maino.com.br/api-reference-maino/12.-notas-fiscais.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.