12. 🧾 NFCe (Cupom Fiscal)

Emissão de Notas Fiscais de Consumidor Sistema para emissão de NFC-e com integração aos provedores fiscais. Recursos disponíveis:

• Emissão online e modo contingência

• Cancelamento e inutilização

• Envio automático por email/SMS

• Integração com PDV

Cancelar NFC-e ou criar devolução automaticamente

post

Este endpoint realiza automaticamente uma das seguintes ações:

1. Cancelar NFC-e: Se ainda estiver dentro do prazo de cancelamento.

2. Criar devolução: Se o prazo de cancelamento expirou, cria uma NF-e de devolução

Fluxo de Funcionamento:

• Primeiro tenta cancelar a NFC-e

• Se o cancelamento falhar (prazo expirado), automaticamente cria uma devolução

• Para devoluções, é obrigatório informar o CNPJ do cliente

• O CNPJ deve estar cadastrado como stakeholder do usuário

Validações realizadas:

• Certificado digital deve estar válido e não vencido

• NFC-e deve existir e pertencer ao usuário

• Para devolução: CNPJ obrigatório e deve existir na base

• CFOP de devolução deve estar configurado

Parametros no body da requisição:

Conforme descrito no schema da request, os parametros abaixo são esperados:

• transaction_id: String Obrigatório

• cnpj: String(somente números) Obrigatório para devolução quando o cancelamento não é possível

• transmitir_nota: booleano Opcional - Default: true

O CNPJ do cliente para devolução (obrigatório quando for criar devolução) deve ser um CNPJ válido e

cadastrado na base de dados, caso você queira ter um fallback ou a possibilidade de gerar a devolução

automáticamente recomendo que sempre envie esse parâmetro.

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

transaction_idstringObrigatório

ID de transação da NFC-e. Atente que este número não se refere ao ID ou ao número da Nota

Example: 1234567890

cnpjstringOpcional

CNPJ do cliente para devolução (obrigatório quando for criar devolução). Deve ser um CNPJ válido e cadastrado na base de dados

Example: 12345678000123

transmitir_notabooleanOpcional

Flag para indicar se a nota de devolução deve ser transmitida automaticamente

Default: trueExample: true

Respostas

401

Token inválido ou expirado

application/json

errorstringOpcionalExample: Chave de API inválida

post

/cancelar_ou_criar_devolucao_nfces

HTTPcURLJavaScriptPython

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

{
  "transaction_id": "1234567890"
}

Exemplo de requisição cancelamento dentro do prazo)Exemplo de requisição cancelamento ou devolução com transmissão automáticaExemplo de requisição cancelamento ou devolução sem transmissão automática

401

Token inválido ou expirado

{
  "error": "Chave de API inválida"
}

Criar devolução de NFC-e

post

Criar NF-e de devolução para uma NFC-e

Endpoint utilizado para criar uma nota fiscal de devolução a partir de uma NFC-e já emitida.

Pré-requisitos:

• NFC-e deve estar aceita pela SEFAZ

• CFOP de devolução deve estar cadastrado no dicionário

• Autenticação via Bearer Token

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

transaction_idstringObrigatório

ID de transação da NFC-e. Atente que este número não se refere ao ID ou ao número da Nota

Example: 1234567890

Respostas

401

Token inválido ou expirado

application/json

errorstringOpcional

Mensagem de erro de autenticação

404

NFC-e não encontrada

application/json

post

/devolucao_nfces

HTTPcURLJavaScriptPython

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

{
  "transaction_id": "1234567890"
}

{
  "error": "text"
}

Lista NFC-es (Cupons Fiscais)

get

Retorna lista de NFC-es (Cupons Fiscais Eletrônicos) emitidas pelo usuário.

Filtros disponíveis:

• transaction_id: Buscar por ID de transação específico

• exibir_xmls: Se true, inclui o XML completo de cada NFC-e na resposta

• page: Número da página para paginação (100 registros por página)

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

transaction_idstringOpcional

ID de transação da NFC-e

exibir_xmlsbooleanOpcional

Incluir XMLs completos na resposta

pageintegerOpcional

Número da página

Respostas

200

Lista de NFC-es

application/json

401

Não autorizado

application/json

errorstringOpcional

get

/nfces

HTTPcURLJavaScriptPython

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

{
  "nfces": [
    {
      "id": 1,
      "numero": "text",
      "serie": "text",
      "chave": "text",
      "transaction_id": "text",
      "status": "processando",
      "data_emissao": "2026-03-05T23:06:21.049Z",
      "cfop": "text",
      "valor_total_produtos": 1,
      "valor_total_nfce": 1,
      "cliente": {
        "nome": "text",
        "cpf_cnpj": "text"
      },
      "danfe_url": "text",
      "xml_url": "text"
    }
  ],
  "pagination": {
    "total": 1
  }
}

Emite NFC-e (Cupom Fiscal)

post

Emite uma NFC-e (Cupom Fiscal Eletrônico) e transmite para a SEFAZ

Este endpoint cria e transmite automaticamente uma NFC-e. O cupom fiscal é vinculado ao caixa aberto do usuário (se não houver caixa aberto, um será criado automaticamente).

Fluxo de Funcionamento:

1. Valida todos os dados (produtos, formas de pagamento, cliente)

2. Cria o cupom fiscal com os itens e pagamentos

3. Gera a NFC-e

4. Transmite para a SEFAZ (exceto se fake: true)

5. Retorna URLs para download do DANFE e XML

Validações importantes:

• Certificado digital deve estar válido e não vencido

• Produtos devem estar cadastrados no sistema (ou configuração permitir cadastro automático)

• Somatório das formas de pagamento deve bater com o valor total dos produtos

• CPF/CNPJ do cliente deve ser válido (se informado)

• NCM, origem e unidade de medida devem ser válidos

Sobre o transaction_id:

• Campo único que identifica a transação no seu sistema

• Se já existir uma NFC-e com o mesmo transaction_id, retorna erro

• Use overwrite_previous_transactions: true para sobrescrever NFC-e anterior (se não estiver aceita)

Modo de teste (fake):

• Use fake: true para emitir sem transmitir para SEFAZ

• Útil para testes de integração

• Não requer certificado digital válido

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

Respostas

400

Erro na validação ou processamento

application/json

401

Não autorizado

application/json

errorstringOpcional

post

/nfces

HTTPcURLJavaScriptPython

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

{
  "nfce": {
    "transaction_id": "VENDA-2023-001",
    "cpf": "12345678901",
    "operador_de_caixa": "João Silva",
    "produtos": [
      {
        "codigo": "PROD-001",
        "descricao": "Produto Exemplo",
        "ncm": "12345678",
        "pu": 50,
        "qtde": 2,
        "origem": "0",
        "unidade_de_medida": {
          "codigo": "UN",
          "descricao": "Unidade"
        }
      }
    ],
    "formas_de_pagamento": [
      {
        "codigo": "01",
        "descricao": "Dinheiro",
        "valor": 100
      }
    ]
  }
}

Exemplo básico de emissão de NFC-eExemplo com desconto, múltiplos pagamentos e dados do cliente

{
  "error": "Certificado inválido. Cadastre um certificado na sua conta antes de transmitir"
}

Exporta XMLs de NFC-es em período

get

Exporta XMLs de NFC-es emitidas em um período específico

Gera um arquivo ZIP contendo todos os XMLs das NFC-es emitidas no período informado.

Parâmetros:

• data_inicio: Data inicial (formato: YYYY-MM-DD)

• data_fim: Data final (formato: YYYY-MM-DD)

Validações:

• Datas são obrigatórias

• Datas devem estar em formato válido

• Data inicial não pode ser maior que data final

• Período máximo: 31 dias

Retorno:

• URL temporária para download do arquivo ZIP

• Link expira após 1 hora

• Arquivo é automaticamente excluído após expiração

Estrutura do ZIP:

• {chave_acesso_44_digitos}.xml - XML da NFC-e

• {chave_acesso}-cancelamento.xml - XML de cancelamento (se NFC-e foi cancelada)

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 · dateObrigatório

Data inicial (YYYY-MM-DD)

Example: 2023-01-01

data_fimstring · dateObrigatório

Data final (YYYY-MM-DD)

Example: 2023-01-31

Respostas

400

Parâmetros inválidos ou nenhuma NFC-e encontrada

application/json

401

Não autorizado

application/json

errorstringOpcional

get

/nfces/exporta_xmls

HTTPcURLJavaScriptPython

GET /api/v2/nfces/exporta_xmls?data_inicio=2026-03-05&data_fim=2026-03-05 HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "errors": {
    "nfces": [
      "Nenhuma NFC-e encontrada no filtro aplicado"
    ]
  }
}