Início rápido

Tudo aqui acontece em homologação (produção restrita da Sefin, sem valor fiscal). Nenhuma Nota tem valor fiscal até você ativar a produção do Prestador. Você vai precisar de:

uma Chave de API (nx_...);
o Certificado A1 (e-CNPJ, arquivo .pfx) do Prestador e a senha dele;
o código IBGE do município do Prestador (Natal/RN: 2408102).

export NOTASX=https://notasx-api.fly.dev
export CHAVE=nx_...   # sua Chave de API

Obtenha uma Chave de API

A primeira Chave é criada com a sessão do painel. Com uma Chave em mãos, você cria outras pela API:

curl -X POST $NOTASX/v1/chaves-api \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"nome": "erp-homologacao"}'

O valor da nova chave (chave) aparece só nesta resposta. Guarde-o num cofre de segredos.

Cadastre o Prestador

curl -X POST $NOTASX/v1/prestadores \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000195", "codigo_municipio": "2408102", "op_simp_nac": 3}'

Guarde o id. O Prestador começa em homologacao e com ativo: false. op_simp_nac: 1 não optante, 2 MEI, 3 ME/EPP do Simples Nacional.

Envie o Certificado A1

curl -X POST $NOTASX/v1/prestadores/$PRESTADOR/certificado \
  -H "Authorization: Bearer $CHAVE" \
  -F arquivo=@certificado.pfx -F senha='senha-do-pfx'

O CNPJ do Certificado tem de ser o do Prestador. Depois disso, o Prestador fica ativo: true.

Crie a Nota

curl -X POST $NOTASX/v1/notas \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-000123" \
  -d '{
    "prestador_id": "'$PRESTADOR'",
    "competencia": "2026-11-11",
    "dados": {"ctrib_nac": "010101", "descricao": "Desenvolvimento de software", "valor_servico": "1500.00"},
    "tomador": {"documento": "11222333000181", "nome": "Cliente Exemplo LTDA"}
  }'

A resposta é 202 com a Nota pendente. O Idempotency-Key protege contra duplicidade: se a chamada falhar no meio, repita com a mesma chave. Veja Idempotência.

Acompanhe o resultado

curl $NOTASX/v1/notas/$NOTA -H "Authorization: Bearer $CHAVE"

Consulte até o status sair de pendente/processando. Com emitida, a NFS-e existe:

{
  "status": "emitida",
  "chave_acesso": "24081022242404473000102000000000002426114744866240",
  "numero_nfse": "24"
}

O XML oficial fica em GET /v1/notas/{id}/xml, que devolve um link válido por 5 minutos.

Próximos passos

Entenda os resultados possíveis em Ciclo da Nota.
Quando estiver tudo certo, ative a produção do Prestador.
Trate os erros pelo codigo: veja Erros.

Começando

Conceitos

Guias

Início rápido

Próximos passos

​Próximos passos

Próximos passos