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 Painel de Controle > Dados Fiscais, os dados do prestador para o modelo que for usar (Nacional e/ou Municipal): código IBGE, regime tributário, endereço, etc.
• Certificado digital A1 (.pfx) enviado — em Painel de Controle > Certificado Digital, usado para assinar digitalmente o documento antes de enviar ao governo.

Sem isso, a emissão é aceita pela API (fica em fila) mas retorna Rejeitada com uma mensagem explicando o que falta.

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.

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.

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).

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)

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"
      }
    }
  }
}

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.