Como receber, via API, as faturas das transportadoras

Entendendo o formato da API

Este artigo explica os princípios básicos para utilização da API do GL, como formato dos dados, forma de autenticação, e URLs para acesso. Comece por ele!

Obtendo um usuário e senha para acesso

Obviamente, o acesso à API somente será autorizado se você possuir as "credenciais" que provem que você (ou melhor, neste caso a sua aplicação), possui os direitos necessários para registrar uma Nota Fiscal no sistema. E para isso você vai precisar ter um usuário cadastrado no sistema com os direitos necessários. Se tiver qualquer dúvida em como cadastrar este usuário, basta enviar um e-mail para o nosso time de suporte, ou com o consultor que atende sua empresa, e eles podem fazer isso por você.

Recebendo a lista de faturas

O ponto de partida é uma chamada para o serviço de "lista de faturas", onde você pode especificar um ou mais parâmetros que servirão como "filtros" para selecionar as faturas desejadas. Esses parâmetros devem ser enviados como "query strings" no request:

GET /faturas-transportador?param1=valor1&param2=valor2&...

Os principais filtros que podem ser enviados são:

periodoCadastramento : Intervalo de datas em que as faturas foram registradas no sistema;

periodoEmissao : Intervalo de datas em que as faturas foram emitidas pelas transportadoras;

periodoVencimento : Intervalo de datas de vencimento das faturas;

periodoLiberacao : Intervalo de datas em que as faturas foram liberadas para pagamento;

periodoBaixa : Intervalo de datas em que as faturas foram pagas;

periodoAtualizacao : Intervalo de datas em que as faturas tiveram a última atualização no sistema;

O período a ser utilizado para a consulta depende do workflow que você irá definir, mas, para efeito de integração com o contas a pagar, geralmente usa-se o período de liberação, que é quando as faturas já estão validadas de devem ser disponibilizadas para pagamento.

Os parâmetros do tipo "período" devem serguir o seguinte formato (observe que os caracteres que delimitam o "objeto JSON" { e }, devem ser codificados, respectivamente %7B e %7D): 

%7Binicio:YYYY-MM-DDT00:00-03:00,termino:YYYY-MM-DDT00:00:00-03:00%7D

Exemplo: Para receber a lista das faturas liberadas entre os dias 01/12/25 e 10/12/25, o request a ser utilizado seria o seguinte:

GET /faturas-transportador?periodoLiberacao=%7Binicio:2025-12-01T00:00-03:00,termino:2025-12-11T00:00:00-03:00%7D

Resultado da consulta

O resultado será um objeto JSON, com a seguinte estrutura: 

{
  "itens": [{fatura1},{fatura2},...],
  "totalItens": 999
}

e cada fatura da lista possui a seguinte estrutura (observe que a ordem dos campos pode ser diferente da apresentada): 

{
  "id": 999,
  "numero": 999,
  "numeroFormatado": "999.999",
  "emissao": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "cadastramento": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "vencimento": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "validacaoAuditoria": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "liberacao": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "baixa": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "ultimaAtualizacao": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "valor": 999.99,
  "desconto": 999.99,
  "valorLiquido": 999.99,
  "faturaDts": [],
  "tags": [],
  "transportadora": {
    "id": 999,
    "nomeExibicao": "xxx",
    "cnpj": "99.999.999/9999-99",
    "grupo": { 
      "id": 999, 
      "nome": "xxx" 
    }
  },
  "situacao": 9,
  "qtdDts": 999,
  "qtdNfs": 999,
  "qtdDtsNaoLocalizados": 0,
  "qtdDtsComPendenciasEmbarcador": 0,
  "qtdNfsComPendenciasEmbarcador": 0,
  "qtdDtsComPendenciasTransportadora": 0,
  "qtdNfsComPendenciasTransportadora": 0,
  "valorTotalDts": 999.99,
  "valorTotalDtsAssociados": 999.99,
  "valorTotalPreDtsAssociados": 999.99,
  "valorDivergencia": 999.99,
  "unidade": {
    "id": 999,
    "sigla": "xxx",
    "nome": "xxx",
    "pessoa": {
      "id": 99,
      "cpfCnpj": {
        "tipoPessoa": 2,
        "numero": 99999999999999,
        "formatado": "99.999.999/9999-99"
       },
      "nomeExibicao": "xxx",
      "grupo": {
        "id": 999,
        "nome": "xxx"
      }
    }
  }
}

Caso seja necessário recuperar também a lista de CTes contidos em cada fatura, isso pode ser feito de 2 formas: 

• Junto com os dados da fatura: Tem a vantagem de trazer todas as informações em um único request, porém o volume de dados pode ficar muito grande. 

  Para isso, deve-se acrescentar ao request o parâmetro nivelDetalheDts=1.

  Dessa forma, o atributo faturaDts da response irá conter um "array" com a lista de DTs da fatura, com o formato a seguir. 

obs: Você também pode solicitar os dados completos de cada DT, colocando o valor 2 para o parâmetro acima, porém o volume de dados retornados irá aumentar significativamente. 

{         
  "id": 999,
  "unidadeEmissora": "xxx",
  "serie": "999",
  "numero": 999999,
  "valor": 99.99,
  "emissao": "YYYY-MM-DDT00:00:00.0000000-03:00",
  "dt": {
    "id": 999999,
    "tipo": 99,
    "valorPreDtApurado": 99.99,
    "valorDivergenciaNoFrete": 0.00,
    "serie": "999",
    "numero": 999999,
    "numeroFormatado": "TRP-999.999-9",
    "obs": "xxx",
    "chaveCte": "9999999999999999999999999999999999999999999",
    "complementar": false
  }
}

• Em um request separado para cada fatura: Reduz o volume de dados do request inicial, mas exige novos requests para cada fatura. 
  O request a ser feito para cada fatura é o seguinte, onde {ID} é o id da fatura desejada: 

GET /faturas-transportador/{ID}/dts

Neste caso o retorno será similar ao anterior, mas irá sempre conter todos os dados dos DTs.