API de Clientes

🤖 Explicar com IA

A API de Clientes é uma ferramenta que permite às empresas gerenciar e recuperar informações de clientes de forma segura e eficiente. Com esta API, as empresas podem integrar funcionalidades de gestão de clientes em seus sites, aplicações e outras soluções de software.

Ela oferece suporte a recursos como paginação, busca por nome ou e-mail e informações detalhadas do cliente, incluindo nome, e-mail, telefone, foto, país e metadados personalizados.

Obter uma lista de todos os clientes¶

Este endpoint recupera uma lista paginada de todos os clientes da sua conta. Por padrão, ele retorna 10 clientes por página.

Parâmetros de Consulta (Query Parameters):

Solicitação (Listar Todos os Clientes):

curl -X GET 'https://api.4geeks.io/v1/customers/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Solicitação (Com Paginação):

curl -X GET 'https://api.4geeks.io/v1/customers/?page=2&page_size=5' \
     -u 'sk_test_51O62xYzAbcDef123:'

Solicitação (Buscar por Nome ou E-mail):

curl -X GET 'https://api.4geeks.io/v1/customers/?search=john' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
    "count": 38,
    "next": "https://api.4geeks.io/v1/customers/?page=3",
    "previous": "https://api.4geeks.io/v1/customers/",
    "results": [
        {
            "id": "217866f3-e1c2-465c-a242-1c04e30ba3fa",
            "developer": 2875,
            "first_name": "test",
            "last_name": "test",
            "email": "shadya.mora+401@4geeks.io",
            "phone": null,
            "photo": "https://seccdn.libravatar.org/avatar/d33b74df677623a5cc2bc9ea26d528fc?d=monsterid",
            "country": null,
            "metadata": null,
            "test": true
        },
        {
            "id": "3048a540-e825-4ccf-a693-fc4771c5f216",
            "developer": 2875,
            "first_name": "panchos",
            "last_name": "Cruz",
            "email": "marco.cruz+24@4geeks.io",
            "phone": null,
            "photo": "https://seccdn.libravatar.org/avatar/79a1c28ca1ef7df0e2b80c4eb4367cbf?d=monsterid",
            "country": "Costa Rica",
            "metadata": null,
            "test": true
        }
    ]
}

Obter um cliente específico¶

Este endpoint recupera os detalhes completos de um cliente específico através do seu ID único.

Parâmetros de Caminho (Path Parameters):

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/customers/03124bfa-a8gd-4e63-823f-90540b9akcff/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK):

{
    "id": "217866f3-e1c2-465c-a242-1c04e30ba3fa",
    "developer": 2875,
    "first_name": "test",
    "last_name": "test",
    "email": "shadya.mora+401@4geeks.io",
    "phone": "+50683236988",
    "photo": "https://seccdn.libravatar.org/avatar/d33b74df677623a5cc2bc9ea26d528fc?d=monsterid",
    "country": "Costa Rica",
    "metadata": null,
    "test": true
}

Buscar clientes¶

Este endpoint recupera uma lista de clientes que correspondem a uma consulta de busca. As buscas são realizadas nos campos first_name e email.

Parâmetros de Consulta (Query Parameters):

Solicitação:

curl -X GET 'https://api.4geeks.io/v1/customers/?search=alejandro' \
     -u 'sk_test_51O62xYzAbcDef123:'

Resposta (200 OK - Resultados Encontrados):

[
    {
        "id": "004b75b1-64d9-42cc-8556-1b111611b67b",
        "developer_id": 2875,
        "first_name": "Shadya",
        "last_name": "Mora Sánchez",
        "email": "shadya.mora@4geeks.io",
        "phone": null,
        "photo": "https://storage.googleapis.com/g-payments.appspot.com/img/Shadya_Mora_test_1696356164.None",
        "country": "Costa Rica",
        "pay_providers": [
            {
                "id": "cus_NHLcuJNDnJDTnK",
                "name": "stripe"
            }
        ],
        "metadata": null,
        "created_on": "2023-02-26T06:56:07.152267Z",
        "test": false
    },
    {
        "id": "008ffa95-31be-41f8-b797-a4d75aafb9a5",
        "developer_id": 2875,
        "first_name": "Josito",
        "last_name": "Urenas",
        "email": "jose.urena+407@4geeks.io",
        "phone": "000000000",
        "photo": "https://storage.googleapis.com/g-payments.appspot.com/img/Josito_Urenas_test_1696279031.jpeg",
        "country": "Argentina",
        "pay_providers": [
            {
                "id": "cus_NWeHJ69zAJZx9Y",
                "name": "stripe"
            }
        ],
        "metadata": null,
        "created_on": "2023-03-14T16:46:08.241614Z",
        "test": true
    }
]

Resposta (404 Not Found - Sem Resultados):

{
    "message": {
        "code": 404,
        "title": "Customer not found",
        "content": "No customers found matching the query: 'customer_name'.",
        "type": "danger",
        "query": "customer_name"
    }
}

Gestão de Endereços¶

Os clientes podem ter até 3 endereços associados ao seu perfil.

Tratamento de Erros¶

A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Abaixo estão erros comuns específicos para clientes:

400 Bad Request (Solicitação Inválida)¶

Ocorre quando a solicitação está malformada ou faltam campos obrigatórios.

Cenários:

Exemplo de Resposta de Erro:

{
    "code": 400,
    "title": "Invalid request",
    "content": "The search query cannot be empty.",
    "type": "danger"
}

401 Unauthorized (Não Autorizado)¶

Falha na autenticação. A Chave de API é inválida, está ausente ou malformada.

Exemplo:

{
    "detail": "Authentication credentials were not provided."
}

Solução:

• Verifique se você incluiu o parâmetro -u 'sk_test_...: ou o cabeçalho Authorization: Basic
• Certifique-se de que sua Chave de API está correta e ativa
• Teste com o Postman usando Basic Auth

404 Not Found (Não Encontrado)¶

O cliente solicitado não existe.

Exemplo:

{
    "code": 404,
    "title": "Customer not found",
    "content": "The customer could not be found, please check the id.",
    "type": "danger"
}

Solução:

• Verifique se o ID do cliente existe
• Use o endpoint de listagem para encontrar o ID correto do cliente
• Certifique-se de que o cliente pertence à sua conta de desenvolvedor

406 Not Acceptable (Não Aceitável)¶

Ocorre ao tentar realizar uma ação inválida.

Exemplo:

{
    "code": 406,
    "title": "Address registration failure",
    "content": "Customer already has 3 addresses registered.",
    "type": "danger"
}

Solução:

• Exclua um endereço existente antes de criar um novo
• Máximo de 3 endereços por cliente

Notas Importantes¶

Melhores Práticas¶

1. Valide os endereços de e-mail - Garanta que os e-mails sejam únicos e válidos antes de criar.
2. Use os metadados com sabedoria - Armazene dados de negócio relevantes nos metadados para facilitar a filtragem posterior.
3. Mantenha os endereços atualizados - Mantenha as informações de endereço atuais para envios precisos.
4. Gerencie a paginação - Use os números de página e page_size para grandes listas de clientes.
5. Busque com eficiência - Use os parâmetros de busca para encontrar clientes rapidamente.
6. Use endereços padrão - Marque os endereços preferidos como padrão por conveniência.

Solução de Problemas¶

Problema: “Customer already has 3 addresses registered”¶

Causa: Tentativa de adicionar mais de 3 endereços a um cliente.
Solução:

• Exclua um endereço existente primeiro.
• Use o endpoint DELETE para remover um endereço não utilizado.
• Em seguida, crie o novo endereço.

Problema: “The customer could not be found”¶

Causa: O ID do cliente não existe ou pertence a uma conta de desenvolvedor diferente.
Solução:

• Verifique o ID do cliente usando o endpoint de listagem.
• Certifique-se de que está usando a Chave de API correta.
• Verifique se o cliente não foi excluído.

Problema: “Authentication credentials were not provided”¶

Causa: Autenticação de Chave de API ausente ou inválida.
Solução:

• Use -u 'sk_test_...: no cURL.
• Ou use o cabeçalho Authorization: Basic <base64_encoded_key>.
• Verifique se sua Chave de API está ativa.

FAQ (Perguntas Frequentes)¶

P: Posso ter endereços de e-mail duplicados?
R: Não, os endereços de e-mail devem ser únicos em sua conta de desenvolvedor. Tentar criar um duplicado resultará em erro.

P: O que acontece com o histórico de pagamentos quando excluo um cliente?
R: Os registros de pagamento são preservados. Você ainda poderá visualizar o histórico de transações mesmo após a exclusão do cliente.

P: Quantos endereços um cliente pode ter?
R: Cada cliente pode ter até 3 endereços. Exclua um endereço existente antes de adicionar um novo se o limite for atingido.

P: Posso buscar por múltiplos campos?
R: O parâmetro de busca pesquisa nos campos first_name e email. Para buscar por outros campos, recupere todos os clientes e filtre do seu lado.

P: Que dados posso armazenar nos metadados?
R: Os metadados aceitam qualquer objeto JSON válido (máx. 10KB). Usos comuns incluem tipo de cliente, fonte de registro, pontos de fidelidade, etc.

P: Com que frequência devo atualizar as informações do cliente?
R: Atualize as informações sempre que elas mudarem. Não há limites de taxa para atualizações.

• Ainda tem dúvidas? Pergunte na comunidade..
• Consulte el changelog.