API de entrada de chargebacks

Envie os chargebacks do seu sistema direto para a Facby. Cada caso novo entra na triagem da plataforma e segue o fluxo configurado pela sua equipe: aviso ao estabelecimento, coleta de provas e defesa.

Disponível nos planos Scale e Enterprise. Todas as chamadas usam HTTPS e JSON em UTF-8.

Autenticação

Cada chamada leva a chave de API do seu ambiente no header X-Api-Key. O administrador cria a chave na plataforma, em Entrada de CBK → Integração por API. Ela aparece uma única vez, na criação: guarde-a no cofre de segredos do seu sistema.

X-Api-Key: fcb_live_3f9c…

O header Authorization: Bearer fcb_live_… também é aceito. Uma chave revogada para de funcionar na hora.

Nunca coloque a chave em código que roda no navegador ou no celular do usuário. Ela dá acesso de escrita ao seu ambiente.

Testar a chave

GET/v1/status

Confere se a chave é válida e mostra a qual ambiente ela pertence.

curl https://api.facby.tech/v1/status \
  -H "X-Api-Key: $FACBY_API_KEY"

# 200
{ "ok": true, "tenant": "Sua Empresa", "chave": "ERP produção", "versao": "v1" }

Enviar chargebacks

POST/v1/chargebacks

Aceita um caso (objeto), uma lista de casos ou { "chargebacks": [...] }, com até 200 casos por chamada.

Caso novo: é aberto na triagem da plataforma.
Caso que já existe (mesmo numero_caso): os dados enviados são atualizados. A fase do caso nunca muda pela API, e um caso encerrado não é alterado.

curl -X POST https://api.facby.tech/v1/chargebacks \
  -H "X-Api-Key: $FACBY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lote-2026-10-27-0800" \
  -d '{
  "numero_caso": "CBK-88412",
  "valor": 1890.50,
  "bandeira": "Mastercard",
  "reason_code": "4853",
  "adquirente": "Cielo",
  "prazo_final": "2026-11-12",
  "ec": { "numero_ec": "1029384756" },
  "arn": "85412396218004417220913",
  "nsu": "000184510",
  "tid": "TID998910",
  "codigo_autorizacao": "8KD31Q",
  "data_venda": "2026-10-08T19:11:00-03:00",
  "cartao": "**** 4417",
  "parcelas": 6,
  "canal_venda": "nao_presente",
  "mensagem_emissor": "Portador informa que a mercadoria não foi entregue."
}'

Campos do caso

Campo	Tipo		Descrição
`numero_caso`	texto (até 60)	obrigatório	Identificador do chargeback no seu sistema. É a chave para atualizar o caso depois.
`valor`	número	obrigatório	Valor contestado, com ponto decimal: `1890.50`.
`bandeira`	texto	obrigatório	`Visa`, `Mastercard`, `Elo`, `Amex`, `Hipercard` ou `Outra`.
`reason_code`	texto	obrigatório	Código do motivo na bandeira: `4853`, `10.4`, `13.1`…
`adquirente`	texto	obrigatório	Cielo, Rede, Stone, Getnet, PagBank, Mercado Pago, Fiserv, Pagar.me, Adyen, Stripe, SafraPay, Sipag, Vero, InfinitePay. Outro nome entra como `Outro`.
`prazo_final`	data	obrigatório	Prazo para a defesa. `AAAA-MM-DD` vale até o fim do dia (horário de Brasília); também aceita data e hora ISO 8601.
`ec.numero_ec` ou `ec.cnpj`	texto	obrigatório	Estabelecimento que fez a venda. Precisa estar cadastrado na plataforma. CNPJ com ou sem pontuação, numérico ou alfanumérico.
`arn`	texto	opcional	Acquirer Reference Number.
`nsu`, `tid`, `codigo_autorizacao`	texto	opcional	Identificadores da transação original.
`numero_caso_adquirente`	texto	opcional	Número do caso no portal da adquirente.
`numero_pedido`	texto	opcional	Pedido na loja, para localizar as provas.
`data_venda`	data e hora	opcional	Data e hora da venda original, ISO 8601 com fuso: `2026-10-08T19:11:00-03:00`.
`cartao`	texto	opcional	Só os 4 últimos dígitos ou o número mascarado (`** 4417`, `411111**4417`). Número completo é recusado.**
`parcelas`	inteiro	opcional	De 1 a 99.
`moeda`	texto	opcional	Código de 3 letras. Padrão `BRL`.
`ciclo`	texto	opcional	`1º Chargeback` (padrão), `2º ciclo` ou `pré-arbitragem`.
`canal_venda`	texto	opcional	`presente` ou `nao_presente`.
`metodo_captura`	texto	opcional	Ex.: link de pagamento, checkout, maquininha.
`mensagem_emissor`	texto	opcional	Texto do emissor sobre a contestação.
`banco_emissor`, `nome_titular`	texto	opcional	Emissor do cartão e nome do titular informado por ele.

Resposta

A resposta traz o resultado de cada caso, na mesma ordem do envio (indice começa em 0). Um caso com erro não impede os demais.

# 200 — ao menos um caso aceito
{
  "recebidos": 3, "criados": 1, "atualizados": 1, "ignorados": 0, "com_erro": 1,
  "resultados": [
    { "indice": 0, "numero_caso": "CBK-88412", "id": "a2b2dc38-…", "status": "criado" },
    { "indice": 1, "numero_caso": "CBK-88390", "id": "1a0c23d0-…", "status": "atualizado" },
    { "indice": 2, "numero_caso": "CBK-88415", "status": "erro",
      "erro": "EC não encontrado no cadastro da Facby (nº do EC ou CNPJ). Cadastre o lojista antes de enviar o caso." }
  ]
}

status	Significado
`criado`	Caso novo aberto na triagem.
`atualizado`	O caso já existia; os dados enviados foram gravados.
`ignorado`	Caso encerrado, ou número repetido no mesmo envio (vale a última ocorrência).
`erro`	O caso não foi gravado; o campo `erro` diz o que corrigir.

Erros

HTTP	erro	Quando acontece
400	`json_invalido`, `formato_invalido`	Corpo que não é JSON ou não traz casos.
401	`chave_ausente`, `chave_invalida`	Sem chave, chave em formato errado ou revogada.
403	`plano_sem_api`	O plano do ambiente não inclui a integração por API.
404	`rota_inexistente`	Endereço ou método não suportado.
413	`lote_grande`	Mais de 200 casos na mesma chamada.
422	—	Nenhum caso do envio foi aceito; veja `resultados`.
502	`indisponivel`	Instabilidade momentânea. Reenvie: o mesmo `numero_caso` não duplica.

Todo erro traz { "erro": "…", "mensagem": "…" }, com a mensagem em português.

Boas práticas

Reenvie sem medo. O numero_caso é a chave do caso no seu ambiente: reenviar atualiza e nunca duplica.
Envie em lotes de até 200 casos e, em caso de erro 502, tente de novo com espera crescente (1 s, 5 s, 30 s).
Use o Idempotency-Key com um identificador do lote: ele aparece no histórico de entradas da plataforma e ajuda a rastrear cada envio.
Cadastre os estabelecimentos antes: o caso precisa de um EC existente, localizado pelo nº do EC ou pelo CNPJ.
Dados do cartão: envie só os 4 últimos dígitos. A Facby não recebe nem guarda o número completo.