Tema
Clientes
O cliente é quem recebe e paga as cobranças. Você pode cadastrar o cliente antes e criar a cobrança com o client_id, ou mandar os dados do cliente direto na cobrança. Veja Cobranças.
Todas as chamadas levam Authorization: Bearer SEU_TOKEN_DE_ACESSO.
| Método | Caminho | Faz |
|---|---|---|
POST | /billing/clients | Cadastra um cliente |
GET | /billing/clients/{id} | Consulta um cliente |
GET | /billing/clients | Lista os clientes |
PUT | /billing/clients/{id} | Altera um cliente |
DELETE | /billing/clients/{id} | Apaga um cliente |
/clients é um apelido de /billing/clients, com as mesmas regras.
{id} é o ID numérico do cliente ou o code dele.
Cadastrar um cliente
http
POST /billing/clients
Content-Type: application/json| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
name | texto | sim | Até 255 caracteres. |
email | texto | sim | E-mail válido, até 255 caracteres. |
document | texto | sim | CPF ou CNPJ válido. |
type | texto | sim | individual (pessoa física) ou company (empresa). |
phone | texto | não | Até 20 caracteres. |
gender | texto | não | male ou female. |
birthdate | data | não | AAAA-MM-DD. |
status_id | número | não | 1 Ativo (padrão), 2 Inativo, 3 Bloqueado. |
address | objeto | não | Endereço. Veja abaixo. |
Campos de address (quando mandar o endereço):
| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
address.street | texto | sim | Até 255 caracteres. |
address.city | texto | sim | Até 100 caracteres. |
address.state | texto | sim | Até 100 caracteres. |
address.number | texto | não | Até 20 caracteres. |
address.zip | texto | não | CEP, até 20 caracteres. |
address.country | texto | não | Até 100 caracteres. |
address.observation | texto | não | Até 500 caracteres. |
bash
curl -X POST https://v1.api.fastgivr.com.br/billing/clients \
-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
-H "Content-Type: application/json" \
-d '{
"name": "Cliente Exemplo",
"email": "cliente@exemplo.com.br",
"document": "00000000000",
"type": "individual",
"phone": "11900000000"
}'js
async function createClient(customer) {
const token = await getValidToken();
const response = await fetch('https://v1.api.fastgivr.com.br/billing/clients', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
name: customer.name,
email: customer.email,
document: customer.document,
type: customer.isCompany ? 'company' : 'individual',
}),
});
const body = await response.json();
if (response.status !== 201) {
throw new Error(`Client not created: HTTP ${response.status}`);
}
return body.data; // body.data.client_id is the id to use in charges
}O documento não é único
A API não impede dois clientes com o mesmo CPF/CNPJ. Antes de cadastrar, procure o cliente com GET /billing/clients?search=00000000000, ou guarde o ID no seu sistema.
Resposta 201
json
{
"data": {
"client_id": 501,
"code": "CODIGO_DO_CLIENTE",
"name": "Cliente Exemplo",
"email": "cliente@exemplo.com.br",
"phone": { "formatted": "(11) 90000-0000", "raw": "11900000000" },
"document": { "formatted": "000.000.000-00", "raw": "00000000000" },
"type": "individual",
"gender": null,
"birthdate": { "formatted": null, "raw": null },
"metadata": null,
"status_id": 1,
"status_detail": { "id": 1, "slug": "active", "title": "Ativo" },
"created_at": { "formatted": "...", "raw": "..." },
"updated_at": { "formatted": "...", "raw": "..." }
}
}Exemplo resumido. O ID do cliente vem em data.client_id.
Consultar um cliente
http
GET /billing/clients/{id}Resposta 200: o cliente em data (mesmos campos do cadastro, mais address) e "message": "Informações sobre o cliente".
Cliente não encontrado: status 404, com "message": "Cliente não encontrado.".
Listar clientes
http
GET /billing/clients?search=Exemplo&page=1&per_page=50| Parâmetro | Tipo | Regra |
|---|---|---|
search | texto | Busca no nome ou no documento (com ou sem pontuação). |
type | texto | individual ou company. |
status_id | texto | Um ou mais IDs separados por vírgula: 1,3. |
status | texto | Um ou mais: active, inactive, blocked. |
created_at_start / created_at_end | data | Cadastro, AAAA-MM-DD. |
updated_at_start / updated_at_end | data | Última alteração, AAAA-MM-DD. |
page | número | Página, a partir de 1. |
per_page | número | Itens por página. Padrão 15. |
A lista vem do mais novo para o mais antigo, no mesmo formato da listagem de cobranças: data (lista) e meta (total, page, limit, total_pages, has_next_page, has_prev_page).
Alterar um cliente
http
PUT /billing/clients/{id}
Content-Type: application/jsonMande só os campos que quer mudar: name, email, phone, type, gender, birthdate, status_id (1, 2 ou 3), address (mesmas regras do cadastro) e metadata.
metadata é uma lista de campos livres:
json
{
"metadata": [
{ "label": "Código no ERP", "value": "C-000123" }
]
}| Campo | Regra |
|---|---|
metadata[].label | Obrigatório, até 255 caracteres. |
metadata[].value | Até 1000 caracteres. |
Resposta: status 201, o cliente em data e "message": "Cliente atualizado com sucesso!".
Apagar um cliente
http
DELETE /billing/clients/{id}O cliente sai da lista (status Excluído). Resposta 204, sem corpo.
Erros
| Status | Quando |
|---|---|
404 | Cliente não existe ou é de outra conta. |
422 | Campo faltando ou inválido. Detalhes por campo em errors. Veja Erros. |
Confira o status HTTP
Na resposta 404 de clientes, o campo success pode vir true. Use sempre o status HTTP.