13. 📄 Notas Fiscais

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

• NF-e emitidas e de fornecedores

• Controle de status e transmissão

• Histórico de manifestação

• Integração com SEFAZ

• Transmitir NF-es para SEFAZ

• Emitir NF-es de todos os tipos (Conta e Ordem, Devolução, Complementar, etc.)

• Consultar NF-e

Cria uma NF-e de Conta e Ordem

post

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.

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de cabeçalho

Idempotency-KeystringOpcional

Chave de idempotência

Corpo

application/json

Respostas

201

NF-e criada com sucesso

application/json

422

Erro de validação

application/json

post

/nfes/conta_e_ordem

HTTPcURLJavaScriptPython

POST /api/v2/nfes/conta_e_ordem HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "nota_fiscal": {
    "numero": "12345",
    "serie": "1",
    "destinatario": "12345678000195",
    "icms_produtos": {
      "123": 18,
      "124": 12
    },
    "fcp_produtos": {
      "123": 2
    },
    "acrescimo_ao_valor_dos_produtos": 10.5,
    "tipo_de_acrescimo_ao_valor_dos_produtos": "valor"
  }
}

{
  "nota_fiscal": {
    "id": "123",
    "serie": "1",
    "numero_nfe": "12345",
    "status": "autorizada",
    "chave_acesso": "35210312345678000195550010000123451000123456",
    "destinatario": "12345678000195"
  },
  "produtos": [
    {
      "codigo": "PROD001",
      "quantidade": "10.0"
    }
  ],
  "referencias": [
    {
      "chave_acesso": "35210312345678000195550010000123451000123456"
    }
  ]
}

Criar NF-e

post

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.

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de cabeçalho

Idempotency-KeystringOpcional

Chave de idempotência para evitar requisições duplicadas

Corpo

application/json

Respostas

201

NF-e criada com sucesso

NF-e criadaapplication/json

422

Erro de validação

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

post

/nfes

HTTPcURLJavaScriptPython

POST /api/v2/nfes HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 627

{
  "nota_fiscal": {
    "serie": "001",
    "numero_nfe": "000000027",
    "tipo_documento": "1",
    "tipo_operacao": "encomenda",
    "tipo_impressao_danfe": "1",
    "forma_emissao": 1,
    "finalidade_emissao": "1",
    "destinatario": "12345678901234",
    "cfop": "1102",
    "codigo_modalidade_frete": "1",
    "codigo_meio_de_pagamento": "01",
    "transportadora": "68202649000129",
    "codigo_processo": "0001",
    "quantidade_volume": 10,
    "especie_volumes": "CAIXA",
    "marca_volumes": "MARCA X",
    "numeracao_volumes": "1-10",
    "peso_bruto": 15.5,
    "peso_liquido": 14
  },
  "produtos": [
    {
      "codigo": "PROD001",
      "quantidade": 1,
      "pu_entrada": 10.5
    }
  ],
  "referencias": [
    {
      "chave_acesso": "35231212345678000190550010000000011000000001"
    }
  ]
}

{
  "value": {
    "nota_fiscal": {
      "id": "12345",
      "serie": "001",
      "numero_nfe": "000000027",
      "tipo_documento": "1",
      "tipo_impressao_danfe": "1",
      "finalidade_emissao": "1",
      "destinatario": "12345678901234",
      "cfop": "5102",
      "codigo_modalidade_frete": "9",
      "codigo_meio_de_pagamento": null,
      "transportadora": null,
      "codigo_processo": null,
      "natureza_da_operacao": "REMESSA DE ENCOMENDA",
      "quantidade_volume": null,
      "especie_volumes": null,
      "marca_volumes": null,
      "numeracao_volumes": null,
      "peso_bruto": null,
      "peso_liquido": null
    },
    "produtos": [
      {
        "codigo": "PROD001",
        "quantidade": 1,
        "pu_entrada": null
      }
    ],
    "referencias": [
      {
        "chave_acesso": "35231212345678000190550010000000011000000001"
      }
    ]
  }
}

Exibir detalhes da NF-e

get

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.

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

idstringObrigatório

ID da NF-e

Parâmetros de consulta

produtos_pageintegerOpcional

Número da página para paginação de produtos

referencias_pageintegerOpcional

Número da página para paginação de referências

Respostas

200

Detalhes da NF-e

application/json

404

NF-e não encontrada

get

/nfes/{id}

HTTPcURLJavaScriptPython

GET /api/v2/nfes/{id} HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "nota_fiscal": {
    "id": "12345",
    "serie": "001",
    "numero_nfe": "000000027",
    "tipo_documento": "1",
    "tipo_impressao_danfe": "1",
    "forma_emissao": "1",
    "finalidade_emissao": "1",
    "destinatario": "12345678901234",
    "cfop": "5102",
    "codigo_modalidade_frete": "0",
    "codigo_meio_de_pagamento": "01",
    "transportadora": "98765432000198",
    "codigo_processo": "PROC001",
    "quantidade_volume": 10,
    "especie_volumes": "CAIXA",
    "marca_volumes": "MARCA X",
    "numeracao_volumes": "1-10",
    "peso_bruto": 15.5,
    "peso_liquido": 14,
    "status": "AUTORIZADA",
    "chave_acesso_nfe": "35231212345678000190550010000000011000000001",
    "protocolo": "135230000000001",
    "dthr_emissao": "2023-12-23T10:00:00-03:00",
    "natureza_da_operacao": "VENDA DE MERCADORIA",
    "valor_total": 1500
  },
  "produtos": [
    {
      "codigo": "PROD001",
      "descricao": "Produto Exemplo",
      "quantidade": 10,
      "valor_unitario": 150,
      "valor_total": 1500
    }
  ],
  "referencias": [
    {
      "chave_acesso": "35231212345678000190550010000000011000000001"
    }
  ]
}

Transmitir NF-e

post

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

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Corpo

application/json

seriestringObrigatório

Série da NF-e

Example: 001

numerostringObrigatório

Número da NF-e

Example: 000000027

urlstringOpcional

URL de callback (Webhook) para receber atualizações de status

Example: https://minha-api.com/webhook/nfe

Respostas

202

NF-e agendada para transmissão

Transmissão agendada com sucessoapplication/json

post

/nfes/transmitir

HTTPcURLJavaScriptPython

POST /api/v2/nfes/transmitir HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "serie": "001",
  "numero": "000000027",
  "url": "https://minha-api.com/webhook/nfe"
}

202

NF-e agendada para transmissão

{
  "value": {
    "message": "Nota fiscal enviada para transmissão",
    "nota_fiscal_id": 12345,
    "status": "transmissao_agendada"
  }
}

Exportar XMLs de NFes dos fornecedores

get

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

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de consulta

data_iniciostringObrigatório

Data de início do período para exportação (formato: dd/mm/yyyy)

Example: 01/03/2023

data_fimstringObrigatório

Data de fim do período para exportação (formato: dd/mm/yyyy)

Example: 31/03/2023

Respostas

200

ZIP com XMLs dos fornecedores

URL para download do ZIPapplication/zipapplication/json

400

Nenhuma NFe encontrada no período

Sem NFes no períodoapplication/zipapplication/json

401

Token inválido ou expirado

Token inválidoapplication/zipapplication/json

get

/nfes_dos_fornecedores

HTTPcURLJavaScriptPython

GET /api/v2/nfes_dos_fornecedores?data_inicio=text&data_fim=text HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "value": {
    "zip_url": "https://maino-storage.s3.amazonaws.com/xmls/fornecedores-202303.zip"
  }
}

Listar notas fiscais confirmadas

get

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

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de consulta

data_referenciastringOpcional

Data de confirmação para filtrar notas fiscais. Formatos aceitos: 'aaaa-mm-dd', 'dd-mm-aaaa', 'aaaa/mm/dd', 'dd/mm/aaaa'

Example: 03/08/2021

pageinteger · mín: 1Opcional

Número da página para paginação (padrão: primeira página)

Example: 2

Respostas

200

Lista de notas fiscais confirmadas

Lista com notas confirmadasLista vazia (sem notas)application/json

401

Token inválido ou expirado

Token inválidoapplication/json

get

/notas_fiscais_confirmadas

HTTPcURLJavaScriptPython

GET /api/v2/notas_fiscais_confirmadas HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "value": {
    "data_referencia": "2021-08-03",
    "notas_fiscais": [
      {
        "serie": "001",
        "numero_nfe": "000001234",
        "data_confirmacao": "2021-08-16T08:15:00Z",
        "xml": "<?xml version=\"1.0\"?>..."
      }
    ],
    "pagination": {
      "total": 150,
      "previous_page": "/api/v2/notas_fiscais_confirmadas?page=1",
      "next_page": "/api/v2/notas_fiscais_confirmadas?page=3"
    }
  }
}

Listar notas fiscais emitidas

get

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

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de consulta

data_iniciostring · dateOpcional

Data inicial de emissão (formato YYYY-MM-DD)

Example: 2023-01-01

data_fimstring · dateOpcional

Data final de emissão (formato YYYY-MM-DD)

Example: 2023-01-31

cnpj_destinatariostringOpcional

CNPJ do destinatário para filtro

Example: 12345678000190

numero_nfestringOpcional

Número da NFe para busca específica

Example: 123456

data_vencimentostring · dateOpcional

Data de vencimento do recebimento (formato YYYY-MM-DD)

Example: 2023-02-15

data_pagamentostring · dateOpcional

Data de liquidação do recebimento (formato YYYY-MM-DD)

Example: 2023-02-10

centro_de_custo_idintegerOpcional

ID do centro de custo

Example: 1

centro_de_custo_descricaostringOpcional

Descrição do centro de custo (busca parcial)

Example: Vendas

exibir_xmlsbooleanOpcional

Incluir conteúdo dos XMLs na resposta

Example: false

pageintegerOpcional

Número da página (padrão: 1, 25 itens por página)

Example: 1

Respostas

200

Lista de notas fiscais emitidas

Lista com notas fiscaisLista vaziaapplication/json

401

Token inválido ou expirado

Token inválidoapplication/json

get

/notas_fiscais_emitidas

HTTPcURLJavaScriptPython

GET /api/v2/notas_fiscais_emitidas HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "value": {
    "notas_fiscais": [
      {
        "id": 12345,
        "serie": "001",
        "numero_nfe": "000001234",
        "dthr_emissao": "2023-01-15T10:30:00Z",
        "valor_nota_nfe": 1500,
        "status": "ACEITA",
        "chave_acesso_nfe": "35230112345678000190550010000012341234567890"
      }
    ],
    "pagination": {
      "total": 1
    }
  }
}

Exportar XMLs de notas fiscais emitidas

get

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

Autorizações

Bearer

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de consulta

data_iniciostringObrigatório

Data de início do período (formato: dd/mm/aaaa)

Example: 01/03/2023

data_fimstringObrigatório

Data de fim do período (formato: dd/mm/aaaa)

Example: 31/03/2023

Respostas

200

Arquivo ZIP com XMLs das NF-es

URLs para downloadapplication/zipapplication/json

400

Nenhuma NFe encontrada no período

Sem NFes no períodoapplication/zipapplication/json

401

Token inválido ou expirado

Token inválidoapplication/zipapplication/json

get

/nfes_emitidas

HTTPcURLJavaScriptPython

GET /api/v2/nfes_emitidas?data_inicio=text&data_fim=text HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "value": {
    "zip_url": "https://storage.example.com/xmls.zip",
    "zip_url_danfe": "https://storage.example.com/danfes.zip"
  }
}