Primeiros passos
Do token de acesso à primeira NFS-e em homologação.
Este guia leva você da credencial à primeira NFS-e, com curl. A nota sai em homologação, sem valor
fiscal. Os mesmos passos valem para NF-e e NFC-e e para qualquer linguagem com cliente HTTP.
Comece pelo Sandbox
Os exemplos usam o Sandbox (api-sandbox.u2dnotafiscal.com.br, realm u2d-nota-fiscal-sandbox). Em
produção, troque os dois e use as credenciais de produção. Veja Ambientes.
Receba suas credenciais
O time da U2D cria a sua conta, contrata os produtos (NFS-e, NF-e, NFC-e) e entrega, por canal seguro, um client id e um client secret para cada ambiente. Guarde o secret como senha: nunca no código-fonte, no front-end ou em e-mail. Ainda não tem credenciais? Fale com a gente pelo Atendimento.
Gere um access token
curl -s https://auth.u2dtecnologia.com.br/realms/u2d-nota-fiscal-sandbox/protocol/openid-connect/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials{
"access_token": "eyJhbGciOiJFUzI1NiIs...",
"expires_in": 300,
"token_type": "Bearer"
}O token vale 5 minutos e não tem refresh. Reaproveite-o enquanto valer e peça outro perto de expirar. Detalhes em Autenticação.
Confira a conta
curl -s https://api-sandbox.u2dnotafiscal.com.br/api/v1/conta \
-H "Authorization: Bearer $ACCESS_TOKEN"{ "id": "6f1c2a9e-3b7d-4c1e-9a2f-5d8e7b6c4a10", "nome": "Sua Empresa", "produtos": ["NFSE"], "ativo": true }produtos lista o que a conta pode emitir.
Cadastre o emitente
O emitente é o CNPJ (ou CPF) que emite as notas. O ambiente é obrigatório: use HOMOLOGACAO até validar a
integração.
curl -s https://api-sandbox.u2dnotafiscal.com.br/api/v1/emitentes \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"cnpjCpf": "11.222.333/0001-81",
"razaoSocial": "Empresa Exemplo Ltda",
"inscricaoMunicipal": "0123456700100",
"endereco": { "logradouro": "Rua Exemplo", "numero": "100", "bairro": "Centro",
"codigoMunicipio": "5300108", "uf": "DF", "cep": "70000-000" },
"ambiente": "HOMOLOGACAO",
"regimeTributario": "SIMPLES_NACIONAL"
}'A resposta é 201 com o id do emitente: guarde-o, ele vai no header X-Emitente-Id de toda rota de nota.
Envie o certificado A1 e configure a série
curl -s -X PUT https://api-sandbox.u2dnotafiscal.com.br/api/v1/emitentes/$EMITENTE_ID/certificado \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F arquivo=@certificado.pfx -F senha="$SENHA_DO_CERTIFICADO"
curl -s -X PUT https://api-sandbox.u2dnotafiscal.com.br/api/v1/emitentes/$EMITENTE_ID/series \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{ "tipo": "NFSE", "ambiente": "HOMOLOGACAO", "serie": "900", "proximoNumero": 1, "padrao": true }'O titular do certificado precisa ter a mesma raiz de CNPJ do emitente. Veja Emitentes.
Emita a NFS-e
Envie o emitente em X-Emitente-Id e um UUID novo em Idempotency-Key:
curl -s -i https://api-sandbox.u2dnotafiscal.com.br/api/v1/nfse \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Emitente-Id: $EMITENTE_ID" \
-H "Idempotency-Key: 3f1c2b9e-5a7d-4c1e-9b2f-8d6a0e4c7b21" \
-H "Content-Type: application/json" \
-d '{
"competencia": "2026-11-06",
"tomador": { "cnpjCpf": "52998224725", "nome": "Cliente Exemplo" },
"servico": { "codigoTributacaoNacional": "010101", "codigoTributacaoMunicipal": "001",
"descricao": "Análise e desenvolvimento de sistemas.", "codigoMunicipioPrestacao": "5300108" },
"valorServico": "1500.00",
"issqn": { "tributacao": "OPERACAO_TRIBUTAVEL", "retencao": "NAO_RETIDO" }
}'A resposta é 202 Accepted com o header Location e a nota em PENDENTE.
Acompanhe o status
curl -s https://api-sandbox.u2dnotafiscal.com.br/api/v1/nfse/$NFSE_ID \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "X-Emitente-Id: $EMITENTE_ID"Em poucos segundos o status vai a AUTORIZADA (com chaveAcesso e numeroNfse) ou a REJEITADA (com os
códigos da Sefin em erros). Em vez de consultar em loop, configure um webhook. Com a nota
autorizada, baixe o XML em GET /nfse/{id}/xml e o PDF em GET /nfse/{id}/danfse.