Códigos de Resposta e de Erro

Esta referência descreve os códigos de resposta e de erro usados pelas operações do POS Integrado. Todas as operações retornam pelo menos um Code numérico e uma Message.

O que são códigos de resposta e de erro

Toda operação do POS Integrado retorna uma resposta com um Code numérico (Int) e uma Message (String).

Todos os valores listados abaixo são retornados no mesmo campo Code. A categorização em “Códigos de Resposta” e “Códigos de Erro” existe somente para clareza da documentação e agrupamento lógico.

Estrutura da resposta

Todas as operações retornam uma resposta estruturada contendo, no mínimo:

Campo	Tipo	Descrição
`Code`	String	Código de resposta (veja a tabela abaixo).
`Message`	String	Resultado legível por humanos.

Um código de resposta 0 indica sucesso.

Códigos de resposta comuns

Código	Descrição
0	Operação executada com sucesso
1	Operação negada
2	Operação cancelada pelo usuário
3	Erro encontrado durante o processamento da operação
4	Erro desconhecido – verifique os detalhes da mensagem
5	POS Integrado ainda no status WAITING_CONFIRMATION. Envie um comando Polling para iniciar.
6	Operação de cancelamento executada com sucesso

Os códigos 2 e 6 tratam de cancelamento, mas significam coisas diferentes. O 2 (Operação cancelada pelo usuário) é retornado por um comando — Sale, Refund ou Pre-authorization — que foi abortado. O 6 (Operação de cancelamento executada com sucesso) é retornado pelo próprio comando Cancel. Ambos valem para o modo SDK (USB / HTTP) e para o modo Cloud2Cloud.

O código 5 indica que o terminal precisa restabelecer a conexão (por exemplo, após uma reinicialização ou queda do enlace). Execute o Polling novamente no mesmo Connector, reenvie os parâmetros de configuração e tente o comando outra vez. Consulte Polling e reconexão.

Quando Code é 3 para Sale, Refund, Pre-authorization ou Shift, o campo Message é uma string codificada em JSON que descreve as validações que falharam. Consulte Erros de Validação.

Códigos de erro para o modo POS Integrado

Esses códigos geralmente aparecem em cenários de ativação, reconexão ou perda de conexão.

A tabela abaixo lista todos os códigos de erro definidos no manual.

Código	Descrição
`1-500`	O terminal não conseguiu inicializar corretamente as dependências para abrir a porta serial.
`1-501`	Problema de conectividade ao tentar configurar a conexão Wi-Fi. Verifique se o Wi-Fi está habilitado no terminal.
`1-502`	Erro ao tentar abrir a porta serial do terminal.
`1-503`	O usuário solicitou sair do Modo POS Integrado.
`A-503`	A conexão Wi-Fi ou USB foi finalizada inesperadamente enquanto a aplicação escutava os comandos.
`A-504`	O usuário está tentando sair do Modo POS Integrado, mas a aplicação não conseguiu encerrar a comunicação.
`A-505`	Uma desconexão de interface foi detectada e o Modo POS Integrado foi desconectado.
`G-XXXX`	Erros relacionados ao Provedor de Integração em Nuvem, como o G-Services.
`S-100`	Houve um erro interno no POS ou uma desconexão de interface, e a comunicação foi interrompida.

Para códigos relacionados a conexão (por exemplo, A-503, A-504, A-505, S-100), siga o fluxo de reconexão descrito nos Conceitos Principais. Não presuma que o Connector continua válido.

Códigos de status de transação

Retornados no campo Status de uma resposta de CheckStatus. Eles descrevem o estado de uma transação anterior, não o resultado do próprio comando CheckStatus — esse resultado fica em Code.

Código de status	Nome do status	Descrição
0	`APPROVED`	Transação capturada. Usado para vendas com cartão padrão e QR Code com cartão.
1	`AUTHORIZED`	Transação autorizada (pré-autorização ou QR PCT).
2	`REFUNDED`	Transação reembolsada (D+1).
3	`CANCELED`	Transação cancelada (D+0).
4	`REVERSED`	Transação revertida (desfeita).
5	`NOT_FOUND`	Nenhuma transação encontrada para o `CallerId` informado.
6	`UNKNOWN`	Status não mapeado.

Os meios de pagamento por QR Code se comportam de forma diferente. Transações QR PCT (Point of Capture) sempre retornam AUTHORIZED e nunca APPROVED. O QR Code com cartão segue o mesmo comportamento de uma venda com cartão padrão.

Diretrizes de tratamento de erros

Sempre verifique o Code da resposta antes de prosseguir (por exemplo, 0 = sucesso).
Não repita operações às cegas; revalide o estado do terminal com Polling após erros.
Para o código 5, envie um comando Polling antes de continuar.
Para erros relacionados a conexão, siga as instruções de reconexão nesta documentação.

Recursos relacionados

Polling e reconexão — Quando fazer o polling e como recuperar.