Quickstart — Emita sua primeira NFS-e em 5 minutos

Guia rápido para devs externos integrarem a API da notta. Ao final você vai ter emitido uma nota fiscal de serviço eletrônica válida via API.

Passo 1 — Criar token (~1 min)

Vá em /app/api/tokens, clique em Gerar novo token, selecione os scopes notas.write e notas.read, copie o token nta_live_... — ele aparece apenas uma vez e não pode ser recuperado depois.

Passo 2 — Configurar prestador (~1 min)

Antes de emitir, verifique que /app/configuracoes/nfse está com CNPJ prestador cadastrado e certificado A1 uploadado (Epic 2). Sem essa configuração, a API retorna invalid_input no primeiro POST.

Passo 3 — Emitir primeira nota (~2 min)

Faça um POST em /api/v1/notas/emitir com o body mínimo. Substitua nta_live_YOURTOKEN pelo token do Passo 1 e a3f8c2e1-4b6d-4c7f-9e0a-1b2c3d4e5f6a pelo id de um Cliente existente.

curl -X POST https://api.notta.app/api/v1/notas/emitir \
  -H "Authorization: Bearer nta_live_YOURTOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": "a3f8c2e1-4b6d-4c7f-9e0a-1b2c3d4e5f6a",
    "tomador_cnpj": "12345678000199",
    "descricao_servico": "Consultoria",
    "valor": 100.00
  }'

// Node.js 22+ (fetch nativo, sem dep)
const res = await fetch("https://api.notta.app/api/v1/notas/emitir", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nta_live_YOURTOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cliente_id: "a3f8c2e1-4b6d-4c7f-9e0a-1b2c3d4e5f6a",
    tomador_cnpj: "12345678000199",
    descricao_servico: "Consultoria",
    valor: 100.0,
  }),
});
const { data } = await res.json();
console.log(data.id, data.status);

import requests

res = requests.post(
    "https://api.notta.app/api/v1/notas/emitir",
    headers={"Authorization": "Bearer nta_live_YOURTOKEN"},
    json={
        "cliente_id": "a3f8c2e1-4b6d-4c7f-9e0a-1b2c3d4e5f6a",
        "tomador_cnpj": "12345678000199",
        "descricao_servico": "Consultoria",
        "valor": 100.00,
    },
)
data = res.json()["data"]
print(data["id"], data["status"])

A resposta é 201 Created com envelope { data: { id, status, ... } }. Se status for emitida, a nota já foi processada pela API Nacional; se for pendente, você pode ouvir o webhook nota.emitida (Story 5.7) ou fazer polling em GET /api/v1/notas/{id}.

Passo 4 — Consultar (~30s)

curl https://api.notta.app/api/v1/notas/{id} \
  -H "Authorization: Bearer nta_live_YOURTOKEN"
# → { "data": { "id": "...", "status": "emitida", "xmlUrl": "...", "pdfUrl": "..." } }

Passo 5 — Cancelar (opcional, ~30s)

Códigos de motivo aceitos: 1 (erro na emissão), 2 (serviço não prestado), 9 (outros).

curl -X POST https://api.notta.app/api/v1/notas/{id}/cancelar \
  -H "Authorization: Bearer nta_live_YOURTOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "motivo": "Erro na descrição do serviço", "codigoMotivo": "1" }'

Sandbox

Ambiente sandbox está disponível em https://sandbox.notta.app. Para receber um token de homologação, vá em /app/api/tokens e marque a opção Ambiente: sandbox.

Nota: provisioning automatizado de sandbox está previsto para o Epic 6. Enquanto isso, use um CNPJ prestador em ambiente homologação da API Nacional (`ambiente: "homologacao"` em /app/configuracoes/nfse).

Pronto! Você emitiu sua primeira NFS-e via API. Explore a referência completa abaixo para descobrir os demais endpoints (clientes, reemissão, webhooks).