Manual da API

Integre o seu sistema ao NFácil

Com a API, o seu sistema (ERP, loja virtual, sistema de gestão) emite notas fiscais de serviço, gera boletos e Pix e acompanha tudo, sem ninguém precisar abrir o painel.

Início rápido

Em cinco minutos você faz a primeira chamada. Os exemplos usam curl, mas qualquer linguagem que faça requisições HTTPS funciona.

1. Crie a credencial. No NFácil, um administrador abre Conta → Integrações → Incluir credencial, escolhe as permissões e as empresas e confirma. A chave (começa com nfk_) aparece uma única vez: guarde-a no cofre de senhas do seu sistema.
2. Descubra o código da conta. Ele aparece no endereço do painel (/contas/acc_...) e também na tela da credencial.
3. Guarde a chave numa variável de ambiente do servidor que vai chamar a API (nunca no código): export NFACIL_API_KEY=.... Os exemplos deste manual usam essa variável.
4. Faça a primeira chamada. Liste as empresas que a credencial enxerga:

curl https://app.nfacil.com.br/api/v1/accounts/acc_EXEMPLO123/companies \
  -H "Authorization: Bearer $NFACIL_API_KEY"

A resposta traz cada empresa com o código co_..., que você usa nas próximas chamadas.

{
  "items": [
    { "id": "co_EXEMPLO456", "legalName": "EMPRESA EXEMPLO SERVIÇOS LTDA", "cnpj": "12345678000190", ... }
  ],
  "nextCursor": null
}

Credenciais e permissões

Toda chamada leva a chave no cabeçalho Authorization:

Authorization: Bearer $NFACIL_API_KEY

• Permissões (escopos). Na criação, você escolhe o que a credencial pode fazer. Uma credencial só de leitura não emite nem cobra.
• Empresas. A credencial pode ser limitada a algumas empresas (CNPJs) da conta. Fora delas, as chamadas respondem como se a empresa não existisse.
• Segurança. Use HTTPS sempre, guarde a chave num cofre de senhas e nunca a coloque no código-fonte, em aplicativos de celular ou no navegador do cliente.
• Troca e revogação. Em Integrações, gire a chave quando alguém que a conhecia sair da equipe, e revogue a credencial que não for mais usada.

Conceitos importantes

Endereço base

Todas as rotas começam com https://app.nfacil.com.br/api/v1 e ficam dentro da conta: /accounts/{accountId}/.... As rotas de uma empresa ficam em /accounts/{accountId}/companies/{companyId}/....

Valores e datas

• Dinheiro sempre como texto, com ponto decimal e até duas casas: "1500.00". Nunca envie número com vírgula flutuante.
• Datas no formato AAAA-MM-DD; data e hora no padrão ISO 8601 (2026-11-04T10:30:00-03:00).
• Competência da nota no formato AAAA-MM. Se não enviar, vale o mês corrente.

Emissão assíncrona

Pedir a emissão não espera a prefeitura: a API responde 202 Accepted com o pedido e a situação inicial. A nota segue sozinha até o fim. Acompanhe pela consulta do pedido:

Idempotência (evita nota em dobro)

Ao emitir uma nota, envie o cabeçalho Idempotency-Key com um UUID novo por pedido. Se a rede cair e você repetir a mesma chamada com a mesma chave, o NFácil devolve o mesmo pedido em vez de criar outro. A chave vale por 24 horas; a mesma chave com um corpo diferente responde 409.

Referência externa

Envie o código do pedido no seu sistema em externalReference (ex.: PED-2026-0001). Ele é único por empresa e permite recuperar a nota ou a cobrança depois, pela rota .../by-reference/{externalReference}, mesmo sem ter guardado o código do NFácil.

Listas e paginação

Listas devolvem items e nextCursor. Para a próxima página, repita a chamada com cursor={nextCursor}. Use limit para o tamanho da página. Quando nextCursor vier null, acabou.

Erros

Toda resposta de erro tem o mesmo formato:

{
  "code": "validation_error",
  "message": "Informe o valor do serviço.",
  "field": "values.amount",
  "requestId": "req_EXEMPLO789"
}

Empresas

As empresas (emitentes) são cadastradas pelo painel. Pela API, você consulta os dados e confere se a empresa está pronta para emitir.

Tomadores (clientes)

O tomador é quem recebe o serviço e a nota. Você pode cadastrá-lo antes ou mandar os dados direto no pedido de emissão.

curl -X POST https://app.nfacil.com.br/api/v1/accounts/acc_EXEMPLO123/companies/co_EXEMPLO456/recipients \
  -H "Authorization: Bearer $NFACIL_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "kind": "pj",
    "document": "98.765.432/0001-10",
    "name": "CLIENTE EXEMPLO COMÉRCIO LTDA",
    "email": "[email protected]",
    "cep": "77000000", "street": "Avenida Exemplo", "number": "100", "district": "Centro",
    "cityIbge": "1721000", "uf": "TO"
  }'

Serviços (catálogo)

O catálogo guarda a descrição, o código de tributação e a alíquota de cada serviço. Na emissão, basta informar o serviceItemId.

Notas fiscais (NFS-e)

Pedir a emissão

curl -X POST https://app.nfacil.com.br/api/v1/accounts/acc_EXEMPLO123/companies/co_EXEMPLO456/nfse \
  -H "Authorization: Bearer $NFACIL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "recipient": { "id": "rcp_EXEMPLO001" },
    "service": { "serviceItemId": "svc_EXEMPLO002" },
    "values": { "amount": "1500.00", "issWithheld": false },
    "competence": "2026-11",
    "externalReference": "PED-2026-0001"
  }'

Resposta 202: o pedido com "state": "queued". Consulte o pedido até chegar em authorized ou rejected.

Acompanhar até autorizar

Consulte a cada 5 a 10 segundos nos primeiros minutos e, depois, com intervalos maiores. Não há necessidade de consultar sem parar: a maioria das notas sai em poucos segundos, mas algumas prefeituras demoram mais.

Cobranças

A cobrança gera boleto com Pix ou só Pix na conta de recebimento configurada na empresa. O dinheiro cai direto na conta da empresa.

curl -X POST https://app.nfacil.com.br/api/v1/accounts/acc_EXEMPLO123/companies/co_EXEMPLO456/charges \
  -H "Authorization: Bearer $NFACIL_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "nfseId": "nfse_EXEMPLO003",
    "amount": "1500.00",
    "dueDate": "2026-11-20",
    "method": "boleto_pix",
    "externalReference": "FAT-2026-0001"
  }'

• Com nfseId, o tomador da nota vira o pagador e a cobrança fica ligada à nota. Para cobrança avulsa, informe recipientId.
• method: boleto_pix (boleto com Pix) ou pix (só Pix).
• Multa e juros: em branco, valem a preferência do tomador ou o padrão da empresa.
• O pagamento é confirmado pelo provedor e aparece na situação da cobrança (paid).

Agendamentos

Agende uma nota única numa data ou notas recorrentes (semanal, mensal, bimestral, trimestral ou anual). O NFácil emite sozinho nas datas.

Receitas completas

Vender um serviço e cobrar

1. Procure o cliente em GET .../recipients?q=documento; se não existir, cadastre com POST .../recipients.
2. Peça a nota com POST .../nfse, usando uma Idempotency-Key nova e a externalReference do seu pedido.
3. Consulte GET .../nfse/{nfseId} até authorized.
4. Crie a cobrança com POST .../charges informando o nfseId.
5. Envie ao cliente o link de pagamento da cobrança, ou deixe o NFácil mandar a nota e o boleto por e-mail (configurado no painel).

Mensalidade automática

1. Confira as datas com POST .../nfse-schedules/preview.
2. Crie o agendamento mensal com a cobrança junto, se quiser.
3. Acompanhe as notas emitidas pela consulta do agendamento ou pela lista de notas.

Boas práticas

• Teste tudo em homologação antes de emitir em produção.
• Use sempre Idempotency-Key nas emissões e guarde a sua externalReference.
• Nunca repita uma emissão que está em verification_required: espere a consulta resolver.
• Trate os erros pelo code, não pelo texto da message, que pode mudar.
• Respeite o 429: espere e tente de novo com intervalo crescente.
• Guarde a chave num cofre de senhas e use uma credencial por sistema, com só as permissões necessárias.
• Registre o requestId dos erros no seu sistema para facilitar o suporte.