Publicado no DOU em 23 out 2018
Revoga o Ato declaratório Executivo Coana nº 4, de 19 de março de 2018 , e estabelece o novo modelo de dados contendo as informações, especificações e requisitos técnicos necessários à integração dos sistemas próprios das lojas francas com os serviços da Receita Federal do Brasil para as Lojas Francas de Fronteira.
O COORDENADOR-GERAL DE ADMINISTRAÇÃO ADUANEIRA, no uso da atribuição que lhe confere o inciso II do art. 334 do Regimento Interno da Secretaria da Receita Federal do Brasil, aprovado pela Portaria MF nº 430, de 9 de outubro de 2017, e tendo em vista o disposto no art. 23 da Portaria MF nº 307, de 17 de julho de 2014, e no artigo 32, inciso III, da Instrução Normativa 1799, de 16 de março de 2018, declara:
Art. 1º As informações, especificações e requisitos técnicos necessários para a integração dos sistemas próprios das lojas francas com os serviços da Receita Federal do Brasil para as Lojas Francas de Fronteira são os constantes do anexo único deste Ato declaratório Executivo.
Art. 2º Fica revogado o Ato declaratório Executivo Coana nº 4, de 19 de março de 2018.
Art. 3º Este Ato declaratório Executivo entra em vigor na data de sua publicação no Diário Oficial da União.
JACKSON ALUIR CORBARI
MODELO DE DADOS - LOJA FRANCA
API - Loja Franca de Fronteira
Documentação para o consumo dos serviços das Lojas Francas de Fronteira
Receita Federal do Brasil
Versão 1.0
Introdução
Todos os serviços seguem o mesmo protocolo de acesso, baseado nas instruções de uso e contratação do serviço API Serpro. A API do Loja Franca de Fronteira foi desenvolvida baseada na arquitetura REST. Ela trabalha exclusivamente com o formato JSON.
A API usa o formato UTF-8.
A URL base da API do ambiente de Validação é https://apigateway.serpro.gov.br/loja-franca-hom/api, o endereço da produção é https://apigateway.serpro.gov.br/loja-franca/api (usaremos a tag < url > para referenciá-las).
Autenticação
Para garantir a identificação e a segurança da origem da informação, toda requisição a API deve seguir três processos:
1. Assinar a requisição com o seu conteúdo anexado mediante a utilização do certificado digital A1 e-CNPJ (cadeia ICP Brasil) da contratante;
2. Submeter a mensagem assinada mediante a apresentação da chave de acesso da API gateway válida (gerada a partir das credencias disponibilizadas no portal do cliente para cada CNPJ) e
3.Verificar a assinatura da requisição, checando se o certificado é válido e não revogado.
Assim, a cada requisição realizada, haverá Validação de Origem que realizará o batimento entre o CNPJ Comercial (CNPJ vinculado as credencias do portal do cliente), CNPJ de Autenticidade (CNPJ assinante da requisição) garantido a irretratabilidade (não repúdio) no nível em cada requisição.
Contratação
Para consumir a API, é necessário utilizar as credenciais de acesso - Consumer Key e Consumer Secret - disponibilizados no portal do Cliente (https://minhaconta.serpro.gov.br). Esses códigos servem para identificar o contrato.
Exemplos de código:
Consumer Key: djaR21PGoYp1iyK2n2ACOH9RedUb
Consumer Secret: ObRsAJWOL4fv2Tp27D1vd8fB3Ote
Token de Acesso (Bearer)
Para consultar a API, é necessário obter um token de acesso temporário (Bearer). Esse token possui um tempo de validade e sempre que expirado, este passo de requisição de um novo token de acesso deve ser repetido.
Para solicitar o token temporário, é necessário realizar uma requisição HTTP POST para o endpoint Token (https://apigateway.serpro.gov.br/token), informando as credenciais de acesso no formato consumerKey:consumerSecret no HTTP Header Authorization, no formato base64.
Após isso feito, será gerada uma chave hash (Bearer token) que deverá ser passada no header das requisições que serão efetuadas. Este header segue o seguinte formato:
Authorization: Bearer < hash >
Payload
Todo o conteúdo a ser enviado para a API do Loja Franca deverá ser o assinado.
A assinatura da mensagem JSON deve ser feita com o uso de um certificado digital Pessoa Jurídica A1, seguindo o padrão das políticas do ICP-Brasil para assinatura digital com referência básica no formato CMS versão 2.2, com algoritmo SHA256WithRSAEncryption.
Para maiores informações, consulte o documento com os requisitos das políticas de assinatura digital na ICP-Brasil DOC-ICP-15.03.
Antes de enviar o conteúdo assinado, o mesmo deve seguir o Formato de mensagem JSON padrão.
Formato de mensagem JSON padrão
"servico": "// endpoint do serviço a ser chamado",
"dados": {
"// JSON de entrada de cada serviço"
A indicação de qual serviço será disparado se dará através do repasse do endpoint que representa cada serviço.
Exemplo de entrada a assinar
O JSON segue o formato documentado por operação e o mesmo fica encapsulado dentro da propriedade dados.
Por exemplo, para a operação Processa venda de viajante.
"servico": "/venda",
"dados" : {
"valorTotalItensImportados": 10,
"valorTotalItensNacionais": 0,
"valorCotacaoLoja": 3.24,
"viajanteParametro": {
"cpf": "00000000191",
"documento": {
"codigoPaisOrigem": 105,
"codigoTipo": 1,
"numero": "12345"
Exemplo de entrada assinada
Operação Processa venda de viajante.
Exemplo de formato do que deverá ser enviado para a API do Loja Franca.
POST https://apigateway.serpro.gov.br/loja-franca/api
HEADERAuthorization: Bearer 953bae789a1726734005d238e939c978BODY/PAYLOADM IAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgMFADCABgkqhkiG9w0BBwEAA KCAMIIG6jCCBNKgAwIBAgIDApVmMA0GCSqGSIb3DQEBCwUAMIGVMQswCQYDVQQGEw JCUjETMBEGA1UECgwKSUNQLUJyYXNpbDE7MDkGA1UECwwyU2VydmljbyBGZWRlcmFsIG RlIFByb2Nlc3NhbWVudG8gZGUgRGFkb3MgLSBTRVJQUk8xNDAyBgNVBAMMK0F1dG9yaWR hZGUgQ2VydGlmaWNhZG9yYSBkbyBTRVJQUk8gRmluYWwgdjUwHhcNMTcwODAyMTI0OTA2 WhcNMjAwODAxMTI0OTA2WjCBoTELMAkGA1UEBhMCQlIxEzARBgNVBAoMCklDUC1Ccm FzaWwxGTAXBgNVBAsMEFBlc3NvYSBGaXNpY2EgQTMxETAPBgNVBAsMCEFSU0VSUFJPM SswKQYDVQQLDCJBdXRvcmlkYWRlIENlcnRpZmljYWRvcmEgU0VSUFJPQUNGMSIwIAYDVQ QDDBlMVUlaIENBUkxPUyBTSUxWRUlSQSBIT1BGMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A MIIBCgKCAQEAi8 YM8V cBZq7DImG6dov33SR
Formatos e tipos
Os seguintes tipos de dados são utilizados pela API do Loja Franca de Fronteira:
Tipo |
Descrição |
Formato |
string |
Cadeia de caracteres |
|
string - data |
String com formato de data |
yyyy-MM-dd |
string - data/hora |
String com formato de data e hora |
yyyy-MM-ddTHH:mm:ss |
integer |
Número inteiro que representa códigos e identificadores |
|
number |
Número inteiro em situações que pode passar do valor 2^31-1 |
|
decimal |
Número fracionado, sempre com duas casas após o decimal, separado por "." |
Ex.: 123456789012.22 (Exceto cotação do dólar, que pode ter até 3 casas após o decimal). |
Tratamento de erros
Erros de negócio
São erros disparados pela API do Loja Franca de Fronteira quando há uma discordância entre os parâmetros enviados e as regras de negócio estabelecidas para as lojas francas.
JSON de Erro
"erros": [
"codigo": integer,
"mensagem": "string"
A resposta HTTP será:
Status Code |
Descrição |
422 |
Erro de negócio do Loja Franca |
Atributos da resposta - Status code 422
Nome |
Descrição |
Tipo |
codigo |
Código que identifica o erro |
integer |
mensagem |
Mensagem de erro |
string |
Exemplo de Erro de Negócio
"erros": [
"codigo": 9,
"mensagem": "cnpjLoja < cnpjLoja/cnpjLoja > não existe como Loja."
Erros de formatação
São erros disparados pela API do Loja Franca de Fronteira quando há uma discordância na formatação/tipo de dados sugeridos pelos parâmetros enviados.
A resposta HTTP será:
Status Code |
Descrição |
400 |
Erro de formatação dos parâmetros enviados |
Atributos da resposta - Status code 400
Nome |
Descrição |
Tipo |
codigo |
Código que identifica o erro |
integer |
mensagem |
Mensagem de erro |
string |
Exemplo de Erro de Formatação
"erros": [
"codigo": 3,
"mensagem": " < tag/tag > com tamanho ou
formato diferente da definição do serviço."
Independentemente do tipo de erro, as mensagens de erro podem conter uma < tag > , que visa facilitar o tratamento do erro caso a aplicação que esteja utilizando a API do Loja Franca de Fronteira queira fazer algum tratamento específico, como por exemplo, uma extração de parâmetros a partir de uma mensagem de erro.
Os erros que a API do Loja Franca de Fronteira dispara pode ser consultada na tabela de erros.
Consulta de cota
Retorna a cota disponível para um determinado viajante.
OBS.: Para Viajante Brasileiro, a identificação pelo número de documento de CPF é sempre obrigatória.
Parâmetros para Viajante (Brasileiro ou Estrangeiro) com CPF
Nome |
Descrição |
Tipo |
Local |
Detalhes |
cpf |
CPF do Viajante |
string |
body |
Obrigatório |
dataNascimento |
Data de nascimento do Viajante |
string |
body |
Obrigatório formato yyyy-MM-dd |
Parâmetros para Viajante Estrangeiro
Nome |
Descrição |
Tipo |
Local |
Detalhes |
documento |
Documento apresentado pelo Viajante |
documento |
body |
Obrigatório |
codigoPaisOrigem |
Código do país de origem do Viajante |
integer |
body |
Obrigatório tabela de países |
codigoTipo |
Código do tipo de documento apresentado pelo Viajante |
integer |
body |
Obrigatório tabela de tipos de documento |
numero |
Número de identificação do documento apresentado pelo Viajante |
string |
body |
Obrigatório |
dataNascimento |
Data de nascimento do Viajante |
string |
body |
Obrigatório formato yyyy-MM-dd |
nomeNoDocumento |
Nome do Viajante presente no documento apresentado |
string |
body |
Obrigatório |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
nomeViajante |
Nome do Viajante cadastrado no Loja Franca |
string |
|
dataUltimaVenda |
Data da última Venda |
string |
formato yyyy-MM-ddTHH:mm:ss |
valorSaldoCota |
Valor restante do saldo de cota |
decimal |
|
saldoCotaProduto |
Saldo de cota de cada produto |
saldoCotaProduto |
|
codigoProduto |
Código do produto |
integer |
tabela de produtos |
quantidade |
Quantidade de produtos restantes na cota |
integer |
SERVICO /viajante/cota
Exemplo de entrada - Viajante Brasileiro
"cpf": "00000000191",
"dataNascimento": "1980-01-01"
Exemplo de entrada - Viajante Estrangeiro
"documento": {
"codigoPaisOrigem": 1,
"codigoTipo": 1,
"numero": "12345",
"dataNascimento": "1980-01-01",
"nomeNoDocumento": "FULANO DE TAL"
Exemplo de resposta
"nomeViajante": "FULANO DE TAL",
"dataUltimaVenda": "2017-12-08T17:13:55",
"valorSaldoCota": 300.0,
"saldoCotaProduto": [
"codigoProduto": 1,
"quantidade": 10
Códigos de erros possíveis
13, 14, 15, 16, 52, 55, 57, 99, -99.
Consulta de viajante
Retorna o nome, a data de nascimento e a data da última venda de um determinado viajante.
Parâmetros para Viajante Brasileiro com CPF
Nome |
Descrição |
Tipo |
Local |
Detalhes |
cpf |
CPF do Viajante |
string |
body |
Obrigatório |
Parâmetros para Viajante Estrangeiro
Nome |
Descrição |
Tipo |
Local |
Detalhes |
documento |
Documento apresentado pelo Viajante |
documento |
body |
Obrigatório |
codigoPaisOrigem |
Código do país de origem do Viajante |
integer |
body |
Obrigatório tabela de países |
codigoTipo |
Código do tipo de documento apresentado pelo Viajante |
integer |
body |
Obrigatório tabela de tipos de documento |
numero |
Número de identificação do documento apresentado pelo Viajante |
string |
body |
Obrigatório |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
nomeViajante |
Nome do Viajante cadastrado no Loja Franca |
string |
|
dataNascimento |
Data de nascimento do Viajante |
string |
formato yyyy-MM-dd |
dataUltimaVenda |
Data da última Venda |
string |
formato yyyy-MM-ddTHH:mm:ss |
SERVICO /viajante/consulta |
Exemplo de entrada - Viajante Brasileiro
"cpf": "00000000191"
Exemplo de entrada - Viajante Estrangeiro
"documento": {
"codigoPaisOrigem": 105,
"codigoTipo": 1,
"numero": "12345"
Exemplo de resposta
"nomeViajante": "FULANO DE TAL",
"dataUltimaVenda": "2017-12-08T17:13:55.765Z",
"dataNascimento": "1970-01-01"
Códigos de erros possíveis
15, 16, 55, 57, 99.
Consulta cotação do dólar
Retorna a cotação do dólar de uma determinada data.
Parâmetros
Nome |
Descrição |
Tipo |
Local |
Detalhes |
dataCotacao |
Data da cotação a pesquisar |
string |
query |
Obrigatório formato yyyy-MM-dd |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
data |
Data da cotação retornada |
string |
formato yyyy-MM-dd |
valorOficial |
Valor da cotação do dólar na data retornada |
decimal |
|
SERVICO /cotacaoDolar?dataCotacao={dataCotacao} |
Exemplo de entrada
// não tem parâmetros JSON, apenas por query string. Ver o endpoint acima.
Exemplo de resposta
"data": "2017-12-01",
"valorOficial": 3.1241
Códigos de erros possíveis
Processa venda de viajante
Efetua uma operação de processamento de venda.
OBS.: Para Viajante Brasileiro, a identificação pelo número de documento de CPF é sempre obrigatória. A identificação por documento é sempre obrigatória independentemente se o Viajante for Brasileiro ou Estrangeiro.
Parâmetros
Nome |
Descrição |
Tipo |
Local |
Detalhes |
valorTotalItensImportados |
Valor total (em US$) de itens importados na Venda para o Viajante |
decimal |
body |
Obrigatório quando valorTotalItensNacionais não for informado ou for igual a 0. |
valorTotalItensNacionais |
Valor total (em US$) de itens nacionais na Venda para o Viajante |
decimal |
body |
Obrigatório quando valorTotalItensImportados não for informado ou for igual a 0. |
valorCotacaoLoja |
Valor da cotação do dólar oferecido pela loja franca |
decimal |
body |
Obrigatório |
viajanteParametro |
Identificação do Viajante |
viajante |
body |
Obrigatório Formato segue os parâmetros da Consulta de viajante. documento é obrigatório para |
brasileiros na venda (atributos codigoPaisOrigem, codigoTipo e numero). |
||||
produtosControleQuantitativo |
Representa a quantidade de produtos controlados presentes na Venda do Viajante |
produtos |
body |
Obrigatório quando é registrada uma venda com produtos controlados. |
codigoProduto |
Código do produto |
integer |
body |
Obrigatório quando é registrada uma venda com produtos controlados. tabela de produtos |
quantidade |
Quantidade de produtos controlados presente na Venda |
integer |
body |
Obrigatório quando é registrada uma venda com produtos controlados. |
valorTotal |
Valor total destes produtos na Venda |
decimal |
body |
Obrigatório quando é registrada uma venda com produtos controlados. |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
idVenda |
Identificação do número da venda gerado pelo sistema Loja Franca de Fronteira |
string |
|
dataHoraVenda |
Data do registro da venda |
string |
formato yyyy-MM-ddTHH:mm:ss |
darf |
Darf gerado para pagamento do viajante caso exceda a Venda exceda a cota |
darf |
|
numero |
Número do Darf gerado |
number |
|
valor |
Valor do Darf a ser pago pelo viajante |
decimal |
|
dataVencimento |
Data de vencimento do Darf |
string |
formato yyyy-MM-dd |
codigoReceita |
Código da receita recolhida |
integer |
|
|
PDF do boleto do Darf gerado |
byte[] |
String encoded em base-64 |
SERVICO /venda
Exemplo de entrada - Venda para Viajante Brasileiro, sem produtos controlado
s{
"valorTotalItensImportados": 10,
"valorTotalItensNacionais": 0,
"valorCotacaoLoja": 3.24,
"viajanteParametro": {
"cpf": "00000000191",
"documento": {
"codigoPaisOrigem": 105,
"codigoTipo": 1,
"numero": "12345"
Exemplo de entrada - Venda para Viajante Estrangeiro, sem produtos controlados
"valorTotalItensImportados": 10,
"valorTotalItensNacionais": 50,
"valorCotacaoLoja": 3.24,
"viajanteParametro": {
"documento": {
"codigoPaisOrigem": 1,
"codigoTipo": 1,
"numero": "12345",
"dataNascimento": "1980-01-01",
"nomeNoDocumento": "FULANO DE TAL"
}Exemplo de entrada - Venda para Viajante Brasileiro, com produtos controlados
"valorTotalItensImportados": 10,
"valorTotalItensNacionais": 0,
"valorCotacaoLoja": 3.24,
"viajanteParametro": {
"cpf": "00000000191",
"documento": {
"codigoPaisOrigem": 105,
"codigoTipo": 1,
"numero": "12345"
"produtosControleQuantitativo": [{
"codigoProduto": 10,
"quantidade": 2,
"valorTotal": 5.3
"codigoProduto": 1,
"quantidade": 1,
"valorTotal": 4.7
Exemplo de resposta, sem Darf
"idVenda": "2017000000020992652",
"dataHoraVenda": "2017-12-11T17:27:41"
}Exemplo de resposta, com Darf
"idVenda": "2017000000020992653",
"dataHoraVenda": "2017-12-11T17:27:41",
"darf": {
"valor": 31.24,
"codigoReceita": 1258,
"numero": 7011734500514907,
"dataVencimento": "2017-12-12",
"pdf": "Base64EncodedString"
}Códigos de erros possíveis
13, 14, 15, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 55, 56, 57.
Entrega venda para viajante
Efetua a operação de entrega de venda.
Parâmetros
Nome |
Descrição |
Tipo |
Local |
Detalhes |
idVenda |
Identificação do número da venda gerado pelo sistema Loja Franca de Fronteira na operação Processa venda de viajante |
string |
query |
Obrigatório |
notaFiscalSaida |
Número da Nota Fiscal de saída gerado pelo sistema gerador de nota fiscal |
string |
query |
Obrigatório |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
dataHoraEntrega |
Data e hora da entrega da venda para o Viajante |
string |
formato yyyy-MM-ddTHH:mm:ss |
SERVICO /venda/entrega?idVenda={idVenda}¬aFiscalSaida={notaFiscalSaida}
Exemplo de entrad
a// não tem parâmetros JSON, apenas por query string. Ver o endpoint acima.
Exemplo de resposta
"dataHoraEntrega": "2017-12-01T16:32:17"
}Códigos de erros possíveis
31, 32, 33, 34, 39, 41, 54.
Cancela venda de viajante
Efetua uma operação de cancelamento de venda.
Parâmetros
Nome |
Descrição |
Tipo |
Local |
Detalhes |
idVenda |
Identificação do número da venda gerado pelo sistema Loja Franca de Fronteira na operação Processa venda de viajante |
string |
query |
Obrigatório |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
dataHoraCancelamento |
Data e hora do cancelamento da venda do Viajante |
string |
formato yyyy-MM-ddTHH:mm:ss |
SERVICO /venda/cancelamento?idVenda={idVenda}
Exemplo de entrad
a// não tem parâmetros JSON, apenas por query string. Ver o endpoint acima.
Exemplo de resposta
"dataHoraCancelamento": "2017-12-01T16:32:17"
}Códigos de erros possíveis
31, 38, 39, 54.
Devolução parcial de venda
Efetua uma operação de devolução parcial de venda.
Parâmetros
Nome |
Descrição |
Tipo |
Local |
Detalhes |
valorTotalItensImportados |
Valor total (em US$) de itens importados a devolver |
decimal |
body |
Obrigatório quando valorTotalItensNacionais não for informado ou for igual a 0. |
valorTotalItensNacionais |
Valor total (em US$) de itens nacionais a devolver |
decimal |
body |
Obrigatório quando valorTotalItensImportados não for informado ou for igual a 0. |
produtosControleQuantitativo |
Representa a quantidade de produtos controlados a devolver |
produtos |
body |
Formato segue os parâmetros do Processa venda de viajante |
codigoProduto |
Código do produto |
integer |
body |
Obrigatório quando é registrada uma venda com produtos controlados. tabela de produtos |
quantidade |
Quantidade de produtos controlados presente na Venda |
integer |
body |
Obrigatório quando é registrada uma venda com produtos controlados. |
valorTotal |
Valor total destes produtos na Venda |
decimal |
body |
Obrigatório quando é registrada uma venda com produtos controlados. |
venda |
Representa a Venda a ser devolvida |
venda |
body |
Obrigatório |
id |
Identificação do número da venda gerado pelo sistema Loja Franca de Fronteira na operação Processa venda de viajante |
string |
body |
Obrigatório |
notaFiscalEntrada |
Número da Nota Fiscal de entrada gerado pelo sistema gerador de nota fiscal |
string |
body |
Obrigatório |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
dataHoraDevolucaoParcial |
Data e hora da devolução |
string |
formato yyyy-MM-ddTHH:mm:ss |
SERVICO /venda/devolucaoParcial
Exemplo de entrada - Devolução parcial de venda, sem produtos controlado
s{
"valorTotalItensImportados": 9.95,
"valorTotalItensNacionais": 0,
"venda": {
"id": "2017000000020992652",
"numeroNotaFiscalEntrada": "42100484684182000157550010000000020108042108"
Exemplo de entrada - Devolução parcial de venda, com produtos controlados
"valorTotalItensImportados": 5.65,
"valorTotalItensNacionais": 0,
"produtosControleQuantitativo": [{
"codigoProduto": 10,
"quantidade": 1,
"valorTotal": 2.65
"venda": {
"id": "2017000000020992652",
"numeroNotaFiscalEntrada": "42100484684182000157550010000000020108042108"
Exemplo de resposta
"dataHoraDevolucaoParcial": "2017-12-11T17:27:41"
}Códigos de erros possíveis
31, 32, 33, 34, 39, 40, 41, 42, 43, 44, 45, 46, 54, 58, 60, 61, 62, 63.
Devolução total de venda
Efetua uma operação de devolução total de venda.
Parâmetros
Nome |
Descrição |
Tipo |
Local |
Detalhes |
idVenda |
Identificação do número da venda gerado pelo sistema Loja Franca de Fronteira na operação Processa venda de viajante |
string |
query |
Obrigatório |
notaFiscalEntrada |
Número da Nota Fiscal de entrada gerado pelo sistema gerador de nota fiscal |
string |
query |
Obrigatório |
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
dataHoraDevolucaoTotal |
Data e hora da devolução da venda |
string |
formato yyyy-MM-ddTHH:mm:ss |
SERVICO /venda/devolucaoTotal?idVenda={idVenda}¬aFiscalEntrada={notaFiscalEntrada}
Exemplo de entrad
a// não tem parâmetros JSON, apenas por query string. Ver o endpoint acima.
Exemplo de resposta
"dataHoraDevolucaoTotal": "2017-12-01T16:32:17"
}Códigos de erros possíveis
31, 32, 33, 34, 39, 40, 41, 54, 58.
Troca item idêntico de venda
Efetua uma operação de troca de item idêntico de uma venda.
Parâmetros
Os parâmetros são exatamente os mesmos da operação Devolução parcial de venda
Atributos da resposta - Status code 200 - OK
Nome |
Descrição |
Tipo |
Detalhes |
dataHoraTrocaItemIdentico |
Data e hora da troca |
string |
formato yyyy-MM-ddTHH:mm:ss |
SERVICO /venda/trocaItemIdentico
Exemplo de entrada - Troca item idêntico, sem produtos controlado
s{
"valorTotalItensImportados": 10,
"valorTotalItensNacionais": 0,
"venda": {
"id": "2017000000020992652",
"numeroNotaFiscalEntrada": "42100484684182000157550010000000020108042108",
"numeroNotaFiscalSaida": "35160400073132000143550012017000006572827920"
Exemplo de entrada - Devolução parcial de venda, com produtos controlados
"valorTotalItensImportados": 10,
"valorTotalItensNacionais": 0,
"produtosControleQuantitativo": [{
"codigoProduto": 10,
"quantidade": 2,
"valorTotal": 5.3
"venda": {
"id": "2017000000020992652",
"numeroNotaFiscalEntrada": "42100484684182000157550010000000020108042108",
"numeroNotaFiscalSaida": "35160400073132000143550012017000006572827920"
Exemplo de resposta
"dataHoraTrocaItemIdentico": "2017-12-11T17:27:41"
}Códigos de erros possíveis
28, 30, 31, 32, 33, 34, 35, 36, 37, 39, 40, 41, 42, 43, 44, 45, 46, 54, 58, 60, 61, 62, 63.
Tabela de produtos
Código |
Descrição |
1 |
Bebida alcóolica |
2 |
Cigarro |
3 |
Fumo |
Tabela de tipos de documento
Código |
Descrição |
Codigo País |
País |
1 |
Passaporte |
TODOS OS PAÍSES |
|
2 |
Registro de Identidade Civil |
105 |
Brasil |
3 |
Cédula de Identidade AC |
105 |
Brasil |
4 |
Cédula de Identidade AL |
105 |
Brasil |
5 |
Cédula de Identidade AM |
105 |
Brasil |
6 |
Cédula de Identidade AP |
105 |
Brasil |
7 |
Cédula de Identidade BA |
105 |
Brasil |
8 |
Cédula de Identidade CE |
105 |
Brasil |
9 |
Cédula de Identidade DF |
105 |
Brasil |
10 |
Cédula de Identidade ES |
105 |
Brasil |
11 |
Cédula de Identidade GO |
105 |
Brasil |
12 |
Cédula de Identidade MA |
105 |
Brasil |
13 |
Cédula de Identidade MG |
105 |
Brasil |
14 |
Cédula de Identidade MS |
105 |
Brasil |
15 |
Cédula de Identidade MT |
105 |
Brasil |
16 |
Cédula de Identidade PA |
105 |
Brasil |
17 |
Cédula de Identidade PB |
105 |
Brasil |
18 |
Cédula de Identidade PE |
105 |
Brasil |
19 |
Cédula de Identidade PI |
105 |
Brasil |
20 |
Cédula de Identidade PR |
105 |
Brasil |
21 |
Cédula de Identidade RJ |
105 |
Brasil |
22 |
Cédula de Identidade RN |
105 |
Brasil |
23 |
Cédula de Identidade RO |
105 |
Brasil |
24 |
Cédula de Identidade RR |
105 |
Brasil |
25 |
Cédula de Identidade RS |
105 |
Brasil |
26 |
Cédula de Identidade SC |
105 |
Brasil |
27 |
Cédula de Identidade SE |
105 |
Brasil |
28 |
Cédula de Identidade SP |
105 |
Brasil |
29 |
Cédula de Identidade TO |
105 |
Brasil |
30 |
Cédula de Identidade para estrangeiro |
105 |
Brasil |
31 |
Documento Nacional de Identidad |
63 |
Argentina |
32 |
Cédula de Identidad |
586 |
Paraguai |
33 |
Cédula de Identidad |
845 |
Uruguai |
34 |
Cédula de Identidad |
850 |
Venezuela |
35 |
Cédula de Identidad para Nacionales |
97 |
Bolívia |
36 |
Cédula de Identidad para Extranjeros |
97 |
Bolívia |
37 |
Cédula de Identidad |
158 |
Chile |
38 |
Cédula de Ciudadanía |
169 |
Colômbia |
39 |
Tarjeta de Identidad |
169 |
Colômbia |
40 |
Cédula de Extranjería |
169 |
Colômbia |
41 |
Cédula de Ciudadanía |
239 |
Equador |
42 |
Cédula de Identidad para extranjeros |
239 |
Equador |
43 |
Documento Nacional de Identidad |
589 |
Peru |
44 |
Carné de Extranjería |
589 |
Peru |
Tabela de países
Ver tabela de países da Receita Federal do Brasil
TABELA DE CÓDIGO DOS PAÍSES
Código |
País |
Código |
País |
Código |
País |
105 |
Brasil |
271 |
Finlândia |
538 |
Noruega |
013 |
Afeganistão |
161 |
Formosa (Taiwan) |
542 |
Nova Caledônia |
756 |
África do Sul |
275 |
França |
548 |
Nova Zelândia |
017 |
Albânia, República da |
281 |
Gabão |
556 |
Omã |
023 |
Alemanha |
285 |
Gambia |
563 |
Pacífico, Ilhas do (administ. dos EUA) |
037 |
Andorra |
289 |
Gana |
566 |
Pacífico, Ilhas do (possessão dos EUA) |
040 |
Angola |
291 |
Georgia, República da |
||
041 |
Anguilla |
293 |
Gibraltar |
573 |
Países Baixos (Holanda) |
043 |
Antigua Barbuda |
297 |
Granada |
575 |
Palau |
047 |
Antilhas Holandesas |
301 |
Grécia |
580 |
Panamá |
053 |
Arábia Saudita |
305 |
Groelândia |
545 |
Papua Nova Guiné |
059 |
Argélia |
309 |
Guadalupe |
576 |
Paquistão |
063 |
Argentina |
313 |
Guam |
586 |
Paraguai |
064 |
Armênia, República da |
317 |
Guatemala |
589 |
Peru |
065 |
Aruba |
337 |
Guiana |
593 |
Pitcairn, Ilha de |
073 |
Arzebaijão, República do |
325 |
Guiana Francesa |
599 |
Polinésia Francesa |
069 |
Austrália |
329 |
Guiné |
603 |
Polônia, República da |
072 |
Áustria |
334 |
Guiné-Bissau |
611 |
Porto Rico |
077 |
Bahamas, Ilhas |
331 |
Guiné-Equatorial |
607 |
Portugal |
080 |
Bahrein, Ilhas |
341 |
Haiti |
623 |
Quênia |
081 |
Bangladesh |
345 |
Honduras |
625 |
Quirguiz, República da |
083 |
Barbados |
351 |
Hong Kong |
628 |
Reino Unido |
085 |
Belarus, República da |
355 |
Hungria, República da |
640 |
República Centro-Africana |
087 |
Bélgica |
357 |
Iemen |
647 |
República Dominicana |
088 |
Belize |
361 |
Índia |
660 |
Reunião, Ilha |
229 |
Benin |
365 |
Indonésia |
670 |
Romênia |
090 |
Bermudas |
367 |
Inglaterra |
675 |
Ruanda |
097 |
Bolívia |
372 |
Irã, República Islâmica do |
676 |
Rússia, Federação da |
098 |
Bósnia-Herzegovina |
369 |
Iraque |
685 |
Saara Ocidental |
101 |
Botsuana |
375 |
Irlanda |
677 |
Salomão, Ilhas |
108 |
Brunei |
379 |
Islândia |
690 |
Samoa |
111 |
Bulgária, República da |
383 |
Israel |
691 |
Samoa Americana |
31 |
Burkina Faso |
386 |
Itália |
697 |
San Marino |
115 |
Burundi |
388 |
Iugoslávia, República Federativa da |
710 |
Santa Helena |
119 |
Butão |
391 |
Jamaica |
715 |
Santa Lúcia |
678 |
Saint Kitts e Nevis |
||||
127 |
Cabo Verde, República de |
399 |
Japão |
695 |
São Cristóvão e Neves, Ilhas |
150 |
Jersey, Ilha do Canal |
||||
145 |
Camarões |
396 |
Johnston, Ilhas |
700 |
São Pedro e Miquelon |
141 |
Camboja |
403 |
Jordânia |
720 |
São Tomé e Príncipe, Ilhas |
149 |
Canadá |
411 |
Kiribati |
705 |
São Vicente e Granadinas |
151 |
Canárias, Ilhas |
420 |
Laos, República Popular Democrática |
728 |
Senegal |
153 |
Casaquistão, República do |
423 |
Lebuan, Ilhas |
735 |
Serra Leoa |
737 |
Servia |
||||
154 |
Catar |
426 |
Lesoto |
731 |
Seychelles |
137 |
Cayman, Ilhas |
427 |
Letônia, República da |
744 |
Síria, República Árabe da |
788 |
Chade |
431 |
Líbano |
748 |
Somália |
158 |
Chile |
434 |
Libéria |
750 |
Sri Lanka |
160 |
China, República Popular |
438 |
Líbia |
754 |
Suazilândia |
163 |
Chipre |
440 |
Liechtenstein |
759 |
Sudão |
511 |
Christmas,Ilhas (Navidad) |
442 |
Lituânia, República da |
764 |
Suécia |
741 |
Cingapura |
445 |
Luxemburgo |
767 |
Suíça |
165 |
Cocos-Keeling, Ilhas |
447 |
Macau |
770 |
Suriname |
169 |
Colômbia |
449 |
Macedônia, Ant.Rep.Iugoslava |
776 |
Tailândia |
173 |
Comores, Ilhas |
450 |
Madagascar |
772 |
Tadjiquistão, República do |
452 |
Madeira, Ilha da |
||||
177 |
Congo |
455 |
Malásia |
780 |
Tanzânia, República Unida da |
888 |
Congo, República Democrática do |
||||
183 |
Cook, Ilhas |
458 |
Malavi |
791 |
Tcheca, República |
190 |
Coréia, República da |
461 |
Maldivas |
782 |
Território Britânico no Oceano Índico |
187 |
Coréia, República Popular Democrática |
464 |
Mali |
795 |
Timor Leste |
193 |
Costa do Marfim |
467 |
Malta |
800 |
Togo |
359 |
Man, Ilha de |
||||
196 |
Costa Rica |
472 |
Marianas do Norte |
810 |
Tonga |
198 |
Coveite |
474 |
Marrocos |
805 |
Toquelau, Ilhas |
195 |
Croácia, República da |
476 |
Marshall, Ilhas |
815 |
Trinidad e Tobago |
199 |
Cuba |
477 |
Martinica |
820 |
Tunísia |
998 |
Delegação Especial da Palestina |
||||
232 |
Dinamarca |
485 |
Maurício |
823 |
Turcas e caicos, Ilhas |
783 |
Djibuti |
488 |
Mauritânia |
824 |
Turcomenistão, República do |
235 |
Dominica, Ilha |
493 |
México |
827 |
Turquia |
372 |
Dubai |
||||
237 |
Dubai |
093 |
Mianmar (Birmânia) |
828 |
Tuvalu |
240 |
Egito |
499 |
Micronésia |
831 |
Ucrânia |
687 |
El salvador |
490 |
Midway, Ilhas |
833 |
Uganda |
244 |
Emirados Árabes Unidos |
505 |
Moçambique |
845 |
Uruguai |
243 |
Eritreia |
||||
239 |
Equador |
494 |
Moldova, República da |
847 |
Uzbequistão, República do |
247 |
Eslovaca, República |
495 |
Mônaco |
551 |
Vanuatu |
246 |
Eslovênia, República da |
497 |
Mongólia |
848 |
Vaticano, Estado da Cidade do |
498 |
Montenegro |
873 |
Wake, Ilha |
||
245 |
Espanha |
501 |
Montserrat, Ilhas |
850 |
Venezuela |
249 |
Estados Unidos |
507 |
Namíbia |
858 |
Vietnã |
251 |
Estônia, República da |
508 |
Nauru |
863 |
Virgens, Ilhas (Britânicas) |
253 |
Etiópia |
517 |
Nepal |
866 |
Virgens, Ilhas (EUA) |
255 |
Falkland (Ilhas Malvinas) |
521 |
Nicarágua |
875 |
Wallis e Futuna, Ilhas |
259 |
Feroe, Ilhas |
525 |
Niger |
888 |
Zaire |
263 |
Fezzan |
528 |
Nigéria |
890 |
Zâmbia |
870 |
Fidji |
531 |
Niue, Ilha |
665 |
Zimbabue |
267 |
Filipinas |
535 |
Norfolk, Ilha |
Tabela de erros
Código |
Mensagem |
1 |
Estrutura do JSON de entrada diferente da definição do serviço. |
2 |
Chave obrigatória {0} sem conteúdo. |
3 |
{0} com tamanho ou formato diferente da definição do serviço. |
4 |
Certificado não foi informado, não é de Equipamento e/ou não é válido. |
9 |
cnpjLoja {0} não existe como Loja. |
10 |
cnpjLoja diferente do Certificado de Autenticação. |
11 |
cnpjLoja {0} Suspenso. |
12 |
cnpjLoja {0} Cancelado. |
13 |
paisOrigem não localizado na Tabela de Países. |
14 |
tipoDocumento inválido. |
15 |
CPF inválido. |
16 |
Viajante não localizado. |
17 |
CPF obrigatório para brasileiros (paisOrigem = Brasil). |
18 |
CPF diferente do CPF vinculado ao documento {0} através de venda no dia {1}. |
19 |
CPF diferente do CPF vinculado ao documento {0} pela RFB. |
20 |
dataNascimento e nomeNoDocumento obrigatórios para estrangeiro com CPF não informado. |
21 |
Documento não pode ser vinculado ao CPF {0} pois desvinculado desse CPF pela RFB. |
22 |
valorTotalItensImportados ou valorTotalItensNacionais deve ser maior que zero. |
23 |
valorTotalItensNacionais não pode ser maior que saldo de cota: {0} |
24 |
valorCotacaoLoja deve ser maior que zero. |
25 |
produtoControleQuantitativo.codigoProduto {0} não localizado na Tabela de Produtos. |
26 |
produtoControleQuantitativo.codigoProduto {0} já informado na venda. |
27 |
produtoControleQuantitativo.quantidade deve ser maior que zero e não superior ao limite de {0} {1}. |
28 |
produtoControleQuantitativo.valorTotalProdutos deve ser maior que zero. |
29 |
Venda gera imposto inferior ao limite mínimo (R$ {0}) para geração de DARF. |
30 |
Somatório dos produtoControleQuantitativo.valorTotal maior que valorTotalItensImportados + valorTotalItensNacionais. |
31 |
idVenda não localizado. |
32 |
{0} DV inválido. |
33 |
{0} emitida por CNPJ diferente da loja. |
34 |
{0} já informada em outras operações. |
35 |
{0} DV inválido. |
36 |
{0} emitida por CNPJ diferente da loja. |
37 |
{0} já informada em outras operações. |
38 |
Venda foi entregue anteriormente. |
39 |
Venda foi cancelada anteriormente. |
40 |
Venda foi totalmente devolvida anteriormente. |
41 |
Venda não foi entregue anteriormente. |
42 |
produtoControleQuantitativo.codigoProduto {0} não informado na venda. |
43 |
produtoControleQuantitativo.codigoProduto {0} já informado na devolução. |
44 |
produtoControleQuantitativo.quantidade deve ser maior que zero e não superior ao saldo da venda. |
45 |
produtoControleQuantitativo.valorTotal deve ser maior que zero e não superior ao saldo da venda. |
46 |
valorTotalItensImportados + valorTotalItensNacionais maior que saldo da venda. |
47 |
valorTotalItensNacionais maior que saldo da venda da produtos Nacionais. |
48 |
valorTotalItensImportados maior que saldo da venda de produtos Importados. |
52 |
Data de nascimento diferente do {0}. |
54 |
Venda desvinculada do Viajante. |
55 |
CPF não localizado. |
56 |
Data sem cotação do dólar. |
57 |
Situação do CPF inválida. |
58 |
notaFiscalSaida igual a notaFiscalEntrada. |
59 |
notaFiscalSaida não deve ser Informada. |
60 |
Saldo da quantidade do produtoControleQuantitativo.codigoProduto {0} zerado sem zerar o valor total da venda deste produto. |
61 |
Valor total do produtoControleQuantitativo.codigoProduto {0} zerado sem zerar a quantidade total vendida deste produto. |
62 |
Ao zerar os valores totais para produtos Nacionais e Importados, é preciso zerar os produtos controlados da venda. |
63 |
Saldo Final de Produtos Controlados Maior que Saldo Final Total da Venda. |
70 |
Conteúdo do Payload é Invalido. |
99 |
Erro no ambiente {0}. {1}. |
-99 |
Erro na comunicação com algum outro sistema externo que a API do Loja Franca de Fronteira se integra. |
Todas as mensagens retornam HTTP Status 422, com exceção das mensagens 1 e 3, que retornam HTTP Status 400.
Todas as mensagens são encapsuladas conforme demonstrado em Tratamento de erros.
As mensagens aqui propostas são sugestões e não necessariamente precisam ser exibidas exatamente da forma como estão no sistema da loja franca que está consumindo a API do Loja Franca de Fronteira, ou seja, elas podem ser customizadas conforme a necessidade.
As mensagens de erro 1, 2, 3, 4, 9, 10, 11, 12, 70 poderão ser disparadas independentemente da operação, pois são mensagens de validação de CNPJ e certificado digital da Loja e mensagens de erros gerais.