Referência da API
Gerar QR Code
Cria um QR Code para identificar o SmartPOS do cliente. Depois da leitura no ConnectTEF, a API envia o smartposId para o webhook configurado.
POST
/qrcodeResposta inicial
201 CreatedResposta inicialJSON
1{2 "qrCode": "QR#22b02ed1-fe3c-42b5-9caa-b28f42829a92",3 "referencia": "loja-123-pdv-001",4 "expiresAt": 17877218485}Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| qrCode | string | Valor que deve ser convertido em QR Code visual e exibido na tela do seu sistema.obrigatório |
| referencia | string | Mesma referência enviada na criação do QR Code.obrigatório |
| expiresAt | timestamp Unix | Momento em que o QR Code deixa de ser válido.obrigatório |
Responda antes de processar
Salve o evento e retorne HTTP 2xx rapidamente dentro de 1 ou 2 segundos no máximo. A conclusão da venda ou pedido, conciliação ou emissão fiscal devem rodar depois, fora do request do webhook.
Evento recebido
Use o campo tipo para decidir o estado da operação no seu sistema.
Webhooksmartpos.identificado
1{2 "id": "evt_qrcode_1",3 "tipo": "smartpos.identificado",4 "criadoEm": "2026-05-22T18:00:00.000Z",5 "dados": {6 "qrCodeId": "QRID-001",7 "referencia": "caixa-01",8 "documentoCliente": "12345678000195",9 "smartposId": "POS001",10 "numeroSerieTerminal": "POS001",11 "adquirente": "REDE"12 }13}Eventos
| Campo | Tipo | Descrição |
|---|---|---|
| smartpos.identificado | event | SmartPOS identificado após leitura do QR Code. |
Decisão operacional
| Campo | Tipo | Descrição |
|---|---|---|
| smartpos.identificado | decisão | Salve dados.smartposId e vincule ao cliente para direcionar as próximas operações para essa maquininha. |
Propriedades do evento
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | Identificador único do evento. Use para idempotência, inclusive em reenvio manual.obrigatório |
| tipo | string | Evento interpretado pelo ConnectTEF. Este é o campo principal para decidir o que fazer no sistema comercial.obrigatório |
| criadoEm | string ISO 8601 | Data e hora em que o ConnectTEF gerou o evento.obrigatório |
| dados.qrCodeId | string | Identificador interno do QR Code lido pelo SmartPOS.obrigatório |
| dados.referencia | string | Referência enviada pelo ERP, PDV ou automação comercial ao gerar o QR Code.obrigatório |
| dados.documentoCliente | string | CPF ou CNPJ do cliente ConnectTEF vinculado ao SmartPOS identificado.obrigatório |
| dados.smartposId | string | Identificador público do SmartPOS. Salve este valor para direcionar as próximas operações.obrigatório |
| dados.numeroSerieTerminal | string | Número de série informado pelo SmartPOS, quando disponível. |
| dados.adquirente | string | Adquirente informada pelo SmartPOS, quando disponível. |
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 | documentoCliente não foi enviado ou está vazio. | Envie o CPF ou CNPJ do cliente cadastrado no campo documentoCliente. |
| 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 identificação para o cliente informado. | Confira se o cliente pertence ao parceiro da chave utilizada. |
| 500 | ERRO_INTERNO | A API encontrou uma falha inesperada ao criar o QR Code. | Registre o status e o corpo da resposta e acione o suporte se o erro persistir. |
Seção ativa: Requisição