Pular para o conteúdo principal

Problemas Conhecidos e Dicas (Gotchas)

A API da Equals possui alguns comportamentos específicos que podem causar confusão durante a integração inicial. Este guia consolida as melhores práticas para lidar com eles.

Comportamentos Confirmados (Dados Reais)​

Baseado em exemplos reais fornecidos, os seguintes comportamentos estão confirmados:

CaracterísticaConfirmação
Datas em formato numéricoYYYYMMDD (ex: 20260330)
Horas em formato numéricoHHMMSS (ex: 152448)
Chaves em UPPERCASEDTMOVIMENTO, VLBRUTO, IDMOVIMENTO
Sinal "N/A" para vendasMovimentos A1 têm SINAL: "N/A"
Sinal "C" para créditosMovimentos D1/D2 têm SINAL: "C"
Pix suportadoBANDEIRA: "Pix", IDBANDEIRA: 135
Campo NRPEDIDO em A1Presente apenas em vendas
Campo PEDIDOADQ em D1/D2Presente apenas em financeiro

Formatos de Data e Hora​

Tipagem Dinâmica (Atenção!)​

Diferente de APIs tradicionais, a tipagem dos campos de data e hora na Equals Connect é dinâmica e depende do valor retornado.

Guia Essencial: Veja a Regra Universal de Tipagem para entender como tratar qualquer campo da API de forma segura.

  • Comportamento: Se o valor começar com zero (ex: hora 09:48:22), ele virá como String ("094822"). Se não (ex: hora 13:51:47), virá como Number (135147).
  • Ação: NUNCA assuma que o campo é apenas Number ou apenas String. Sempre converta para String e use padStart antes de processar.

2. Inconsistência na Caixa das Chaves (Case Sensitivity)​

Embora o padrão confirmado seja UPPERCASE, algumas rotas ou versões da API podem retornar campos em camelCase ou snake_case.

  • Problema: record.DTMOVIMENTO pode ser undefined se a API retornar dtMovimento.
  • Solução: Utilize um Wrapper de Normalização que converte todas as chaves para maiúsculas antes de processar.

3. Sandbox: Status Fixo​

No ambiente Sandbox, as remessas geralmente ficam presas no status EM_PROCESSAMENTO.

  • Dica: Não espere pelo status CONCLUIDO no Sandbox. Assim que receber o ID da remessa, você já pode tentar chamar equals_connect_baixar_remessa.

4. Diferença entre A1, D1 e D2​

  • A1 (Venda): É apenas uma previsão. O dinheiro ainda não caiu.
  • D1 (Pagamento): É o depósito efetivo na sua conta na data prevista.
  • D2 (Antecipação): O dinheiro caiu antes do esperado (com taxa de antecipação).

Wrapper de Normalização Recomendado​

Para evitar bugs, implemente uma classe normalizadora no seu projeto. Veja o arquivo normalizer.ts para uma implementação de referência.

Este conteúdo foi útil para você?