#Notas fiscais de serviço (NFS-e) — beta

Com a API de NFS-e a sua empresa emite notas fiscais de serviço eletrônicas no Padrão Nacional a partir da marx: você envia um JSON simples e a marx monta, assina e transmite a nota ao Ambiente Nacional da NFS-e, guarda o XML e gera o PDF (DANFSe).

#Como funciona

1. Você cadastra o emissor (o CNPJ que emite as notas), envia o certificado digital A1 desse CNPJ e cadastra os serviços que ele presta.
2. Cada nota é pedida com POST /api/nfse e um reference seu. A resposta é imediata (202) e a nota segue para a fila de emissão.
3. O resultado chega por webhook (event_type_nfse_authorized ou event_type_nfse_rejected) e também pode ser consultado na API.
4. Notas autorizadas têm PDF e XML disponíveis, e podem ser canceladas ou substituídas.

Você nunca envia XML nem códigos do leiaute fiscal: a marx traduz os campos (tabela no fim da página).

#Configuração passo a passo

Todas as chamadas usam as mesmas credenciais da API de pagamentos (X-Client-Id e X-Client-Secret, veja Credenciais e autenticação).

#1. Cadastre o emissor

POST /api/nfse/issuers

curl -X POST https://marx.loco.ltd/api/nfse/issuers \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "cnpj": "11.222.333/0001-81",
    "legal_name": "Minha Empresa LTDA",
    "municipal_registration": "0101010101",
    "city_ibge": "4106902",
    "tax_regime": "simples",
    "simples_collection": "das",
    "series": "900",
    "approximate_tax_percent": "6.00",
    "email": "fiscal@minhaempresa.com.br"
  }'

A resposta (201) traz o emissor com ready: false e a lista do que falta em missing: certificate, service, approximate_tax_percent (ME/EPP sem percentual) e activation. O emissor nasce inativo e em teste.

#2. Envie o certificado digital A1

PUT /api/nfse/issuers/{id}/certificate

O certificado e-CNPJ A1 (ICP-Brasil) do próprio CNPJ do emissor assina as notas. Envie o arquivo .pfx (ou .p12) e a senha:

curl -X PUT https://marx.loco.ltd/api/nfse/issuers/11222333000181/certificate \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -F file=@certificado-a1.pfx -F password="$SENHA_DO_CERTIFICADO"

Ou em JSON, com o arquivo em Base64: {"pfx_base64": "MIIK…", "password": "…"}.

O certificado só é aceito se abrir com a senha, contiver a chave privada, estiver dentro da validade e for um e-CNPJ do mesmo CNPJ do emissor (o Ambiente Nacional recusa notas assinadas com certificado de outro CNPJ, inclusive de contador ou procurador).

• O arquivo e a senha ficam guardados criptografados e nunca são devolvidos pela API. As respostas trazem só os dados públicos: titular, CNPJ, validade e impressão digital (fingerprint_sha256).
• GET /api/nfse/issuers/{id}/certificate mostra esses dados; DELETE remove o certificado (o emissor para de emitir até receber outro).
• Renovação: o A1 vale 1 ano. Envie o novo com o mesmo PUT; ele substitui o anterior na hora. Guarde sempre uma cópia do .pfx e da senha no seu cofre de senhas.

#3. Cadastre os serviços

POST /api/nfse/issuers/{id}/services

curl -X POST https://marx.loco.ltd/api/nfse/issuers/11222333000181/services \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "code": "01.03.01", "nbs": "1.1506.21.00", "description": "Assinatura de software (SaaS)" }'

Os códigos e a NBS de cada serviço são definidos com o seu contador. GET lista os serviços, PATCH /api/nfse/issuers/{id}/services/{service_id} altera e DELETE remove um serviço que ainda não foi usado em nenhuma nota.

#4. Ative o emissor

curl -X PATCH https://marx.loco.ltd/api/nfse/issuers/11222333000181 \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" -d '{"active": true}'

A ativação só é aceita quando não falta mais nada: a resposta passa a trazer "ready": true e "missing": [].

#5. Teste e produção

Todo emissor começa em teste ("environment": "test"): as notas vão para o ambiente de produção restrita do Emissor Nacional e não têm valor fiscal. A numeração de teste é separada, então os testes não deixam buracos na numeração real.

Faça os testes que precisar (emitir, consultar, cancelar, substituir). Quando estiver tudo certo, peça ao time marx para mudar o emissor para produção. A partir daí as notas são reais. Cada nota informa em que ambiente foi emitida (environment).

#Emitir uma nota

POST /api/nfse

curl -X POST https://marx.loco.ltd/api/nfse \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "fatura-2026-10-0042",
    "amount": "149.90",
    "competence_date": "2026-10-01",
    "customer": {
      "tax_id": "11.222.333/0001-81",
      "name": "Cliente LTDA",
      "email": "financeiro@cliente.com.br"
    },
    "service": { "code": "010301", "description": "Assinatura Pro — outubro/2026" }
  }'

Resposta 202:

{
  "object": "nfse",
  "id": "8f1c2a7e-4b1d-4f43-9b2f-5e8d9a4b1c22",
  "status": "queued",
  "environment": "test",
  "reference": "fatura-2026-10-0042",
  "issuer": { "id": "…", "cnpj": "11222333000181" },
  "number": null,
  "access_key": null,
  "amount": "149.9",
  "competence_date": "2026-10-01",
  "description": "Assinatura Pro — outubro/2026",
  "service": { "code": "010301", "nbs": "115062100" },
  "customer": { "tax_id": "11222333000181", "country": "BR", "name": "Cliente LTDA", "email": "financeiro@cliente.com.br" },
  "errors": [],
  "cancellation": null,
  "replaces_id": null,
  "replaced_by_id": null,
  "links": {},
  "created_at": "2026-10-06T10:00:00-03:00"
}

Se o emissor ainda não estiver pronto, a resposta é 422 com o que falta: {"error": "…", "missing": ["certificate"]}.

#Exportação de serviços

Quando o tomador é do exterior (customer.country diferente de BR), a nota é de exportação: o ISS não incide (tribISSQN = 3), o tax_id é o identificador fiscal estrangeiro (NIF) e o grupo de comércio exterior é obrigatório. Envie export:

{
  "reference": "consultoria-2026-10",
  "amount": "24480.00",
  "customer": { "tax_id": "98-7654321", "country": "US", "name": "Acme Inc" },
  "service": { "code": "010601", "description": "Consultoria em TI — outubro/2026" },
  "export": { "currency": "USD", "amount_in_currency": "4896.00", "mode": "cross_border" }
}

#ISS retido pelo tomador

Quando o seu cliente retém o ISS (tpRetISSQN = 2), envie "iss_withheld": true. A alíquota vem de iss_rate na nota, ou da alíquota do serviço, ou de iss_withholding_rate do emissor (até 5%).

A API recusa (422) antes de enviar quando a regra nacional não permite:

#IBS e CBS (Reforma Tributária)

A partir de 01/01/2027, toda NFS-e precisa do grupo IBS/CBS, inclusive de empresas do Simples Nacional. Em 2026 ele é opcional para o Simples. Configure os códigos no emissor (ibs_cbs), em cada serviço ou em uma nota específica:

• Configurado, o grupo vai em toda nota. Sem configuração ele é omitido até 31/12/2026.
• A partir de 2027, a API recusa a nota e o emissor aparece com missing: ["ibs_cbs"] enquanto faltar.
• Os valores de IBS e CBS do Simples são calculados pelo Ambiente Nacional; você informa só os códigos.

#Status da nota

#Consultar, listar e baixar

Antes da autorização, PDF e XML respondem 404.

#Cancelar

POST /api/nfse/{id}/cancel

curl -X POST https://marx.loco.ltd/api/nfse/8f1c2a7e-4b1d-4f43-9b2f-5e8d9a4b1c22/cancel \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "service_not_provided" }'

Responde 202 com cancellation.status = "pending"; quando o cancelamento é registrado, a nota fica cancelled e chega o webhook event_type_nfse_cancelled. Só notas authorized podem ser canceladas.

#Substituir

POST /api/nfse/{id}/replace

Cria uma nota nova que substitui a original. Envie um reference novo e só os campos que mudam; os demais são copiados da original.

curl -X POST https://marx.loco.ltd/api/nfse/8f1c2a7e-4b1d-4f43-9b2f-5e8d9a4b1c22/replace \
  -H "X-Client-Id: $MARX_CLIENT_ID" -H "X-Client-Secret: $MARX_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "fatura-2026-10-0042-v2", "service": { "description": "Assinatura Pro — outubro/2026 (contrato 123)" } }'

reason é opcional: other (padrão), rejected_by_customer, simples_exclusion, simples_inclusion, immunity_added ou immunity_removed. A resposta (202) é a nota nova, com replaces_id. Quando ela for autorizada, a original passa a replaced.

#Emissão automática no pagamento

Com auto_issue_on_payment: true no emissor, a marx emite uma nota para cada cobrança paga (uma por pagamento, nunca duas). Para a nota sair completa, envie os dados do tomador e, se quiser, o serviço e a descrição no metadata da cobrança:

{
  "metadata": {
    "nfse": {
      "customer": { "cnpj": "11222333000181", "name": "Cliente LTDA", "email": "financeiro@cliente.com.br" },
      "service_code": "010301",
      "description": "Assinatura Pro — outubro/2026"
    }
  }
}

Sem esses dados, usamos o pagador informado pela rede Pix quando ele vem completo; caso contrário a nota fica em needs_data. Devoluções não cancelam a nota automaticamente.

#Webhooks

As notas usam o mesmo envio, assinatura e novas tentativas dos webhooks de pagamento. O payload é a nota (mesmo formato de GET /api/nfse/{id}).

#Erros comuns na emissão

Os códigos vêm do Ambiente Nacional, em errors[].code:

#Como os campos viram a nota

#Checklist antes de produção

• [ ] Regime, códigos de serviço, NBS e texto da descrição confirmados com o contador.
• [ ] Inscrição municipal idêntica ao Indicador Municipal do Emissor Nacional (confira também no ambiente de produção).
• [ ] Percentual aproximado de tributos configurado (obrigatório para ME/EPP).
• [ ] Códigos de IBS/CBS configurados e testados antes de 01/01/2027.
• [ ] Exportação: notas de teste com export emitidas, se você tem clientes no exterior.
• [ ] Série exclusiva da marx (diferente da usada no portal).
• [ ] Notas de teste emitidas, consultadas, canceladas e substituídas com sucesso.
• [ ] Webhooks event_type_nfse_* tratados e assinatura validada.
• [ ] reference único em todo pedido de nota.
• [ ] Lembrete para renovar o certificado A1 antes do vencimento.
• [ ] Pedido ao time marx para mudar o emissor para produção.