Pular para o conteúdo principal

List

POST {URL}list

O serviço List lista as vendas de acordo com os critérios de busca. Ele retorna um resumo de cada transação. O dado mais importante desse resumo é o UniqueId, usado depois nos serviços Details e Change.

💡 Papel no fluxo recomendado

O List é o primeiro passo do fluxo de integração. Utilize-o sempre com FilterImportState = 1 (OnlyNotImported) para obter exclusivamente as transações que o seu sistema ainda não importou.

Boas práticas​

  • Use filtros de data (DateFrom e DateTo) para limitar o período da consulta.
  • O intervalo máximo permitido entre DateFrom e DateTo é de 7 dias. Para períodos maiores, faça múltiplas consultas fracionadas.
  • Prefira consultas específicas com Locator ou Ticket quando você já tiver o localizador ou número do bilhete. (Nessas buscas diretas, o intervalo de datas não é obrigatório e o limite de 7 dias não se aplica).
  • Combine filtros de tipo (TransactionTypes) e status (TransactionStates) para obter resultados mais precisos.
  • Use FilterImportState = 1 para trazer só as transações ainda não importadas.
  • Evite requisições sem filtros, que geram alto volume de dados e sobrecarga desnecessária.
  • Ajuste o OffSet quando necessário, para manter o fuso horário das datas alinhado com o seu sistema.

Requisição​

{
  "DateFrom": "2022-01-08T19:41:15.750Z",   // Data inicial (obrigatório se não informar Locator/Ticket)
  "DateTo": "2022-01-15T19:41:15.750Z",     // Data final (máximo 7 dias de diferença de DateFrom)
  "FilterDateType": 1,                       // 1 = LastUpdate | 2 = Create | 3 = Insert
  "OffSet": "-03:00:00",                     // Fuso horário (padrão do servidor: -03:00:00)
  "TransactionTypes": [],                    // ex.: [1, 100, 2]
  "TransactionStates": [],                   // ex.: [4]
  "FilterLinkType": 0,                       // 0 = Any | 1 = OnlyWithParent | 2 = OnlyWithoutParent
  "FilterImportState": 1,                    // 0 = Any | 1 = OnlyNotImported | 2 = OnlyImported
  "Locator": "",
  "Ticket": "",
  "AccessCredentials": {
    "Company": {
      "Identifier": "{{identifier}}",
      "Password": "{{password}}"
    }
  }
}

📌 Atenção: Os comentários (//) no JSON acima servem apenas como documentação didática. Remova-os na implementação da sua aplicação, pois JSON estrito não aceita comentários.

Campos da Requisição​

CampoObrigatórioTipoDescrição
DateFromCondicional*string (date-time)Data inicial (filtra transações com data $\ge$ DateFrom). Obrigatório se não informar Locator ou Ticket.
DateToCondicional*string (date-time)Data final (filtra transações com data $\le$ DateTo). Obrigatório se não informar Locator ou Ticket. O intervalo máximo entre DateFrom e DateTo é de 7 dias.
OffSetNãostring (±hh:mm:ss)Fuso horário dos valores de DateFrom / DateTo e das datas retornadas. Padrão: -03:00:00 (horário de Brasília).
FilterDateTypeNãointegerCampo de data usado no filtro: 1 LastUpdate, 2 Create, 3 Insert. Enum fixo.
TransactionTypesNãointeger[]Lista de tipos de transação desejados. Enum fixo (ex.: 1 AirReservation, 100 AirTicket, 2 Hotel, 3 Car, 11 ServiceTax). Veja tabela completa de TransactionTypes.
TransactionStatesNãointeger[]Lista de status das transações desejadas. Enum fixo (ex.: 2 Reserved, 4 Issued, 5 Canceled). Veja tabela completa de TransactionStates.
FilterLinkTypeNãointegerFiltro por vínculo de cesta: 0 Any, 1 OnlyWithParent, 2 OnlyWithoutParent. Enum fixo.
FilterImportStateNãointegerFiltro por status de importação: 0 Any, 1 OnlyNotImported, 2 OnlyImported. Enum fixo.
LocatorNãostringLocalizador da reserva. Se informado, dispensa DateFrom e DateTo.
TicketNãostringNúmero do bilhete emitido. Se informado, dispensa DateFrom e DateTo.
AccessCredentialsSimobjectCredenciais do ambiente (Company.Identifier e Company.Password). Veja Autenticação.

* Veja as regras de obrigatoriedade abaixo.

Detalhes de campos de controle​

OffSet: indica o fuso horário dos valores enviados em DateFrom e DateTo e das datas da resposta. Garante consistência entre sistemas que operam em fusos diferentes.

FilterDateType: define qual campo de data da transação é comparado com o intervalo DateFrom e DateTo:

  • 1 (LastUpdate): data da última alteração do registro. É a opção recomendada para rotinas de sincronização contínua.
  • 2 (Create): data de criação inicial da reserva/venda.
  • 3 (Insert): data de gravação física no banco de dados.

Tipos de busca e regras de validação​

O backend implementa validações rigorosas antes de executar a consulta:

Tipo de buscaQuando se aplicaParâmetros relevantesRegra de datasValidação no backend
1. Busca direta (por localizador ou bilhete)Quando Locator ou Ticket for preenchidoLocator ou TicketDateFrom e DateTo não são obrigatóriosA consulta localiza a transação específica. Não há limitação de intervalo de dias.
2. Busca por períodoQuando não houver Locator nem TicketDateFrom, DateTo, FilterDateType, etc.DateFrom e DateTo são OBRIGATÓRIOSO intervalo máximo permitido entre as datas é de 7 dias (diff.Days <= 7).

🛑 Atenção: Restrição de tipo de transação exclusiva

Se o array TransactionTypes contiver apenas o tipo 13 (Corporate), a API rejeita a requisição lançando a exceção:

Message: "GetList Error: invalid transation error"

O tipo Corporate não pode ser consultado isoladamente via List.

Erros de validação do List​

Cenário de falhaMensagem retornada em Errors[i].MessageCausa
Sem Locator/Ticket e sem DateFrom"GetList Error: DateFrom mandatory"Data inicial não informada na busca por período.
Sem Locator/Ticket e sem DateTo"GetList Error: DateTo mandatory"Data final não informada na busca por período.
Intervalo entre DateTo e DateFrom maior que 7 dias"GetList Error: Maximum period exceeded - 7 days"A diferença entre as datas ultrapassa o limite de 7 dias. Fracione a consulta.
TransactionTypes contendo apenas Corporate"GetList Error: invalid transation error"Consulta restrita exclusivamente a transações corporativas.

Exemplo de retorno de erro de validação:

{
  "Request": {
    "DateFrom": "2026-01-01T00:00:00Z",
    "DateTo": "2026-01-20T00:00:00Z",
    "AccessCredentials": null
  },
  "OffSet": "-03:00:00",
  "Transactions": null,
  "Errors": [
    {
      "Message": "GetList Error: Maximum period exceeded - 7 days",
      "Exception": ""
    }
  ],
  "Success": false,
  "RequestDate": "2026-10-09T09:15:30.456-03:00"
}

Resposta​

{
  "Request": {
    "DateFrom": "2022-01-08T19:41:15.75Z",
    "DateTo": "2022-01-15T19:41:15.75Z",
    "TransactionTypes": [],
    "TransactionStates": [],
    "FilterLinkType": 0,
    "FilterImportState": 1,
    "Locator": "",
    "Ticket": "",
    "AccessCredentials": null
  },
  "OffSet": "-03:00:00",
  "Transactions": [
    {
      "TransactionType": 1,
      "TransactionTypeDescription": "AirReservation",
      "Id": 14467,
      "UniqueId": "AIR-64E28584-3D4B-458F-B629-19EA16E7975D",
      "Locator": "4UQWSS",
      "Ticket": "",
      "LastUpdate": "2022-01-10T08:49:55.557",
      "TransactionState": 2,
      "TransactionStateDescription": "Reserved",
      "ImportState": 0,
      "ImportStateDescription": "Undefined",
      "Parent": null
    }
  ],
  "Errors": [],
  "Success": true,
  "RequestDate": "2022-07-15T12:16:50.8267116-03:00"
}

Estrutura raiz da resposta​

CampoTipoDescrição
RequestListRQEco dos parâmetros da requisição (as credenciais de acesso retornam null por segurança).
OffSetstringFuso horário efetivamente aplicado na resposta (ex.: "-03:00:00").
TransactionsTransactionHeader[]Lista com o resumo de cada transação encontrada. Retorna null se Success for false.
ErrorsError[]Coleção de erros. Vazio ([]) em requisições bem-sucedidas. Cada item contém Message (string) e Exception (string, vazia em produção).
SuccessbooleanAvaliado no backend como `Errors == null
RequestDatestring (date-time)Data e hora em que a requisição foi processada pelo servidor.

Campos de cada item de Transactions (TransactionHeader)​

CampoTipoDescrição
TransactionType / TransactionTypeDescriptioninteger / stringTipo da transação (Enum fixo, ex.: 1 AirReservation, 100 AirTicket, 2 Hotel, 3 Car, 11 ServiceTax).
IdintegerIdentificador numérico interno no banco de dados.
UniqueIdstringIdentificador único com prefixo da transação. Deve ser utilizado para chamar o Details e o Change. O prefixo indica o tipo do produto (AIR-..., TKT-..., TS-..., HTL-..., CAR-...).
LocatorstringLocalizador da reserva (PNR da cia aérea, voucher de hotel, localizador de carro).
TicketstringNúmero do bilhete emitido (quando aplicável).
LastUpdatestring (date-time)Data e hora da última atualização do registro.
TransactionState / TransactionStateDescriptioninteger / stringStatus atual da transação (Enum fixo, ex.: 2 Reserved, 4 Issued, 5 Canceled).
ImportState / ImportStateDescriptioninteger / stringNo cabeçalho retornado pelo List, este campo retorna fixo como 0 (Undefined) por desenho da consulta de projeção no banco de dados. O filtro de importação é aplicado diretamente na consulta SQL via FilterImportState.
ParentLinkInformações da transação "pai", caso exista vínculo (ex.: bilhete vinculado à reserva original). Contém LinkType, TransactionType, Id, UniqueId, Locator, Ticket e TransactionState.

💡 Exemplos práticos de payloads

Para visualizar amostras completas de requisição e resposta do serviço List, consulte a página Exemplos.