DOCUMENTAÇÃO DA API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Cadastre-se (v2)
PURPOSE: Cria uma conta grátis e recebe uma senha de login e um token da API. Sem necessidade de autenticação.

--- API DETAILS ---
Method: POST
URL: https://gender-api.com/v2/sign-up

--- AUTHENTICATION ---
Header: Content-Type: application/json

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: O endereço de e-mail para se cadastrar. Não é necessário informar nome ou sobrenome.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Deve ser verdadeiro. O usuário precisa concordar com os Termos e Condições e com a Política de Privacidade.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Assina a newsletter. O padrão é falso.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Idioma da conta. Um entre en, de, es. O padrão é en.

--- REQUEST EXAMPLES ---

Example 1: Cadastre-se com um endereço de e-mail
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Cadastre-se e assine a newsletter
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true,
    "newsletter": true,
    "locale": "en"
}

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "email": "user@example.com",
    "password": "",
    "api_token": "",
    "free_requests_per_month": 100,
    "status": "awaiting_activation",
    "message": "Account created. Ask the user to click the activation link sent to their email address. The API token below activates automatically once the email is confirmed and can then be used as a Bearer token against the API.",
    "docs_url": "https://gender-api.com/skill.md"
}

--- RESPONSE FIELDS ---

Field: email
  Type: string
  Description: O endereço de e-mail cadastrado.

Field: password
  Type: string
  Description: Uma senha de login aleatória para o painel web. Ela é exibida apenas uma vez; guarda-a com segurança. O utilizador pode redefini-la mais tarde através do fluxo de “esqueci a senha”.

Field: api_token
  Type: string
  Description: O token bearer da API. Use assim: "Authorization: Bearer " em requisições /v2/.... Ele começa a funcionar assim que o usuário confirma o e-mail.

Field: free_requests_per_month
  Type: int
  Description: O número de solicitações gratuitas concedidas por mês.

Field: status
  Type: string
  Description: O status da conta. "awaiting_activation" até o endereço de e-mail ser confirmado.

Field: message
  Type: string
  Description: Orientação fácil de entender sobre o próximo passo (confirmar o endereço de e-mail).

Field: docs_url
  Type: string
  Description: Link para as instruções de implementação de IA prontas para uso (skill.md).

--- IMPLEMENTATION NOTES ---

1. Make sure to replace placeholder values:
   - Replace '' with your actual API key
   - Replace domain placeholders with the actual API domain

2. Handle errors appropriately:
   - Check HTTP status codes
   - Parse error responses
   - Implement retry logic for transient failures

3. Best Practices:
   - Store API keys securely (use environment variables)
   - Implement rate limiting on your side
   - Cache responses when appropriate
   - Use HTTPS for all requests
   - Set appropriate timeout values

4. RECOMMENDED: Implement the Statistics Endpoint
   - The statistics endpoint allows users to monitor their credit usage
   - Users can see how many credits they have used and how many are left
   - This helps prevent unexpected service interruptions
   - API v1: GET /get-stats?key=YOUR_API_KEY
   - API v2: GET /v2/statistic (with Authorization Bearer token)
   - Display remaining credits in your application's UI
   - Consider adding alerts when credits are running low

--- IMPLEMENTATION TEMPLATE ---

// Example implementation in cURL:
curl -X POST \
  'https://gender-api.com/v2/sign-up' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","accept_terms":true}'

--- CREDIT USAGE ---
Required Requests: 0

=== END OF INSTRUCTIONS ===