Referência da API

Criar pagamento

Cria uma intenção de pagamento no SmartPOS. A resposta inicial confirma aceite, envio ou fila; a aprovação ou recusa chega depois pelo webhook.

POST

/v1/payments

terminalcURL

1curl -X POST "https://api.connecttef.com.br/v1/payments" \2  -H "x-api-key: <sua_api_key>" \3  -H "Content-Type: application/json" \4  -d '{5    "referencia": "550e8400-e29b-41d4-a716-446655440000",6    "documentoCliente": "12345678000195",7    "smartposId": "POS001",8    "valorCentavos": 14990,9    "formaPagamento": "credito",10    "parcelas": 1,11    "modoExecucao": "imediato",12    "comprovante": {13      "imprimir": {14        "cliente": true,15        "loja": true16      },17      "visualizar": {18        "cliente": false,19        "loja": false20      }21    }22  }'

Headers

Campo	Tipo	Descrição
x-api-key	string	Chave de autenticação da integração, gerada no portal do parceiro.obrigatório
Content-Type	header	Use application/json em chamadas com body.obrigatório

Campos do body

Campo	Tipo	Descrição
referencia	string	Identificador único desta tentativa operacional. Gere uma nova referência para cada pagamento enviado à API, inclusive nova tentativa da mesma venda após cancelamento, recusa, troca de cartão ou falha de comunicação. Use um UUID começando no primeiro caractere e não coloque nada antes dele.obrigatório
documentoCliente	string	CPF ou CNPJ do cliente ConnectTEF vinculado aos SmartPOS. Envie preferencialmente somente números.obrigatório
smartposId	string	Obrigatório no modo imediato. No modo manual, pode ser omitido para publicar nos SmartPOS disponíveis do cliente.
valorCentavos	integer	Valor em centavos. Exemplo: 14990 representa R$ 149,90.obrigatório
formaPagamento	string	Opcional. Valores aceitos: credito, debito, pix ou voucher. Se omitido, o SmartPOS usa o fluxo padrão disponível.
parcelas	integer	Número de parcelas quando aplicável. Use 1 para venda à vista ou omita quando não houver parcelamento.
parcelamento	string	Obrigatório quando formaPagamento for credito e parcelas for maior que 1. Valores aceitos: estabelecimento ou administradora.
modoExecucao	string	Use imediato para iniciar no SmartPOS informado. Use manual para criar um card para o operador confirmar. Se omitido, usa imediato.
comanda	object	Dados exibidos no card da fila manual. Obrigatório somente quando modoExecucao for manual.
comprovante	object	Preferências de impressão e preview dos comprovantes do cliente e da loja.

Use referência única desde o primeiro caractere

A referência identifica a tentativa operacional enviada à API, não a venda, pedido, mesa, comanda ou cupom. Gere uma nova referência para cada tentativa, inclusive quando o operador cancelar, o pagamento for recusado, o cliente trocar o cartão ou o sistema reenviar uma nova solicitação. Algumas adquirentes podem considerar apenas os 10 primeiros caracteres; por isso, use um UUID começando no primeiro caractere e não coloque nada antes dele.

Pode usar sufixo depois do UUID, como 550e8400-e29b-41d4-a716-446655440000-INFOPET. Evite formatos como INFOPET_550e8400-e29b-41d4-a716-446655440000, _MEU_SUFIXO-550e8400-e29b-41d4-a716-446655440000, PEDIDO_0001 ou CAIXA01_0001.

Campos de comanda/manual

Campo	Tipo	Descrição
comanda.identificacao	string	Identificação exibida no card da fila manual, como nome, mesa, senha ou pedido.obrigatório
comanda.itens[].titulo	string	Título do item exibido no card.
comanda.itens[].descricao	string	Descrição complementar do item exibido no card.
comanda.endereco	string	Endereço ou contexto operacional exibido ao operador, quando fizer sentido.

Campos de comprovante

Campo	Tipo	Descrição
comprovante.imprimir.cliente	boolean	Quando true, solicita impressão do comprovante do cliente no SmartPOS.
comprovante.imprimir.loja	boolean	Quando true, solicita impressão do comprovante da loja no SmartPOS.
comprovante.visualizar.cliente	boolean	Quando true, solicita preview do comprovante do cliente, conforme disponibilidade do SmartPOS.
comprovante.visualizar.loja	boolean	Quando true, solicita preview do comprovante da loja, conforme disponibilidade do SmartPOS.

Regras de execução

Campo	Tipo	Descrição
modoExecucao imediato	regra	Inicia a cobrança no SmartPOS informado. Exige smartposId.
modoExecucao manual	regra	Cria um card para o operador iniciar depois. Pode omitir smartposId para publicar nos SmartPOS disponíveis do cliente.
comanda no manual	regra	Obrigatória quando modoExecucao for manual, pois define o conteúdo exibido ao operador.

Resposta inicial

202 Accepted

Resposta inicialimediato

1{2  "referencia": "550e8400-e29b-41d4-a716-446655440000",3  "status": "processando",4  "mensagem": "Pagamento enviado ao SmartPOS.",5  "targets": [6    {7      "smartposId": "POS001",8      "status": "enviado"9    }10  ]11}

Campos da resposta

Campo	Tipo	Descrição
referencia	string	Mesma referência enviada na requisição. Use para consultar, conciliar e deduplicar a operação.obrigatório
status	string	Estado inicial da operação. Não representa aprovação, recusa ou conclusão final.obrigatório
mensagem	string	Mensagem resumida sobre o aceite, envio ou fila inicial da operação.obrigatório
smartposId	string	SmartPOS direcionado pela operação, quando a rota retorna esse campo no nível principal.
targets	array	SmartPOS que receberam ou deveriam receber a solicitação inicial.obrigatório
targets[].smartposId	string	Identificador público do SmartPOS de destino.obrigatório
targets[].status	string	Resultado inicial de publicação para aquele SmartPOS.obrigatório

erro.jsonJSON

1{2  "erro": {3    "codigo": "API_KEY_INVALIDA",4    "mensagem": "API key invalida ou inativa.",5    "acao": "Confira se a chave foi copiada do portal do parceiro e se está ativa."6  }7}

HTTP	Código	Quando acontece	Como corrigir
400	`CAMPO_OBRIGATORIO`	Algum campo obrigatório está ausente ou vazio.	Revise referencia, documentoCliente, valorCentavos e modoExecucao antes de reenviar.
400	`CAMPO_INVALIDO`	Algum campo foi enviado com tipo, tamanho ou formato inválido.	Revise o campo indicado em erro.campo antes de reenviar.
400	`DOCUMENTO_CLIENTE_INVALIDO`	documentoCliente não é CPF/CNPJ válido ou o cliente não foi encontrado.	Confira o cadastro do cliente e envie o documento preferencialmente somente com números.
400	`VALOR_INVALIDO`	valorCentavos ou parcelas não é inteiro positivo dentro do limite aceito.	Envie valorCentavos em centavos, sem casas decimais, e parcelas como número inteiro.
400	`FORMA_PAGAMENTO_INVALIDA`	formaPagamento, parcelas ou parcelamento não formam uma combinação aceita.	Use credito, debito, pix ou voucher; em crédito parcelado, informe parcelamento.
400	`SMARTPOS_OBRIGATORIO_MODO_IMEDIATO`	modoExecucao é imediato e smartposId não foi informado.	Liste os SmartPOS do cliente, escolha um smartposId e reenvie a solicitação.
400	`COMANDA_OBRIGATORIA_MODO_MANUAL`	modoExecucao é manual e os dados de comanda não foram enviados.	Envie comanda.identificacao e os dados que devem aparecer no card do operador.
400	`WEBHOOK_NAO_CONFIGURADO`	O parceiro ainda não configurou URL de webhook.	Configure o webhook no portal do parceiro antes de iniciar operações.
401	`API_KEY_NAO_INFORMADA`	O header x-api-key não foi enviado.	Informe a chave da integração no header x-api-key.
401	`API_KEY_INVALIDA`	A chave não existe, foi rotacionada ou está inativa.	Use a chave ativa gerada no portal do parceiro.
403	`CLIENTE_NAO_AUTORIZADO`	A API key não autoriza operação para o cliente informado.	Confira se o cliente pertence ao parceiro da chave utilizada.
404	`SMARTPOS_NAO_ENCONTRADO`	smartposId não pertence ao cliente informado ou não está vinculado.	Use GET /v1/customers/{documentoCliente}/smartpos e selecione um smartposId válido.
409	`REFERENCIA_DUPLICADA`	A referência já foi usada em uma tentativa operacional anterior.	Se está consultando ou conciliando a operação já criada, reutilize o retorno salvo. Se é uma nova tentativa, gere uma nova referência.
500	`ERRO_INTERNO`	A API encontrou uma falha inesperada ao processar a solicitação.	Registre status, referência e corpo da resposta antes de acionar o suporte.

Atenção

Não finalize a venda com a resposta inicial. Finalize apenas quando receber pagamento.aprovado no webhook.

Próximo passo

Receber o resultado finalUse os webhooks para saber se o pagamento foi aprovado ou recusado.