🏪 Retail Pre-Register

This document describes how to pre-register a retail company (varejista) through the Partners API. Use this endpoint when the retail is not yet registered with Kapitale and you need to onboard them before creating orders or consulting receivables.

Endpoint

Method: POST

Path: /retail/pre-register

Required scope: partner-can/retail.create

Content-Type: multipart/form-data

Authentication

All requests must include a valid OAuth2 bearer token in the Authorization header:

The industry context is resolved from the partner credentials associated with the token (M2M). The retail will be linked to that industry.

Form Fields

Field	Type	Required	Description
`retail_cnpj`	string	Yes	Retail CNPJ (validated; digits with or without mask).
`retail_representative_name`	string	Yes	Legal representative full name.
`retail_representative_email`	string	Yes	Representative e-mail address.
`retail_representative_cpf`	string	Yes	Representative CPF (11 digits).
`retail_representative_phone`	string	Yes	Representative phone (Brazilian format: DDD + 9 digits).
`social_contract`	file	Yes	Articles of incorporation (PDF, JPG, JPEG, or PNG; max 10 MB).
`representative_id_document`	file	Yes	Representative ID (RG or CNH front; PDF, JPG, JPEG, or PNG; max 10 MB).

Request Example

Success Response (200)

Returns the created company record (partial example):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cnpj": "12345678000190",
  "name": "Empresa Varejo LTDA",
  "email": "contato@varejo.com.br",
  "phone": "11987654321",
  "created_by_industry": true,
  "status": "waiting"
}

What Happens on Success

Company data is fetched from the credit bureau (Procob) using the CNPJ.

The legal representative user is created or updated in Kapitale.

Documents are stored and sent to the receivable provider for quotation.

The company is marked as created by the industry partner (created_by_industry: true).

Error Responses

Code	Meaning	Recommended Action
`400`	Bad Request	Check CNPJ, CPF, e-mail, phone, or file type/size.
`401`	Unauthorized	Check token validity, expiration, and scope (`partner-can/retail.create`).
`404`	Not Found	CNPJ not found or invalid in the credit bureau.
`409`	Conflict	CNPJ already registered, user rejected, or missing representative document.
`500`	Internal Server Error	Contact support.

Recommended Flow

GET /company/cnpj/{cnpj} — if registered_retail is false, call pre-register.

POST /retail/pre-register — onboard the retail with required documents.

GET /receivable/{cnpj} — consult receivables (requires registration).

POST /order — create payment orders.

⚠️ Points of Attention

The CNPJ must not already exist in Kapitale; otherwise the API returns 409.

Only PDF, JPG, JPEG, and PNG files are accepted (max 10 MB per file).

Receivable consultation (GET /receivable/{cnpj}) is only available after the client is registered with Kapitale.

🏪 Retail Pre-Register

Endpoint#

Authentication#

Form Fields#

Request Example#

Success Response (200)#

What Happens on Success#

Error Responses#

Recommended Flow#

⚠️ Points of Attention#