---
title: "Emitir NFe - Devolução via XML."
url: "https://devcenter.stone.com.br/apis/stone-tax/versions/206fd1c1-6382-4ada-8612-c67fdc65e050/paths/api-v1-Nfe-Xml-Devolucao-Emitir/post"
---

> Full API specification: https://devcenter.stone.com.br/apis/stone-tax/versions/206fd1c1-6382-4ada-8612-c67fdc65e050.md

# Emitir NFe - Devolução via XML.

`POST` `/api/v1/Nfe/Xml/Devolucao/Emitir`

Permite a emissão de uma <strong>Nota Fiscal Eletrônica (NFe) de devolução</strong> utilizando como base o arquivo XML da nota de origem. O recurso realiza a leitura do arquivo fornecido, correlaciona os itens para estorno e aplica as <strong>regras fiscais de devolução</strong> conforme o regime tributário do emissor e a natureza da operação. Este endpoint simplifica o processo de devolução ao extrair dados diretamente do XML original, exigindo apenas a relação de itens e quantidades a serem devolvidas. ⚠️ **ATENÇÃO**: O arquivo XML deve ser enviado em formato **Base64**. Certifique-se de que a nota de origem esteja autorizada na SEFAZ, pois chaves de acesso inexistentes ou canceladas impedirão a emissão. ⚙️ **REGRA DE NEGÓCIO**: Caso a devolução seja parcial, informe apenas os itens e quantidades correspondentes no objeto de itens. Para devolução total, a lista deve refletir exatamente o conteúdo da nota de origem. 🧪 **TESTE**: Em ambiente de homologação, as notas emitidas possuem **sem valor jurídico** e não afetam o estoque real ou limites fiscais junto à SEFAZ.

## Header parameters

- `danfe` (string, optional) - Escolha o formato do DANFE gerado na emissão da nota (Default: Nenhum).
- `tipoDanfeNfe` (string, optional) - Tipo de DANFE gerado (Opcional).
- `DocumentoEmissor` (string, required) - Documento do emissor.

## Request body

Content types: `multipart/form-data`

## Responses

- `200` - OK
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `422` - Unprocessable Content
- `500` - Internal Server Error

## OpenAPI definition

```yaml
openapi: 3.0.4
info:
  title: Stone Tax API
  version: 1.0.0
servers:
  - url: https://stone-tax-sdx.stone.com.br
    description: Ambiente de Desenvolvimento
  - url: https://stone-tax.stone.com.br
    description: Ambiente de Produção
paths:
  /api/v1/Nfe/Xml/Devolucao/Emitir:
    post:
      tags:
        - Nfe
      summary: Emitir NFe - Devolução via XML.
      description: >-
        Permite a emissão de uma <strong>Nota Fiscal Eletrônica (NFe) de
        devolução</strong> utilizando como base o arquivo XML da nota de origem.


        O recurso realiza a leitura do arquivo fornecido, correlaciona os itens
        para estorno e aplica as <strong>regras fiscais de devolução</strong> 

        conforme o regime tributário do emissor e a natureza da operação.


        Este endpoint simplifica o processo de devolução ao extrair dados
        diretamente do XML original, exigindo apenas a relação de itens e
        quantidades a serem devolvidas.


        ⚠️ **ATENÇÃO**: O arquivo XML deve ser enviado em formato **Base64**.
        Certifique-se de que a nota de origem esteja autorizada na SEFAZ, pois
        chaves de acesso inexistentes ou canceladas impedirão a emissão.


        ⚙️ **REGRA DE NEGÓCIO**: Caso a devolução seja parcial, informe apenas
        os itens e quantidades correspondentes no objeto de itens. Para
        devolução total, a lista deve refletir exatamente o conteúdo da nota de
        origem.


        🧪 **TESTE**: Em ambiente de homologação, as notas emitidas possuem
        **sem valor jurídico** e não afetam o estoque real ou limites fiscais
        junto à SEFAZ.
      parameters:
        - name: danfe
          in: header
          description: "Escolha o formato do DANFE gerado na emissão da nota (Default:
            Nenhum)."
          schema:
            $ref: "#/components/schemas/DanfeEmissaoNotasModelEnum"
        - name: tipoDanfeNfe
          in: header
          description: Tipo de DANFE gerado (Opcional).
          schema:
            $ref: "#/components/schemas/TipoDanfeNfeModelEnum"
        - name: DocumentoEmissor
          in: header
          description: Documento do emissor.
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - ArquivoXml
                - CodigoErp
              type: object
              properties:
                CodigoErp:
                  minLength: 1
                  type: string
                  description: Identificador da operação fiscal no ERP.
                Serie:
                  type: string
                  description: Série do documento fiscal (Informar somente se estiver configurado
                    para geração numérica manual).
                NumeroDocumento:
                  type: integer
                  description: Numero do documento fiscal (Informar somente se estiver configurado
                    para geração numérica manual).
                  format: int64
                ModeloDocumentoFiscalDevolvido:
                  $ref: "#/components/schemas/ModeloNotaFiscalModelEnum"
                ArquivoXml:
                  type: string
                  description: Arquivo XML da nota fiscal.
                  format: binary
                TipoEmissao:
                  $ref: "#/components/schemas/TipoEmissaoNfeModelEnum"
                Destinatario.TipoDocumento:
                  $ref: "#/components/schemas/TipoDocumentoNotaFiscalModelEnum"
                Destinatario.Documento:
                  type: string
                  description: Documento do destinatário.
                Destinatario.Nome:
                  type: string
                  description: Nome do destinatário.
                Destinatario.Endereco.Logradouro:
                  type: string
                  description: Logradouro.
                Destinatario.Endereco.Numero:
                  type: string
                  description: Número.
                Destinatario.Endereco.Complemento:
                  type: string
                  description: Complemento.
                Destinatario.Endereco.Bairro:
                  type: string
                  description: Bairro.
                Destinatario.Endereco.CodigoMunicipio:
                  type: string
                  description: Código do município.
                Destinatario.Endereco.NomeMunicipio:
                  type: string
                  description: Nome do município.
                Destinatario.Endereco.Uf:
                  $ref: "#/components/schemas/UfExtNotaFiscalModelEnum"
                Destinatario.Endereco.Cep:
                  type: string
                  description: CEP.
                Destinatario.Endereco.CodigoPais:
                  type: string
                  description: Código do país.
                Destinatario.Endereco.Pais:
                  type: string
                  description: Nome do país.
                Destinatario.Telefone:
                  type: string
                  description: Telefone do destinatário.
                Destinatario.InscricaoEstadual:
                  type: string
                  description: Inscrição estadual do destinatário.
                Destinatario.InscricaoSuframa:
                  type: string
                  description: Inscrição SUFRAMA.
                Destinatario.InscricaoMunicipal:
                  type: string
                  description: Inscrição municipal.
                Destinatario.Email:
                  type: string
                  description: Email do destinatário.
                AutXml:
                  type: array
                  items:
                    $ref: "#/components/schemas/NfeAuxXmlInputModel"
                  description: Documentos autorizados a visualizar a NFe.
                ItensDevolvidos:
                  type: array
                  items:
                    $ref: "#/components/schemas/EmitirNfeDevolucaoDetalheItemInputModel"
                  description: Lista de itens devolvidos (Informar nulo para devolução completa da
                    nota).
            encoding:
              CodigoErp:
                style: form
              Serie:
                style: form
              NumeroDocumento:
                style: form
              ModeloDocumentoFiscalDevolvido:
                style: form
              ArquivoXml:
                style: form
              TipoEmissao:
                style: form
              Destinatario.TipoDocumento:
                style: form
              Destinatario.Documento:
                style: form
              Destinatario.Nome:
                style: form
              Destinatario.Endereco.Logradouro:
                style: form
              Destinatario.Endereco.Numero:
                style: form
              Destinatario.Endereco.Complemento:
                style: form
              Destinatario.Endereco.Bairro:
                style: form
              Destinatario.Endereco.CodigoMunicipio:
                style: form
              Destinatario.Endereco.NomeMunicipio:
                style: form
              Destinatario.Endereco.Uf:
                style: form
              Destinatario.Endereco.Cep:
                style: form
              Destinatario.Endereco.CodigoPais:
                style: form
              Destinatario.Endereco.Pais:
                style: form
              Destinatario.Telefone:
                style: form
              Destinatario.InscricaoEstadual:
                style: form
              Destinatario.InscricaoSuframa:
                style: form
              Destinatario.InscricaoMunicipal:
                style: form
              Destinatario.Email:
                style: form
              AutXml:
                style: form
              ItensDevolvidos:
                style: form
      responses:
        "200":
          description: OK
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/EmissaoNotaFiscalViewModel"
            application/json:
              schema:
                $ref: "#/components/schemas/EmissaoNotaFiscalViewModel"
            text/json:
              schema:
                $ref: "#/components/schemas/EmissaoNotaFiscalViewModel"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseErrorResult"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseErrorResult"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseErrorResult"
        "422":
          description: Unprocessable Content
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/EmissaoNotaFiscalViewModel"
            application/json:
              schema:
                $ref: "#/components/schemas/EmissaoNotaFiscalViewModel"
            text/json:
              schema:
                $ref: "#/components/schemas/EmissaoNotaFiscalViewModel"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseErrorResult"
      security:
        - BearerAuth: []
security:
  - BearerAuth: []
components:
  schemas:
    DanfeEmissaoNotasModelEnum:
      enum:
        - Html
        - Pdf
        - Nenhum
      type: string
      description: Tipo de arquivo DANFE gerado na emissão.
    TipoDanfeNfeModelEnum:
      enum:
        - Retrato
        - Simplificado
      type: string
      description: Tipo de danfe para NFe.
    ModeloNotaFiscalModelEnum:
      enum:
        - Nfe
        - Nfce
      type: string
      description: Modelo de nota fiscal.
    TipoEmissaoNfeModelEnum:
      enum:
        - Automatica
        - Normal
        - ContingenciaFsda
        - ContingenciaSvcan
        - ContingenciaSvcrs
      type: string
      description: Tipo de emissão de NFe.
    TipoDocumentoNotaFiscalModelEnum:
      enum:
        - Cpf
        - Cnpj
        - IdEstrangeiro
      type: string
      description: Tipo de documento.
    UfExtNotaFiscalModelEnum:
      enum:
        - RO
        - AC
        - AM
        - RR
        - PA
        - AP
        - TO
        - MA
        - PI
        - CE
        - RN
        - PB
        - PE
        - AL
        - SE
        - BA
        - MG
        - ES
        - RJ
        - SP
        - PR
        - SC
        - RS
        - MS
        - MT
        - GO
        - DF
        - EX
      type: string
      description: Lista de Unidades Federativas para Nota Fiscal incluíndo exterior.
    NfeAuxXmlInputModel:
      required:
        - documento
      type: object
      properties:
        tipoDocumento:
          $ref: "#/components/schemas/TipoDocumentoNotaFiscalModelEnum"
        documento:
          minLength: 1
          type: string
          description: Documento autorizado.
      additionalProperties: false
      description: Documentos autorizados a capturar e visualizar a NFe.
    EmitirNfeDevolucaoDetalheItemInputModel:
      required:
        - item
        - quantidadeDevolvida
      type: object
      properties:
        item:
          minimum: 0
          exclusiveMinimum: true
          type: integer
          description: Número da sequência do item na nota.
          format: int32
        quantidadeDevolvida:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: Quantidade de itens a serem devolvidos.
          format: double
        rastros:
          type: array
          items:
            $ref: "#/components/schemas/EmitirNfeDevolucaoDetalheItemRastroInputModel"
          description: Informações de rastro do item.
          nullable: true
      additionalProperties: false
      description: Dados de devolução do item da nota.
    EmissaoNotaFiscalViewModel:
      type: object
      properties:
        sucesso:
          type: boolean
          description: Indica se a nota foi autorizada pela sefaz ou não.
        codigoStatus:
          type: integer
          description: Código de status de envio para a sefaz.
          format: int32
        mensagemSefaz:
          type: string
          description: Mensagem de retorno da sefaz.
          nullable: true
        serie:
          type: string
          description: Série da nota fiscal.
          nullable: true
        numeroDocumento:
          type: integer
          description: Número do documento.
          format: int64
        chaveAcesso:
          type: string
          description: Chave de acesso da nota fiscal.
          nullable: true
        numeroProtocolo:
          type: string
          description: Número do protocolo de autorização da nota fiscal.
          nullable: true
        linkQrcode:
          type: string
          description: Link de acesso a nota fiscal (Apenas para NFC-e).
          nullable: true
        danfe:
          type: string
          description: Arquivo DANFE solicitado (HTML ou PDF Base64).
          nullable: true
        emitidaEmContingencia:
          type: boolean
          description: Indica se a nota foi emitida em modo contingência.
      additionalProperties: false
      description: Dados de retorno da emissão de nota fiscal.
    ResponseErrorResult:
      type: object
      properties:
        status:
          type: integer
          format: int32
        titulo:
          type: string
          nullable: true
        erros:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          nullable: true
      additionalProperties: false
    EmitirNfeDevolucaoDetalheItemRastroInputModel:
      required:
        - dataFabricacao
        - dataValidade
        - numeroLote
      type: object
      properties:
        numeroLote:
          maxLength: 20
          minLength: 1
          type: string
          description: Número do lote do produto.
        quantidadeLote:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: Quantidade do lote.
          format: double
        dataFabricacao:
          minLength: 1
          type: string
          description: Data de fabricação do lote.
          format: date-time
        dataValidade:
          minLength: 1
          type: string
          description: Data de validade do lote.
          format: date-time
      additionalProperties: false
      description: Dados de rastreabilidade do item da NFe .
  securitySchemes:
    BearerAuth:
      type: http
      description: Autenticação via token JWT. Obtenha o token através do endpoint
        /Autenticacao/ObterToken usando Basic Auth. O token expira em 1 hora.
      scheme: bearer
      bearerFormat: JWT
```