POST /api/v1/accounts/kyc/documents

Faz upload de um documento KYC para o seller de uma organização. Aceita imagens e PDF (apenas CNH_FULL). Limite de 3 MB por arquivo.

Envia um documento KYC para verificação do seller de uma organização. A requisição deve ser multipart/form-data. Cada chamada envia um documento por vez. Use Consultar Status KYC para saber quais documentos ainda estão pendentes.

A organização pai pode enviar documentos em nome de suas sub-organizações filhas. Basta usar o JWT da organização pai e informar o organization_id da filha.

​

Autenticação

Aceita dois tipos de autenticação:

• JWT da própria organização — organização enviando seus próprios documentos
• JWT da organização pai — organização pai enviando documentos em nome de uma filha

​

Corpo da Requisição (multipart/form-data)

organization_id · string · required

Identificador único da organização cujo documento será enviado.

type · string · required

Tipo do documento. Valores aceitos: SELFIE, CNH_FULL, CNH_FRONT, CNH_BACK, RG_FRONT, RG_BACK.

file · file · required

Arquivo do documento. Tamanho máximo: 3 MB.

​

Formatos Aceitos por Tipo

Tipo	Formatos	PDF aceito?
SELFIE	JPEG, PNG, BMP, WebP, HEIC, HEIF	Não
CNH_FULL	JPEG, PNG, BMP, WebP, HEIC, HEIF, PDF	Sim
CNH_FRONT	JPEG, PNG, BMP, WebP, HEIC, HEIF	Não
CNH_BACK	JPEG, PNG, BMP, WebP, HEIC, HEIF	Não
RG_FRONT	JPEG, PNG, BMP, WebP, HEIC, HEIF	Não
RG_BACK	JPEG, PNG, BMP, WebP, HEIC, HEIF	Não

​

Resposta

success · boolean

true quando o documento foi enviado com sucesso.

document_type · string

Tipo do documento enviado.

result · object

Resposta bruta do gateway de pagamento.

​

Exemplos

​

Sub-organização enviando seu próprio documento

cURL

curl -X POST "https://app.chargefy.io/api/v1/accounts/kyc/documents" \
  -H "Authorization: Bearer $SUBORG_ACCESS_TOKEN" \
  -F "organization_id=org_01j9abc333" \
  -F "type=SELFIE" \
  -F "file=@/caminho/para/selfie.jpg"

​

Organização pai enviando documento de uma filha

cURL

curl -X POST "https://app.chargefy.io/api/v1/accounts/kyc/documents" \
  -H "Authorization: Bearer $PARENT_ACCESS_TOKEN" \
  -F "organization_id=org_01j9abc333" \
  -F "type=CNH_FRONT" \
  -F "file=@/caminho/para/cnh_frente.jpg"

​

Fluxo completo de envio de documentos

import { Chargefy } from 'chargefy-js';
import fs from 'fs';

const chargefy = new Chargefy({ accessToken: '<supabase_jwt>', server: 'production' });
const orgId = 'org_01j9abc333';

// 1. Verificar quais documentos ainda faltam
const statusResult = await chargefy.kyc.getDocuments(orgId);
if (!statusResult.ok) throw new Error('Falha ao consultar status KYC');

const { documents, kycComplete } = statusResult.value;

if (kycComplete) {
  console.log('KYC já está completo!');
} else {
  console.log('Documentos pendentes:', documents.pendingUpload);

  // 2. Enviar cada documento pendente
  for (const docType of documents.pendingUpload) {
    const filePath = `./documentos/${docType.toLowerCase()}.jpg`;
    const file = fs.readFileSync(filePath);

    const uploadResult = await chargefy.kyc.uploadDocument(orgId, docType, file);
    if (uploadResult.ok) {
      console.log(`✓ ${docType} enviado com sucesso`);
    } else {
      console.error(`✗ Falha ao enviar ${docType}:`, uploadResult.error);
    }
  }
}

​

Resposta de Exemplo

{
  "success": true,
  "document_type": "SELFIE",
  "result": {}
}

​

Erros

Status	Descrição
400	Campo ausente, tipo inválido, formato de arquivo não permitido ou arquivo maior que 3 MB
401	Token ausente ou inválido
403	Token não pertence à organização ou à sua organização pai
404	Seller não encontrado para esta organização
412	Seller não pode receber documentos no estado atual (ex: já aprovado ou desabilitado)