Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt

Use this file to discover all available pages before exploring further.

Cria um hosted flow para uma plataforma a partir do CPF/CNPJ do seller. O contrato é idempotente por plataforma e documento: chamadas repetidas para o mesmo seller retornam o mesmo flow quando possível.

​
Autenticação

Requer API key de plataforma com escopo administrativo via header Authorization: Bearer.

​
Corpo da Requisição

​
taxpayer_id
string
required
CPF ou CNPJ do seller.
​
return_url
string
required
URL para onde o seller volta ao concluir ou sair do cadastro.
​
seller_display_name
string
Nome inicial exibido no wizard.
​
external_reference
string
Identificador do seller no seu sistema.
​
metadata
object
Metadados string-string que serão ecoados em webhooks dentro de platform_reference.
​
authorize
boolean
default:"false"
Quando true, a resposta inclui uma URL /connect com authorization_code de curta duração para abrir o wizard imediatamente.

​
Resposta

​
id
string
ID do hosted flow (hf_*).
​
organization_id
string
ID da sub-organização criada ou reutilizada.
​
status
string
Estado do flow: INIT, PROCESSING, FINISHED, FAILED ou EXPIRED.
​
taxpayer_id
string
CPF/CNPJ normalizado.
​
taxpayer_type
string
individual ou business.
​
return_url
string
URL de retorno configurada.
​
external_reference
string | null
Referência externa recebida.
​
metadata
object
Metadados recebidos.
​
result
object | null
Snapshot final preenchido após conclusão.
​
url
string
Presente quando authorize=true.
​
authorization_expires_at
string
Expiração da URL autorizada.

​
Exemplo

cURL
curl -X POST "https://api.chargefy.io/v1/hosted-flow-create" \
  -H "Authorization: Bearer $CHARGEFY_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxpayer_id": "12.345.678/0001-90",
    "seller_display_name": "Acme Ltda",
    "return_url": "https://example.com/onboarding/return",
    "external_reference": "seller_123",
    "metadata": {
      "workspace_id": "ws_789"
    },
    "authorize": true
  }'
Response
{
  "id": "hf_abc123",
  "organization_id": "org_seller_new",
  "status": "INIT",
  "taxpayer_id": "12345678000190",
  "taxpayer_type": "business",
  "return_url": "https://example.com/onboarding/return",
  "error_url": null,
  "external_reference": "seller_123",
  "metadata": {
    "workspace_id": "ws_789"
  },
  "result": null,
  "url": "https://app.chargefy.io/connect/hf_abc123?authorization_code=...",
  "authorization_expires_at": "2026-04-30T18:31:00Z"
}