Atendimento

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.

Nesta página