Sumário


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:

  1. 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;
  2. 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.

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:



  • Sem rótulos