Caso de uso

"Como merchant, preciso que meu cliente consiga realizar a emissão de uma NFS-e por transação."

Diagrama de fluxo

Emissão de uma NFS-e por transação

Para realizar a emissão de uma NFS-e por transação, você pode utilizar o Endpoint de emissão de nota fiscal NFS-e por transação. Você também pode verificar os formatos de callbacks aqui.

🚧
Pré-requisitos para uso do serviço
Antes de enviar uma solicitação de emissão de NFS-e, verifique se:

A funcionalidade está habilitada e configurada. Saiba mais

Informações sobre o payload de envio

Atributo	Tipo	Descrição	Obrigatório	Tamanho
`IdTransaction`	int	Código identificador da transação. Ex: 12345	Sim	Tamanho: 10
`CompetencyDate`	string	Data de competência da NFS-e. Ex: 2025-03-20	Não	Tamanho: 10
`Service.IdService`	int	Codigo do serviço para emissão da NFS-e. Ex: 123	Sim	Tamanho min: 03 Tamanho max: 200
`Customer.Phone`	string	Telefone do comprador Ex: 5199999999	Não
`Customer.Email`	string	Email do comprador Ex: [email protected]	Não
`Customer.Adress.ZipCode`	string	CEP do endereço do comprador Ex: 90670090	Não	Tamanho: 08
`Customer.Adress.Street`	int	Logradouro do endereço do comprador Ex: Av. Princesa Isabel	Não	Tamanho min: 03 Tamanho max: 150
`Customer.Adress.Number`	string	Número do endereço do comprador Ex: 123	Não	Tamanho min: 01 Tamanho max: 15
`Customer.Adress.Complement`	string	Complemento do endereço do comprador Ex: Sala 801	Não	Tamanho min: 03 Tamanho max: 150
`Customer.Adress.District`	string	Bairro do endereço do comprador Ex: Higienopolis	Não	Tamanho min: 03 Tamanho max: 60
`Customer.Adress.CityName`	string	Cidade do endereço do comprador Ex: Porto Alegre	Não	Tamanho min: 01 Tamanho max: 15
`Customer.Adress.StateInitials`	string	UF do endereço do comprador Ex: RS	Não	Tamanho: 02
`Customer.Adress.CountryName`	string	Pais do endereço do comprador Ex: Brasil	Não	Tamanho min: 03 Tamanho max: 200

📘
Data de competência
Se não for passado o atributo CompetencyDate, que é a Data de Competência da NFS-e, será usada a data de solicitação de emissão como competência.

📘
Dados do cliente
Caso sejam informados os dados do Customer, as informações existentes na transação serão substituídas.

🚧
Atenção
O Endpoint de emissão de nota fiscal NFS-e por transação permite emitir a NFS-e independente do status da transação!

Exemplos de payloads de envio

{
    "Service": {
        "IdService": 1
    }
}

{
    "Service": {
        "IdService": 1
    },
    "CompetencyDate": "2025-03-25",
    "Customer": {
        "Phone": "51999999999",
        "Email": "[email protected]",
        "Address": {
            "ZipCode": "90670090",
            "Street": "Logradouro",
            "Number": "123",
            "Complement": "Complemento",
            "District": "Higienopolis",
            "CityName": "Porto Alegre",
            "StateInitials": "RS",
            "CountryName": "Brasil"
        }
    }
}

Exemplos de payloads de retorno síncrono

{
    "HasError": true,
    "ErrorCode": "1315",
    "Error": "O Id do serviço não foi informado ou é inválido."
}

//

{
  "HasError":true,
  "ErrorCode":"1326",
  "Error":"O corpo da requisição está vazio ou mal formatado."
}

//

{
  "HasError":true,
  "ErrorCode":"1317",
  "Error":"A data de competência, se informada, deve ser uma data válida."
}

//

{
  "HasError":true,
  "ErrorCode":"1319",
  "Error":"O CEP do endereço do cliente é obrigatório."
}

{
    "HasError": true,
    "ErrorCode": "1318",
    "Error": "O logradouro do endereço do cliente é obrigatório."
}

{
  "HasError":true,
  "ErrorCode":"1320",
  "Error":"O número do endereço do cliente é obrigatório."
}

{
  "HasError":true,
  "ErrorCode":"1321",
  "Error":"O bairro do endereço do cliente é obrigatório."
}

{
  "HasError":true,
  "ErrorCode":"1322",
  "Error":"A cidade do endereço do cliente é obrigatório."
}

{
  "HasError":true,
  "ErrorCode":"1323",
  "Error":"A UF do endereço do cliente é obrigatório."
}

{
  "HasError":true,
  "ErrorCode":"1324",
  "Error":"O país do endereço do cliente é obrigatório."
}

{
    "HasError": true,
    "ErrorCode": "1327",
    "Error": "A transação informada para emissão de NFS-e, não existe."
}

{
    "HasError": true,
    "ErrorCode": "403",
    "Error": "Não foi possível realizar a autenticação com os parâmetros informados."
}

Códigos de resposta síncrono

Código	Descrição
202 - Accepted	O pedido de emissão de NFS-e foi recebido com sucesso e será processado.
403 - Forbidden	O token enviado é inválido ou inexistente,
200 - OK	As informações enviadas estão inválidas.

Exemplos de payloads de retorno assíncrono (Callbacks)

Os eventos de callback serão enviados caso o status da NFS-e mude. Para mais informações clique aqui.

{
  "Identificador": "b646d331-ce89-469b-8dad-b9d613673080",
  "Status": 2,
  "UrlXmlAutorizacao": "",
  "UrlPdf": ".pdf",
  "NumeroNfse": "202500000000195",
  "NumeroRps": "250328182632755",
  "Mensagem": "Sucesso - NFSe Gerada",
  "Protocolo": "2880d2dace044697949eeecc76c4dd20",
  "DataEmissao": "2025-03-28T18:33:14-03:00"
}

{
  "Identificador": "17374d24-5884-4018-802d-882222543e96",
  "Status": 19,
  "Erro": "Já existe uma nota fiscal de serviço para chave idempotencia(0789A6189384021659430C31C320022A7568D39EBFB2DDD95FC1A48BBA8A1502) informada."
}

{
  "Identificador": "da71b033-56a8-4447-a6e9-105e273ba537",
  "Status": 4,
  "UrlXmlCancelamento": "https://stnotafiscalhml.blob.core.windows.net/nfse/3/da71b033-56a8-4447-a6e9-105e273ba537-Cancelamento.xml",
  "Protocolo": "4191299f3e3b46dfa777eaea0931c855"
}