Conector POS

Como funciona

1. Você cria um terminal e recebe um código de 6 dígitos. O operador digita o código no app GetPrime da maquininha, em modo integração.
2. Na hora da venda, você cria uma cobrança para aquele terminal. A maquininha pega a cobrança em segundos e mostra o valor ao cliente.
3. Quando o pagamento termina, enviamos um webhook e a cobrança fica disponível para consulta com o status final e o comprovante (NSU, autorização, bandeira).

Autenticação

Todas as chamadas usam a chave do integrador no cabeçalho Authorization. A chave fica só no seu servidor; um integrador enxerga apenas os próprios terminais e cobranças.

POST https://api-app.ticketsprime.com.br/api/conector/v1/cobrancas
Authorization: Bearer ck_SUA_CHAVE
Content-Type: application/json

Atende várias lojas? Use uma única chave e separe as lojas pelos terminais (o campo referencia do terminal guarda o identificador do seu lado).

Terminais

Um terminal representa uma maquininha ligada ao seu sistema (um caixa, um balcão, um garçom).

curl -X POST https://api-app.ticketsprime.com.br/api/conector/v1/terminais \
  -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "nome": "Caixa 1", "referencia": "loja7-caixa1" }'

{
  "id": "3f6c1b2e-0000-4a5b-9c1d-7e8f90a1b2c3",
  "nome": "Caixa 1",
  "referencia": "loja7-caixa1",
  "status": "aguardando_vinculo",
  "codigoVinculo": "482913",
  "codigoExpiraEm": "2026-10-26T13:11:47.300Z",
  "criadoEm": "2026-10-26T13:01:47.300Z"
}

Cobranças

curl -X POST https://api-app.ticketsprime.com.br/api/conector/v1/cobrancas \
  -H "Authorization: Bearer ck_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "terminalId": "3f6c1b2e-0000-4a5b-9c1d-7e8f90a1b2c3",
    "valor": 2590,
    "tipo": "credito",
    "parcelas": 3,
    "parcelamento": "loja",
    "descricao": "Pedido 1234",
    "referencia": "loja7-pedido1234-t1",
    "validadeSegundos": 180
  }'

// Sem webhook (ou enquanto ele não chega): consulte a cobrança até um status final.
const FINAIS = ["aprovada", "recusada", "cancelada", "erro"];

async function aguardar(id, { intervaloMs = 2000, limiteMs = 5 * 60_000 } = {}) {
  const fim = Date.now() + limiteMs;
  while (Date.now() < fim) {
    const resp = await fetch(`https://api-app.ticketsprime.com.br/api/conector/v1/cobrancas/${id}`, {
      headers: { Authorization: "Bearer ck_SUA_CHAVE" },
    });
    const c = await resp.json();
    if (FINAIS.includes(c.status)) return c;
    await new Promise((r) => setTimeout(r, intervaloMs));
  }
  throw new Error("A cobrança não terminou no tempo esperado: consulte de novo antes de cobrar outra vez.");
}

Status

pendente ──▶ em_andamento ──▶ aprovada | recusada | cancelada | erro

Quando acontece erro

Resultado

O campo resultado chega quando a cobrança termina. Nas não aprovadas, erroCodigo e mensagem dizem o motivo.

A hora do pagamento é o concluidaEm da cobrança.

Referência e reenvio

A referencia identifica esta tentativa de cobrança e é única por terminal.

• Caiu a rede no meio do POST? Reenvie com a mesma referência e os mesmos valor, tipo e parcelas: você recebe a mesma cobrança, sem duplicar.
• Mesma referência com outro valor, tipo ou parcelas responde 409.
• Nova tentativa da mesma venda (cartão recusado, outro cartão, pagamento dividido) usa referência nova, como pedido1234-t2.
• Se a maquininha não pegar a cobrança dentro de validadeSegundos, ela vira cancelada com EXPIRADA: uma maquininha desligada não recebe cobrança velha depois. Depois que a maquininha pega, o prazo não vale mais.

Boas práticas

• Grave a cobrança (id e referência) antes de mostrar “aguardando a maquininha” ao operador.
• Use o webhook para reagir na hora e a consulta (GET /cobrancas/{id}) como conferência. Sem webhook, consulte a cada 2 segundos.
• Em erro, nunca cobre de novo automaticamente. Mostre ao operador que o pagamento precisa ser conferido.
• Ofereça um botão de cancelar enquanto a cobrança estiver pendente.
• Use ultimoContatoEm do terminal para avisar que a maquininha está desligada ou fora do modo integração antes de cobrar.