ℹ️ Conteúdo em atualização
Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.
🔧 Troubleshooting - Venda
Este guia ajuda você a identificar e resolver problemas comuns ao integrar com as APIs de Venda em Loja Física e Venda E-commerce.
🎯 Início Rápido: Checklist de Debug
Antes de abrir um chamado de suporte, verifique:
- Token válido: Seu JWT está dentro da validade?
- Headers corretos: Header
Authorization: Bearer <token>está presente? - URL correta: Está usando HML ou PRD apropriadamente?
- Formato JSON: Body está em JSON válido?
- Campos obrigatórios: Todos os campos required foram enviados?
- NSU único: O NSU da requisição é único e não foi reutilizado?
- Working key vigente: A working key não expirou antes de criptografar a senha? (Venda Loja)
- msgId único: O
msgIdé um UUID único por requisição? (Venda Loja) - Prazo de captura: A pré-autorização foi criada há menos de 5 dias? (E-commerce)
🛒 Venda Loja
1️⃣ Consultar Limite e Situação (GET /limite-situacao)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione parâmetro: ?estabelecimento=12345 |
Campo(s) obrigatório(s) | cartao é obrigatório. | Adicione header: cartao: 1234567890123456 |
Campo(s) obrigatório(s) | valorCompra é obrigatório. | Adicione parâmetro: &valorCompra=150.00 |
Campo(s) com formato(s) inválido(s) | estabelecimento inválido, só aceita números. | Verifique se o estabelecimento contém apenas dígitos. |
Exemplo de requisição correta:
curl -X GET "https://app-bff-venda-hml.credsystem.com.br/venda-loja/api/v1/limite-situacao?estabelecimento=12345&valorCompra=150.00&isInfoPlanos=true" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "cartao: 1234567890123456" \
-H "cpf: 12345678901"
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Obtenha um novo token via endpoint de autenticação. |
Não Autorizado | Token expirado. | Tokens JWT têm validade limitada. Renove seu token. |
Como renovar o token:
- Faça nova requisição ao endpoint de autenticação
- Guarde o novo token
- Implemente lógica de renovação automática (antes de expirar)
2️⃣ Obter Working Key (GET /working-key)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Verifique o Bearer token informado. |
Não Autorizado | Authorization expirado. | Gere um novo Bearer token. |
Boas práticas com a Working Key
- Renove a working key antes de cada conjunto de transações
- Verifique o campo
dataExpiracaoantes de utilizá-la para criptografar - Nunca reutilize uma working key expirada
3️⃣ Criar Pré-autorização com Cartão (POST /pre-autorizacoes)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Dados de entrada inválidos ou não existentes | Corpo da requisição vazio ou malformado. | Verifique o payload JSON enviado. |
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | identificador é obrigatório. | Adicione no body: "identificador": "PDV01" |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "MAQ001" |
Campo(s) obrigatório(s) | usuario é obrigatório. | Adicione no body: "usuario": "vendedor01" |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Gere um NSU único de 12 dígitos numéricos. |
Campo(s) obrigatório(s) | cartao.tarja é obrigatório. | Adicione no body: "cartao": {"tarja": "1234..."} |
Campo(s) obrigatório(s) | cartao.senhaCriptografada é obrigatório. | Criptografe a senha com a working key antes de enviar. |
Campo(s) obrigatório(s) | msgId é obrigatório. | Adicione no body: "msgId": "uuid-unico" |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Verifique o Bearer token informado. |
Não Autorizado | Authorization expirado. | Gere um novo Bearer token. |
⚠️ 400 Bad Request — Motivos de Negação de Negócio
Além das validações de campos, o endpoint pode retornar 400 com os seguintes motivoNegacao:
motivoNegacao | Descrição | Solução |
|---|---|---|
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
CARTAO_BLOQUEADO | O cartão está bloqueado. | Oriente o cliente a contatar a central do cartão. |
CARTAO_CANCELADO | O cartão foi cancelado. | Solicite cartão ativo ao cliente. |
CARTAO_VALIDADE_INVALIDA | Validade do cartão inválida. | Solicite cartão com validade vigente. |
CARTAO_CVV_NAO_CONFERE | CVV não confere. | Verifique o CVV com o cliente. |
CARTAO_NAO_LOCALIZADO | Cartão não encontrado na base. | Confirme os dados do cartão. |
CARTAO_NAO_AUTORIZADO | Cartão sem autorização. | Consulte o suporte Credsystem. |
VALOR INVALIDO | Valor da venda inválido. | Verifique o campo venda.valor. |
PLANO OU PARCELAMENTO NAO DISPONIVEL | Plano ou parcelamento não disponível. | Consulte os planos via GET /limite-situacao. |
PLANO_NAO_LOCALIZADO | Código de plano não encontrado. | Use plano retornado pelo GET /limite-situacao. |
NEGADO_PREVENCAO_AUTORIZACAO | Negado por prevenção. | Consulte o suporte Credsystem. |
VOUCHER_NAO_LOCALIZADO | Voucher não encontrado. | Verifique o campo cartao.voucher. |
VOUCHER_EXPIRADO | Voucher fora do prazo de validade. | Solicite novo voucher. |
PREAUTORIZACAO_VOUCHER_CRIPTOGRAFADO_UTILIZADO | Voucher criptografado já utilizado. | Gere nova pré-autorização. |
FORMATO DE SENHA CRIPTOGRADA INVALIDO | Senha em formato inválido. | Verifique o processo de criptografia com a working key. |
Senha inválida. | Senha incorreta para o cartão. | Criptografe a senha corretamente. |
Falha na tradução da senha. | Erro ao traduzir senha. | Obtenha nova working key e recriptografe. |
A SENHA NÃO ESTA PRESENTE | Campo senhaCriptografada ausente. | Adicione a senha criptografada no body. |
ERRO DE LEITURA NA TARJA MAGNETICA | Dados da tarja com erro. | Verifique o campo cartao.tarja. |
Dica: Sempre consulte o limite e obtenha a working key imediatamente antes de criar a pré-autorização para evitar negativas por dados desatualizados.
4️⃣ Criar Pré-autorização com Biometria (POST /pre-autorizacoes/biometria)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | cpf é obrigatório. | Adicione no body: "cpf": "12345678901" |
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Gere um NSU único de 12 dígitos numéricos. |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "MAQ001" |
Campo(s) obrigatório(s) | identificador é obrigatório. | Adicione no body: "identificador": "PDV01" |
Campo(s) com formato(s) inv álido(s) | CPF inválido. | Informe CPF com 11 dígitos numéricos sem máscara. |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 400 Bad Request — Motivos de Negação de Negócio
Além das validações de campos, o endpoint pode retornar 400 com os seguintes motivoNegacao:
motivoNegacao | Descrição | Solução |
|---|---|---|
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
CPF_INVALIDO | CPF informado é inválido. | Informe CPF com 11 dígitos sem máscara. |
CLIENTE NAO CADASTRADO NA BASE (COMPRA SEM CARTAO) | CPF não encontrado na base. | Confirme o CPF do cliente. |
VALOR_INVALIDO | Valor da venda inválido. | Verifique o campo venda.valor. |
CARTAO NAO LOCALIZADO | Cartão não encontrado. | Confirme os dados do CPF informado. |
PLANO_OU_PARCELAMENTO_NAO_DISPONIVEL | Plano não disponível. | Consulte os planos via GET /limite-situacao. |
LOJA_NAO_LOCALIZADA_INATIVA_OU_NAO_PERMITIDA | Estabelecimento não localizado, inativo ou sem permissão. | Verifique o código do estabelecimento. |
CARTAO_CANCELADO | Cartão cancelado. | Solicite cartão ativo ao cliente. |
PRE_VENDA_NAO_AUTORIZADA | Pré-venda não autorizada. | Consulte o suporte Credsystem. |
ERRO_AO_GERAR_VOUCHER | Erro ao gerar voucher de biometria. | Tente novamente. Se persistir, consulte o suporte. |
ERRO_AO_ACIONAR_SERVICO_VOUCHER | Falha ao acionar serviço de voucher. | Verifique disponibilidade do serviço. |
NUMERO_VOUCHER_INVALIDO | Número de voucher inválido. | Verifique o campo voucher. |
5️⃣ Consultar Status da Pré-autorização (GET /pre-autorizacoes/sonda/{preautorizacao})
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Parâmetro obrigatório ausente | O identificador preautorizacao não foi informado na URL. | Inclua o número na URL: /pre-autorizacoes/sonda/789012 |
Exemplo de requisição correta:
curl -X GET "https://app-bff-venda-hml.credsystem.com.br/venda-loja/api/v1/pre-autorizacoes/sonda/789012" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Obtenha um novo token via endpoint de autenticação. |
Não Autorizado | Token expirado. | Renove seu token antes de tentar novamente. |
Pré-autorização não localizada ou cancelada
A API retorna 200 OK com motivoNegacao no body quando a pré-autorização não está disponível:
motivoNegacao | Situação |
|---|---|
PRE_AUTORIZACAO_NAO_LOCALIZADA | Pré-autorização não encontrada — verifique o número. |
PRE_AUTORIZACAO_CANCELADA | Pré-autorização já cancelada. |
CONTATO CANCELADO | Contato cancelado. |
6️⃣ Capturar Venda (POST /pre-autorizacoes/captura)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | preAutorizacao é obrigatório. | Adicione no body: "preAutorizacao": 789012 |
Campo(s) obrigatório(s) | numeroPedido é obrigatório. | Adicione no body: "numeroPedido": "PED-2025-001" |
Campo(s) obrigatório(s) | valor é obrigatório. | Adicione no body: "valor": 150.00 |
Dados de entrada inválidos | Corpo da requisição vazio ou malformado. | Verifique o Content-Type e o payload JSON. |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 400 Bad Request — Motivos de Negação de Negócio
Além das validações de campos, o endpoint pode retornar 400 com os seguintes motivoNegacao:
motivoNegacao | Descrição | Solução |
|---|---|---|
PARAMETROS_ENTRADA_INVALIDOS | Parâmetros de entrada inválidos. | Verifique o payload enviado. |
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
PREAUTORIZACAO_NAO_ENCONTRADA | Pré-autorização não encontrada. | Confirme o número retornado na criação. |
PREAUTORIZACAO_JA_CAPTURADA | Pré-autorização já capturada. | Evite capturar duas vezes a mesma pré-autorização. |
PREAUTORIZACAO_CANCELADA | Pré-autorização foi cancelada. | Crie uma nova pré-autorização. |
BIOMETRIA_NAO_CAPTURADA | Biometria não foi capturada. | Oriente o cliente a completar o processo biométrico. |
7️⃣ Desfazer Venda (POST /pre-autorizacoes/desfazimento)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | tarja é obrigatório. | Adicione no body: "tarja": "1234567890123456" |
Campo(s) obrigatório(s) | valor é obrigatório. | Adicione no body: "valor": 150.00 |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Adicione no body: "nsu": "123456789012" |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "MAQ001" |
Campo(s) obrigatório(s) | cpf é obrigatório. | Adicione no body: "cpf": "12345678901" |
Campo(s) obrigatório(s) | cartao é obrigatório. | Adicione no body: "cartao": "1234567890123456" |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Resposta de erro
O endpoint retorna 400 com {"mensagem": "NAO_AUTORIZADO"} para erros de autorização.
Dica: O NSU deve ser idêntico ao utilizado na transação original. Guarde o NSU em seu sistema após cada transação bem-sucedida.
8️⃣ Cancelar Contrato (POST /contrato/cancelamento)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | identificador é obrigatório. | Adicione no body: "identificador": "PDV01" |
Campo(s) obrigatório(s) | contrato é obrigatório. | Adicione no body: "contrato": "456789" |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "MAQ001" |
Campo(s) obrigatório(s) | cartao é obrigatório. | Adicione no body: "cartao": "1234567890123456" |
Campo(s) obrigatório(s) | tarja é obrigatório. | Adicione no body: "tarja": "1234567890123456" |
Campo(s) obrigatório(s) | cpf é obrigatório. | Adicione no body: "cpf": "12345678901" |
Campo(s) com formato(s) inválido(s) | CPF inválido. | Informe CPF com 11 dígitos numéricos sem máscara. |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Motivos de Negação (motivoNegacao):
motivoNegacao | Descrição | Solução |
|---|---|---|
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
CANCELAMENTO_NAO_PERMITIDO | Cancelamento não permitido para este contrato. | Consulte as regras de cancelamento. |
VOUCHER_NAO_LOCALIZADO | Voucher não encontrado. | Verifique o campo voucher. |
VOUCHER_FORA_DA_VALIDADE | Voucher fora do prazo de validade. | Solicite novo voucher. |
CONTRATO_NAO_LOCALIZADO | Contrato não encontrado. | Confirme o número do contrato. |
🌐 Venda E-commerce
1️⃣ Consultar Limite e Situação (GET /limite-situacao)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione parâmetro: ?estabelecimento=12345 |
Campo(s) obrigatório(s) | cartao é obrigatório. | Adicione header: cartao: 1234567890123456 |
Campo(s) obrigatório(s) | valorCompra é obrigatório. | Adicione parâmetro: &valorCompra=250.00 |
Campo(s) com formato(s) inválido(s) | estabelecimento inválido, só aceita números. | Verifique se o estabelecimento contém apenas dígitos. |
Exemplo de requisição correta:
curl -X GET "https://app-bff-venda-hml.credsystem.com.br/venda-ecommerce/api/v1/limite-situacao?estabelecimento=12345&valorCompra=250.00&isInfoPlanos=true" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "cartao: 1234567890123456" \
-H "cpf: 12345678901"
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Obtenha um novo token via endpoint de autenticação. |
Não Autorizado | Token expirado. | Tokens JWT têm validade limitada. Renove seu token. |
Como renovar o token:
- Faça nova requisição ao endpoint de autenticação
- Guarde o novo token
- Implemente lógica de renovação automática (antes de expirar)
2️⃣ Criar Pré-autorização com Cartão (POST /pre-autorizacoes)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Dados de entrada inválidos ou não existentes | Corpo da requisição vazio ou malformado. | Verifique o payload JSON enviado. |
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | cartao.numero é obrigatório. | Adicione no body: "cartao": { "numero": "1234..." } |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Gere um NSU único de 12 dígitos numéricos. |
Campo(s) obrigatório(s) | venda.valor é obrigatório. | Adicione no body: "venda": { "valor": 250.00, ... } |
Campo(s) com formato(s) inválido(s) | Validade do cartão inválida. | Use formato MM/AAAA, ex: "validade": "12/2028" |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Verifique o Bearer token informado. |
Não Autorizado | Authorization expirado. | Gere um novo Bearer token. |
⚠️ 400 Bad Request — Motivos de Negação de Negócio
Além das validações de campos, o endpoint pode retornar 400 com os seguintes motivoNegacao:
motivoNegacao | Descrição | Solução |
|---|---|---|
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
CARTAO_BLOQUEADO | O cartão está bloqueado. | Oriente o cliente a contatar a central do cartão. |
CARTAO_CANCELADO | O cartão foi cancelado. | Solicite cartão ativo ao cliente. |
CARTAO_VALIDADE_INVALIDA | Validade do cartão inválida. | Solicite cartão com validade vigente. |
CARTAO_CVV_NAO_CONFERE | CVV não confere. | Verifique o CVV com o cliente. |
CARTAO_NAO_LOCALIZADO | Cartão não encontrado. | Confirme os dados do cartão. |
CARTAO_NAO_AUTORIZADO | Cartão sem autorização. | Consulte o suporte Credsystem. |
VALOR INVALIDO | Valor da venda inválido. | Verifique o campo venda.valor. |
PLANO OU PARCELAMENTO NAO DISPONIVEL | Plano não disponível. | Consulte GET /limite-situacao. |
PLANO_NAO_LOCALIZADO | Código de plano não encontrado. | Use plano retornado pelo GET /limite-situacao. |
NEGADO_PREVENCAO_AUTORIZACAO | Negado por prevenção. | Consulte o suporte Credsystem. |
ERRO DE LEITURA NA TARJA MAGNETICA | Erro nos dados do cartão. | Verifique os dados fornecidos. |
Dica: Sempre consulte o limite do cartão antes de criar uma pré-autorização para evitar negativas desnecessárias.
3️⃣ Criar Pré-autorização com Token (POST /pre-autorizacoes/token)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | cpf é obrigatório para autenticação por token. | Adicione no body: "cpf": "12345678901" |
Campo(s) obrigatório(s) | token é obrigatório. | Adicione no body: "token": "123456" |
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Gere um NSU único de 12 dígitos numéricos. |
Campo(s) com formato(s) inválido(s) | CPF inválido. | Informe CPF com 11 dígitos numéricos sem máscara. |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Verifique o Bearer token informado. |
Não Autorizado | Authorization expirado. | Gere um novo Bearer token. |
4️⃣ Consultar Status da Pré-autorização (GET /pre-autorizacoes/sonda/{preautorizacao})
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Parâmetro obrigatório ausente | O identificador preautorizacao não foi informado na URL. | Inclua o número na URL: /pre-autorizacoes/sonda/789012 |
Exemplo de requisição correta:
curl -X GET "https://app-bff-venda-hml.credsystem.com.br/venda-ecommerce/api/v1/pre-autorizacoes/sonda/789012" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
⚠️ 401 Unauthorized
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Authorization inválido | Informe o token de autorização válido. | Obtenha um novo token via endpoint de autenticação. |
Não Autorizado | Token expirado. | Renove seu token antes de tentar novamente. |
Pré-autorização não localizada ou cancelada
A API retorna 200 OK com motivoNegacao no body quando a pré-autorização não está disponível:
motivoNegacao | Situação |
|---|---|
PRE_AUTORIZACAO_NAO_LOCALIZADA | Pré-autorização não encontrada — verifique o número. |
PRE_AUTORIZACAO_CANCELADA | Pré-autorização já cancelada. |
CONTATO CANCELADO | Contato cancelado. |
5️⃣ Capturar Venda (POST /pre-autorizacoes/captura)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | preAutorizacao é obrigatório. | Adicione no body: "preAutorizacao": 789012 |
Campo(s) obrigatório(s) | numeroPedido é obrigatório. | Adicione no body: "numeroPedido": "PED-2025-001" |
Campo(s) obrigatório(s) | valor é obrigatório. | Adicione no body: "valor": 250.00 |
Dados de entrada inválidos | Corpo da requisição vazio ou malformado. | Verifique o Content-Type e o payload JSON. |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 400 Bad Request — Motivos de Negação de Negócio
Além das validações de campos, o endpoint pode retornar 400 com os seguintes motivoNegacao:
motivoNegacao | Descrição | Solução |
|---|---|---|
PARAMETROS_ENTRADA_INVALIDOS | Parâmetros de entrada inválidos. | Verifique o payload enviado. |
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
PREAUTORIZACAO_NAO_ENCONTRADA | Pré-autorização não encontrada. | Confirme o número retornado na criação. |
PREAUTORIZACAO_JA_CAPTURADA | Pré-autorização já capturada. | Evite capturar duas vezes a mesma pré-autorização. |
PREAUTORIZACAO_CANCELADA | Pré-autorização foi cancelada. | Crie uma nova pré-autorização. |
6️⃣ Cancelar Contrato (POST /contrato/cancelamento)
⚠️ 400 Bad Request
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | identificador é obrigatório. | Adicione no body: "identificador": "PDV01" |
Campo(s) obrigatório(s) | contrato é obrigatório. | Adicione no body: "contrato": "456789" |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "MAQ001" |
Campo(s) obrigatório(s) | cartao é obrigatório. | Adicione no body: "cartao": "1234567890123456" |
Campo(s) obrigatório(s) | tarja é obrigatório. | Adicione no body: "tarja": "1234567890123456" |
Campo(s) obrigatório(s) | cpf é obrigatório. | Adicione no body: "cpf": "12345678901" |
Campo(s) com formato(s) inválido(s) | CPF inválido. | Informe CPF com 11 dígitos numéricos sem máscara. |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Motivos de Negação (motivoNegacao):
motivoNegacao | Descrição | Solução |
|---|---|---|
NAO_AUTORIZADO | Token inválido ou sem permissão. | Verifique o Bearer token. |
CANCELAMENTO_NAO_PERMITIDO | Cancelamento não permitido para este contrato. | Consulte as regras de cancelamento. |
VOUCHER_NAO_LOCALIZADO | Voucher não encontrado. | Verifique o campo voucher. |
VOUCHER_FORA_DA_VALIDADE | Voucher fora do prazo de validade. | Solicite novo voucher. |
CONTRATO_NAO_LOCALIZADO | Contrato não encontrado. | Confirme o número do contrato. |
7️⃣ Desfazer Venda (POST /desfazimento/cartao e POST /desfazimento/token)
⚠️ 400 Bad Request — Desfazimento com Cartão
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | valor é obrigatório. | Adicione no body: "valor": 250.00 |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Adicione no body: "nsu": "123456789012" |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "ECOM001" |
Campo(s) obrigatório(s) | cartao é obrigatório. | Adicione no body: "cartao": "1234567890123456" |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
⚠️ 400 Bad Request — Desfazimento com Token
Possíveis Causas:
| Título | Detalhe | Solução |
|---|---|---|
Campo(s) obrigatório(s) | estabelecimento é obrigatório. | Adicione no body: "estabelecimento": "12345" |
Campo(s) obrigatório(s) | valor é obrigatório. | Adicione no body: "valor": 250.00 |
Campo(s) obrigatório(s) | nsu é obrigatório e deve ter 12 dígitos. | Adicione no body: "nsu": "123456789012" |
Campo(s) obrigatório(s) | codigoMaquina é obrigatório. | Adicione no body: "codigoMaquina": "ECOM001" |
Campo(s) obrigatório(s) | token é obrigatório. | Adicione no body: "token": "123456" |
Campo(s) obrigatório(s) | cpf é obrigatório. | Adicione no body: "cpf": "12345678901" |
Authorization é obrigatório | Informe o token de autorização válido. | Adicione header: Authorization: Bearer <seu_token> |
Resposta de erro
O endpoint retorna 400 com {"mensagem": "NAO_AUTORIZADO"} para erros de autorização.
Dica: O NSU deve ser idêntico ao utilizado na transação original. Guarde o NSU em seu sistema após cada transação bem-sucedida.
🌐 Ambientes
| Ambiente | API | URL Base |
|---|---|---|
| Homologação | Venda Loja | https://apihml.credsystem.com.br/venda-loja/api/v1 |
| Produção | Venda Loja | https://api.credsystem.com.br/venda-loja/api/v1 |
| Homologação | Venda E-commerce | https://apihml.credsystem.com.br/venda-ecommerce/api/v1 |
| Produção | Venda E-commerce | https://api.credsystem.com.br/venda-ecommerce/api/v1 |
Ambiente correto
Sempre confirme que está usando a URL do ambiente correto. Transações em HML não afetam dados reais de produção.
📞 Contato com Suporte
Se o problema persistir após seguir este guia:
Informações para incluir no chamado:
- TraceId da requisição com erro
- Timestamp de quando ocorreu
- Endpoint que estava sendo acessado
- Dados enviados (remova informações sensíveis)
- Resposta recebida (completa)
- Ambiente (HML ou PRD)
- Passos para reproduzir o problema
Canais de Contato:
Tempo de Resposta:
- 🔴 Crítico (produção parada): 2 horas
- 🟡 Alto (funcionalidade impactada): 8 horas
- 🟢 Normal (dúvidas, melhorias): 24 horas
📊 Status da API
Para verificar o status em tempo real da API:
🔗 Status Page (se disponível)