vassourita / ploomes-test

Simple API developed for a technical test

PloomesTest API

Developed for a technical test. This doc has been generated based on the OpenApi Specification.

This is a simple REST API for a single resource, where you can create, see, update, and delete items.

Swagger endpoints:

Swagger UI [OFFLINE]

Swagger Json Docs [OFFLINE]

Useful endpoints to test the API:

CPF generator

CNPJ generator

Client

POST /api/clients

Creates a new client.

Body parameter

{
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11912234556",
  "address": "Rua Ferreira de Araujo, Pinheiros, 79",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil"
}

Parameters

Name	In	Type	Required	Description
body	body	CreateClientDto	false	The payload to create the client.

Example responses

201 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": 1,
  "typeName": "company",
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11912234556",
  "address": "Rua Ferreira de Araujo, Pinheiros, 79",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
201	Created	Success	Client
400	Bad Request	Bad Request	ErrorList

This operation does not require authentication

GET /api/clients

Gets all clients within the given page, page size, query and client type.

Parameters

Name	In	Type	Required	Description
page	query	integer(int32)	false	The page number.
pageSize	query	integer(int32)	false	The page size.
query	query	string	false	The company name to be searched.
type	query	string	false	The company type to be filtered. Must be 'person' or 'company', otherwise it will be ignored.

Example responses

200 Response

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "type": 1,
    "typeName": "company",
    "federalDocument": "12345678000190",
    "name": "Ploomes",
    "email": "[e-mail]",
    "phone": "11912234556",
    "address": "Rua Ferreira de Araujo, Pinheiros, 79",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "05428000",
    "country": "Brasil",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Success	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[Client]	false	none	[Client entity definition.]
» id	string(uuid)	true	read-only	Client's unique identifier.
» type	ClientType(int32)	true	none	Client type definition. The length of the federal document will define the client type.
» typeName	string	true	read-only	Client's type.
» federalDocument	string	true	none	Client's CPF or CNPJ.
» name	string	true	none	Client's name.
» email	string	true	none	Client's email address.
» phone	string	true	none	Client's phone number.
» address	string	true	none	Client's address.
» city	string	true	none	Client's city.
» state	string	true	none	Client's state.
» zipCode	string	true	none	Client's zip code.
» country	string	true	none	Client's country.
» createdAt	string(date-time)	true	none	Client's creation date.
» updatedAt	string(date-time)	true	none	Client's last update date.

Enumerated Values

Property	Value
type	0
type	1

This operation does not require authentication

GET /api/clients/{id}

Gets the client with the given id.

Parameters

Name	In	Type	Required	Description
id	path	string(uuid)	true	The client id.

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": 1,
  "typeName": "company",
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11912234556",
  "address": "Rua Ferreira de Araujo, Pinheiros, 79",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Client
404	Not Found	Not Found	ProblemDetails

This operation does not require authentication

DELETE /api/clients/{id}

Deletes the client with the given id.

Parameters

Name	In	Type	Required	Description
id	path	string(uuid)	true	The id of the client to be deleted.

Responses

Status	Meaning	Description	Schema
204	No Content	Success	None
404	Not Found	Not Found	ProblemDetails

This operation does not require authentication

PUT /api/clients/{id}

Updates the client with the given id.

Body parameter

{
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11999999999",
  "address": "Rua Ferreira de Araujo, Pinheiros, 80",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil"
}

Parameters

Name	In	Type	Required	Description
id	path	string(uuid)	true	The id of the client to be updated.
body	body	UpdateClientDto	false	The payload to update the client.

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": 1,
  "typeName": "company",
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11999999999",
  "address": "Rua Ferreira de Araujo, Pinheiros, 80",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	Client
400	Bad Request	Bad Request	ErrorList

This operation does not require authentication

Schemas

Client

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": 1,
  "typeName": "company",
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11912234556",
  "address": "Rua Ferreira de Araujo, Pinheiros, 79",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Client entity definition.

Properties

Name	Type	Required	Restrictions	Description
id	string(uuid)	true	read-only	Client's unique identifier.
type	ClientType	true	none	Client type definition. The length of the federal document will define the client type.
typeName	string	true	read-only	Client's type.
federalDocument	string	true	none	Client's CPF or CNPJ.
name	string	true	none	Client's name.
email	string	true	none	Client's email address.
phone	string	true	none	Client's phone number.
address	string	true	none	Client's address.
city	string	true	none	Client's city.
state	string	true	none	Client's state.
zipCode	string	true	none	Client's zip code.
country	string	true	none	Client's country.
createdAt	string(date-time)	true	none	Client's creation date.
updatedAt	string(date-time)	true	none	Client's last update date.

CreateClientDto

{
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11912234556",
  "address": "Rua Ferreira de Araujo, Pinheiros, 79",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil"
}

Payload used to create a client.

Properties

Name	Type	Required	Restrictions	Description
federalDocument	string	true	none	Client's CPF or CNPJ. Must be unique. Should contain only digits (11 or 14). The length will define the client type.
name	string	true	none	Client's name.
email	string(email)	true	none	Client's email address.
phone	string	true	none	Client's phone number. Should contain only digits and the region code, up to a maximum of 11 digits.
address	string	true	none	Client's address.
city	string	true	none	Client's city.
state	string	true	none	Client's state.
zipCode	string	true	none	Client's zip code.
country	string	true	none	Client's zip country.

ErrorList

{
  "errors": [
    "Invalid federal document. Try a valid CPF or CNPJ, without punctuation"
  ]
}

A validation errors list.

Properties

Name	Type	Required	Restrictions	Description
errors	[string]	true	none	none

ProblemDetails

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Error details of a failed 404 request.

Properties

Name	Type	Required	Restrictions	Description
additionalProperties	any	false	none	none
type	string¦null	false	none	none
title	string¦null	false	none	none
status	integer(int32)¦null	false	none	none
detail	string¦null	false	none	none
instance	string¦null	false	none	none

UpdateClientDto

{
  "federalDocument": "12345678000190",
  "name": "Ploomes",
  "email": "[e-mail]",
  "phone": "11912234556",
  "address": "Rua Ferreira de Araujo, Pinheiros, 79",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "05428000",
  "country": "Brasil"
}

Payload used to update a client.

Properties

Name	Type	Required	Restrictions	Description
federalDocument	string¦null	false	none	Client's CPF or CNPJ. Must be unique. Should contain only digits (11 or 14). The length will define the client type.
name	string¦null	false	none	Client's name.
email	string(email)¦null	false	none	Client's email address.
phone	string¦null	false	none	Client's phone number. Should contain only digits and the region code, up to a maximum of 11 digits.
address	string¦null	false	none	Client's address.
city	string¦null	false	none	Client's city.
state	string¦null	false	none	Client's state.
zipCode	string¦null	false	none	Client's zip code.
country	string¦null	false	none	Client's zip country.