1 Conceito
A API de Recolha Genérica permite que seja integrado com demais cartões frotas, para isso é necessário que sejam configuradas as URLS necessárias para integração.
2 Requisitos
Para utilização desta integração será necessário alguns requisitos:
- A versão exigida é a 3.3.1.127 (AutoSystem) ou superior;
- Ter o módulo Recolha de Notas liberado na Intranet;
- Ter um ambiente que atenda a documentação abaixo.
3 Configurações Gerais
Abaixo serão descritas as principais configurações para que a integração funcione com sucesso.
3.1 Configuração Integração
No módulo Gerencial, acessar o menu Configurações > Módulos > Configurações de Frota > Recolha de Notas, selecionar a empresa desejada e clicar no ícone “+” para cadastrar a recolha, é possível cadastrar várias recolhas para uma empresa.
Ao clicar no ícone o sistema apresentará uma tela para realizar a configuração da recolha.
Na guia Dados Recolha de Nota, será necessário preencher os campos:
- Nome Integração: Informar o nome da recolha que está sendo configurada;
- URL: Informar a URL da integração (disponibilizada pela empresa do cartão);
- Usuário: Informar o usuário da integração (disponibilizada pela empresa do cartão);
- Senha: Informar a senha da integração (disponibilizada pela empresa do cartão);
- Cód Estabelecimento: Informar o código do estabelecimento (disponibilizada pela empresa do cartão);
No campo de Motivos Pagamento, selecionar a forma de pagamento que será utilizada para a recolha.
Importante
Ao adicionar o motivo de pagamento, não será possível reutilizar este em um cadastro de outra recolha de notas. Salvo caso registro em matriz/filial.
Para que a forma de pagamento apareça nessa tela, é necessário marcar a opção “Recolha de Notas” no menu Cadastros > Motivos de Movimentações > Informações > Outras Informações. Não é permitido vincular o mesmo pagamento para mais de uma recolha.
Ainda na tela de Cadastro Recolha Nota, temos as opções de escolhas:
- Envia XML ao finalizar a venda: enviar o XML da nota emitida para o sistema de recolha de notas quando o cliente utiliza essa opção.
- Utilizar dados cadastrais da API: utilizar os dados cadastrais do cliente para emissão da NF-e que são retornados da API. Com a opção marcada, não utiliza os dados do sistema.
- Efetuar retentativas de consulta aos dados do cliente: com a opção marcada o sistema realiza 4 tentativas de consultas na API. Com a opção desmarcada é realizado apenas 1 tentativa.
Ao finalizar as configurações, clicar em Confirmar para salvar o cadastro. O sistema então exibirá a tela com a recolha cadastrada:
Para desativar a integração basta desmarcar a opção “Ativar Integração” na tela de configuração da recolha:
Será exibido um “X” na recolha selecionada, informando que a mesma está desativada:
4 Fluxo de Integração
O fluxo de integração com a API é configurado da seguinte forma:
- Durante o processo da venda, o sistema consulta a API enviando o código do estabelecimento e o número de autorização (TEF ou POS), para obter o retorno dos dados de emissão da NF-e;
- Após o processo de emissão da NF-e o sistema envia o arquivo de XML da nota fiscal caso o cliente utilize o sistema de recolha de notas.
5 Autenticação API
A autenticação para utilização da API deve ser executada através do esquema "HTTP Basic". Neste processo de autenticação, é utilizado um login e senha. Geralmente, as bibliotecas cuidam do envio do usuário e senha, ou seja, basta informar um nome de usuário e uma senha válidos e a biblioteca fará todo o resto. Caso contrário, será possível implementar a autenticação manualmente. Para isso, basta enviar em cada requisição um cabeçalho HTTP com o nome "Authorization".
Um exemplo para o valor deste cabeçalho é: Basic dGVzdGU6dGVzdGU=
Onde "Basic" é uma palavra que sempre será enviada.
O restante "dGVzdGU6dGVzdGU=" é o resultado da codificação em base64 da string "teste:teste". Neste caso, o primeiro "teste" é o nome de usuário e o segundo "teste" é a senha. No esquema de autenticação "Basic", o símbolo ":" (dois pontos) tem a função de separar o usuário da senha.
Portanto, para um par de login/senha onde o login seja "teste" e a senha também seja "teste", temos o cabeçalho final: Basic dGVzdGU6dGVzdGU=
6 API's de Integração: Consulta NF-e
Para a emissão da Nota Fiscal Eletrônica (NF-e) com base no código de autorização da transação do cartão, é necessário consultar as informações relevantes.
Em situações que o cliente não possui o recolhimento de notas, a requisição de consulta irá retornar o status 46. Nesse caso, é possível concluir o fluxo da integração/venda sem a necessidade de emitir a NF-e.
No entanto, é importante ressaltar que a emissão da NF-e pode ser exigida em outros cenários, portanto, é fundamental estar ciente das obrigações fiscais e seguir as regulamentações aplicáveis.
GET https://minha_url.com.br/recolhaAutonoma/dadosEmissaoNfeRecolhaAutonoma
Request - [Query Params]
- codigoEstabelecimento: Integer (int64) – REQUERIDO
- codigoAutorizacao: Integer (int64) – REQUERIDO
- Código da autorização para qual deseja-se consultar os dados de emissão da NFE. Informar neste campo o número de autorização emitido pelos meios de captura (POS ou TEF) no momento do abastecimento.
- dataAutorizacao: date (’yyyy-MM-dd’) – REQUERIDO
- Data no formato ISO 860-1 para a transação de abastecimento. Não pode ser maior que a atual.
Response - [Content-Type: application/json]
- cnpj: string (14 caracteres máx.)
- CNPJ do cliente (somente números) para emissão da NFE.
- razaoSocial: string (80 caracteres máx.)
- Razão social do cliente para emissão da NFE.
- inscricaoEstadual: string (20 caracteres máx.)
- Inscrição estadual do cliente para emissão da NFE.
- cfop: string (35 caracteres máx.)
- Lista de CFOPs definidos pelo cliente para emissão da NFE.
- quilometragem:
- Quilometragem do veículo vinculado ao cartão transação.
- placaDoVeiculo:
- Placa do veículo vinculado ao cartão da transação
- endereco: element
- Agrupador das informações do endereço.
- logradouro: string (80 caracteres máx.)
- Lagradouro do endereço de emissão da NFE.
- numero: string (6 caracteres máx.)
- Número do endereço de emissão da NFE, quando sem número exibe “S/N”.
- complemento: string (20 caracteres máx.)
- Complemento do endereço de emissão da NFE.
- bairro: string (60 caracteres máx.)
- Nome do bairro do endereço de emissão da NFE.
- cidade: string (50 caracteres máx.)
- Nome da cidade do endereço de emissão da NFE.
- uf: string (2 caracteres)
- Sigla da UF do endereço de emissão da NFE.
- cep: string (8 caracteres)
- cep (somente números) do endereço de emissão da NFE.
- codigoIbge: integer (int64)
- Código da cidade conforme base do IBGE.
- logradouro: string (80 caracteres máx.)
- Agrupador das informações do endereço.
HTT Status Codes
- 200 – OK (Autorização Encontrada);
- 400 – Bad Request (Erros nos dados informados)
- 404 – Not Found (Não foram encontrados dados para emissão de NFE para a autorização e estabelecimento informados)
- 460 – Business Exception (Erros referentes as regras operacionais do sistema de recolha)
Exemplos JSONs
Retorno Status 200: { "cnpj": "12345678901234", "razaoSocial": "Company Name", "inscricaoEstadual": "1234567890", "cfop": "123456", "quilometragem": "10000", "placaDoVeiculo": "ABC1234", "endereco": { "logradouro": "Street Name", "numero": "123", "complemento": "Apt 4", "bairro": "Neighborhood", "cidade": "City", "uf": "CA", "cep": "12345678", "codigoIbge": 1234567 } Retorno Status 460 (Erros referentes as regras operacionais do sistema de recolha): { "erros": [ { "codigo":"001", "detalhe":"Cliente não possui recolha de notas" } ] }
7 API's de Integração: Upload de Nota Fiscal
Possibilita que o estabelecimento envie o arquivo XML de nota fiscal emitida para o cliente que utiliza o sistema de recolha de notas.
POST https://minha_url.com.br/recolhaAutonoma/nfe
Request - [Content-Type: application/json]
- codigoEstabelecimento: Integer (int64) - REQUERIDO
- codigoAutorizacao: Integer (int64) - REQUERIDO
- Código da autorização para qual deseja-se consultar os dados de emissão da NFE. Informar neste campo o número de autorização emitido pelos meios de captura (POS ou TEF) no momento do abastecimento.
- dataAutorizacao: date (’yyyy-MM-dd’)
- Data no formato ISO 860-1 para a transação de abastecimento. Não pode ser maior que a atual.
- arquivo.nomeOriginal: string (60 caracteres máx.) - REQUERIDO
- Nome original do arquivo que está sendo enviado na chamada, incluindo a extensão. (.xml).
- arquivo.base64Encode: string (1000000 caracteres máx.) - REQUERIDO
- Conteúdo do arquivo XML da nota fiscal com codificação base64/ISO 8859-1. O tamanho máximo do arquivo decodificado deve ser de 100 Kb. Será validado utilizando o hash MD5, e se o conteúdo representa um arquivo XML.
- arquivo.MD5hash: string (32 caracteres máx.) - REQUERIDO
- Valor codificado hash MD5 do arquivo XML enviado no campo base64Encode.
Exemplo de JSONs
Request - [Content-Type: application/json] { "codigoEstabelecimento": 123456, "codigoAutorizacao": 789012, "dataAutorizacao": "2022-01-01", "arquivo": { "nomeOriginal": "nota_fiscal.xml", "base64Encode": "SGVsbG8gd29ybGQh", "MD5hash": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }
8 Vídeo Explicativo
Confira abaixo um vídeo explicativo com as informações descritas acima: