Documentação para Desenvolvedores

Clientes

Recurso Descrição
POST /api/v1/customers Criar cliente
GET /api/v1/customers/:id Informações do cliente
PATCH /api/v1/customers/:id Atualizar cliente
PUT /api/v1/customers/:id Atualizar cliente
GET /api/v1/customers Listar clientes
GET /api/v1/customers/cnpj_cpf Buscar por CPF ou CNPJ
GET /api/v1/customers/email Buscar por e-mail

Modelo de Dados

Parâmetro Obr. Tipo Tamanho Descrição
id N/A Integer   ID do cliente
person_name Sim String 255 Nome Completo ou Razão Social
person_type N/A String   Tipo de Cliente
cnpj_cpf Sim String 20 CNPJ/CPF (formato 999.999.999-99 ou 99.999.999/9999-99)
zipcode Sim Integer 8 CEP (formato 99999999)
address Sim Text   Endereço
city_name Sim String 255 Cidade
state Sim String 2 Estado (sigla do estado, Ex: RJ)
neighborhood Sim String 255 Bairro
address_number Não String 255 Número
address_complement Não String 255 Complemento
phone_number Não String 255 Telefone (formato 9988888888)
email Não String 255 E-mail
mobile_local_code Não String 4 DDD do Celular
mobile_number Não String 15 Celular
notes Não Text   Anotações
email_cc Não String 255 E-mail alternativo
created_via_api N/A Boolean   Enviado pela API

Criar cliente

POST /api/v1/customers

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer":{}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/customers'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
...

{"errors":{"customer":["não pode ficar em branco"]}}
Requisição:
@customer = BoletoSimples::Customer.create({person_name: 'Joao Da Silva'})
if @customer.persisted?
  puts "Sucesso :)"
  puts @customer.attributes
else
  puts "Erro :("
  puts @customer.response_errors
end
Resposta:
Erro :(
{
  :cnpj_cpf => [
    [0] "não pode ficar em branco"
  ],
  :zipcode => [
    [0] "não pode ficar em branco"
  ]
}
Requisição:
$customer = BoletoSimples\Customer::create(['person_name' => 'Joao da Silva']);
if($customer->isPersisted()) {
  echo "Sucesso :)\n";
  print_r($customer->attributes());
} else {
  echo "Erro :(\n";
  print_r($customer->response_errors);
}
Resposta:
Erro :(
Array
(
    [cnpj_cpf] => Array
        (
            [0] => não pode ficar em branco
        )

    [zipcode] => Array
        (
            [0] => não pode ficar em branco
        )

)

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer":{"person_name":"Nome do Cliente", "cnpj_cpf": "125.812.717-28", "zipcode": "20071004", "address": "Rua quinhentos", "city_name": "Rio de Janeiro", "state": "RJ", "neighborhood": "bairro"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://sandbox.boletosimples.com.br/api/v1/customers'
Resposta:
HTTP/1.1 201 Created
Date: Fri, 17 Oct 2014 19:30:06 GMT
Status: 201 Created
Location: https://sandbox.boletosimples.com.br/api/v1/customers/1
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "city_name":"Rio de Janeiro",
  "person_name":"Nome do Cliente",
  "address":"Rua quinhentos",
  "address_complement":null,
  "address_number":null,
  "mobile_number":null,
  "cnpj_cpf":"125.812.717-28",
  "email":null,
  "neighborhood":"bairro",
  "person_type":"individual",
  "phone_number":null,
  "zipcode":"20071004",
  "mobile_local_code":null,
  "state":"RJ"
}
Requisição:
@customer = BoletoSimples::Customer.create({
  person_name: "Joao da Silva",
  cnpj_cpf: "782.661.177-64",
  email: "cliente@bom.com",
  address: "Rua quinhentos",
  city_name: "Rio de Janeiro",
  state: "RJ",
  neighborhood: "bairro",
  zipcode: "20071004",
  address_number: "111",
  address_complement: "Sala 4",
  phone_number: "2112123434"
})
if @customer.persisted?
  puts "Sucesso :)"
  puts @customer.attributes
else
  puts "Erro :("
  puts @customer.response_errors
end
Resposta:
Sucesso :)
{
           "person_name" => "Joao da Silva",
              "cnpj_cpf" => "782.661.177-64",
                 "email" => "cliente@bom.com",
               "address" => "Rua quinhentos",
             "city_name" => "Rio de Janeiro",
                 "state" => "RJ",
          "neighborhood" => "bairro",
               "zipcode" => "20071004",
        "address_number" => "111",
    "address_complement" => "Sala 4",
          "phone_number" => "2112123434",
                    "id" => 67,
         "mobile_number" => nil,
           "person_type" => "individual",
     "mobile_local_code" => nil,
       "created_via_api" => true
}
Requisição:
$customer = BoletoSimples\Customer::create([
  'person_name' => "Joao da Silva",
  'cnpj_cpf' => "860.196.915-19",
  'email' => "cliente@example.com",
  'address' => "Rua quinhentos",
  'city_name' => "Rio de Janeiro",
  'state' => "RJ",
  'neighborhood' => "bairro",
  'zipcode' => "20071004",
  'address_number' => "111",
  'address_complement' => "Sala 4",
  'phone_number' => "2112123434"
]);
if($customer->isPersisted()) {
  echo "Sucesso :)\n";
  print_r($customer->attributes());
} else {
  echo "Erro :(\n";
  print_r($customer->response_errors);
}
Resposta:
Sucesso :)
Array
(
    [id] => 66
    [city_name] => Rio de Janeiro
    [person_name] => Joao da Silva
    [address] => Rua quinhentos
    [address_complement] => Sala 4
    [address_number] => 111
    [mobile_number] =>
    [cnpj_cpf] => 860.196.915-19
    [email] => cliente@example.com
    [neighborhood] => bairro
    [person_type] => individual
    [phone_number] => 2112123434
    [zipcode] => 20071004
    [mobile_local_code] =>
    [state] => RJ
    [created_via_api] => 1
)

Informações do cliente

GET /api/v1/customers/:id

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/customers/1'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "city_name":"Rio de Janeiro",
  "person_name":"Nome do Cliente",
  "address":"Rua quinhentos",
  "address_complement":null,
  "address_number":null,
  "mobile_number":null,
  "cnpj_cpf":"125.812.717-28",
  "email":null,
  "neighborhood":"bairro",
  "person_type":"individual",
  "phone_number":null,
  "zipcode":"20071004",
  "mobile_local_code":null,
  "state":"RJ"
}
Requisição:
@customer = BoletoSimples::Customer.find(67)
puts @customer.attributes
Resposta:
{
             "city_name" => "Rio de Janeiro",
           "person_name" => "Joao da Silva",
               "address" => "Rua quinhentos",
    "address_complement" => "Sala 4",
        "address_number" => "111",
         "mobile_number" => nil,
              "cnpj_cpf" => "782.661.177-64",
                 "email" => "cliente@bom.com",
          "neighborhood" => "bairro",
           "person_type" => "individual",
          "phone_number" => "2112123434",
               "zipcode" => "20071004",
     "mobile_local_code" => nil,
                 "state" => "RJ",
       "created_via_api" => true,
                    "id" => 67
}
Requisição:
$customer = BoletoSimples\Customer::find(66);
print_r($customer->attributes());
Resposta:
Array
(
    [id] => 66
    [city_name] => Rio de Janeiro
    [person_name] => Joao da Silva
    [address] => Rua quinhentos
    [address_complement] => Sala 4
    [address_number] => 111
    [mobile_number] =>
    [cnpj_cpf] => 860.196.915-19
    [email] => cliente@example.com
    [neighborhood] => bairro
    [person_type] => individual
    [phone_number] => 2112123434
    [zipcode] => 20071004
    [mobile_local_code] =>
    [state] => RJ
    [created_via_api] => 1
)

Atualizar cliente

PATCH /api/v1/customers/:id ou PUT /api/v1/customers/:id

Exemplo de requisição inválida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer":{"person_name":""}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PATCH 'https://sandbox.boletosimples.com.br/api/v1/customers/1'
Resposta:
HTTP/1.1 422 Unprocessable Entity
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
...

{"errors":{"person_name":["não pode ficar em branco"]}}
Requisição:
@customer = BoletoSimples::Customer.find(1)
@customer.person_name = ""
if @customer.save
  puts "Sucesso :)"
  puts "Novo nome: #{@customer.person_name}"
else
  puts "Erro :("
  puts @customer.response_errors
end
Resposta:
Erro :(
{
  :person_name => [
    [0] "não pode ficar em branco"
  ]
}
Requisição:
$customer = BoletoSimples\Customer::find(1);
$customer->person_name = '';
if($customer->save()) {
  echo "Sucesso :)\n";
  echo "Novo nome: " . $customer->person_name . "\n";;
} else {
  echo "Erro :(\n";
  print_r($customer->response_errors);
}
Resposta:
Erro :(
Array
(
    [person_name] => Array
        (
            [0] => não pode ficar em branco
        )

)

Exemplo de requisição válida

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-d '{"customer":{"person_name":"Nome do Cliente Atualizado"}}' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X PUT 'https://sandbox.boletosimples.com.br/api/v1/customers/1'
Resposta:
HTTP/1.1 204 No Content
Server: Cowboy
Content-Length: 0
Connection: keep-alive
Strict-Transport-Security: max-age=2592000
Location: https://sandbox.boletosimples.com.br/api/v1/customers/1
...

{
  "id":1,
  "city_name":"Rio de Janeiro",
  "person_name":"Nome do Cliente Atualizado",
  "address":"Rua quinhentos",
  "address_complement":null,
  "address_number":null,
  "mobile_number":null,
  "cnpj_cpf":"125.812.717-28",
  "email":null,
  "neighborhood":"bairro",
  "person_type":"individual",
  "phone_number":null,
  "zipcode":"20071004",
  "mobile_local_code":null,
  "state":"RJ"
}
Requisição:
@customer = BoletoSimples::Customer.find(1)
@customer.person_name = "Nome 1234"
if @customer.save
  puts "Sucesso :)"
  puts "Novo nome: #{@customer.person_name}"
else
  puts "Erro :("
  puts @customer.response_errors
end
Resposta:
Sucesso :)
Novo nome: Nome 1234
Requisição:
$customer = BoletoSimples\Customer::find(1);
echo "Nome antigo: " . $customer->person_name . "\n";;
$customer->person_name = 'Nome 1234';
if($customer->save()) {
  echo "Sucesso :)\n";
  echo "Novo nome: " . $customer->person_name . "\n";;
} else {
  echo "Erro :(\n";
  print_r($customer->response_errors);
}
Resposta:
Sucesso :)
Novo nome: Nome 1234

Listar clientes

GET /api/v1/customers

Parâmetro Obr. Tipo Descrição
page Não Number Número da Página
per_page Não Number Quantidade de registros por página (Maximo de 250)

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET "https://sandbox.boletosimples.com.br/api/v1/customers?page=1&per_page=50"
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Link: <https://sandbox.boletosimples.com.br/api/v1/customers?page=3&per_page=50>; rel="last", <https://sandbox.boletosimples.com.br/api/v1/customers?page=2&per_page=50>; rel="next"
Total: 101
Content-Type: application/json; charset=utf-8
...

[
  {
    "id":1,
    "city_name":"Rio de Janeiro",
    "person_name":"Nome do Cliente",
    "address":"Rua quinhentos",
    "address_complement":null,
    "address_number":null,
    "mobile_number":null,
    "cnpj_cpf":"125.812.717-28",
    "email":null,
    "neighborhood":"bairro",
    "person_type":"individual",
    "phone_number":null,
    "zipcode":"20071004",
    "mobile_local_code":null,
    "state":"RJ"
  }
]
Requisição:
@customers = BoletoSimples::Customer.all(page: 1, per_page: 2)
puts "Clientes Retornados: #{@customers.count}"
puts "Total: #{BoletoSimples.last_request.total}"
puts "Primeira Página: #{BoletoSimples.last_request.links[:first]}"
puts "Página Anterior: #{BoletoSimples.last_request.links[:prev]}"
puts "Próxima Página: #{BoletoSimples.last_request.links[:next]}"
puts "Última Página: #{BoletoSimples.last_request.links[:last]}"
Resposta:
Clientes Retornados: 2
Total: 9
Primeira Página:
Página Anterior:
Próxima Página: https://sandbox.boletosimples.com.br/api/v1/customers?page=2&per_page=2
Última Página: https://sandbox.boletosimples.com.br/api/v1/customers?page=5&per_page=2
Requisição:
$customers = BoletoSimples\Customer::all(['page' => 1, 'per_page' => 2]);
echo "Clientes Retornados: " . sizeof($customers) . "\n";
echo "Total: " . BoletoSimples::$last_request->total . "\n";
echo "Primeira Página: " . BoletoSimples::$last_request->links['first'] . "\n";
echo "Página Anterior: " . BoletoSimples::$last_request->links['prev'] . "\n";
echo "Próxima Página: " . BoletoSimples::$last_request->links['next'] . "\n";
echo "Última Página: " . BoletoSimples::$last_request->links['last'] . "\n";
Resposta:
Clientes Retornados: 2
Total: 9
Primeira Página:
Página Anterior:
Próxima Página: https://sandbox.boletosimples.com.br/api/v1/customers?page=2&per_page=2
Última Página: https://sandbox.boletosimples.com.br/api/v1/customers?page=5&per_page=2

Buscar por CPF ou CNPJ

GET /api/v1/customers/cnpj_cpf

Parâmetro Obr. Tipo Descrição
q Sim String CPF ou CNPJ formatado

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/customers/cnpj_cpf?q=125.812.717-28'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "city_name":"Rio de Janeiro",
  "person_name":"Nome do Cliente",
  "address":"Rua quinhentos",
  "address_complement":null,
  "address_number":null,
  "mobile_number":null,
  "cnpj_cpf":"125.812.717-28",
  "email":null,
  "neighborhood":"bairro",
  "person_type":"individual",
  "phone_number":null,
  "zipcode":"20071004",
  "mobile_local_code":null,
  "state":"RJ"
}

Buscar por e-mail

GET /api/v1/customers/email

Parâmetro Obr. Tipo Descrição
q Sim String E-mail

Exemplo

Requisição:
curl -i \
-u $BOLETOSIMPLES_TOKEN:x \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X GET 'https://sandbox.boletosimples.com.br/api/v1/customers/email?q=cliente@example.com'
Resposta:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 19:46:16 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "id":1,
  "city_name":"Rio de Janeiro",
  "person_name":"Nome do Cliente",
  "address":"Rua quinhentos",
  "address_complement":null,
  "address_number":null,
  "mobile_number":null,
  "cnpj_cpf":"125.812.717-28",
  "email":"cliente@example.com",
  "neighborhood":"bairro",
  "person_type":"individual",
  "phone_number":null,
  "zipcode":"20071004",
  "mobile_local_code":null,
  "state":"RJ"
}
Requisição: