Consumers

O Consumer representa quem recebe eventos, quase sempre um cliente seu. Os endpoints pertencem a um Consumer, e todo evento é publicado para um Consumer.

O externalId

Você identifica o Consumer pelo id que ele já tem no seu sistema, e não por um id nosso. O id com prefixo csm_ existe, mas você não precisa guardá-lo: toda chamada que fala de um Consumer aceita o externalId.

É isso que evita a tabela de-para. Quando o pedido 1234 do cliente 42 é pago, você publica para cliente-42, o id que você já tem na mão.

O externalId é único dentro do ambiente e tem até 200 caracteres. Use o id interno, e não o e-mail ou o CNPJ: id interno não muda.

Cadastrar

cURL

curl -X POST https://api.notyfacil.com.br/v1/consumers \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"cliente-42","name":"Padaria do Zé"}'

Node.js

const resposta = await fetch('https://api.notyfacil.com.br/v1/consumers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOTYFACIL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ externalId: 'cliente-42', name: 'Padaria do Zé' }),
})

PHP

$ch = curl_init('https://api.notyfacil.com.br/v1/consumers');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('NOTYFACIL_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['externalId' => 'cliente-42', 'name' => 'Padaria do Zé']),
]);
$consumer = json_decode(curl_exec($ch), true);

{ "id": "csm_01JB8XZQ4T9M2NKPWV3RYCF7HD", "externalId": "cliente-42", "name": "Padaria do Zé", "createdAt": "2026-09-10T12:00:00Z" }

Um externalId repetido responde 409. Isso deixa o cadastro seguro para rodar no mesmo fluxo em que o cliente nasce no seu sistema: se a chamada for repetida, a segunda falha sem criar nada.

Listar

curl https://api.notyfacil.com.br/v1/consumers \
  -H "Authorization: Bearer $NOTYFACIL_KEY"

Devolve os 100 Consumers mais recentes do ambiente. Esta listagem não é paginada.

Um Consumer por ambiente

Consumers de desenvolvimento e de produção são cadastros separados, mesmo com o mesmo externalId. Ao ir para produção, cadastre-os de novo com a chave whk_live_.

Referência: cadastrar um Consumer · listar Consumers