Início rápido

Da Chave de API à primeira NFS-e em homologação, em cinco chamadas.

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

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

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

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

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

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