Fontes e a URL de ingestão

A fonte é a porta de entrada do recebimento: uma URL que você entrega a um provedor, com a configuração de como conferir o que chega por ela e para onde repassar.

Criar

curl -X POST https://api.notyfacil.com.br/v1/ingest/sources \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mercado Pago","type":"webhook"}'

A resposta já traz a URL de ingestão, pronta para colar no provedor:

{ "id": "src_01JB8Z2R4K7M1QX5VN3HT9WCDF", "name": "Mercado Pago", "type": "webhook", "status": "enabled", "url": "https://api.notyfacil.com.br/in/ing_…", "provider": "none", "hasSecret": false }

A fonte nasce sem provedor e sem verificação. O passo seguinte é dizer qual é o provedor e guardar o segredo dele:

curl -X PATCH https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z2R4K7M1QX5VN3HT9WCDF \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"mercadopago"}'

curl -X PUT https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z2R4K7M1QX5VN3HT9WCDF/secret \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret":"a-chave-secreta-que-o-mercado-pago-mostrou"}'

O segredo entra e nunca volta pela API; hasSecret passa a dizer true. Os códigos de cada provedor e onde achar o segredo estão em provedores. Por fim, adicione um destino: sem destino, a fonte grava as mensagens e não repassa nada.

A URL é uma credencial

Cuidado

Quem tem a URL de ingestão consegue mandar mensagens para a sua fonte. Com a verificação de assinatura configurada, mensagem forjada é recusada com 401. Sem verificação, ela é aceita e repassada.

Se a URL vazar, rotacione o token:

curl -X POST https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z2R4K7M1QX5VN3HT9WCDF/rotate-token \
  -H "Authorization: Bearer $NOTYFACIL_KEY"

A URL antiga deixa de funcionar na hora, sem janela de graça, porque o motivo de rotacionar é a URL estar nas mãos erradas. Cadastre a nova no provedor logo em seguida; até lá, o que ele mandar recebe 404.

Pausar

curl -X PATCH https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z2R4K7M1QX5VN3HT9WCDF \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

A fonte pausada continua respondendo 202 ao provedor e gravando o que chega, e não repassa nada. É o jeito de parar o repasse sem que o provedor note e desative o webhook. Para voltar, "status":"enabled". As mensagens que chegaram durante a pausa podem ser repassadas com replay.

Alerta de silêncio

Um provedor que desativa o webhook não avisa ninguém. A fonte pode:

curl -X PATCH https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z2R4K7M1QX5VN3HT9WCDF \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"silenceAlertMinutes":1440,"alertEmails":"financeiro@padariadoze.com.br, dev@padariadoze.com.br"}'

Com silenceAlertMinutes, a fonte manda e-mail quando passa esse tempo sem receber nenhuma mensagem. O aviso sai uma vez por período de silêncio e só volta a ser enviado depois que uma mensagem nova chegar. 0 desliga, e o máximo é 43.200 minutos (30 dias). alertEmails aceita até 5 endereços separados por vírgula.

Escolha o tempo pelo ritmo normal da fonte: um gateway que recebe pagamentos o dia todo merece algumas horas; um provedor que manda um webhook por semana precisa de mais de sete dias.

Fontes agendadas

Uma fonte do tipo cron não tem provedor: ela mesma gera uma mensagem nos horários de uma expressão cron, e a repassa aos destinos como qualquer outra. Serve para disparar uma rotina do seu sistema num horário, com o retry, o histórico e o replay de uma entrega.

curl -X POST https://api.notyfacil.com.br/v1/ingest/sources \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Fechamento diário","type":"cron"}'

curl -X PATCH https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z6P1D3F8K4NWQ7XR2MTHV \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cronExpression":"0 23 * * *","cronTimezone":"America/Sao_Paulo","cronPayload":"{\"rotina\":\"fechamento\"}"}'

• cronExpression: formato padrão de cinco campos (minuto, hora, dia do mês, mês, dia da semana).
• cronTimezone: fuso IANA. O padrão é America/Sao_Paulo.
• cronPayload: o corpo da mensagem, um objeto JSON em forma de texto.

Cada disparo vira uma mensagem com método CRON, Content-Type: application/json e o payload como corpo, com verificação skipped. Mudar a expressão reagenda a partir de agora, e pausar a fonte suspende os disparos.

Excluir

curl -X DELETE https://api.notyfacil.com.br/v1/ingest/sources/src_01JB8Z2R4K7M1QX5VN3HT9WCDF \
  -H "Authorization: Bearer $NOTYFACIL_KEY"

Exclui a fonte com tudo que é dela: destinos, mensagens e histórico de entregas. A URL deixa de existir. Não tem volta; para só parar o repasse, pause.

Referência: recebimento