Contatos - Manual do usuário

Introdução

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

Atributos com o valor null serão retornados na resposta.

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. 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.

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.

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.

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.

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.

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.

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

GET /api/v1/contacts

Exemplo de resposta para visualizar vários contatos

{
  "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.

Exemplo de requisição para criar um contato

POST /api/v1/contacts

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

{
  "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

{
  "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.

Exemplo de requisição para editar um contato

PUT /api/v1/contacts/:id

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

{
  "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

{
    "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)

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

​Introdução

​Rotas

​Visualizar vários contatos

​Parâmetros aceitos

​Visualizar um contato específico

​Criar um contato

​Editar um contato

​Excluir um contato

​Visualizando vários contatos

​Criando um contato

​Editando um contato

​Enums

​Person Type

​Contact Type

​Erros

​Erros de validação

Introdução

Rotas

Visualizar vários contatos

Parâmetros aceitos

Visualizar um contato específico

Criar um contato

Editar um contato

Excluir um contato

Visualizando vários contatos

Criando um contato

Editando um contato

Enums

Person Type

Contact Type

Erros

Erros de validação