API para parceiros · v1

Aceite o cartão Nicomaco

Autenticação por chave no cabeçalho Authorization: Bearer nk_live_…. Respostas em JSON, datas em ISO 8601 com fuso. Limite de 600 requisições por minuto por chave.

Fluxo

Na venda, o cliente informa o número do cartão. Você cria o direito em /direitos.
O titular confirma no painel (ou você envia o código do verso e o direito já nasce ativo).
Na entrada, o leitor lê o cartão e chama /validar. A resposta diz se libera.

POST/api/v1/cartoes/consulta

Confere se um número de cartão existe e pode receber direitos. Não devolve dados pessoais.

{ "numero": "7821 4410 0093 5518" }

→ { "numero": "7821441000935518", "apto": true, "linha": "black", "cartao_id": "cid_…" }

POST/api/v1/direitos

Liga um ingresso, voucher, hospedagem, acesso ou associação ao cartão. Sem o código do verso, fica aguardando o titular confirmar no painel. Com o código correto, já nasce ativo. Repetir a mesma referencia_externa devolve o direito existente (idempotente).

{
  "numero": "7821441000935518",
  "codigo_verificacao": "N696KF",      // opcional
  "tipo": "INGRESSO",                  // INGRESSO | VOUCHER | HOSPEDAGEM | ACESSO | ASSOCIACAO
  "titulo": "Festival — Pista",
  "local": "Arena, Aracaju",
  "valido_de": "2026-11-20T16:00:00-03:00",
  "valido_ate": "2026-11-21T04:00:00-03:00",
  "usos_max": 1,
  "referencia_externa": "PEDIDO-1234"
}

→ 201 { "id": "…", "status": "aguardando_titular", … }

GET/api/v1/direitos/:id

Consulta um direito criado por você.

DELETE/api/v1/direitos/:id

Cancela (reembolso, check-out antecipado).

POST/api/v1/validar

Seu leitor lê o link do chip (NDEF) e envia aqui. Libera se a assinatura for válida, o toque for novo, o cartão estiver ativo e houver um direito seu valendo agora. Por padrão consome um uso; envie "consumir": false para só consultar.

{ "link": "https://card.nicomaco.com.br/1/EF963FF7…65337086", "leitor_id": "portao-a" }

→ { "resultado": "liberar", "nivel": "criptografado", "cartao_id": "cid_…", "direito": { … } }
→ { "resultado": "negar", "motivo": "toque_repetido" | "sem_direito" | "usos_esgotados"
     | "aguardando_titular" | "cartao_bloqueado" | "cartao_nao_reconhecido", "mensagem": "…" }

Privacidade

O cartao_id é diferente para cada parceiro: duas empresas não conseguem cruzar dados do mesmo cliente. Nenhuma rota devolve nome, documento ou contato do titular.