POST/v1/nfse

Criar uma NFS-e

Registra uma emissão e devolve imediatamente a nota em fila. Use uma referência estável, um serviço já cadastrado e acompanhe o resultado por consulta ou webhook.

Antes de chamar: crie ou liste o serviço e persista o service_id. A emissão não aceita um serviço fiscal avulso.

Request

Envie uma cobrança, não uma nota improvisada.

A chave vai no header. A referência identifica a cobrança no seu sistema; repetir a mesma referência com o mesmo payload é seguro.

Endereço sem código IBGE. Envie o CPF/CNPJ, nome e o endereço que sua aplicação já validou. A TOOB usa somente o CEP para resolver o município; não altera logradouro, número ou bairro. Se você enviar municipality_code, ele precisa corresponder ao CEP.

json

{
  "reference": "cobranca_2026_08_00042",
  "customer": {
    "document": "39053344705",
    "name": "Cliente de Teste",
    "address": {
      "zip_code": "01310100",
      "street": "Avenida Paulista",
      "number": "100",
      "district": "Bela Vista",
      "complement": "Sala 12"
    }
  },
  "service_id": "srv_SUBSTITUA_PELO_ID",
  "amount_cents": 150000,
  "sandbox_scenario": "authorized"
}

bash

curl https://api.notas.toob.com.br/v1/nfse \\\n  -H "Authorization: Bearer $TOOB_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d @emissao.json

Campo	Tipo	Obrigatório	Regra
reference	string	Sim	Identificador estável da cobrança. É a idempotência pública.
service_id	string	Sim	Um srv_... ativo, criado no painel ou pela API.
amount_cents	integer	Sim	Valor em centavos. Ex.: R$ 1.500,00 → 150000.
customer_id	string	Condicional	Caminho avançado: cliente cus_... com cadastro fiscal completo.
customer	object	Condicional	Happy path. Alternativa a customer_id; exige document, name e endereço.
customer.address.zip_code	string	Sim com customer	CEP usado pela TOOB para resolver o município/IBGE.
customer.address.street	string	Sim com customer	Logradouro validado pela sua aplicação; não é sobrescrito.
customer.address.number	string	Sim com customer	Número do endereço do tomador.
customer.address.district	string	Sim com customer	Bairro do endereço do tomador.
customer.municipality_code	string	Não	IBGE avançado. Se enviado, deve coincidir com o CEP.
customer.address.complement	string	Não	Complemento do endereço.
customer.address.street_type	string	Não	Tipo de logradouro, por exemplo Rua ou Avenida.
service.description	string	Não	Detalha esta nota sem mudar o serviço do catálogo.
sandbox_scenario	enum	Só teste	authorized, rejected ou slow.

Tomador

Emita direto ou reutilize um cliente.

Você não precisa criar um cliente antes da primeira NFS-e. No caminho mais simples, mande os dados completos no campo customer e a TOOB cria ou reutiliza o cadastro fiscal pelo documento. A emissão não sobrescreve um cadastro existente.

Use customer_id apenas quando sua aplicação administra o catálogo de clientes e mantém o cus_... com dados fiscais completos. Para alterar um cliente, use PATCH /v1/customers/{id}, nunca uma nova emissão.

Response · 202

A emissão é assíncrona.

Guarde id, reference e livemode. Depois consulte GET /v1/nfse/{id} até um estado terminal.

Se o e-mail estiver habilitado para a chave no painel, a TOOB o envia após a autorização. O 202 não representa uma nota autorizada nem uma entrega de e-mail.

json

{
  "id": "nfse_...",
  "status": "queued",
  "livemode": false,
  "idempotent": false,
  "reference": "cobranca_2026_08_00042",
  "customer_id": "cus_..."
}

queued

Aceita e aguardando processamento.

processing

Assinando ou transmitindo.

issued

Autorizada; documento fiscal disponível.

Erros

Corrija ou repita com confiança.

service_not_found
O serviço não pertence a esta organização ou não existe.

idempotency_conflict
A mesma reference foi usada com dados diferentes.

← Serviços e catálogo Eventos e webhooks