> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payfi.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Minimal integration path for a pilot partner.

This is the shortest partner flow that creates a customer, creates an operation, uploads documents, and reads the final analysis posture.

All partner API calls use signed headers:

```http theme={null}
X-PayFi-Api-Key: pfk_test_...
X-PayFi-Nonce: random-128-bit-value
X-PayFi-Signature: t=1779100000000,h=<sha256_raw_body_hex>,v1=<hmac_hex>
Idempotency-Key: partner-write-key
```

## 1. Create or update a customer

`POST /v1/customers`

```json theme={null}
{
  "partnerCustomerId": "acme-customer-123",
  "legalName": "Acme Ltda",
  "taxId": "12.345.678/0001-95",
  "cnae": "4691-5/00",
  "email": "financeiro@acme.example"
}
```

```json theme={null}
{
  "customerId": "cus_example",
  "partnerCustomerId": "acme-customer-123",
  "legalName": "Acme Ltda"
}
```

## 2. Create the operation

`POST /v1/operations`

```json theme={null}
{
  "customerId": "cus_example",
  "operationType": "IMPORT_GOODS",
  "exchangeModality": "TERM",
  "partnerOperationId": "acme-op-123",
  "declaredBeneficiaryName": "Shenzhen NovaTech Components Co Ltd",
  "declaredEconomicOwnerName": "Shenzhen NovaTech Components Co Ltd",
  "buyerCountry": "BR"
}
```

`declaredBeneficiaryName`, `declaredEconomicOwnerName`, and `buyerCountry` are nullable for legacy compatibility, but the guided trust-v2 flow requires all three. PayFi does not infer the economic owner from the customer or importer name. The two-letter ISO buyer country controls country-specific validation such as CNPJ; an absent country never causes PayFi to assume Brazil.

```json theme={null}
{
  "operationId": "op_example",
  "partnerOperationId": "acme-op-123",
  "status": "REQUIREMENTS_PENDING",
  "requirementsStatus": "PENDING"
}
```

PayFi then prepares the required document list. Wait for `operation.requirements.ready` before collecting files for the operation.

## 3. Register each document

After the requirement list is approved, register each document before uploading bytes.

`POST /v1/operations/{operationId}/documents`

```json theme={null}
{
  "documentType": "invoice",
  "fileName": "invoice-123.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 123456
}
```

```json theme={null}
{
  "documentId": "doc_example",
  "status": "UPLOAD_PENDING",
  "uploadUrl": "https://storage.example.com/presigned-upload",
  "uploadUrlExpiresInSeconds": 300
}
```

## 4. Upload and complete

Upload the file bytes directly to `uploadUrl`:

```http theme={null}
PUT https://storage.example.com/presigned-upload
Content-Type: application/pdf
Content-Length: 123456
```

Then complete the upload:

`POST /v1/upload-sessions/{token}/documents/{documentId}/complete`

```json theme={null}
{
  "documentId": "doc_example",
  "status": "CLEAN",
  "operationStatus": "DOCUMENTS_UPLOADED"
}
```

## 5. Read status and analysis posture

Use `GET /v1/operations/{operationId}` for partner reconciliation:

```json theme={null}
{
  "operationId": "op_example",
  "partnerOperationId": "acme-op-123",
  "customerId": "cus_example",
  "status": "READY_FOR_MANUAL_REVIEW",
  "operationType": "IMPORT_GOODS",
  "exchangeModality": "TERM",
  "declaredBeneficiaryName": "Shenzhen NovaTech Components Co Ltd",
  "declaredEconomicOwnerName": "Shenzhen NovaTech Components Co Ltd",
  "buyerCountry": "BR",
  "requirementsStatus": "APPROVED",
  "requiredDocumentTypes": ["invoice", "bill_of_lading", "packing_list"],
  "missingDocumentTypes": [],
  "score0To100": 94,
  "score1To10": 10,
  "riskLevel": "low",
  "createdAt": "2026-05-20T12:00:00.000Z",
  "updatedAt": "2026-05-20T12:10:00.000Z"
}
```

Partners should also subscribe to signed webhooks for asynchronous updates. The API Reference includes endpoint-level examples for the `ACTION_REQUIRED` path where a required document type is still missing after analysis.