Referência da API
Solicitar impressão
Use o SmartPOS como uma impressora integrada ao seu sistema. Envie comprovantes, imagens e outros conteúdos diretamente para impressão, sem precisar de uma impressora adicional.
POST
/v1/print-jobsResposta inicial
202 AcceptedResposta inicialJSON
1{2 "referencia": "9f1c2d3e-4b5a-4678-9abc-0d1e2f3a4b5c",3 "status": "processando",4 "mensagem": "Impressao enviada ao SmartPOS.",5 "smartposId": "POS001",6 "targets": [7 {8 "smartposId": "POS001",9 "status": "enviado"10 }11 ]12}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 |
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.
Webhookimpressao.concluida
1{2 "id": "evt_01JZ9W7X6WV7MR9J9MGQ2YKBA2",3 "tipo": "impressao.concluida",4 "criadoEm": "2026-05-28T14:45:00Z",5 "dados": {6 "referencia": "9f1c2d3e-4b5a-4678-9abc-0d1e2f3a4b5c",7 "documentoCliente": "12345678000195",8 "status": "concluida",9 "smartposId": "POS001",10 "resultadoSmartPOS": {11 "executado": true,12 "codigoStatus": "0",13 "mensagemOperador": "Impressão concluída"14 }15 }16}Eventos
| Campo | Tipo | Descrição |
|---|---|---|
| impressao.concluida | event | Solicitação de impressão concluída. |
| impressao.falhou | event | Solicitação de impressão não concluída. |
Decisão operacional
| Campo | Tipo | Descrição |
|---|---|---|
| impressao.concluida | decisão | Registre a impressão como concluída. Este evento não altera o financeiro da venda. |
| impressao.falhou | decisão | Registre a falha de impressão. Este evento não altera o financeiro da venda. |
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.referencia | string | Referência enviada no request de impressão.obrigatório |
| dados.documentoCliente | string | CPF ou CNPJ do cliente ConnectTEF vinculado à impressão.obrigatório |
| dados.status | string | Status normalizado complementar ao tipo.obrigatório |
| dados.smartposId | string | Identificador público do SmartPOS que executou a impressão. |
| dados.resultadoSmartPOS.executado | boolean | Indica se o SmartPOS executou a solicitação antes de retornar o resultado. |
| dados.resultadoSmartPOS.codigoStatus | string | Código bruto do SmartPOS, mantido para diagnóstico e conferência. |
| dados.resultadoSmartPOS.mensagemOperador | string | Mensagem operacional retornada pelo SmartPOS para exibição ou log. |
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 da impressão está ausente ou vazio. | Revise referencia, documentoCliente, smartposId, conteudo.tipo e conteudo.base64. |
| 400 | CAMPO_INVALIDO | O conteúdo não está em Base64 válido ou algum campo excede o tamanho aceito. | Codifique o conteúdo corretamente e mantenha apenas o que precisa ser impresso. |
| 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 da impressão já foi usada em uma tentativa operacional anterior. | Se é uma nova tentativa de impressão, 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
Impressão concluída ou falha de impressão são resultados operacionais. Não use esse evento para aprovar, recusar ou estornar venda.
Seção ativa: Requisição