Integrar o Maxtra Fiscal com ajuda de IA

Guia para quem não é programador ou está começando, e quer que o próprio sistema (loja, ERP, CRM, planilha com automação) emita NFS-e sozinho. Uma ferramenta de IA que escreve código, como ChatGPT, Claude, Cursor ou Copilot, faz a parte técnica com você. Você cuida das decisões e dos testes.

Se você já programa, vá direto ao guia completo da API.

O que você vai precisar

Acesso ao painel do Maxtra Fiscal, com a empresa cadastrada e o certificado A1 enviado.
O sistema que vai emitir as notas, e alguém com acesso ao código dele. Pode ser você, com a ajuda da IA.
Uma ferramenta de IA que escreve código. Funciona melhor quando ela consegue abrir links ou quando você anexa os arquivos da documentação.

Não precisa entender de nota fiscal eletrônica para começar. O Maxtra Fiscal valida, assina e transmite a nota. O seu sistema só precisa dizer para quem, qual serviço e qual valor.

Palavras que vão aparecer

Termo	O que significa
NFS-e	Nota fiscal de serviço eletrônica.
Tomador	O cliente que contratou o serviço e recebe a nota.
Homologação	Ambiente de teste. As notas não têm validade fiscal e não consomem a franquia do plano. Comece sempre por aqui.
Produção	Ambiente real. As notas valem para a prefeitura.
Chave de API	Uma senha que permite ao seu sistema emitir notas em nome da empresa. Começa com `fiscal_`.
Idempotency-Key	Um código único por nota, por exemplo o número do pedido. Se a internet cair e o sistema tentar de novo com o mesmo código, o Maxtra Fiscal devolve a mesma nota em vez de emitir outra.
Referência externa	O identificador do pedido no seu sistema. Ele volta junto com a nota, para você saber de qual pedido ela é.
Webhook	Um aviso automático que o Maxtra Fiscal envia ao seu sistema quando a nota é autorizada, rejeitada ou cancelada.

Passo 1. Crie a chave de teste no painel

No painel, abra API.
Em Chaves de acesso, clique em Criar chave.
Dê um nome (por exemplo, "Loja virtual"), escolha o ambiente Homologação e a permissão Operador: emitir e consultar.
Copie a chave. Ela aparece uma única vez.
Na mesma tela, copie o Endereço base. É o endereço que o seu sistema vai chamar.

Segurança: não cole a chave em conversas com a IA. Peça que o código leia a chave de uma variável de ambiente (MAXTRA_API_KEY) e coloque o valor só no servidor. Se a chave vazar, revogue-a no painel e crie outra.

Passo 2. Entregue o guia para a sua IA

A sua ferramenta de IA não conhece o Maxtra Fiscal de antemão. Ela aprende lendo o nosso guia, então o jeito mais simples é anexar um único arquivo na conversa:

maxtra-fiscal-guia-para-ia.md: este passo a passo junto com o guia completo da API. Baixe no site do Maxtra Fiscal, na seção Integração.

Se a sua ferramenta abre links, ela também pode ler os mesmos textos direto do servidor, em {ENDERECO}/api/docs/iniciantes.md, {ENDERECO}/api/docs/guia.md e {ENDERECO}/api/docs/openapi.yaml, onde {ENDERECO} é o endereço do seu painel.

Passo 3. Use o pedido pronto

Anexe o arquivo, copie o texto abaixo, troque o que está entre colchetes e envie para a sua ferramenta de IA:

Anexei o arquivo maxtra-fiscal-guia-para-ia.md. Ele explica a API do Maxtra Fiscal, que emite NFS-e.
Leia o arquivo inteiro antes de escrever código.

Quero integrar meu sistema para emitir a nota automaticamente.
Não sou programador experiente: explique cada passo e me diga onde colar cada arquivo.

Meu sistema: [descreva: linguagem, framework ou plataforma, por exemplo "loja em WordPress" ou "API em Node.js com Express"].
Quando emitir: [por exemplo, "quando o pedido for marcado como pago"].
Dados que tenho de cada cliente: [nome, CPF/CNPJ, e-mail, endereço...].

Regras obrigatórias:
1. Use o ambiente de homologação (cabeçalho X-Ambiente: homologacao).
2. Leia a chave de API da variável de ambiente MAXTRA_API_KEY e o endereço de MAXTRA_BASE_URL. Nunca escreva a chave no código.
3. Envie Idempotency-Key com o identificador do pedido e repita a mesma chave em toda nova tentativa.
4. Envie referencia_externa com o identificador do pedido.
5. Trate as respostas 200 (autorizada), 202 (processando), 422 (rejeitada) e 502/504 (incerto: consulte antes de tentar de novo).
6. Valores em dinheiro vão como texto, por exemplo "1500.00".

Comece me dizendo quais dados do serviço eu preciso confirmar com meu contador.

Passo 4. Teste em homologação

Rode o código que a IA escreveu e faça um pedido de teste.
No painel, abra Notas fiscais com o ambiente Homologação selecionado. A nota deve aparecer lá.
Se ela for rejeitada, copie a mensagem de erro e cole na conversa com a IA. Os erros mais comuns são código de serviço, NBS, alíquota ou endereço do tomador incompletos. O guia completo tem a lista de erros frequentes.
Faça o mesmo pedido de novo, com o mesmo identificador, e confira que não aparece uma segunda nota.

Os dados fiscais do serviço (código, NBS, alíquota e regime) não são calculados pelo Maxtra Fiscal. Confirme esses valores com o seu contador.

Passo 5. Receba os avisos automáticos (opcional)

Para o seu sistema saber na hora quando a nota foi autorizada, peça à IA:

Agora crie a rota que recebe os webhooks do Maxtra Fiscal, conforme a seção "Webhooks" do guia.
Verifique a assinatura X-Maxtra-Signature com o segredo da variável MAXTRA_WEBHOOK_SECRET,
ignore eventos repetidos pelo X-Maxtra-Event-Id e marque o pedido como "nota emitida"
quando chegar nota.autorizada.

Depois cadastre o endereço dessa rota no painel, em API → Webhooks, e use o botão Enviar evento de teste para conferir.

Passo 6. Vá para produção

O responsável pela empresa marca Permitir emissões em produção nesta empresa em Configurações.
Envie o certificado A1 (e, se o município exigir, o token da prefeitura) também no ambiente Produção.
Crie uma nova chave no ambiente Produção. A chave de homologação não funciona em produção.
Troque X-Ambiente para producao e a variável MAXTRA_API_KEY para a nova chave.
Emita uma primeira nota real de valor baixo e confira no painel.

Precisa de ajuda?

Fale com a equipe do Maxtra Fiscal. Ao pedir ajuda, envie a mensagem de erro e o identificador do pedido (a Idempotency-Key). Nunca envie a chave de API.