API de NFS-e

Notas Fiscais de Serviço Eletrônicas

6 endpoints · base https://api.comando.one/v1 · autenticação por chave cmd_live_…

GET/nfse

Listar NFS-e

nfse:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

`page`(query)	integer	Número da página (default: 1)
`per_page`(query)	integer	Itens por página (default: 20, máx: 100)
`status`(query)	"rascunho" \| "transmitindo" \| "autorizada" \| "rejeitada" \| "cancelada"
`invoice_id`(query)	string (uuid)	Filtrar por fatura

Resposta 200 — Listagem paginada

`id`	string (uuid)
`invoice_id`	string (uuid)
`invoice_number`	string \| null
`numero_nfse`	string \| null
`status`	"rascunho" \| "transmitindo" \| "autorizada" \| "rejeitada" \| "cancelada"
`protocolo`	string \| null
`chave_acesso`	string \| null
`danfse_url`	string \| null
`artifact_source`	string \| null
`cancelada_at`	string \| null (date-time)
`created_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/nfse" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/nfse

Emitir NFS-e

Emite uma NFS-e a partir de uma fatura. O método (certificado/portal) vem da configuração da empresa. Pode levar alguns segundos. **Discriminação do serviço (o texto que vai à prefeitura).** Por padrão é o número da fatura seguido, uma linha por item, do `description` de cada item — e, só se o `description` estiver vazio, o `name`. Ou seja: com os dois preenchidos, o `name` é exibição interna e NÃO chega ao documento fiscal. Para controlar o texto, mande `discriminacao` (até 2000 caracteres). Nota autorizada não se edita: errou o texto, é cancelar e reemitir — por isso confira antes. Um 409 de nota anterior só vale para nota `autorizada` ou `transmitindo`; fatura com nota **cancelada** pode ser emitida de novo. **Os itens da fatura NÃO precisam de `service_id`** — item avulso emite normalmente; a classificação fiscal (cTribNac, cNBS, alíquotas) vem da configuração fiscal da empresa e do CNAE padrão, não do item. Códigos: **201** = autorizada ou em transmissão — o `id` devolvido é o mesmo `{id}` de `/v1/nfse/{id}`, `/files`, `/sync` e `/cancel`. **422 com `status: 'rejeitada'`** = o fisco REJEITOU (motivo em `message`) — não existe nota, não afirme ao usuário que foi emitida. **422 sem `status`** = a EMPRESA não está configurada para emitir. **409** = esta fatura já tem nota (o `error` traz o id da existente). **424** = o provedor fiscal falhou; o motivo dele vem em `error`. Retentativa é segura: mande o header `Idempotency-Key` (a mesma resposta volta, com `Idempotent-Replayed: true`), e mesmo sem ele o 409 impede uma segunda nota para a mesma fatura.

nfse:emitir

Parâmetros, corpo, resposta e exemplo

Corpo (JSON)

`invoice_id`obrigatório	string (uuid)	Fatura a partir da qual emitir a NFS-e
`discriminacao`	string	Opcional. Texto integral da discriminação do serviço (xDescServ) — substitui o montado dos itens. Nota autorizada não se edita (só cancela e reemite), então é aqui que se acerta o texto. Inclua o número da fatura se quiser que ele apareça. Sem o campo: número da fatura + a descrição de cada item.

Resposta 201 — Emissão solicitada

`id`	string \| null	Id da NFS-e — use em /v1/nfse/{id}, /files, /sync e /cancel. Mesmo valor de history_id.
`invoice_id`	string
`status`	string	autorizada \| transmitindo \| rejeitada
`numero_nfse`	string \| null
`chave_acesso`	string \| null
`history_id`	string \| null	Alias de `id`, mantido por compatibilidade.
`message`	string \| null

Exemplo

curl -X POST "https://api.comando.one/v1/nfse" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"<string (uuid)>"}'

GET/nfse/{id}

Obter NFS-e

nfse:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — NFS-e com detalhes de cancelamento

`id`	string (uuid)
`invoice_id`	string (uuid)
`invoice_number`	string \| null
`numero_nfse`	string \| null
`status`	"rascunho" \| "transmitindo" \| "autorizada" \| "rejeitada" \| "cancelada"
`protocolo`	string \| null
`chave_acesso`	string \| null
`danfse_url`	string \| null
`artifact_source`	string \| null
`cancelada_at`	string \| null (date-time)
`created_at`	string (date-time)
`cancel_motivo`	integer \| null
`cancel_justificativa`	string \| null
`cancel_protocolo`	string \| null
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/nfse/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

PATCH/nfse/{id}/cancel

Cancelar NFS-e

nfse:cancelar

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`motivo`obrigatório	1 \| 2 \| 3 \| 4 \| 9	1=erro na emissão, 2=serviço não prestado, 3=duplicidade de emissão, 4=decisão judicial, 9=outros. Use o código pelo RÓTULO, não pela ordem.
`justificativa`obrigatório	string

Resposta 200 — Cancelamento solicitado

`id`	string
`status`	string
`cancel_protocolo`	string \| null

Exemplo

curl -X PATCH "https://api.comando.one/v1/nfse/{id}/cancel" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"motivo":"<1 | 2 | 3 | 4 | 9>","justificativa":"<string>"}'

GET/nfse/{id}/files

URLs assinadas do XML e DANFSE

Retorna URLs temporárias (30 min). `xml_signed_url` = XML autorizado. `danfse_signed_url` = DANFSe em PDF (gerada sob demanda a partir do XML se ainda não existir). `danfse_html_signed_url` = HTML OFICIAL publicado pelo ADN, quando disponível — é outro documento, não uma versão pior do PDF. `danfse_formato` diz o que veio em `danfse_signed_url` (pdf|html).

nfse:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — URLs assinadas

`id`	string
`invoice_id`	string
`status`	string
`xml_signed_url`	string \| null
`danfse_signed_url`	string \| null
`danfse_html_signed_url`	string \| null	HTML oficial publicado pelo ADN, quando existir. É outro documento, não uma versão pior do PDF — nulo aqui não se substitui por danfse_signed_url.
`danfse_formato`	"pdf" \| "html" \| null	O que veio em danfse_signed_url.
`signed_url_ttl_seconds`	integer

Exemplo

curl -X GET "https://api.comando.one/v1/nfse/{id}/files" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/nfse/{id}/sync

Sincronizar status da NFS-e com o provedor

nfse:read

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Resultado da sincronização

`id`	string
`invoice_id`	string
`processed`	integer
`updated`	integer
`attached`	integer

Exemplo

curl -X POST "https://api.comando.one/v1/nfse/{id}/sync" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Início rápido, autenticação, SDK, servidor MCP e o playground para testar sem escrever código estão na documentação completa. A especificação em OpenAPI está em api.comando.one/openapi.json.

Outros recursos da API

Clientes (16)Contratos (13)Faturas (12)Webhooks (12)Serviços (9)Split de Pagamentos (9)Catálogos (7)Propostas (6)

Ou deixe a IA usar a API por você

O servidor MCP expõe estes mesmos recursos ao ChatGPT, Claude ou Gemini — com OAuth, sem chave de API.

Conectar um assistente