Documentação da API

POST /insert_contact

Resumo

Este endpoint permite criar um novo contato em uma unidade específica.

---

Descrição

Utilize este endpoint para inserir um novo contato no sistema, associado a uma unidade específica. O contato pode ser uma pessoa física (natural_person) ou jurídica (legal), com informações como CPF/CNPJ, nome, endereço, e outros detalhes.

---

Requisição

Body da Requisição

O corpo deve ser um objeto JSON com os seguintes parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
access_token	string	Sim	Token de autenticação do usuário.	b31643fc-a45f-448c-99ee-736a547f6989
unit_token	string	Sim	Token identificador da unidade.	e6988e9e-b0c1-410c-ae08-aed7c64ac71f
type	string	Sim	Tipo de contato (legal ou natural_person).	natural_person
register	string	Sim	CPF (pessoa física) ou CNPJ (pessoa jurídica).	12345678909 ou 12345678000195
fullName	string	Sim (pessoa física)	Nome completo do contato (para natural_person).	João Silva
fantasyName	string	Não	Nome fantasia (para legal).	Empresa XYZ
socialReason	string	Sim (pessoa jurídica)	Razão social (para legal).	XYZ Comércio Ltda
birthDate	string	Não	Data de nascimento (formato DD/MM/YYYY).	15/05/1990
phone	string	Não	Número de telefone.	11987654321
email	string	Não	Endereço de e-mail.	[email protected]
address	string	Não	Endereço completo.	Rua Exemplo, 123
zip_code	string	Não	CEP (apenas números).	12345678
state	string	Não	Estado (sigla).	SP
city	string	Não	Cidade.	São Paulo
neighborhood	string	Não	Bairro.	Centro
observation	string	Não	Observações sobre o contato.	Cliente estratégico
data_bank	string	Não	Dados bancários do contato.	Banco: 001, Ag: 1234, Conta: 56789-0
number	string	Não	Número do endereço.	123
complement	string	Não	Complemento do endereço.	Apto 45

---

Exemplo de Requisição

Curl (Pessoa Física)

curl -X POST 'https://portal.fipli.pro/api/v1/insert_contact' \
-H 'Content-Type: application/json' \
-d '{
  "access_token": "b31643fc-a45f-448c-99ee-736a547f6989",
  "unit_token": "e6988e9e-b0c1-410c-ae08-aed7c64ac71f",
  "type": "natural_person",
  "register": "12345678909",
  "fullName": "João Silva",
  "birthDate": "15/05/1990",
  "phone": "11987654321",
  "email": "[email protected]",
  "address": "Rua Exemplo, 123",
  "zip_code": "12345678",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Centro",
  "observation": "Cliente estratégico",
  "data_bank": "Banco: 001, Ag: 1234, Conta: 56789-0",
  "number": "123",
  "complement": "Apto 45"
}'

Curl (Pessoa Jurídica)

curl -X POST 'https://portal.fipli.pro/api/v1/insert_contact' \
-H 'Content-Type: application/json' \
-d '{
  "access_token": "b31643fc-a45f-448c-99ee-736a547f6989",
  "unit_token": "e6988e9e-b0c1-410c-ae08-aed7c64ac71f",
  "type": "legal",
  "register": "12345678000195",
  "fantasyName": "Empresa XYZ",
  "socialReason": "XYZ Comércio Ltda",
  "phone": "1133334444",
  "email": "[email protected]",
  "address": "Av. Principal, 456",
  "zip_code": "87654321",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Jardins",
  "observation": "Fornecedor principal",
  "data_bank": "Banco: 033, Ag: 5678, Conta: 12345-6",
  "number": "456",
  "complement": "Sala 10"
}'

---

Resposta

200 OK

Criação realizada com sucesso.

{
  "success": true,
  "message": "Contact inserted successfully",
  "token": "a6927665-6d56-4839-ad23-37d48717da13"
}

Erros Comuns

Status	Mensagem	Descrição
400	"Missing required parameters."	Algum parâmetro obrigatório (access_token, unit_token, type, register) não foi enviado.
400	"Invalid CPF."	O CPF fornecido é inválido (para type: natural_person).
400	"Invalid CNPJ."	O CNPJ fornecido é inválido (para type: legal).
400	"Full name is required for natural persons."	O campo fullName é obrigatório para pessoa física.
400	"Company name (social reason) is required for legal entities."	O campo socialReason é obrigatório para pessoa jurídica.
400	"Invalid contact type."	O tipo de contato fornecido não é legal ou natural_person.
403	"Invalid authentication data."	Token de autenticação inválido ou não autorizado.
404	"Unit not found."	A unidade com o unit_token fornecido não foi encontrada.
500	"An unexpected error occurred. Please try again later."	Erro interno no servidor.

---

Observações

• O campo register deve ser um CPF válido para natural_person ou um CNPJ válido para legal. A validação é feita após a remoção de caracteres não numéricos.
• O campo birthDate deve estar no formato DD/MM/YYYY e será convertido para YYYY-MM-DD para armazenamento.
• Os campos phone e zip_code têm caracteres não numéricos removidos antes do armazenamento.
• Campos opcionais podem ser omitidos ou enviados como null.
• A inserção é realizada de forma transacional, garantindo a consistência dos dados no banco.
• O contato é automaticamente marcado como ativo (active: true) ao ser criado.
• Certifique-se de que os tokens estejam válidos e que a unidade exista no sistema.