API: parceiros

Gerencie parceiros de negócio (clientes, fornecedores, contratantes, contratados) via REST.

Parceiros são as pessoas físicas ou jurídicas com quem sua empresa se relaciona — clientes, fornecedores, contratantes, contratados, tomadores, remetentes e destinatários. Use estes endpoints para sincronizar o cadastro com seu ERP/TMS.

Modelo

Campo	Tipo	Descrição
id	uuid	Identificador do parceiro (gerado).
person_kindreq	enum(pf,pj)	Pessoa física ou jurídica.
cpf_cnpjreq	string	CPF (11) ou CNPJ (14), só dígitos. Único por empresa.
legal_namereq	string	Razão social ou nome completo.
trade_name	string	Nome fantasia.
ie	string	Inscrição estadual.
ie_isento	boolean	Indicador de IE isento.
rntrc	string	RNTRC quando aplicável.
rntrc_categoria	string	Categoria do RNTRC (ex.: ETC, TAC).
email	string	E-mail de contato.
phone	string	Telefone.
whatsapp	string	WhatsApp.
cep	string	CEP.
uf	string(2)	UF.
municipio_codigo	string	Código IBGE do município.
municipio_nome	string	Nome do município.
logradouro	string	Endereço.
numero	string	Número.
complemento	string	Complemento.
bairro	string	Bairro.
roles	string[]	Papéis aceitos: contratante, contratado, tomador, destinatario, remetente, cliente_frete, fornecedor.
notes	string	Observações livres (até 2000 chars).
is_active	boolean	Ativo/inativo.
created_at	ISO timestamp	Data de criação.
updated_at	ISO timestamp	Última atualização.

Escopo e isolamento

Os endpoints retornam e gravam exclusivamente parceiros da empresa dona da API key.company_id e created_by são preenchidos pelo backend — não envie no payload.

GET/api/public/v1/partnersAuth: API key

Lista parceiros da empresa autenticada. Requer escopo read.

Query params

Campo	Tipo	Descrição
q	string	Busca em legal_name, trade_name e cpf_cnpj.
role	string	Filtra por papel (ex.: contratado).
only_active	boolean	Quando true, retorna só is_active=true.
limit	number	Máx 200 (default 50).
created_before	ISO timestamp	Paginação por cursor: traz registros anteriores a esta data.

bash

curl "https://freteflow.log.br/api/public/v1/partners?role=contratado&only_active=true&limit=100" \
  -H "X-API-Key: ff_live_..."

POST/api/public/v1/partnersAuth: API key

Cria um parceiro. Requer escopo write.

bash

curl -X POST https://freteflow.log.br/api/public/v1/partners \
  -H "X-API-Key: ff_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "person_kind": "pj",
    "cpf_cnpj": "12345678000190",
    "legal_name": "Transportes Boa Viagem Ltda",
    "trade_name": "Boa Viagem",
    "rntrc": "12345678",
    "rntrc_categoria": "ETC",
    "email": "contato@boaviagem.com.br",
    "phone": "+5511999990000",
    "uf": "SP",
    "municipio_nome": "São Paulo",
    "roles": ["contratado", "fornecedor"],
    "is_active": true
  }'

Se já existir um parceiro com o mesmo cpf_cnpj na empresa, a API responde 409 com error.code = "partner_cpf_cnpj_exists" e o existing_id do registro.

GET/api/public/v1/partners/{id}Auth: API key

Retorna o parceiro pelo id, incluindo as contas bancárias cadastradas em bank_accounts.

bash

curl https://freteflow.log.br/api/public/v1/partners/3f9b... \
  -H "X-API-Key: ff_live_..."

PATCH/api/public/v1/partners/{id}Auth: API key

Atualiza campos do parceiro. Todos os campos do modelo são opcionais; envie apenas o que mudar.

bash

curl -X PATCH https://freteflow.log.br/api/public/v1/partners/3f9b... \
  -H "X-API-Key: ff_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "trade_name": "Boa Viagem Logística", "is_active": false }'

Contas bancárias

A criação e edição de contas bancárias do parceiro ainda é feita pela tela /cadastros/parceiros. A API retorna as contas existentes na resposta de GET /partners/{id} para consulta. Avise se precisa de POST/PATCH/DELETE de contas via API.

Sem DELETE via API

A exclusão de parceiros não é exposta na API pública. Para remover, use a tela ou marque o registro como is_active: false via PATCH.