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

# Contatos

## **Introdução**

Na API do Procfy as transações são representadas por um objeto JSON com os seguintes atributos:

<Info>
  Atributos com o valor `null` serão retornados na resposta.
</Info>

| Atributo             | Tipo    | Descrição                                             |
| :------------------- | :------ | :---------------------------------------------------- |
| id                   | integer | Identificador único do contato                        |
| name                 | string  | Nome do contato                                       |
| document\_1          | string  | CPF ou CNPJ do contato                                |
| document\_2          | string  | RG ou Inscrição Estadual do contato                   |
| sector\_activity\_id | string  | Identificador único da atividade econômica do contato |
| email                | string  | Email do contato                                      |
| phone\_number        | string  | Telefone do contato                                   |
| cell\_phone\_number  | string  | Celular do contato                                    |
| birth\_date          | date    | Data de nascimento do contato                         |
| description          | string  | Descrição do contato                                  |
| contact\_type        | string  | Tipo do contato                                       |
| person\_type         | string  | Tipo de pessoa do contato                             |
| addresses            | array   | Lista de endereços do contato                         |

Atributos de endereço:

| Atributo        | Tipo    | Descrição                       |
| :-------------- | :------ | :------------------------------ |
| id              | integer | Identificador único do endereço |
| country         | string  | País do endereço                |
| state           | string  | Estado do endereço              |
| city            | string  | Cidade do endereço              |
| address\_line1  | string  | Linha 1 do endereço             |
| address\_line2  | string  | Linha 2 do endereço             |
| district        | string  | Bairro do endereço              |
| postcode        | string  | Código postal do endereço       |
| address\_number | string  | Número do endereço              |

Alguns atributos quando não informados, são preenchidos automaticamente com valores padrão:

| Atributo      | Valor padrão       |
| :------------ | :----------------- |
| person\_type  | undefined\_person  |
| contact\_type | undefined\_contact |
| country       | Brasil             |

***

## **Rotas**

| Método | Endpoint             | Descrição                        |
| :----- | :------------------- | :------------------------------- |
| GET    | /api/v1/contacts     | Visualizar vários contatos       |
| GET    | /api/v1/contacts/:id | Visualizar um contato específico |
| POST   | /api/v1/contacts     | Criar um contato                 |
| PUT    | /api/v1/contacts/:id | Editar um contato                |
| DELETE | /api/v1/contacts/:id | Excluir um contato               |

### **Visualizar vários contatos**

O Procfy utiliza o padrão de paginação para retornar os resultados das requisições. Para mais informações sobre paginação, consulte a seção [**paginação**](/paginacao#introducao).

Para visualizar vários contatos, você deve fazer uma requisição para a API utilizando o método `GET` no endpoint correspondente ao objeto que deseja visualizar.

```text theme={null}
GET /api/v1/contacts
```

#### **Parâmetros aceitos**

| Parâmetro | Tipo    | Descrição                      |
| :-------- | :------ | :----------------------------- |
| page      | integer | Número da página               |
| items     | integer | Quantidade de itens por página |

#### **Visualizar um contato específico**

Para visualizar um contato específico, você deve fazer uma requisição para a API utilizando o método `GET` no endpoint correspondente ao objeto que deseja visualizar.

```text theme={null}
GET /api/v1/contacts/:id
```

#### **Criar um contato**

Para criar um objeto, você deve fazer uma requisição para a API utilizando o método `POST` no endpoint correspondente ao objeto que deseja criar.

```text theme={null}
POST /api/v1/contacts
```

#### **Editar um contato**

Para editar um objeto, você deve fazer uma requisição para a API utilizando o método `PUT` no endpoint correspondente ao objeto que deseja editar.

```text theme={null}
PUT /api/v1/contacts/:id
```

#### **Excluir um contato**

Para excluir um objeto, você deve fazer uma requisição para a API utilizando o método `DELETE` no endpoint correspondente ao objeto que deseja excluir.

```text theme={null}
DELETE /api/v1/contacts/:id
```

***

## **Visualizando vários contatos**

A API utiliza o padrão de paginação para retornar os resultados das requisições. Para mais informações sobre paginação, consulte a seção [**paginação**](/paginacao#introducao).

> Exemplo de requisição para visualizar vários contatos

```text theme={null}
GET /api/v1/contacts
```

> Exemplo de resposta para visualizar vários contatos

```json theme={null}
{
  "page": {
    "page": 1,
    "items": 50,
    "pages": 1,
    "last": 1,
    "next": null,
    "prev": null,
    "count": 2,
    "from": 1,
    "to": 2
  },
  "data": [
    {
      "id": 48,
      "name": "Fulano da Silva",
      "document_1": "99.999.999/9999-99",
      "document_2": "9999999999999",
      "email": "fulano@example.com",
      "phone_number": "(99) 99999-9999",
      "cell_phone_number": "(99) 99999-9999",
      "birth_date": "2004-12-03",
      "description": "Observações",
      "contact_type": "customer",
      "person_type": "natural",
      "addresses": [
        {
          "id": 9,
          "country": "BR",
          "state": "PR",
          "city": "Dois Vizinhos",
          "address_line1": "Endereco",
          "address_line2": "complemento",
          "district": "Bairro",
          "postcode": "11111111",
          "address_number": "123"
        }
      ]
    },
    {
      "id": 49,
      "name": "Beltrano da costa",
      "document_1": "99.999.999/9999-99",
      "document_2": "22222222222",
      "email": "beltrano@example.com",
      "phone_number": "(99) 99999-9999",
      "cell_phone_number": "(99) 99999-9999",
      "birth_date": "2004-12-03",
      "description": "Observações",
      "contact_type": "employee",
      "person_type": "undefined_person",
      "addresses": [
        {
          "id": 10,
          "country": "BR",
          "state": "RJ",
          "city": "Belford Roxo",
          "address_line1": "Endereco",
          "address_line2": "Complemento",
          "district": "Bairro",
          "postcode": "00000000",
          "address_number": "123"
        }
      ]
    }
  ]
}
```

***

## **Criando um contato**

Para criar um objeto, você deve fazer uma requisição para a API utilizando o método `POST` no endpoint correspondente ao objeto que deseja criar.

A API vai retornar o objeto criado, caso não ocorra nenhum erro.

O corpo da requisição deve conter um objeto com os atributos necessários para a criação do objeto.

Os atributos são:

| Atributo              | Tipo    | Obrigatório | Descrição                           |
| :-------------------- | :------ | :---------- | :---------------------------------- |
| name                  | string  | sim         | Nome do contato                     |
| contact\_type         | string  | sim         | Tipo do contato                     |
| person\_type          | string  | sim         | Tipo de pessoa                      |
| email                 | string  | não         | Email do contato                    |
| phone\_number         | string  | não         | Telefone do contato                 |
| document\_1           | string  | não         | CPF/CNPJ do contato                 |
| document\_2           | string  | não         | RG do contato                       |
| sector\_activity\_id  | integer | não         | ID do setor de atividade do contato |
| cell\_phone\_number   | string  | não         | Celular do contato                  |
| birth\_date           | date    | não         | Data de nascimento do contato       |
| description           | string  | não         | Descrição do contato                |
| addresses\_attributes | object  | não         | Endereços do contato                |

Atributos do objeto `addresses_attributes`:

| Atributo        | Tipo   | Obrigatório | Descrição                 |
| :-------------- | :----- | :---------- | :------------------------ |
| country         | string | sim         | País do endereço          |
| state           | string | não         | Estado do endereço        |
| city            | string | não         | Cidade do endereço        |
| address\_line1  | string | não         | Linha 1 do endereço       |
| address\_line2  | string | não         | Linha 2 do endereço       |
| district        | string | não         | Bairro do endereço        |
| postcode        | string | não         | Código postal do endereço |
| address\_number | string | não         | Número do endereço        |

Veja a lista de atributos necessários para a criação do objeto na [tabela de atributos](/contatos#introdução).

> Exemplo de requisição para criar um contato

```text theme={null}
POST /api/v1/contacts
```

> Exemplo de corpo da requisição para criar um contato

```json theme={null}
{
  "name": "Nome",
  "document_1": "99.999.999/9999-99",
  "contact_type": "customer",
  "person_type": "natural",
  "document_2": "9999999999999",
  "sector_activity_id": "",
  "email": "exemplo@hotmail.com",
  "phone_number": "(99) 99999-9999",
  "cell_phone_number": "(99) 99999-9999",
  "birth_date": "2004-12-03",
  "description": "",
  "addresses_attributes": {
    "0": {
      "country": "BR",
      "state": "AL",
      "city": "Atalaia",
      "address_line1": "endereco",
      "address_line2": "complemento",
      "district": "bairro",
      "postcode": "12345678",
      "address_number": "123"
    }
  }
}
```

> Exemplo de resposta para criar um contato

```json theme={null}
{
  "id": 47,
  "name": "Nome",
  "document_1": "99.999.999/9999-99",
  "document_2": "9999999999999",
  "sector_activity_id": null,
  "email": "exemplo@hotmail.com",
  "phone_number": "(99) 99999-9999",
  "cell_phone_number": "(99) 99999-9999",
  "birth_date": "2004-12-03",
  "description": "",
  "contact_type": "undefined_contact",
  "person_type": "undefined_person",
  "addresses": [
    {
      "id": 8,
      "country": "BR",
      "state": "AL",
      "city": "Atalaia",
      "address_line1": "endereco",
      "address_line2": "complemento",
      "district": "bairro",
      "postcode": "12345678",
      "address_number": "123"
    }
  ]
}
```

***

## **Editando um contato**

Para editar um objeto, você deve fazer uma requisição para a API utilizando o método `PUT` no endpoint correspondente ao objeto que deseja editar.

A API vai retornar o objeto editado, caso não ocorra nenhum erro.

O corpo da requisição deve conter um objeto com os atributos necessários para a edição do objeto.

Veja a lista de atributos necessários para a edição do objeto na [tabela de atributos](/contatos#introdução).

> Exemplo de requisição para editar um contato

```text theme={null}
PUT /api/v1/contacts/:id
```

> Exemplo de corpo da requisição para editar um contato

```json theme={null}
{
  "name": "Nome alterado",
  "document_1": "99.999.999/9999-99",
  "document_2": "9999999999999",
  "contact_type": "customer",
  "person_type": "natural",
  "sector_activity_id": "",
  "email": "exemplo@hotmail.com",
  "phone_number": "(99) 99999-9999",
  "cell_phone_number": "(99) 99999-9999",
  "birth_date": "2004-12-03",
  "description": "",
  "addresses_attributes": {
    "0": {
      "country": "BR",
      "state": "AL",
      "city": "Atalaia",
      "address_line1": "endereco",
      "address_line2": "complemento",
      "district": "bairro",
      "postcode": "12345678",
      "address_number": "123"
    }
  }
}
```

> Exemplo de resposta para editar um contato

```json theme={null}
{
    "id": 47,
    "name": "Nome alterado",
    "document_1": "99.999.999/9999-99",
    "document_2": "9999999999999",
    "contact_type": "customer",
    "person_type": "natural",
    "sector_activity_id": null,
    "email": "example@hotail.com",
    "phone_number": "(99) 99999-9999",
    "cell_phone_number": "(99) 99999-9999",
    "birth_date": "2004-12-03",
    "description": "",
    "addresses": [
        {
            "id": 8,
            "country": "BR",
            "state": "AL",
            "city": "Atalaia",
            "address_line1": "endereco",
            "address_line2": "complemento",
            "district": "bairro",
            "postcode": "12345678",
            "address_number": "123"
        }
    ]
}
```

***

## **Enums**

Os enums são utilizados para definir os valores permitidos para os atributos de um objeto. A sua utilização é importante para garantir a integridade dos dados.

#### **Person Type**

O atributo `person_type` é utilizado para definir o tipo de pessoa.

| Valor             | Descrição       |
| :---------------- | :-------------- |
| undefined\_person | Indefinida      |
| natural           | Pessoa física   |
| legal             | Pessoa Jurídica |

#### **Contact Type**

O atributo `contact_type` é utilizado para definir o tipo de contato.

| Valor              | Descrição   |
| :----------------- | :---------- |
| undefined\_contact | Outro       |
| customer           | Cliente     |
| employee           | Funcionário |
| supplier           | Fornecedor  |
| partner            | Parceiro    |
| associate          | Associado   |

***

## **Erros**

Erros que podem ocorrer durante a execução de um contato.

Os erros de validação retornam um objeto com a chave `error` e `description` com a mensagem de erro. A mensagem de erro pode variar de acordo com o erro ocorrido.

### **Erros de validação**

Os erros de validação são retornados quando os atributos obrigatórios não são informados ou quando os atributos informados não estão de acordo com as regras de validação.

> Exemplo de resposta para erro de validação na criação ou edição de um contato (Objeto em branco)

```json theme={null}
{
  "error": "Registro inválido",
  "description": "A validação falhou: Nome não pode ficar em branco, Nome é muito curto (mínimo: 2 caracteres)"
}
```