Documentação da API

Visão geral

A API pública permite que sistemas de terceiros (ERPs, e-commerces, sistemas de gestão) emitam e consultem documentos fiscais em nome de uma empresa cadastrada na plataforma. Toda comunicação é feita em JSON sobre HTTPS.

Todos os endpoints ficam sob esse domínio. Em ambiente de desenvolvimento local, a API roda por padrão em http://localhost:5037.

Autenticação

A autenticação é feita por API Key, enviada em um cabeçalho HTTP em toda requisição:

X-Api-Key: SUA_CHAVE_AQUI

Como obter uma API Key

1. Acesse o Portal do Cliente da plataforma e entre com seu usuário.
2. Selecione a empresa (tenant) para a qual deseja emitir documentos.
3. Vá em API Keys no menu lateral e clique em "+ Gerar nova API Key".
4. A chave é exibida uma única vez — copie e guarde em local seguro (variável de ambiente, cofre de segredos). Não é possível recuperá-la depois.

Uma API Key pode ser revogada a qualquer momento na mesma tela, sem afetar outras chaves da empresa. Requisições com chave ausente, incorreta ou revogada recebem 401 Unauthorized.

Pré-requisitos antes de emitir

Antes de emitir o primeiro documento pela API, a empresa precisa ter, no Portal do Cliente:

• Dados fiscais cadastrados — em Configurações > Dados fiscais, um cadastro só vale para NFS-e Nacional, NFS-e Municipal, NF-e e NFC-e: endereço, inscrições, regime tributário, séries e CSC. Preenchido uma vez, o sistema usa os mesmos dados em cada tipo de nota. A inscrição municipal habilita a NFS-e Municipal (obrigatória em São Paulo) e a inscrição estadual habilita NF-e e NFC-e.
• Certificado digital A1 (.pfx) enviado — em Configurações > Certificado digital ou pela API (Subir certificado digital), usado para assinar digitalmente o documento antes de enviar ao governo.

Para NF-e e NFC-e, o mesmo cadastro precisa ter inscrição estadual, regime tributário (CRT), série e, só para a NFC-e, o CSC (ID + código, gerado no portal da SEFAZ da sua UF — homologação e produção são diferentes). Detalhes em NFC-e e NF-e. Para criar a empresa e subir o certificado por integração, veja Cadastrar empresa.

Sem isso, a emissão é aceita pela API (fica em fila) mas retorna Rejeitada com uma mensagem explicando o que falta. No caso da NFC-e, a API já responde 400 na hora quando o cadastro da NFC-e não foi preenchido.

Emitir documento fiscal

Cabeçalhos

Corpo da requisição

O corpo tem sempre o mesmo envelope — só o conteúdo de payload muda conforme o tipo:

{
  "tipo": "NfseNacional",
  "payload": { ... }
}

Respostas

202 Accepted — ainda processando

Devolvida quando o processamento não termina dentro dos 25 segundos de espera. O documento continua em fila — consulte depois pelo GET.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Pendente"
}

200 OK — processamento concluído

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Autorizada",
  "numeroProtocolo": "35325042252125180000131000000000000326083321214463",
  "motivoRejeicao": null,
  "xmlGerado": "<?xml version=\"1.0\"?><NFSe>...</NFSe>",
  "linkDanfse": "https://api.maxerp.com.br/v1/documentos-fiscais/3fa85f64-5717-4562-b3fc-2c963f66afa6/danfse"
}

400 Bad Request

{ "erro": "Tipo de documento 'Nfse' inválido." }

Ocorre quando tipo não é reconhecido ou payload está ausente/nulo. Para "NFCe", também quando a empresa ainda não preencheu o cadastro da NFC-e (Dados fiscais) ou o payload não pôde ser lido.

401 Unauthorized

API Key ausente, incorreta ou revogada.

Consultar documento fiscal

Resposta — 200 OK

Mesmo formato do POST acima (id, status, numeroProtocolo, motivoRejeicao, xmlGerado) — use para acompanhar um documento que ficou Pendente. Depois de autorizada, a resposta também traz:

404 Not Found

Documento inexistente, ou pertencente a outra empresa (a API nunca revela a existência de documentos de terceiros).

Baixar DANFSe

Resposta

200 OK — PDF do DANFSe (Content-Type: application/pdf).

400 Bad Request

Documento não é do tipo NfseNacional — DANFSe hoje só é gerado para esse tipo (NFS-e Municipal usa o link próprio da prefeitura, retornado no mesmo campo linkDanfse quando disponível).

404 Not Found

Documento inexistente, ou ainda não autorizado (DANFSe só existe depois da autorização).

Baixar DANFCE (NFC-e)

Resposta

200 OK — PDF do DANFCE (Content-Type: application/pdf): cupom de 80 mm com itens, totais, formas de pagamento, chave de acesso, protocolo de autorização e QR Code de consulta. Notas canceladas saem com a faixa "NFC-e CANCELADA"; em homologação o cupom traz o aviso "sem valor fiscal".

400 Bad Request

O documento não é uma NFC-e.

404 Not Found

Documento inexistente, ou ainda não autorizado (o DANFCE só existe depois da autorização).

Parceiros: cadastrar empresas

Como funciona a responsabilidade:

• O parceiro é responsável pelas empresas que cria: a cobrança delas vai para o responsável financeiro do parceiro.
• Cada empresa criada é uma emissão separada, com API Key, certificado, numeração e documentos próprios. O mesmo CNPJ pode ser cadastrado por parceiros diferentes, sem nenhuma ligação entre as empresas.
• O parceiro só enxerga e altera as empresas que ele mesmo criou.

O e-mail do cliente é obrigatório e validado: precisa ser de alguém que já tem login no Portal do Cliente. Ele ganha acesso de administrador à empresa no Portal (quem paga continua sendo o responsável do parceiro).

curl -X POST https://api.maxerp.com.br/v1/empresas \
  -H "X-Parceiro-Token: SEU_TOKEN_DE_PARCEIRO" \
  -H "Content-Type: application/json" \
  -d '{ "cnpj": "27.529.641/0001-94", "razaoSocial": "IMPULSO PARK - SP", "emailCliente": "rogerio@cliente.com.br" }'

201 Created

{ "empresaId": "4dd1be5c-1e31-457f-b6e6-6d55b6ea86c2", "cnpj": "27529641000194", "razaoSocial": "IMPULSO PARK - SP",
  "emailCliente": "rogerio@cliente.com.br", "nomeCliente": "Rogério Salvieri", "jaExistia": false,
  "apiKey": "…mostrada só nesta resposta…" }

A apiKey da empresa (para emitir notas) só aparece na criação — guarde-a; se perder, gere outra em Gerar nova API Key. Se o seu parceiro já cadastrou esse CNPJ, a resposta é 200 OK com jaExistia: true: nada é duplicado, só se garante o acesso do cliente, e nenhuma chave nova é gerada.

Erros

Listar e consultar as empresas do parceiro

Mesmo header X-Parceiro-Token. Só aparecem as empresas criadas pelo parceiro; uma empresa de outro parceiro responde 404 empresa_nao_encontrada.

[ { "empresaId": "…", "cnpj": "27529641000194", "razaoSocial": "IMPULSO PARK - SP", "status": "Ativo",
    "temCertificado": true, "certificadoValidoAte": "2027-04-06T17:10:00Z", "ultimoUsoApiKey": "2026-10-20T21:30:00Z" } ]

Gerar nova API Key da empresa

Como a chave só é mostrada na criação, o parceiro pode gerar outra para uma empresa dele. As chaves anteriores da empresa deixam de valer na hora.

curl -X POST https://api.maxerp.com.br/v1/empresas/{empresaId}/api-key \
  -H "X-Parceiro-Token: SEU_TOKEN_DE_PARCEIRO"

200 OK

{ "empresaId": "…", "apiKey": "…mostrada só nesta resposta…", "chavesRevogadas": 1 }

Subir certificado digital

Envia (ou substitui) o certificado digital A1 (.pfx) da empresa. A primeira rota usa o token do parceiro (X-Parceiro-Token) e vale para as empresas que ele criou; a segunda usa a X-Api-Key da própria empresa e envia o certificado dela. As duas aceitam as mesmas formas de envio:

Multipart (arquivo)

curl -X POST https://api.maxerp.com.br/v1/empresas/{empresaId}/certificado \
  -H "X-Parceiro-Token: SEU_TOKEN_DE_PARCEIRO" \
  -F "arquivo=@certificado.pfx" -F "senha=SENHA_DO_CERTIFICADO"

JSON (base64)

{ "arquivoBase64": "MIIK…", "nomeArquivo": "certificado.pfx", "senha": "SENHA_DO_CERTIFICADO" }

200 OK

{ "empresaId": "…", "nomeArquivo": "certificado.pfx", "validoAte": "2027-04-06T17:10:00Z",
  "titular": "IMPULSO PARK - BRASILIA:27529641000780", "cnpjCertificado": "27529641000780", "substituiu": false }

O sistema abre o arquivo com a senha antes de salvar. A senha é guardada criptografada. O certificado precisa estar dentro da validade, ter a chave privada e ser do CNPJ da empresa (a raiz de 8 dígitos é aceita, então o certificado da matriz vale para a filial).

Erros

Consultar e listar notas (NFS-e)

Referência externa na emissão

No POST /v1/documentos-fiscais informe, ao lado de tipo e payload, o campo opcional referenciaExterna (texto de até 40 caracteres, por exemplo o número do pedido no ERP):

{ "tipo": "NfseNacional", "referenciaExterna": "PED-000123", "payload": { … } }

• Idempotente: se já existe uma nota não cancelada e não rejeitada com a mesma referência, a API não emite outra: devolve a nota existente (200 OK). Se a anterior foi cancelada ou rejeitada, a emissão segue normalmente.
• Mais de 40 caracteres: 400 com code: "referencia_invalida".
• A referência volta em todas as consultas (referenciaExterna).

Recuperar uma nota pela referência

Devolve a nota (ou items: []) sem depender do id, para recuperar o resultado quando a resposta da emissão se perdeu (timeout).

Listagem paginada

Observação: cpfCnpjTomador e numeroDps são filtrados sobre as 5.000 notas mais recentes que atendem aos demais filtros; combine com um período (dataEmissaoDe) em bases grandes.

curl "https://api.maxerp.com.br/v1/documentos-fiscais?status=Autorizada&dataEmissaoDe=2026-11-01&page=1&pageSize=50" \
  -H "X-Api-Key: SUA_API_KEY"

Exemplo de resposta (200 OK)

{
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "items": [
    {
      "id": "0f355f99-f80b-4801-8e0f-2c804990f33f",
      "status": "Autorizada",
      "numeroProtocolo": "13026032203160760000154000000000084926105150126468",
      "motivoRejeicao": null,
      "linkDanfse": "https://api.maxerp.com.br/v1/documentos-fiscais/0f355f99-f80b-4801-8e0f-2c804990f33f/danfse",
      "chaveAcesso": "13026032203160760000154000000000084926105150126468",
      "numero": "849",
      "serie": "1",
      "codigoVerificacao": null,
      "alertas": [],
      "linkDanfce": null,
      "linkDanfe": null,
      "tipo": "NfseNacional",
      "motivo": null,
      "numeroNota": "849",
      "numeroDps": "647",
      "serieDps": "1",
      "dataEmissao": "2026-10-23T15:44:25Z",
      "dataAutorizacao": "2026-10-23T15:45:25Z",
      "dataCancelamento": null,
      "atualizadoEm": "2026-10-23T15:45:31.208Z",
      "valorServicos": 2180.0,
      "valorIss": 109.0,
      "aliquota": 5.0,
      "valorLiquido": 2071.0,
      "tomador": {
        "cpfCnpj": "11892491000149",
        "razaoSocial": "SOUZA E VASCONCELOS LTDA",
        "email": "a@b.com"
      },
      "servico": {
        "codigoItemListaServico": "080201",
        "discriminacao": "CLUBE"
      },
      "referenciaExterna": "PED-000123",
      "links": {
        "pdf": "https://api.maxerp.com.br/v1/documentos-fiscais/0f355f99-f80b-4801-8e0f-2c804990f33f/danfse",
        "xml": "https://api.maxerp.com.br/v1/documentos-fiscais/0f355f99-f80b-4801-8e0f-2c804990f33f/xml"
      }
    }
  ]
}

Detalhe de uma nota

Mesmo formato dos itens da listagem, mais xmlGerado (o XML autorizado, ou o enviado quando houve rejeição).

Exemplo de resposta (200 OK)

{
  "id": "0f355f99-f80b-4801-8e0f-2c804990f33f",
  "status": "Autorizada",
  "numeroProtocolo": "13026032203160760000154000000000084926105150126468",
  "motivoRejeicao": null,
  "xmlGerado": "<NFSe …>…</NFSe>",
  "linkDanfse": "https://api.maxerp.com.br/v1/documentos-fiscais/0f355f99-f80b-4801-8e0f-2c804990f33f/danfse",
  "chaveAcesso": "13026032203160760000154000000000084926105150126468",
  "numero": "849",
  "serie": "1",
  "codigoVerificacao": null,
  "alertas": [],
  "linkDanfce": null,
  "linkDanfe": null,
  "tipo": "NfseNacional",
  "motivo": null,
  "numeroNota": "849",
  "numeroDps": "647",
  "serieDps": "1",
  "dataEmissao": "2026-10-23T15:44:25Z",
  "dataAutorizacao": "2026-10-23T15:45:25Z",
  "dataCancelamento": null,
  "atualizadoEm": "2026-10-23T15:45:31.208Z",
  "valorServicos": 2180.0,
  "valorIss": 109.0,
  "aliquota": 5.0,
  "valorLiquido": 2071.0,
  "tomador": {
    "cpfCnpj": "11892491000149",
    "razaoSocial": "SOUZA E VASCONCELOS LTDA",
    "email": "a@b.com"
  },
  "servico": {
    "codigoItemListaServico": "080201",
    "discriminacao": "CLUBE"
  },
  "referenciaExterna": "PED-000123",
  "links": {
    "pdf": "https://api.maxerp.com.br/v1/documentos-fiscais/0f355f99-f80b-4801-8e0f-2c804990f33f/danfse",
    "xml": "https://api.maxerp.com.br/v1/documentos-fiscais/0f355f99-f80b-4801-8e0f-2c804990f33f/xml"
  }
}

Campos devolvidos

Cancelar uma nota

curl -X POST https://api.maxerp.com.br/v1/documentos-fiscais/{id}/cancelar \
  -H "X-Api-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "motivo": "Nota emitida com valor incorreto" }'

Só para nota autorizada. O cancelamento é assíncrono: a API responde 202 Accepted com a nota em CancelamentoPendente; acompanhe pela consulta até Cancelada (se o governo recusar, a nota volta a Autorizada e o motivo da recusa aparece em motivo). No Ambiente Nacional o motivo precisa ter ao menos 15 caracteres.

Erros

Todas as rotas desta seção respondem erros como { "code": "...", "message": "..." }:

Consumo (bilhetagem)

Quantidade de documentos autorizados por emitente e tipo em um período, para faturar por volume. Só leitura: nunca emite nem altera nada. Autenticação: X-Api-Key.

curl "https://api.maxerp.com.br/v1/consumo?dataDe=2026-11-01&dataAte=2026-11-30&tipo=NfseNacional" \
  -H "X-Api-Key: SUA_API_KEY"

Regras de contagem

• O período é pela data de autorização da nota (nas notas antigas, sem essa data, vale a data de criação).
• total conta apenas notas Autorizadas (um cancelamento ainda pendente continua contando como autorizada). Rejeitada, Falha, Pendente e Cancelada não entram.
• canceladas é informado à parte: notas autorizadas no período que depois foram canceladas. Elas não estão em total — para faturar, use total; some canceladas se quiser o bruto.
• Emitentes da conta: a empresa dona da X-Api-Key e, se ela é parceiro de negócio, todas as empresas que ela cadastrou. Todos aparecem em uma só chamada, inclusive os sem movimento: com tipo informado vêm com total: 0; sem tipo vêm com tipo: null e total: 0.

Chave de administração: consumo de todas as empresas

Para faturar todo mundo em uma chamada (todas as empresas e todos os parceiros), use a chave de administração no header X-Admin-Key no lugar da X-Api-Key. Ela é gerada pela MaxERP no painel Admin (Chaves de administração), é mostrada uma única vez e pode ser revogada. Vale só para leitura de consumo: não emite documentos nem consulta notas.

curl "https://api.maxerp.com.br/v1/consumo?dataDe=2026-11-01&dataAte=2026-11-30"   -H "X-Admin-Key: SUA_CHAVE_DE_ADMINISTRACAO"

Cada item traz também empresaId e parceiroId (nulo quando a empresa não foi criada por parceiro). Como o mesmo CNPJ pode existir em parceiros diferentes, o mesmo cnpj pode aparecer mais de uma vez, uma por empresa.

Exemplo de resposta (200 OK)

{
  "dataDe": "2026-11-01",
  "dataAte": "2026-11-30",
  "itens": [
    {
      "cnpj": "11111111000191",
      "tipo": "NfseNacional",
      "total": 3,
      "canceladas": 0
    },
    {
      "cnpj": "27529641000194",
      "tipo": "NfseNacional",
      "total": 2,
      "canceladas": 1
    },
    {
      "cnpj": "33000167000101",
      "tipo": "NfseNacional",
      "total": 0,
      "canceladas": 0
    }
  ]
}

Erros

Formato { "code": "...", "message": "..." }:

Municípios aceitos

A plataforma trabalha com dois modelos de documento diferentes (tipo no payload), e dentro do modelo Nacional existem duas formas de transmissão. Nos três casos, o payload que você monta é decidido pelo tipo — a plataforma escolhe o caminho de transmissão certo sozinha, sem exigir nada extra na maioria dos casos.

1. Ambiente Nacional compartilhado (ADN) — tipo: "NfseNacional"

O caminho padrão e mais comum, cobrindo os 5.571 entes federados aderentes citados acima. Basta informar o código IBGE correto em codigoCidadePrestacao — a plataforma detecta e usa o caminho certo automaticamente. → ver exemplo de payload.

Consulta rápida — seu município está aderente?

Busque abaixo (dados oficiais do gov.br, atualizados em 08/09/2026). Aderente = "Sim" significa que a prefeitura já compartilha dados com o Ambiente Nacional; use o código IBGE do município em codigoCidadePrestacao normalmente.

Fonte: Monitoramento das Adesões à NFS-e (gov.br). Lista sujeita a mudanças semanais pelo governo federal — em caso de dúvida sobre um lançamento específico, a página oficial é sempre a fonte mais atual.

2. Webservice próprio da prefeitura, mesmo schema Nacional — tipo: "NfseNacional"

Este NÃO passa pelo ADN. Alguns municípios ainda não aderiram ao ambiente compartilhado e mantêm o próprio sistema de recebimento — mas usando o mesmo schema/formato de documento (DPS) do Ambiente Nacional, só que a plataforma manda direto pro webservice da prefeitura em vez de passar pela infraestrutura do governo federal. O tipo no payload continua sendo "NfseNacional" (é o mesmo documento) — só muda, por trás dos panos, pra onde ele é enviado.

Precisa de outro município nessa situação? Entre em contato com o time responsável pela sua instalação — a integração é adicionada caso a caso, conforme o comunicado oficial da prefeitura.

3. NFS-e Municipal (ABRASF) — tipo: "NfseMunicipal"

Modelo totalmente diferente do Nacional — schema/documento próprio (padrão ABRASF), usado por municípios que ainda não migraram pra Reforma. Hoje, testado e validado em produção apenas para:

Outros municípios ABRASF podem funcionar (a biblioteca de base suporta dezenas de provedores), mas não foram testados nesta plataforma — recomendamos validar em homologação antes de emitir em produção.

Campos — NFS-e Nacional

Use quando tipo = "NfseNacional". Os dados do prestador (sua empresa) não entram no payload — vêm do cadastro em Dados Fiscais.

Objeto raiz

tomador

servico

servico.retencoesFederais

servico.deducao

servico.comercioExterior

servico.locacao

servico.obra

servico.evento

servico.exploracaoRodoviaria

substituicao

ibsCbs

Exemplo completo — NFS-e Nacional (Ambiente Nacional/ADN)

{
  "tipo": "NfseNacional",
  "payload": {
    "numeroDps": 42,
    "serieDps": "00001",
    "tomador": {
      "cpfCnpj": "58639313000174",
      "razaoSocial": "EMPRESA TOMADORA LTDA",
      "inscricaoMunicipal": "73341",
      "codigoCidade": "5107909",
      "cep": "78555440",
      "endereco": "AVENIDA EXEMPLO",
      "numero": "1668",
      "bairro": "CENTRO",
      "telefone": "6533334444",
      "email": "financeiro@empresatomadora.com.br"
    },
    "servico": {
      "codigoItemListaServico": "010701",
      "discriminacao": "Desenvolvimento de sistema sob demanda — OS 1234",
      "valorServicos": 2500.00,
      "aliquotaIss": 0,
      "codigoCidadePrestacao": "3532504",
      "codigoNbs": "115013000",
      "informacoesComplementares": "Ordem de Serviço 1234",
      "tipoRetIss": 1,
      "valorPercAliqSN": 6.0
    }
  }
}

Exemplo — Lucro Presumido/Real com retenções federais e desconto

{
  "tipo": "NfseNacional",
  "payload": {
    "numeroDps": 43,
    "serieDps": "00001",
    "tomador": {
      "cpfCnpj": "58639313000174",
      "razaoSocial": "EMPRESA TOMADORA LTDA",
      "codigoCidade": "5107909"
    },
    "servico": {
      "codigoItemListaServico": "010701",
      "discriminacao": "Consultoria técnica especializada — Contrato 987",
      "valorServicos": 10000.00,
      "aliquotaIss": 5,
      "codigoCidadePrestacao": "3532504",
      "descontoIncondicional": 500.00,
      "retencoesFederais": {
        "valorIrrf": 150.00,
        "valorCsll": 100.00,
        "valorInss": 0,
        "pisCofinsCst": "AliquotaBasica",
        "valorBaseCalculoCofins": 9500.00,
        "aliquotaPis": 0.65,
        "aliquotaCofins": 3.00,
        "valorPis": 61.75,
        "valorCofins": 285.00,
        "tipoRetencaoPisCofinsCsll": "PisCofinsRetidos"
      }
    }
  }
}

Este exemplo não informa valorPercAliqSN porque o prestador não é optante do Simples Nacional — nesse caso a API preenche automaticamente o indicador de transparência fiscal (totTrib) exigido pela Lei 12.741/2012.

Exemplo — Brasília/DF, evento (item 12) e IBS/CBS

Prestador optante do Simples Nacional (por isso sem aliquotaIss, com valorPercAliqSN) emitindo em Brasília para um evento — item da lista 12 (diversões públicas), que exige o bloco evento nesse município (ver aviso acima). O tomador aqui é pessoa física (CPF).

{
  "tipo": "NfseNacional",
  "payload": {
    "numeroDps": 3,
    "serieDps": "3",
    "tomador": {
      "cpfCnpj": "00000000000",
      "razaoSocial": "NOME DO TOMADOR",
      "cep": "15123012",
      "endereco": "RUA EXEMPLO",
      "numero": "45",
      "bairro": "CENTRO",
      "email": "contato@tomador.com.br"
    },
    "servico": {
      "codigoItemListaServico": "120501",
      "codigoTribMunicipal": "1205",
      "discriminacao": "Show musical - Festival de Verao",
      "valorServicos": 5000.00,
      "codigoCidadePrestacao": "5300108",
      "codigoNbs": "125079000",
      "tipoRetIss": 1,
      "valorPercAliqSN": 6.0,
      "evento": {
        "descricao": "Show Musical / Festival de Verao",
        "dataInicio": "2026-08-27T00:00:00",
        "dataFim": "2026-08-27T23:59:59",
        "codigoCidade": "5300108",
        "cep": "71608900",
        "logradouro": "Aeroporto Internacional de Brasilia Juscelino Kubitschek",
        "numero": "S/N",
        "bairro": "Setor de Habitacoes Individuais Sul"
      }
    },
    "ibsCbs": {
      "indicadorUsoFinal": "Nao",
      "codigoIndicadorOperacao": "030101",
      "indicadorDestinatario": "ProprioTomador",
      "codigoSituacaoTributaria": "200",
      "codigoClassificacaoTributaria": "200048"
    }
  }
}

Este payload corresponde a uma emissão real autorizada em produção. codigoClassificacaoTributaria: "200048" é o código de Parques de Diversão (alíquota reduzida) — troque pelo código correto da tabela oficial para o seu tipo de serviço.

Campos — NFS-e Municipal

Use quando tipo = "NfseMunicipal" (padrão ABRASF). Os dados do prestador também vêm do cadastro, não do payload.

Objeto raiz

tomador

servico

servico.ibsCbs (Municipal)

Campos opcionais de servico — tributação, deduções e retenções

Além de itemListaServico, discriminacao, valorServicos, aliquota e ibsCbs (tabela acima), o objeto servico aceita:

tomador.cpfCnpj pode ir vazio (""): a nota sai com tomador não identificado (consumidor final).

Regras de formato (manual do Web Service da NFS-e de São Paulo, v3.3.9)

• Discriminação: quebras de linha são trocadas por | e espaços nas pontas são removidos (você pode mandar \n).
• E-mail do tomador: até 75 caracteres; maior que isso, o e-mail é omitido em vez de a nota ser recusada. E-mails com erro comum de digitação são corrigidos ou removidos.
• Item do serviço: em São Paulo o itemListaServico tem 5 dígitos (ex.: "08117") — diferente do código de 6 dígitos da NFS-e Nacional.
• Campos obrigatórios: numeroRps, serieRps e servico.itemListaServico. Um corpo com os nomes do padrão Nacional (numeroDps, codigoItemListaServico…) enviado como NfseMunicipal é recusado com uma mensagem listando o que falta.
• Alertas: a prefeitura pode autorizar a nota e devolver avisos (ex.: código 1259, serviço de diversões públicas com ISS recolhido pelo SDPE). Eles vêm no campo alertas da resposta.

Exemplos prontos

Os corpos abaixo estão disponíveis para baixar em /docs/exemplos/ (e no repositório, em docs/exemplos-payload/) e são validados por teste automático:

Exemplo — NFS-e Municipal (São Paulo, Layout 1)

{
  "tipo": "NfseMunicipal",
  "payload": {
    "numeroRps": "1042",
    "serieRps": "1",
    "tomador": {
      "cpfCnpj": "58639313000174",
      "razaoSocial": "EMPRESA TOMADORA LTDA",
      "endereco": "AVENIDA EXEMPLO",
      "numero": "1668",
      "bairro": "CENTRO",
      "codigoMunicipioIbge": "5107909",
      "uf": "MT",
      "cep": "78555440",
      "telefone": "6533334444",
      "email": "financeiro@empresatomadora.com.br"
    },
    "servico": {
      "itemListaServico": "0107",
      "discriminacao": "Consultoria em TI — OS 1234",
      "valorServicos": 1800.00,
      "aliquota": 3.0
    }
  }
}

O município que processa a nota é sempre o cadastrado na sua empresa (prestador) — não há campo de cidade do prestador no payload. Este exemplo funciona em qualquer instalação com prestador cadastrado em São Paulo.

Exemplo — NFS-e Municipal (São Paulo, Layout 2 / IBS-CBS)

Mesmo payload, acrescido do bloco ibsCbs — ativa automaticamente o Layout 2 da prefeitura de São Paulo. Payload real usado em produção.

{
  "tipo": "NfseMunicipal",
  "payload": {
    "numeroRps": "8605",
    "serieRps": "6",
    "tomador": {
      "cpfCnpj": "58639313000174",
      "razaoSocial": "EMPRESA TOMADORA LTDA",
      "email": "financeiro@empresatomadora.com.br"
    },
    "servico": {
      "itemListaServico": "08117",
      "discriminacao": "Ingresso - evento cultural",
      "valorServicos": 320.00,
      "aliquota": 5.0,
      "ibsCbs": {
        "codigoCnae": "9321200",
        "codigoNbs": "125079000",
        "codigoIndicadorOperacao": "030101",
        "codigoClassificacaoTributaria": "200048",
        "codigoSituacaoTributaria": "200"
      }
    }
  }
}

Campos — NFC-e

Use quando tipo = "NFCe" (NFC-e, modelo 65 — cupom fiscal eletrônico do varejo). A emissão é síncrona: a SEFAZ da UF da empresa autoriza na hora e a resposta do POST já traz o resultado, a chave de acesso e o link do cupom. Funciona para todas as UFs. Os dados do emitente (inscrição estadual, regime, endereço, CSC) não entram no payload — vêm do cadastro em Painel de Controle > Dados fiscais.

Cadastro prévio (Dados fiscais)

Objeto raiz

consumidor

itens[]

pagamentos[]

Exemplo mínimo

{
  "tipo": "NFCe",
  "payload": {
    "itens": [
      { "codigo": "001", "descricao": "Produto", "ncm": "21069090", "cfop": "5102", "unidade": "UN", "quantidade": 1, "valorUnitario": 1.00 }
    ],
    "pagamentos": [ { "forma": "01", "valor": 1.00 } ]
  }
}

Exemplo completo — Simples Nacional, consumidor identificado e pagamento misto

{
  "tipo": "NFCe",
  "payload": {
    "serie": 2,
    "consumidor": { "cpfCnpj": "39053344705", "nome": "Fulano de Tal" },
    "itens": [
      {
        "codigo": "001",
        "descricao": "Pao frances",
        "ncm": "19059090",
        "cfop": "5102",
        "unidade": "KG",
        "quantidade": 0.75,
        "valorUnitario": 18.90,
        "desconto": 0.50,
        "codigoBarras": "7891000100103",
        "origem": 0,
        "cstIcms": "102"
      },
      {
        "codigo": "002",
        "descricao": "Refrigerante lata 350ml",
        "ncm": "22021000",
        "cfop": "5102",
        "unidade": "UN",
        "quantidade": 2,
        "valorUnitario": 5.50
      }
    ],
    "pagamentos": [
      { "forma": "17", "valor": 10.00 },
      { "forma": "01", "valor": 20.00 }
    ],
    "informacoesAdicionais": "Obrigado pela preferencia!"
  }
}

Exemplo — Regime Normal (ICMS 18%)

{
  "tipo": "NFCe",
  "payload": {
    "itens": [
      {
        "codigo": "010", "descricao": "Camiseta", "ncm": "61091000", "cfop": "5102", "unidade": "UN",
        "quantidade": 1, "valorUnitario": 59.90,
        "cstIcms": "00", "aliquotaIcms": 18
      }
    ],
    "pagamentos": [ { "forma": "03", "valor": 59.90 } ]
  }
}

Resposta — nota autorizada

{
  "id": "5794503a-72bc-4f5f-920f-6b0c848b4f6d",
  "status": "Autorizada",
  "numeroProtocolo": "53261043809837000270650020000000011123535978",
  "motivoRejeicao": null,
  "xmlGerado": "<?xml version=\"1.0\"?><nfeProc>...</nfeProc>",
  "linkDanfse": null,
  "chaveAcesso": "53261043809837000270650020000000011123535978",
  "numero": "1",
  "serie": "2",
  "linkDanfce": "https://api.maxerp.com.br/v1/documentos-fiscais/5794503a-72bc-4f5f-920f-6b0c848b4f6d/danfce"
}

Exemplo — cURL

curl -X POST "https://api.maxerp.com.br/v1/documentos-fiscais" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "NFCe",
    "payload": {
      "itens": [
        { "codigo": "001", "descricao": "Produto", "ncm": "21069090", "cfop": "5102", "unidade": "UN", "quantidade": 1, "valorUnitario": 1.00 }
      ],
      "pagamentos": [ { "forma": "01", "valor": 1.00 } ]
    }
  }'

Rejeições comuns

Campos — NF-e (modelo 55)

Use quando tipo = "NFe": nota fiscal de produtos (venda a empresa ou pessoa física, e-commerce), devolução, retorno de remessa, complementar e ajuste. A emissão passa pela fila e a SEFAZ da UF da empresa autoriza; consulte o resultado pelo GET se o POST responder Pendente. Itens, pagamentos e tributos (ICMS, PIS, COFINS) seguem as mesmas regras da NFC-e.

Objeto raiz

Devolução, retorno de remessa, complementar e ajuste

• O CFOP precisa combinar com o tipo de operação: entrada usa 1xxx/2xxx/3xxx; saída usa 5xxx/6xxx/7xxx. Incoerência é recusada na hora.
• O CFOP acompanha o destino: 5xxx vira 6xxx (e 1xxx vira 2xxx) quando o destinatário é de outra UF.
• Complementar, ajuste e devolução saem sem pagamento (forma 90, valor 0) — não é preciso enviar pagamentos.
• Na entrada própria, PIS/COFINS usam o CST 98 (o 49 é só de saída) e não há DIFAL.
• Limitações atuais: CST de ICMS suportados 00, 40, 41, 50 e 60 (CSOSN 102, 103, 300, 400, 500); devolução com ICMS-ST, redução de base ou IPI ainda não é montada; só chaves de NF-e entram em chavesReferenciadas.

Exemplo — devolução de venda (entrada própria)

{
  "tipo": "NFe",
  "payload": {
    "tipoOperacao": 0,
    "finalidade": 4,
    "chavesReferenciadas": ["35261011222333000181550030000000151234567815"],
    "destinatario": {
      "cpfCnpj": "39053344705", "nome": "Maria Compradora", "indicadorIe": 9,
      "endereco": { "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista",
                    "codigoMunicipioIbge": "3550308", "municipio": "São Paulo", "uf": "SP", "cep": "01310100" }
    },
    "itens": [ { "codigo": "CAM-AZ-M", "descricao": "Camiseta algodão azul M", "ncm": "61091000",
                 "cfop": "1202", "unidade": "UN", "quantidade": 1, "valorUnitario": 50.00, "cstIcms": "102" } ]
  }
}

Status possíveis

Referência de erros HTTP

Exemplo — cURL

curl -X POST "https://api.maxerp.com.br/v1/documentos-fiscais" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "NfseNacional",
    "payload": {
      "numeroDps": 42,
      "serieDps": "00001",
      "tomador": {
        "cpfCnpj": "58639313000174",
        "razaoSocial": "EMPRESA TOMADORA LTDA",
        "email": "financeiro@empresatomadora.com.br"
      },
      "servico": {
        "codigoItemListaServico": "010701",
        "discriminacao": "Servico prestado",
        "valorServicos": 2500.00,
        "aliquotaIss": 5,
        "codigoCidadePrestacao": "3532504"
      }
    }
  }'

# Consultar depois:
curl "https://api.maxerp.com.br/v1/documentos-fiscais/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

Exemplo — PHP

<?php

$apiKey = 'SUA_CHAVE_AQUI';
$baseUrl = 'https://api.maxerp.com.br/v1/documentos-fiscais';

$payload = [
    'tipo' => 'NfseNacional',
    'payload' => [
        'numeroDps' => 42,
        'serieDps' => '00001',
        'tomador' => [
            'cpfCnpj' => '58639313000174',
            'razaoSocial' => 'EMPRESA TOMADORA LTDA',
            'email' => 'financeiro@empresatomadora.com.br',
        ],
        'servico' => [
            'codigoItemListaServico' => '010701',
            'discriminacao' => 'Servico prestado',
            'valorServicos' => 2500.00,
            'aliquotaIss' => 5,
            'codigoCidadePrestacao' => '3532504',
        ],
    ],
];

$ch = curl_init($baseUrl);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
]);

$respostaBruta = curl_exec($ch);
$statusHttp = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$resposta = json_decode($respostaBruta, true);

if ($statusHttp === 200 || $statusHttp === 202) {
    echo "Documento: {$resposta['id']} — status: {$resposta['status']}\n";

    if ($resposta['status'] === 'Pendente') {
        // Consultar novamente mais tarde:
        // GET https://api.maxerp.com.br/v1/documentos-fiscais/{$resposta['id']}
    }
} else {
    echo "Erro ({$statusHttp}): " . ($resposta['erro'] ?? $respostaBruta) . "\n";
}

Exemplo — JavaScript (fetch)

const resposta = await fetch('https://api.maxerp.com.br/v1/documentos-fiscais', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'SUA_CHAVE_AQUI',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tipo: 'NfseNacional',
    payload: {
      numeroDps: 42,
      serieDps: '00001',
      tomador: {
        cpfCnpj: '58639313000174',
        razaoSocial: 'EMPRESA TOMADORA LTDA',
        email: 'financeiro@empresatomadora.com.br',
      },
      servico: {
        codigoItemListaServico: '010701',
        discriminacao: 'Servico prestado',
        valorServicos: 2500.00,
        aliquotaIss: 5,
        codigoCidadePrestacao: '3532504',
      },
    },
  }),
});

const dados = await resposta.json();

if (resposta.ok) {
  console.log(`Documento ${dados.id} — status: ${dados.status}`);
} else {
  console.error(`Erro (${resposta.status}):`, dados.erro ?? dados);
}

Boas práticas

• Trate o 202 como normal, não como erro. Documentos que demoram mais para autorizar (ex.: webservice do governo lento) retornam 202 — sua integração deve consultar o GET periodicamente até sair de Pendente/Processando.
• Guarde sempre o id retornado, mesmo em caso de rejeição — ele é sua referência para consultar o documento depois ou para abrir um chamado de suporte.
• Não reenvie o mesmo número de DPS/RPS em caso de dúvida. Se não tiver certeza se uma emissão foi recebida, consulte pelo id antes de reenviar — reemitir o mesmo número pode ser rejeitado pelo governo como duplicidade.
• Homologação vs. Produção é uma configuração do ambiente da própria plataforma (não um parâmetro da requisição) — confirme com o time responsável pela instalação em qual ambiente sua API Key está operando antes de emitir documentos reais.
• Nunca exponha sua API Key em código client-side (JavaScript rodando no navegador, apps mobile). Chame a API sempre a partir do seu backend.

Suporte

Dúvidas sobre a integração, credenciais ou comportamento inesperado da API: entre em contato com o time responsável pela sua instalação da Max ERP Fiscal Platform.