Emissão de NFS-e

Emite uma NFS-e

Valida, cria e transmite a nota. Se a empresa ainda não pode emitir (sem certificado válido, sem regime tributário, conta sem plano de Emissão), devolve 412 empresa_nao_pronta com a mesma lista de GET /v1/companies/{id}/prontidao e não cria nada. Com payload inválido devolve 422 com todos os erros e não cria nada. Com payload válido, a nota entra na fila de emissão e a chamada acompanha o resultado pelo tempo pedido em Prefer: wait=N:

  • 201: autorizada dentro do prazo. Corpo: a nota.
  • 202: ainda transmitindo. Corpo: a nota; acompanhe por Location ou pelo webhook NFSE_AUTORIZADA.
  • 422 nfse_rejeitada: rejeitada pelo Sistema Nacional. O corpo traz nfse_id e a nota inteira.
  • 422 falha_transmissao: a transmissão terminou sem confirmação dentro da espera. O corpo traz nfse_id e a nota inteira; veja falha.dps_enviada antes de emitir de novo.

202 não é erro. A nota existe e está sendo cuidada: acompanhe por webhook ou por GET /v1/nfse/{id}. Repetir a chamada com a mesma Idempotency-Key devolve a MESMA resposta gravada (a foto do momento, que pode continuar transmitindo mesmo depois de a nota autorizar): para saber o status atual, use o GET.

Use sempre Idempotency-Key. Repetir a MESMA chave com o MESMO corpo devolve a mesma resposta, sem criar outra nota; a mesma chave com corpo diferente é 409 idempotencia_conflito.

post/v1/nfse

Request

  • Base URL: https://api.sudrel.com.br/api
  • URL: https://api.sudrel.com.br/api/v1/nfse
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Identificador único da SUA tentativa de emissão (ex.: um UUID gerado pelo seu sistema). Mesma chave e mesmo corpo: mesma resposta, sem nota nova, por 30 dias. Mesma chave e corpo diferente: 409 nas primeiras 24 horas; depois disso, a chave vale como nova.

Preferstring
Example:wait=15

wait=N: quantos segundos a chamada acompanha a nota antes de responder 202. Padrão 10, máximo 30; wait=0 responde na hora.

X-Sudrel-Simularstring

Simulador de falhas, só com a chave sdr_test_ (com a de produção é 422 simulacao_so_no_sandbox). Um cenário da seção Simulador de falhas, por exemplo timeout_depois_autorizada ou rejeicao:E0240. Cenário desconhecido é 422 simulacao_invalida.

Request body

empresa_idstring

Empresa emissora. Dispensado quando a chave de API é restrita a uma empresa.

referenciastring

Seu identificador para esta nota (pedido, contrato). Único por empresa; repetido é 409 com o id da nota existente.

modelostring

Nome ou id de um modelo de emissão salvo no painel. Preenche descrição, código de serviço e competência quando não enviados.

valorstring required

Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 tipo_invalido).

Example request

{
  "tomador": {
    "documento": "11222333000181",
    "endereco": {
      "cep": "40020000"
    }
  },
  "valor": "1500.00",
  "servico": {
    "codigo_nacional": "010701",
    "competencia": "2026-09",
    "nbs": "1.1302.21.00",
    "obra": {
      "endereco": {
        "cep": "40020000"
      }
    }
  },
  "retencoes": {
    "pis": {
      "valor": "1500.00",
      "aliquota": "2.5"
    },
    "cofins": {
      "valor": "1500.00",
      "aliquota": "2.5"
    },
    "csll": {
      "valor": "1500.00",
      "aliquota": "2.5"
    },
    "irrf": {
      "valor": "1500.00",
      "aliquota": "2.5"
    },
    "inss": {
      "valor": "1500.00",
      "aliquota": "2.5"
    }
  },
  "apuracao_propria": {
    "pis": {
      "valor": "1500.00",
      "aliquota": "2.5"
    },
    "cofins": {
      "valor": "1500.00",
      "aliquota": "2.5"
    }
  },
  "iss": {
    "aliquota": "2.5"
  }
}

Response

Autorizada.

idstring
referenciastring nullable
status'transmitindo' | 'autorizada' | 'rejeitada' | 'cancelada' | 'falha_transmissao' | 'descartada' | 'aguardando_confirmacao'
empresa_idstring
ambiente'producao' | 'sandbox'

sandbox = emitida com chave de teste, no ambiente de testes do Sistema Nacional, sem valor fiscal.

simulacaostring nullable

Cenário do simulador de falhas (X-Sudrel-Simular); null em nota de verdade. Nota simulada nunca foi à Sefin.

origem'api' | 'planilha' | 'manual' | 'monitoramento'
numerostring nullable
chave_acessostring nullable
valorstring

Texto decimal com ponto, sem separador de milhar. Número JSON é recusado (422 tipo_invalido).

tomadorobject
retencoesobject
apuracao_propriaobject
issobject
recuperada_emstring date-time nullable
regras_versaostring

Versões do catálogo de correções automáticas e do catálogo de regras de campo que decidiram esta nota, nessa ordem.

criada_emstring date-time
atualizada_emstring date-time

Example response

{
  "valor": "1500.00",
  "servico": {
    "competencia": "2026-10"
  },
  "rejeicao": {
    "explicacao": {
      "codigo": "inscricao_municipal_obrigatoria",
      "campo": "/prestador/inscricao_municipal"
    }
  },
  "confirmacao": {
    "competencia": "2026-09"
  },
  "ajustes": [
    {
      "campo": "/prestador/inscricao_municipal",
      "regra": "correcao.E0120"
    }
  ],
  "regras_versao": "2026-09-30.1+2026-10-02.1"
}

Changes

No recorded changes to this operation across all 1 revision of this API.