Respostas e erros¶

Como a resposta é entregue¶

A API devolve o retorno como texto, no formato do fornecedor de cada produto. Não existe uma estrutura única entre produtos: cada consulta tem seus próprios campos. Já um mesmo produto mantém o mesmo formato de uma chamada para outra.

Os formatos que você pode receber são:

Formato	Como identificar
JSON	O corpo começa com `{` ou `[`
XML	O corpo começa com `<` e não contém `<!--BLOCO-->`
Blocos	Vários trechos separados por `<!--BLOCO-->`, às vezes dentro de `<ConsultaIntegrada>…</ConsultaIntegrada>`. Cada bloco segue o formato da sua fonte
Confirmação de pedido	Produtos marcados como processamento posterior devolvem a confirmação do pedido, não o resultado final

Como tratar o retorno¶

Leia o corpo como texto. Não use um parser fixo antes de saber o formato.
Verifique se é um erro da SuiteCred (estrutura abaixo).
Guarde o retorno bruto junto com produtoID, documento consultado e data. Ele serve de comprovante, evita repetir uma consulta já cobrada e permite reprocessar depois.
Interprete conforme o formato do produto.

PHPNode.js

function interpretarResposta($corpo)
{
    $corpo = trim($corpo);
    $json  = json_decode($corpo, true);

    if (is_array($json) && isset($json['suite']['erro']) && $json['suite']['erro']) {
        return ['ok' => false, 'erro' => $json['suite']['mensagem'], 'bruto' => $corpo];
    }
    if (is_array($json)) {
        return ['ok' => true, 'formato' => 'json', 'dados' => $json, 'bruto' => $corpo];
    }
    if (strpos($corpo, '<!--BLOCO-->') !== false) {
        $blocos = array_values(array_filter(array_map('trim', explode('<!--BLOCO-->', $corpo))));
        return ['ok' => true, 'formato' => 'blocos', 'dados' => $blocos, 'bruto' => $corpo];
    }
    if (substr($corpo, 0, 1) === '<') {
        return ['ok' => true, 'formato' => 'xml', 'dados' => $corpo, 'bruto' => $corpo];
    }
    return ['ok' => true, 'formato' => 'texto', 'dados' => $corpo, 'bruto' => $corpo];
}

function interpretarResposta(corpo) {
  corpo = corpo.trim();
  let json = null;
  try { json = JSON.parse(corpo); } catch (_) {}

  if (json && json.suite && json.suite.erro) {
    return { ok: false, erro: json.suite.mensagem, bruto: corpo };
  }
  if (json) return { ok: true, formato: 'json', dados: json, bruto: corpo };
  if (corpo.includes('<!--BLOCO-->')) {
    const blocos = corpo.split('<!--BLOCO-->').map((b) => b.trim()).filter(Boolean);
    return { ok: true, formato: 'blocos', dados: blocos, bruto: corpo };
  }
  if (corpo.startsWith('<')) return { ok: true, formato: 'xml', dados: corpo, bruto: corpo };
  return { ok: true, formato: 'texto', dados: corpo, bruto: corpo };
}

Antes de entrar em produção¶

Como os campos variam por produto, faça uma consulta de teste para cada produto que você vai usar e mapeie no seu sistema os campos que interessam. Combine com a SuiteCred os documentos de teste, porque toda consulta é cobrada.

statusConsulta¶

Quando o retorno traz o campo statusConsulta, o valor "0" indica consulta feita com sucesso e "9" indica erro.

Erros¶

Erros de validação, autenticação, saldo e limite retornam este JSON:

{
  "suite": {
    "produto": "localizepf",
    "produtoID": "5",
    "mensagem": "Distribuidor - Chave não preenchida",
    "erro": true,
    "protocolo": "",
    "data": "20/10/2026 14:32:10",
    "documento": "",
    "statusConsulta": "9"
  }
}

Verifique o corpo, não só o status HTTP

Os erros acima são entregues com HTTP 200. Para saber se a consulta falhou, verifique se existe suite.erro = true ou statusConsulta = "9".

Mensagens conhecidas¶

Mensagem	Causa	O que fazer
`Distribuidor - Chave não preenchida`	Parâmetro `chave` ausente	Envie a chave
`Distribuidor - Senha não preenchida`	Parâmetro `senha` ausente	Envie a senha em MD5
`Distribuidor - Metodo não preenchida`	Parâmetro `metodo` ausente	Envie o `metodo` do produto
`Distribuidor - produtoID não preenchida`	Parâmetro `produtoID` ausente	Envie o `produtoID` do produto
`CI: Usuário ou Senha Invalidos`	Chave ou senha incorretas	Confira a chave, o MD5 da senha e o `typePass=1`
`CI: Cliente não encontrado`	Credencial sem cliente ativo vinculado	Fale com a SuiteCred
`ERROR: Distribuidor - Chave ou Senha Invalidos adm`	Credencial inválida na verificação de saldo	Confira chave e senha
`1 - Você não tem saldo…` / `2 - Você não tem saldo…`	Conta pré-paga sem saldo suficiente	Adicione saldo
`WSADM: Você não tem limite para fazer consultas, entrar em contato.`	Conta pós-paga sem limite disponível	Fale com a SuiteCred
`O cliente precisa ser verificado para consultar`	Produto exige cadastro verificado	Conclua a verificação do cadastro

Erros vindos do fornecedor da consulta chegam no formato do próprio produto, com statusConsulta igual a 9 quando houver.