Emissão de NFS-e com Cliente Domiciliado no Exterior
Como emitir uma Nota Fiscal de Serviço Eletrônica (NFS-e) quando o tomador do serviço está domiciliado fora do Brasil. Caso não encontre uma resposta para sua dúvida, fique à vontade para entrar em contato.
Informar o endereço do tomador no exterior não é suficiente na maioria das prefeituras. O que mais falta nas integrações são dois grupos:
- Prefeitura de São Paulo → grupo
location+ campotaxationType. - Prefeituras no Ambiente Nacional → grupo
foreignTrade.
Se você não sabe em qual caso a sua prefeitura está, veja como saber qual é o meu caso.
Sumário
- Como a plataforma identifica um cliente no exterior
- Campos do tomador
- Cenário 1: Prefeitura de São Paulo
- Cenário 2: Prefeituras no Ambiente Nacional
- Como o local da prestação é resolvido
- Emissão via planilha
- Perguntas frequentes
Como a plataforma identifica um cliente no exterior
O campo borrower.address.country é a referência. Os valores seguem o padrão ISO 3166-1 alfa-3 — 3 letras.
BRA(ou campo ausente) → cliente nacional.- Qualquer outro valor (
USA,ARG,DEU…) → cliente no exterior, e a plataforma relaxa automaticamente os campos de endereço que não se aplicam.
Isso resolve a identificação do tomador. O que a identificação não resolve é a declaração fiscal da operação — que é justamente o objeto dos dois cenários abaixo.
Campos do tomador
Para um tomador no exterior, os obrigatórios são reduzidos em relação a uma emissão nacional:
| Campo | Descrição | Obrigatório |
|---|---|---|
borrower.type | Tipo do tomador (Undefined, NaturalPerson, LegalEntity) | Sim |
borrower.name | Nome ou Razão Social do tomador | Sim |
borrower.federalTaxNumber | CPF ou CNPJ (informe 0 quando não aplicável) | Não |
borrower.email | Email do tomador | Não |
borrower.address.country | Sigla do país, ISO 3166-1 alfa-3 (ex.: USA, ARG) | Sim |
borrower.address.postalCode | Código postal no exterior | Não |
borrower.address.street | Logradouro | Sim |
borrower.address.number | Número do endereço | Sim |
borrower.address.district | Bairro | Sim |
borrower.address.city.name | Nome da cidade | Sim |
borrower.address.city.code | Código IBGE — não se aplica ao exterior | Não |
borrower.address.state | Estado, província ou região (até 60 caracteres) | Não |
cityServiceCode | Código do serviço no município | Sim |
description | Descrição do serviço prestado | Sim |
servicesAmount | Valor total do serviço | Sim |
E os campos que declaram a operação como destinada ao exterior:
| Campo | Descrição | Quando é necessário |
|---|---|---|
taxationType | Tipo de tributação. Para exportação de serviço, Export | São Paulo — e recomendado em qualquer prefeitura, por ser o que classifica a operação como exportação |
location | Local da prestação do serviço. Para exterior, basta location.country (ISO 3166-1 alfa-3): com país estrangeiro, city.code, city.name e state são opcionais (ver o cenário 1) | |
foreignTrade | Grupo de comércio exterior (modo de prestação, vínculo, moeda, valor na moeda, mecanismos de apoio) | Ambiente Nacional (ver o cenário 2) |
federalTaxNumber, postalCode, city.code e state são opcionais. O federalTaxNumber pode ser 0 quando o cliente não possui documento brasileiro. O city.code (IBGE) não deve ser informado — não existe código IBGE para cidade estrangeira.
Cenário 1: Prefeitura de São Paulo
Em São Paulo, além do endereço do tomador, a nota precisa declarar que o serviço foi prestado no exterior. Isso é feito com o grupo location (informando location.country) e o campo taxationType.
JSON completo
{
"borrower": {
"type": "LegalEntity",
"name": "GLOBAL TECH CONSULTING INC",
"federalTaxNumber": 0,
"email": "contato@globaltech.example",
"address": {
"country": "USA",
"postalCode": "10001",
"street": "5th Avenue",
"number": "100",
"district": "Manhattan",
"city": {
"name": "New York"
},
"state": "NY"
}
},
"cityServiceCode": "0101",
"description": "Serviço de consultoria em tecnologia prestado a tomador no exterior.",
"servicesAmount": 1000.0,
"taxationType": "Export",
"location": {
"country": "USA"
}
}
O que cada campo faz aqui
| Campo | Efeito |
|---|---|
taxationType: "Export" | Classifica a operação como exportação de serviço. É o que produz a tributação "P" (exportação) no RPS do layout anterior de São Paulo |
location.country: "USA" | Declara o local da prestação no exterior. No layout atual (IBS/CBS) é o que faz a nota sair com o país da prestação em vez do município do prestador |
location.city e location.state | Opcionais quando country é estrangeiro. Não precisa informá-los — o município não é repassado à prefeitura nessa situação |
Até então o grupo location exigia city.code, city.name e state mesmo com país estrangeiro, e esta página orientava preencher com o município do prestador só para passar na validação. Isso produzia um payload que se contradiz — country: "USA" junto de São Paulo/SP — para campos que a serialização descartava: o XML enviado à prefeitura levava apenas o país da prestação.
Agora, com country diferente de BRA, os três campos são opcionais, no mesmo critério que o borrower.address já seguia.
Payloads antigos continuam válidos. Se a sua integração já envia o município do prestador, ela segue funcionando e gera exatamente o mesmo XML — não há nada a corrigir com pressa. O que for enviado continua sendo validado: um city.code que não seja um IBGE de 7 dígitos, ou um state fora do padrão de 2 letras, continua retornando 400.
Não são alternativas. location.country é lido pelo layout atual (IBS/CBS) para montar o país da prestação; o layout anterior não lê esse campo e declara a exportação pelo taxationType. Enviar os dois é o que funciona nos dois layouts, e é por isso que a recomendação é enviar o par.
O location aceita os mesmos campos de um endereço (street, number, district, city, postalCode, state, country).
location exige cidade e UF mesmo para o exteriorA validação do grupo não olha o país. Enviar apenas location.country retorna 400 Bad Request com quatro erros:
location.city can not be null
location.city.code must be a valid IBGE city code
location.city.name can not be null or empty
location.state must be a valid ISO 3166-2 code, samples (SP, RJ, AC)
Então informe city.code (7 dígitos, IBGE), city.name e state junto com o country. Quando country é estrangeiro, a prefeitura usa apenas o país e esses três campos não afetam o resultado — a convenção é repetir o município do prestador, como no exemplo acima.
Vale notar o contraste: o endereço do tomador no exterior é liberado (não exige cidade nem CEP). A exigência acima é específica do grupo location.
Se a nota é de exportação de serviço e não declara local de prestação no exterior, ela sai com o município do prestador e a Prefeitura de São Paulo recusa com:
[657] A indicação de local de prestação no exterior deverá ser informada quando a classificação tributária for de exportação de serviços.
É uma regra de negócio da prefeitura, não de schema — o XML é aceito na validação e recusado depois, então o erro chega no retorno da emissão. Informar location.country resolve.
location.country segue o mesmo padrão do endereço do tomador: ISO 3166-1 alfa-3 (USA, ARG, DEU). A plataforma converte para o código de 2 letras que a prefeitura espera.
Uma sigla que não esteja na tabela de países não gera erro: a nota sai declarando BR como país da prestação. Confira a sigla na tabela ISO 3166-1 alfa-3 antes de integrar.
Cenário 2: Prefeituras no Ambiente Nacional
Prefeituras que aderiram ao Ambiente Nacional (padrão nacional da NFS-e) esperam o grupo foreignTrade nas emissões destinadas ao exterior. Ele corresponde ao grupo comExt do DPS e carrega os dados da operação de comércio exterior: modo de prestação, vínculo entre as partes, moeda, valor na moeda e mecanismos de apoio.
JSON completo
{
"borrower": {
"type": "LegalEntity",
"name": "GLOBAL TECH CONSULTING INC",
"federalTaxNumber": 0,
"email": "contato@globaltech.example",
"address": {
"country": "USA",
"postalCode": "10001",
"street": "5th Avenue",
"number": "100",
"district": "Manhattan",
"city": {
"name": "New York"
},
"state": "NY"
}
},
"cityServiceCode": "4444",
"description": "Serviço de consultoria em tecnologia prestado a tomador no exterior.",
"servicesAmount": 1000.0,
"taxationType": "Export",
"location": {
"country": "USA",
"city": {
"code": "3550308",
"name": "São Paulo"
},
"state": "SP"
},
"foreignTrade": {
"serviceMode": "CrossBorder",
"relationShip": "NoLink",
"currency": "USD",
"serviceAmountInCurrency": 200.0,
"supportMechanismProvider": "None",
"supportMechanismReceiver": "None",
"temporaryGoods": "No",
"mdicDelivery": false
}
}
Campos obrigatórios quando foreignTrade é enviado
O grupo é opcional. Mas ao enviá-lo, estes campos passam a ser obrigatórios — omitir qualquer um deles retorna 400 Bad Request apontando o campo:
| Campo | Descrição |
|---|---|
serviceMode | Modo de prestação. CrossBorder, ConsumptionInBrazil, TemporaryPersonnel ou ConsumptionAbroad |
relationShip | Vínculo entre as partes. NoLink, Controlled, Controller, Affiliate, HeadOffice, Branch ou OtherLink |
currency | Moeda da transação (ISO 4217 — ver a observação abaixo) |
serviceAmountInCurrency | Valor do serviço na moeda informada. Não pode ser negativo |
supportMechanismProvider | Mecanismo de apoio/fomento do prestador. None quando não houver |
supportMechanismReceiver | Mecanismo de apoio/fomento do tomador. None quando não houver |
temporaryGoods | Vínculo à movimentação temporária de bens. Unknown, No, LinkedImportDeclaration ou LinkedExportDeclaration |
mdicDelivery | Entrega MDIC. true ou false — não aceita nulo |
Opcionais: importDeclaration (número da DI — no layout nacional é truncado em 12 caracteres na emissão) e exportRegistration (registro de exportação).
serviceMode: confirme antes de usar "movimento temporário de pessoas físicas" ou "presença comercial no exterior"Os valores CrossBorder (transfronteiriço) e ConsumptionInBrazil (consumo no Brasil) correspondem ao layout nacional sem ambiguidade.
Para os dois modos restantes, o nome do valor na API e o código que o layout nacional espera estão em conferência — se a sua operação é um desses dois casos, fale com o suporte antes de integrar, para não declarar um modo de prestação diferente do real.
A lista completa de códigos e descrições de cada enumeração está na Tabela de Referência — Comércio Exterior (foreignTrade).
currency: use a sigla de 3 letras — ou o código numéricoA conversão de sigla para o código numérico que o padrão nacional exige cobre BRL, USD, EUR, GBP, JPY, CNY e ARS.
Uma sigla fora dessa lista (CHF, CAD, AUD, MXN…) não é reconhecida e a nota sai declarando Real (986) — sem erro, sem aviso. Para essas moedas, informe diretamente o código numérico ISO 4217 de 3 dígitos, que é repassado como está:
"currency": "756"
(756 = franco suíço.) Códigos numéricos válidos: ISO 4217.
temporaryGoods não aceita "None"O valor para "não há movimentação temporária de bens" é "No". Não existe "None" nesta enumeração — diferente de supportMechanismProvider e supportMechanismReceiver, onde "None" é o valor correto para "nenhum mecanismo".
Como o local da prestação é resolvido
Quando você não informa location, a plataforma deduz o local da prestação. A ordem é:
location— quando informado, vence tudo.activityEvent.address— quando a nota é de evento e o evento traz endereço.taxationType: "OutsideCity"— usa o endereço do tomador: município dele se for nacional, país dele se for estrangeiro.- Fallback — município do prestador.
Ou seja, uma nota para o exterior sem location e sem taxationType: "OutsideCity" cai no passo 4 e declara o município do prestador como local da prestação — o que gera a recusa [657] em São Paulo.
São Paulo tem uma rede de segurança: se a nota traz classificação tributária de exportação de serviço no grupo IBS/CBS (ibsCbs.classCode = 410004) e o tomador é estrangeiro, a prefeitura recebe o país da prestação mesmo sem location — e não há [657]. É uma proteção contra a recusa, não um substituto: ela depende de a nota trazer aquela classificação específica, e não cobre o layout anterior.
Informar location.country é o caminho explícito e recomendado, em qualquer prefeitura: não depende de dedução, de classificação tributária nem de layout.
Emissão via planilha
Também é possível emitir com cliente no exterior pela planilha de importação. O campo que determina o cenário é o endereco_pais.
| Coluna da Planilha | API | Descrição | Obrigatório |
|---|---|---|---|
cpf_cnpj | borrower.federalTaxNumber | CPF ou CNPJ (informe 0 para exterior) | Não |
nome | borrower.name | Nome ou Razão Social do tomador | Sim |
email | borrower.email | Email do tomador | Não |
endereco_pais | borrower.address.country | Sigla do país ISO 3166-1 alfa-3 (ex.: USA, ARG, DEU) | Sim |
endereco_cep | borrower.address.postalCode | Código postal no exterior | Não |
endereco_logradouro | borrower.address.street | Logradouro | Sim |
endereco_numero | borrower.address.number | Número do endereço | Sim |
endereco_bairro | borrower.address.district | Bairro | Sim |
endereco_cidade_nome | borrower.address.city.name | Nome da cidade | Sim |
endereco_cidade_codigo | borrower.address.city.code | Código IBGE — não preencher para exterior | Não |
endereco_estado | borrower.address.state | Estado, província ou região | Não |
codigo_servico | cityServiceCode | Código do serviço no município | Sim |
descricao | description | Descrição do serviço prestado | Sim |
valor | servicesAmount | Valor total do serviço | Sim |
Exemplo de preenchimento
| cpf_cnpj | nome | endereco_pais | endereco_cep | endereco_logradouro | endereco_numero | endereco_bairro | endereco_cidade_nome | endereco_estado | codigo_servico | descricao | valor | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Global Tech Consulting Inc | contato@globaltech.example | USA | 10001 | 5th Avenue | 100 | Manhattan | New York | NY | 0101 | Serviço de consultoria em tecnologia | 1000.00 |
location, taxationType nem foreignTradeAs colunas da planilha cobrem o endereço do tomador, não a declaração fiscal da operação. Se a sua prefeitura exige location/taxationType (São Paulo) ou foreignTrade (Ambiente Nacional), a emissão para o exterior precisa ser feita pela API — ou fale com o suporte para avaliar o seu caso.
Perguntas frequentes (FAQ)
Como sei em qual cenário a minha prefeitura está?
Consulte a página de prefeituras integradas e procure a coluna Amb. Nacional do município: Sim indica que a prefeitura está no Ambiente Nacional. Na dúvida, o caminho seguro é enviar taxationType e location (que São Paulo exige e as demais aceitam) e acrescentar foreignTrade se o município já estiver no Ambiente Nacional. Se preferir confirmar antes, fale com o suporte.
Preciso informar o CPF/CNPJ do cliente no exterior?
Não. O campo federalTaxNumber (ou cpf_cnpj na planilha) é opcional para clientes no exterior. Informe 0 quando o cliente não possuir documento brasileiro.
Posso enviar foreignTrade para uma prefeitura que não está no Ambiente Nacional?
Sim — o grupo é aceito no cadastro da nota e ignorado por layouts que não o utilizam. Mas atenção: uma vez enviado, os campos obrigatórios do grupo passam a valer, e um deles ausente retorna 400 mesmo que a prefeitura não fosse usar o grupo.
Qual código ISO 3166-1 usar para o país do cliente?
Os códigos seguem o padrão ISO 3166-1 alfa-3. Exemplos comuns:
| País | Código |
|---|---|
| Estados Unidos | USA |
| Argentina | ARG |
| Alemanha | DEU |
| Reino Unido | GBR |
| Japão | JPN |
| Portugal | PRT |
| Canadá | CAN |
Posso usar cálculo automático de impostos para clientes no exterior?
Sim. O cálculo automático funciona normalmente — a plataforma identifica os detalhes tributários a partir do código de serviço. O taxationType continua sendo seu, porque é a classificação da operação, não o cálculo.
O que acontece com o ISS em serviços prestados ao exterior?
A tributação varia conforme o enquadramento. Consulte seu contador para confirmar se o serviço se enquadra como exportação de serviço — e, nesse caso, envie taxationType: "Export", que é o que declara a operação como tal.
Como cadastrar, atualizar ou customizar um imposto?
Para cadastro, atualização ou customização de imposto da sua empresa, entre em contato com o suporte. A configuração é feita pela equipe na plataforma.
Dúvidas adicionais
Caso tenha dúvidas específicas sobre a emissão para cliente no exterior, entre em contato com o suporte ou consulte seu contador para orientação sobre o enquadramento da sua empresa.
Relacionados:
- Comércio exterior em Tipos de atividade — o grupo
foreignTradeentre os demais grupos por tipo de serviço - ISS e local de prestação — o grupo
locationnos cenários nacionais - Tabela de Referência — Comércio Exterior (
foreignTrade) - Referência completa de campos
- Cálculo Automático de Impostos · Cálculo Manual de Impostos
- Dúvidas na Integração da NFS-e