Referência da API
Registre cadastros e pagamentos indicados, gere links de indicação para seus clientes e consulte afiliados e indicações. Valores sempre em centavos de real (inteiros). Crie chaves em Integrações → API.
https://filiafy.com.br/api/v1 · Authorization: Bearer iq_…
post/leads
Registrar um cadastro indicado
Para quem não usa Filiafy.convert no snippet. Escopo leads:write. 201 quando criado; 200 quando a pessoa já era indicação do programa (a primeira atribuição vale).
Escopo: leads:write
Parâmetros
| Campo | Tipo | Obrigatório |
|---|---|---|
| Idempotency-KeyQualquer texto de até 200 caracteres. A mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replayed: true); com outro corpo, 422. | string | Não |
Corpo (JSON)
Informe ao menos email, external_id ou customer_id.
| Campo | Tipo | Obrigatório |
|---|---|---|
| programEndereço (slug) do programa. | string | Sim |
| referral_code | string | Sim |
| string (email) | Não | |
| external_idO id da pessoa no seu sistema. | string | Não |
| customer_idO id do cliente no gateway. | string | Não |
| name | string | Não |
Respostas
200Já existia.201Criado.400JSON inválido ou maior que 64 KB.401Chave ausente, inválida ou revogada.403A chave não tem o escopo necessário.404Programa não encontrado.422Campos inválidos, ou Idempotency-Key reutilizada com outro corpo.429Limite de 600 requisições por minuto por chave.
post/conversions
Registrar um pagamento de cliente indicado
Para gateways sem integração nativa. Escopo conversions:write. O cliente é reconhecido por customer_id, external_id ou email; com referral_code, um cliente desconhecido vira indicação desse afiliado. payment_id torna a chamada idempotente.
Escopo: conversions:write
Parâmetros
| Campo | Tipo | Obrigatório |
|---|---|---|
| Idempotency-KeyQualquer texto de até 200 caracteres. A mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replayed: true); com outro corpo, 422. | string | Não |
Corpo (JSON)
| Campo | Tipo | Obrigatório |
|---|---|---|
| program | string | Não |
| referral_code | string | Não |
| string (email) | Não | |
| external_id | string | Não |
| customer_id | string | Não |
| payment_id | string | Sim |
| amount_cents | integer | Sim |
| net_amount_cents | integer | Não |
| paid_at | string (date-time) | Não |
| subscription_id | string | Não |
| currency | string = "BRL" | Não |
Respostas
200Pagamento já registrado.201Conversão criada.400JSON inválido ou maior que 64 KB.401Chave ausente, inválida ou revogada.403A chave não tem o escopo necessário.404Nenhuma indicação para este cliente.422Campos inválidos, ou Idempotency-Key reutilizada com outro corpo.429Limite de 600 requisições por minuto por chave.
post/referrers
Obter o link de indicação de um cliente
Para mostrar "Indique e ganhe" dentro do seu produto. Escopo referrers:write. Cria o indicador na primeira chamada (201) e devolve o mesmo nas próximas (200). program só é obrigatório com mais de um programa de indicação. customer_id (id no Stripe ou Asaas) permite aplicar recompensas de desconto.
Escopo: referrers:write
Parâmetros
| Campo | Tipo | Obrigatório |
|---|---|---|
| Idempotency-KeyQualquer texto de até 200 caracteres. A mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replayed: true); com outro corpo, 422. | string | Não |
Corpo (JSON)
| Campo | Tipo | Obrigatório |
|---|---|---|
| string (email) | Sim | |
| name | string | Não |
| program | string | Não |
| customer_id | string | Não |
| external_id | string | Não |
Respostas
200Já era indicador.201Indicador criado.400JSON inválido ou maior que 64 KB.401Chave ausente, inválida ou revogada.402Limite de afiliados ativos do plano.403A chave não tem o escopo necessário.404Programa não encontrado ou nenhum programa de indicação.409Pessoa recusada/suspensa, ou external_id de outra pessoa.422Campos inválidos, ou Idempotency-Key reutilizada com outro corpo.429Limite de 600 requisições por minuto por chave.
get/affiliates
Listar afiliados e indicadores
Escopo affiliates:read. Mais recentes primeiro. Nunca devolve CPF/CNPJ nem chave Pix.
Escopo: affiliates:read
Parâmetros
| Campo | Tipo | Obrigatório |
|---|---|---|
| program(query) | string | Não |
| status(query) | "pending" | "approved" | "rejected" | "suspended" | Não |
| email(query) | string | Não |
| external_id(query) | string | Não |
| page(query) | integer | Não |
| per_page(query) | integer | Não |
Respostas
200Uma página de afiliados.401Chave ausente, inválida ou revogada.403A chave não tem o escopo necessário.422Parâmetros inválidos.429Limite de 600 requisições por minuto por chave.
get/referrals/{id}
Consultar uma indicação
Escopo referrals:read. A indicação com o afiliado, os pagamentos (centavos) e as recompensas.
Escopo: referrals:read
Parâmetros
| Campo | Tipo | Obrigatório |
|---|---|---|
| id(path) | string (uuid) | Sim |
Respostas
200A indicação.401Chave ausente, inválida ou revogada.403A chave não tem o escopo necessário.404Não encontrada neste workspace.429Limite de 600 requisições por minuto por chave.
Webhooks de saída
conversion.created
| Campo | Tipo | Obrigatório |
|---|---|---|
| id | string (uuid) | Não |
| program | string | Não |
| referral_id | string (uuid) | Não |
| affiliate | object | Não |
| provider | "asaas" | "stripe" | "api" | Não |
| payment_id | string | Não |
| amount_cents | integer | Não |
| paid_at | string (date-time) | Não |
| first_payment | boolean | Não |
commission.accrued
| Campo | Tipo | Obrigatório |
|---|---|---|
| idLançamento no extrato. | string (uuid) | Não |
| conversion_id | string (uuid) | Não |
| program | string | Não |
| affiliate | object | Não |
| amount_cents | integer | Não |
| available_at | string (date-time) | Não |
payout.completed
| Campo | Tipo | Obrigatório |
|---|---|---|
| idItem do lote. | string (uuid) | Não |
| batch_id | string (uuid) | Não |
| period | string | Não |
| affiliate | object | Não |
| amount_cents | integer | Não |
| method | "asaas_pix" | "manual" | Não |
| paid_at | string (date-time) | Não |