🚀 Integration Flow

Step 1: Initial Setup

Before starting the integration, you will need:

Access Credentials: Request credentials from the Kapitale team

JWT Token: Obtain a valid token via OAuth2 client_credentials (see Authentication)

Environment: Define whether you will use development or production environment

Step 2: Fetch Retail Information (GET /company/cnpj/:cnpj)

Before creating an order, it is recommended to fetch retail information by CNPJ. This endpoint returns complete retail data that can be used to fill the order creation form.

Endpoint: GET /company/cnpj/{cnpj}

Parameters:

cnpj (path): Retail CNPJ (numbers only, 14 digits)

Request Example:

Success Response (200):

Scenario 1: Registered Retail (registered_retail: true)

{
  "name": "Empresa Varejo LTDA",
  "retail_representative": "João Silva",
  "email": "contato@varejo.com.br",
  "phone": "11987654321",
  "address": "Rua das Flores",
  "number": "123",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "complement": "Sala 45",
  "zip_code": "01310-100",
  "registered_retail": true
}

Scenario 2: Unregistered Retail (registered_retail: false)

{
  "name": "Nova Empresa Varejo LTDA",
  "retail_representative": "Maria Santos",
  "email": "contato@novaempresa.com.br",
  "phone": "11976543210",
  "address": "Avenida Paulista",
  "number": "1000",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "complement": "",
  "zip_code": "01310-100",
  "registered_retail": false
}

💡 Tip:

If registered_retail is true, the data comes from Kapitale's database and is more reliable

If registered_retail is false, the data was fetched from the credit bureau (Procob) and may need validation

Use the returned fields (retail_representative, email, phone) to fill the order creation form

Step 3: Create an Order (POST /order)

After obtaining retail information, you can create a payment order.

Endpoint: POST /order

Request Body:

{
  "order_number": "ORD-001",
  "expiry_date": "2025-12-31",
  "requested_amount": 10000,
  "retail_cnpj": "00.000.000/0001-00",
  "retail_representative": "João Silva",
  "retail_email": "joao@empresa.com",
  "retail_phone": "11999999999",
  "purchase_date": "2025-02-26",
  "purchase_items": [
    { "value": 5000, "quantity": 2, "description": "Produto A" }
  ]
}

Success Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_no": "ORD-2024-001",
  "expiry_date": "2024-12-31T00:00:00.000Z",
  "requested_amount": 10000.50,
  "paid_amount": 9785.49,
  "payment_status": "pending",
  "order_status": "pending",
  "retail_fee": 0,
  "industry_fee": 0.0215,
  "created_at": "2024-01-15T10:30:00.000Z"
}

⚠️ Important:

The retail CNPJ (retail_cnpj) must contain numbers only (14 digits)

The requested amount must be greater than 1

Dates must be in YYYY-MM-DD format

The order will be created with status pending and will await approval

💡 Practical Example: Using the retail information returned in Step 2:

Step 4: Query Orders

After creating an order, you can query it in several ways:

4.1 List Orders (with pagination)

Endpoint: GET /order

Returns a paginated list of orders for the industry (CNPJ obtained from the token).

Query Parameters:

page (optional): Page number (default: 1)

limit (optional): Items per page (default: 10)

status (optional): Status filter (e.g., pending,pending_invoice)

retail_cnpj (optional): Partial filter by retail CNPJ

Example:

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "order_no": "ORD-2024-001",
      "order_status": "pending",
      "payment_status": "pending",
      "retail": {
        "name": "Empresa Varejo LTDA",
        "cnpj": "98765432000110"
      }
    }
  ],
  "page": 1,
  "totalPages": 5,
  "limit": 10,
  "count": 50,
  "pendingInvoices": 3
}

4.2 Fetch Order by ID

Endpoint: GET /order/{id}

Example:

Step 5: Set Invoice

When an order has status pending_invoice, you can attach the invoice.

Endpoint: PATCH /order/invoice/{order_id}

Request: multipart/form-data

Fields:

invoice_number (string): Invoice number

invoice (file): PDF or image file of the invoice

Example using cURL:

⚠️ Important:

The file must be PDF or image

The invoice number must be unique

The order must have status pending_invoice

Step 6: Cancel Order (If Necessary)

Endpoint: PATCH /order/cancel/{order_id}

Request Body:

{
  "reason": "Order canceled at customer request"
}

Real-time notifications (optional)

The partner can configure a webhook to receive notifications of order events (creation, approval, and rejection) without needing to poll the API. To request configuration, contact the Kapitale team via email and refer to the complete documentation in Webhooks.

🚀 Integration Flow

Step 1: Initial Setup#

Step 2: Fetch Retail Information (GET /company/cnpj/:cnpj)#

Step 3: Create an Order (POST /order)#

Step 4: Query Orders#

4.1 List Orders (with pagination)#

4.2 Fetch Order by ID#

Step 5: Set Invoice#

Step 6: Cancel Order (If Necessary)#

Real-time notifications (optional)#