DOCUMENTAZIONE API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Registrati (v2)
PURPOSE: Crea un account gratuito e ricevi una password di accesso e un token API. Non è richiesta alcuna autenticazione.

--- 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: L’indirizzo email con cui registrarti. Non serve inserire nome o cognome.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Deve essere true. L’utente deve acconsentire ai Termini e Condizioni e all’Informativa sulla privacy.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Iscriviti alla newsletter. Il valore predefinito è false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Lingua dell’account. Una tra en, de, es. Il valore predefinito è en.

--- REQUEST EXAMPLES ---

Example 1: Registrati con un indirizzo email
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Iscriviti e iscriviti alla 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: L’indirizzo email registrato.

Field: password
  Type: string
  Description: Una password di accesso casuale per la dashboard web. Viene restituita una sola volta: salvala in modo sicuro. L’utente può reimpostarla in seguito tramite la procedura “Password dimenticata”.

Field: api_token
  Type: string
  Description: Il bearer token dell’API. Usalo come "Authorization: Bearer " per le richieste /v2/.... Inizia a funzionare quando l’utente conferma la propria email.

Field: free_requests_per_month
  Type: int
  Description: Il numero di richieste gratuite concesse ogni mese.

Field: status
  Type: string
  Description: Lo stato dell’account. "awaiting_activation" finché l’indirizzo email non viene confermato.

Field: message
  Type: string
  Description: Guida chiara sul passaggio successivo (confermare l’indirizzo email).

Field: docs_url
  Type: string
  Description: Link alle istruzioni di implementazione AI pronte per il prompt (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 ===