Pular para o conteúdo principal

Uso adequado da API Sales

Esta página descreve o que consideramos o uso adequado da API Sales. Toda integração deve seguir este fluxo: ele reduz o volume de dados trafegado, evita reprocessamento e protege a performance da plataforma para todos os clientes.

Resumo em uma frase​

Chame o List para saber o que há de novo, chame o Details para cada item, um de cada vez, e, assim que terminar de processar o item, chame o Change para marcá-lo como importado. Assim ele não volta no próximo List.

O fluxo​

1. Chame o List para descobrir o que processar​

Chame o List com um período definido (DateFrom / DateTo, com intervalo máximo de 7 dias) e com FilterImportState = 1 (OnlyNotImported). Assim, a resposta traz somente as transações que o seu sistema ainda não marcou como importadas.

{
  "DateFrom": "2026-10-01T00:00:00",
  "DateTo": "2026-10-08T00:00:00",
  "FilterDateType": 1,
  "OffSet": "-03:00:00",
  "FilterImportState": 1,
  "AccessCredentials": {
    "Company": {
      "Identifier": "{{identifier}}",
      "Password": "{{password}}"
    }
  }
}

O List retorna apenas um resumo de cada venda. O campo que importa para os próximos passos é o UniqueId (ex.: AIR-64E28584-3D4B-458F-B629-19EA16E7975D).

2. Chame o Details para cada item, um de cada vez​

Para cada UniqueId retornado, chame o Details para obter as informações completas (pagamentos, tarifas, taxas, passageiros, fornecedor etc.).

{
  "TransactionUniqueId": "AIR-64E28584-3D4B-458F-B629-19EA16E7975D",
  "OffSet": "-03:00:00",
  "AccessCredentials": {
    "Company": {
      "Identifier": "{{identifier}}",
      "Password": "{{password}}"
    }
  }
}
  • Faça uma requisição por UniqueId. Cada produto (AIR, TKT, TS, HTL, CAR…) é processado individualmente.
  • Faça as chamadas de forma sequencial ou com paralelismo baixo e controlado. Evite disparar centenas de requisições simultâneas.

3. Processe o item no seu sistema​

Grave, concilie ou exporte a venda no seu sistema, conforme a sua regra de negócio.

4. Chame o Change para marcar o item como importado​

Assim que o item for processado com sucesso, chame o Change com ImportState = 2:

{
  "TransactionUniqueId": "AIR-64E28584-3D4B-458F-B629-19EA16E7975D",
  "ImportState": 2,
  "AccessCredentials": {
    "Company": {
      "Identifier": "{{identifier}}",
      "Password": "{{password}}"
    }
  }
}

Com isso, a transação fica marcada como importada e não é mais retornada nas próximas chamadas ao List com FilterImportState = 1.

⚠️ Atenção: Só marque depois de processar

Chame o Change somente depois de concluir com sucesso a gravação ou o processamento do item no seu sistema. Se qualquer etapa falhar, não chame o Change: o item permanecerá com status "não importado" e será retornado novamente na próxima execução do List, garantindo tolerância a falhas e zero perda de vendas.

5. Repita o ciclo​

Execute o fluxo periodicamente, em uma rotina agendada (ex.: a cada 5, 10 ou 15 minutos). Como as transações já processadas não voltam mais, cada ciclo traz apenas o que é novo ou pendente.

Exemplo de implementação (pseudocódigo)​

async function sincronizarVendas() {
  // 1. O que ainda não foi importado?
  const list = await post('list', {
    DateFrom: inicioDoPeriodo,
    DateTo: fimDoPeriodo,
    FilterDateType: 1,      // LastUpdate
    FilterImportState: 1,   // OnlyNotImported
    AccessCredentials,
  });

  if (!list.Success) {
    log(list.Errors);
    return;
  }

  for (const resumo of list.Transactions) {
    try {
      // 2. Detalhes de UM item
      const details = await post('details', {
        TransactionUniqueId: resumo.UniqueId,
        AccessCredentials,
      });
      if (!details.Success) throw details.Errors;

      // 3. Processa no seu sistema
      await gravarNoMeuSistema(details.Transaction);

      // 4. Marca como importado no backend da Wooba (sai das próximas consultas)
      await post('change', {
        TransactionUniqueId: resumo.UniqueId,
        ImportState: 2,
        AccessCredentials,
      });
    } catch (erro) {
      // Sem change: o item volta no próximo ciclo
      log(resumo.UniqueId, erro);
    }
  }
}

Faça / Não faça​

✅ Faça❌ Não faça
Use sempre um período (DateFrom / DateTo) curto de no máximo 7 dias (regra validada pela API)Tentar consultar períodos superiores a 7 dias sem usar Locator ou Ticket (resulta em erro da API)
Use FilterImportState = 1 para trazer só o que ainda não foi importadoChamar o List sem filtro de importação e filtrar o resultado do seu lado
Chame o Details um item por vez, com paralelismo controladoDisparar o Details em massa e em paralelo para todos os itens
Chame o Change com ImportState = 2 logo após processar cada itemDeixar de chamar o Change, o que faz o mesmo item voltar em todo ciclo
Trate Success e Errors em todas as respostasAssumir que toda resposta foi bem-sucedida
Guarde as credenciais em variáveis de ambiente ou num cofre de segredosDeixar Identifier e Password fixos no código-fonte
Combine com o Webhook para saber quando há novidadesFazer polling agressivo do List (ex.: a cada poucos segundos)

💡 Por que este fluxo é a melhor prática?

  • Menos tráfego e alta performance: o List devolve apenas o resumo do que é novo, e o Details só é requisitado para o que realmente precisa ser gravado.
  • Sem duplicidade ou reprocessamento: a chamada de Change persiste o registro na tabela de exportação da credencial, funcionando como um checkpoint transacional.
  • Resiliência nativa: se o seu banco cair ou sua aplicação reiniciar durante o processamento, as vendas não processadas simplesmente serão reentregues no próximo ciclo.
  • Eficiência de infraestrutura: evita sobrecarregar os servidores da Wooba e previne bloqueios por taxa de requisições.